Hiperstation for Mainframe Servers User Guide
370
Hiperstation Hiperstation for Mainframe Servers User Guide Release 8.0.1
Transcript of Hiperstation for Mainframe Servers User Guide
Hiperstation Hiperstation for Mainframe Servers
User Guide
Release 8.0.1
ii Hiperstation for Mainframe Servers User Guide
Please direct questions about Hiperstationor comments on this document to:
Compuware Customer Support
http://go.compuware.com/
This document and the product referenced in it are subject to the following legends:
Copyright 1994-2013 Compuware Corporation. All rights reserved. Unpublished rights reserved under the Copyright Laws of the United States.
U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in Compuware Corporation license agreement and as provided in DFARS 227.7202-1(a) and 227.7202-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable. Compuware Corporation.
This product contains confidential information and trade secrets of Compuware Corporation. Use, disclosure, or reproduction is prohibited without the prior express written permission of Compuware Corporation. Access is limited to authorized users. Use of this product is subject to the terms and conditions of the user’s License Agreement with Compuware Corporation.
Compuware, Hiperstation, Hiperstation for VTAM, Hiperstation for Mainframe Servers, Hiperstation for WebSphere MQ, QAHiperstation+, QAPlayback, File-AID, File-AID for DB2, File-AID for IMS, File-AID/MVS, and File-AID/RDX are trademarks or registered trademarks of Compuware Corporation.
ISPF, CICS, DB2, DFSMS, MVS/ESA, MVS/SP, MVS/XA, OS/390, RACF, REXX, VTAM, BookManager, MQSeries, WebSphere MQ, zSeries, and z/OS are trademarks or registered trademarks of International Business Machines Corporation.
Adobe® Reader® is a trademark of Adobe Systems Incorporated in the United States and/or other countries.
All other company and product names are trademarks or registered trademarks of their respective owners.
CWQGUG8A December 4, 2013.
iii
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiAccessing Hiperstation Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
HTML Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xviiiBookManager Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xviii
PC Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xviiiMainframe Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixKnown-Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Using this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixManual Contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixNotation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxCommand Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
Reading Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiAccessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Installing Windows Accessibility Features . . . . . . . . . . . . . . . . . . . . . . . .xxiiiSelecting Font and Font Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiiiChanging Color and Contrast. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiiiSetting Cursor Blink Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxivUsing Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxivAccessibility Exceptions Work Arounds . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Known Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxivSolutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvFrontLine Support Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvContacting Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Phone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvWeb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviMail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Corporate Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Chapter 1. Hiperstation for Mainframe Servers Overview . . . . . . . . . . . . . . . . . . 1-1
Chapter 2. APPC Global Recording and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Creating an APPC Global Recording Request. . . . . . . . . . . . . . . . . . . . . . . . . . .2-2
Define Script Creation Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6Monitoring and Managing Existing Requests . . . . . . . . . . . . . . . . . . . . . . . . .2-10
View Active Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11Reviewing Repositories and Creating Scripts . . . . . . . . . . . . . . . . . . . . . . . . . .2-12
Generate Scripts from a Selected Repository. . . . . . . . . . . . . . . . . . . . . . .2-14Generate Scripts from Selected Sessions . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Defining Global Recording Manager Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16Accessing Global Recording Administration . . . . . . . . . . . . . . . . . . . . . . . . . .2-16Using the Global Recording Batch Interface . . . . . . . . . . . . . . . . . . . . . . . . . .2-17
Create a Global Recording Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17Create a Global Recording Request with the Batch Interface . . . . . .2-17Global Recording Request Parameter Syntax . . . . . . . . . . . . . . . . . .2-18Global Recording Request Parameters . . . . . . . . . . . . . . . . . . . . . . . .2-20
Check the Status of Existing Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . .2-39
iv Hiperstation for Mainframe Servers User Guide
Manage Existing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40Retrieve the Parameters of an Existing Request. . . . . . . . . . . . . . . . . . . . 2-42Generate a Request Parameters Skeleton . . . . . . . . . . . . . . . . . . . . . . . . . 2-43Create Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-43
Script Creation Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44Troubleshoot Failed Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50
Recording Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50Script Create Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50
Generating a Capture Segment Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50Review the Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52
Merging APPC Capture Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52
Chapter 3. APPC Unattended Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Starting Unattended Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Generating APPC Unattended Processing Statements . . . . . . . . . . . . . . . . . . . 3-2
Setting Unattended Statement Parameters . . . . . . . . . . . . . . . . . . . . . . . . 3-2CONTROL Statement Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3ALLOCATE/ACCEPT Statement Parameters. . . . . . . . . . . . . . . . . . . . 3-4SCRIPT Statement Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7COMPANY Statement Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8CACHE INCLUDE and EXCLUDE Statement Parameters . . . . . . . . . 3-8
Building Unattended Statements and JCL. . . . . . . . . . . . . . . . . . . . . . . . . 3-8Building JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Restrict Specified Script Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Chapter 4. Unattended Playback of APPC Scripts . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Using Unattended Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Step 1. Review Storage Requirements for Unattended Mode Processing . 4-1Step 2. Record the Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Step 3. Identify the Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Step 4. Identify the Scripts To Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Step 5. Submit the Batch Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Playing Back APPC Datastreams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Timing Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Think-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Control and Timing Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Unattended Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4Editing APPC Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
APPC Statement Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4APPC Control Script Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
<VERSION> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5<CONTENT> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5<DETAIL> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5<ERROR> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6<EXTDATA> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6<INBOUND> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6<OUTBOUND> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7<PIU> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7<REPLACE> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7<EXTRACT> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10<TIME> Tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11<UNKNOWN> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
APPC Verb Script Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11<CONFIRM> Tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11<CONFIRMED> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12<ALLOCATE> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12<DEALLOCATE> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
v
<FLUSH> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12<PREPARE_TO_RECEIVE> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13<REQUEST_TO_SEND> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13<SEND_DATA> Tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13<SEND_ERROR> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14<SEND_EXPEDITED_DATA> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14
Contents of APPC Detail Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-15
APPC Unattended Playback Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16Statement Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16APPC Unattended Playback Statement Summary. . . . . . . . . . . . . . . . . . .4-17CONTROL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18CACHEXCL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20CACHINCL Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20COMPANY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21TABLEDEF Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21TABLE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22ALLOCATE and ACCEPT Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22
Required Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24Optional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24
APPCGRP Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-29Required Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-30Optional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-30
SCRIPT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32Required Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32Optional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32Script Not Found Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32
Unattended Playback Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32APPC REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-35
APPC Error Determination REXX Variables . . . . . . . . . . . . . . . . . . . . . . .4-35APPC Environment Data REXX Variables. . . . . . . . . . . . . . . . . . . . . . . . .4-36APPC Application Data REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . .4-36
APPC_ACTUAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37APPC_EXPECTED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37APPC_ACTUAL_LENGTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38APPC_EXPECTED_LENGTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38
APPC General REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39CYCLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39GRPCYCLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39
APPC Summary Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40Outbound Performance Information . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40Inbound Performance Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40Elapsed Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40
APPC Unattended Playback Example Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40Example 1: Play Back 100 APPC Conversations All at Once . . . . . . . . . .4-41Example 2: Play Back 100 APPC Conversations Started Every 3 Seconds 4-41Example 3: Play Back 100 APPC Conversations Started at Intervals . . . .4-41Example 4: Play Back One Lengthened APPC Conversation . . . . . . . . . .4-42Example 5: Play Back Two Related APPC Conversations . . . . . . . . . . . . .4-42Example 6: Play Back APPC Conversations Started in Various Ways . . . .4-43
Allocate 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44Allocate 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44Allocate 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44Allocate 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44
vi Hiperstation for Mainframe Servers User Guide
APPC Data-Driven Testing Example Using REXX . . . . . . . . . . . . . . . . . . . . . 4-44Review the Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45Extract the Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-47Share the Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-48Replace the Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-51Alter the Request String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-53Play Scripts Serially and Concurrently . . . . . . . . . . . . . . . . . . . . . . . . . . 4-54
Create Playback Control Statements for the Business Transaction . 4-55Create JCL to Play Back the Business Transaction . . . . . . . . . . . . . . 4-56Review the Playback Job Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-57
APPC Data-Driven Testing Example Using Playback Tables. . . . . . . . . . . . . . 4-59Playback Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60Extract the Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60Store a Shared Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60Retrieve a Shared Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60Alter the Request String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-61Getting Playback Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-63
Sample Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64
Chapter 5. APPC Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1Summary Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Outbound Performance Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Inbound Performance Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Elapsed Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
REXX Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Chapter 6. TCP/IP Global Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1Adding a Global Recording Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Correcting Invalid IP Address Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6Monitoring and Maintaining Existing Requests. . . . . . . . . . . . . . . . . . . . . . . . 6-8
View Session Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9Monitor All Existing Requests (Administrator Access) . . . . . . . . . . . . . . 6-10
Using the Global Recording Batch Interface. . . . . . . . . . . . . . . . . . . . . . . . . . 6-10Create a Global Recording Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Global Recording Request Parameter Syntax. . . . . . . . . . . . . . . . . . 6-11Global Recording Request Parameters . . . . . . . . . . . . . . . . . . . . . . . 6-13
Check the Status of Existing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19Manage Existing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20Retrieve the Parameters of an Existing Request. . . . . . . . . . . . . . . . . . . . 6-21Generate a Request Parameters Skeleton . . . . . . . . . . . . . . . . . . . . . . . . . 6-22Troubleshoot Failed Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23
Merging TCP/IP Capture Repositories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23
Chapter 7. TCP/IP Scripts and Subset Repositories . . . . . . . . . . . . . . . . . . . . . . . . 7-1Creating Scripts and Subset Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Create TCP/IP Scripts and Establish Filtering Criteria. . . . . . . . . . . . . . . . 7-1DB2 Connect Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4IMS Connect Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5CTG Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7ECI Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Filtering IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9Define Activity Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11Specify the Source Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13Define Detail Data Storage and Output Requirements . . . . . . . . . . . . . . 7-14Specify Output Datasets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16Select Script Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17
vii
Specify Subset Repository Output Datasets. . . . . . . . . . . . . . . . . . . . . . . .7-18Select a Processing Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-19
Browsing and Editing Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-20Browse a Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-21
<VERSION> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-21<DETAIL> Tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-21<TIME> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-22<CONNECT> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-22<DISCONNECT> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-24<CLIENT> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-25<SERVER> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-25<CTG> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-26<DB2> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-26<ECI> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-27<IMS> Tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-27<CONTENT> Tag for Inline Data. . . . . . . . . . . . . . . . . . . . . . . . . . . .7-28<CONTENT> Tag for External Data . . . . . . . . . . . . . . . . . . . . . . . . . .7-29
Edit a Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-29Script Syntax Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-30<REPLACE> Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-32Offset and Length Determination Macros . . . . . . . . . . . . . . . . . . . .7-33Hiperstation for Mainframe Servers REXX Variables . . . . . . . . . . . .7-35
Editing TCP/IP Detail Data with File-AID/MVS . . . . . . . . . . . . . . . . . . . . . . . .7-38Assign a PF Key to MAPD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-39Map an Individual Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-39Map an Entire Data File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-40Access MAPD Help Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-41Troubleshoot Message Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-41
Script Dataset Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-41Detail Dataset Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-42General Information and Error Messages . . . . . . . . . . . . . . . . . . . . .7-42
Chapter 8. TCP/IP Interactive Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1Introducing TCP/IP Interactive Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-1Creating a New Interactive Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2Generating a Playback from a Script Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-4Changing Playback Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-5
Environment Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-5Socket Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-8Script Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-11
Submitting Your Playback for Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-12Selecting a Previously Saved Playback to Review . . . . . . . . . . . . . . . . . . . . . . .8-14Deleting a Playback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-14Generating Playback Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-14
TCP/IP - Basic Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-15TCP/IP - Custom Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-16
Chapter 9. TCP/IP Unattended Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1Creating Playback Control Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-1
Define Statements for Server Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3CONTROL Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3SOCKETS Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-8SCRIPT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-15COLLECT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-16
Define Statements for Client Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-18CONTROL Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-18SOCKETS Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-22
viii Hiperstation for Mainframe Servers User Guide
SCRIPT Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25Preparing the Playback Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25Submitting the Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-27
Review Playback Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-28Playback Return Code Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . 9-28
Troubleshooting with the Playback Error Summary . . . . . . . . . . . . . . . . . . . 9-30
Chapter 10. TCP/IP Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1Reporting Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1Creating and Managing Reporting Control Assets . . . . . . . . . . . . . . . . . . . . . 10-2
CONTROL Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3REPORT Statements for Basic Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6
HTML Exception REPORT Statement. . . . . . . . . . . . . . . . . . . . . . . . 10-6Response Time and Script Timing REPORT Statements . . . . . . . . . 10-9
REPORT Statement for Custom Reports . . . . . . . . . . . . . . . . . . . . . . . . . 10-9Preparing the Reporting Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13Submitting the Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16Reading and Navigating Basic Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
HTML Exception Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17Script Timing Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20Response Time Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
Chapter 11. Archive Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1Introducing the Archive Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1
Using Hiperstation as a Security Monitoring Tool . . . . . . . . . . . . . . . . . 11-1Implementing Hiperstation as a Security Monitoring Tool . . . . . . . . . . 11-1Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Using the Archive Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
Chapter 12. Hiperstation for Mainframe Servers Profile Defaults . . . . . . . . . . . . 12-1APPC Profile Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1TCP/IP Profile Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6Auditing TCP/IP Profile Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13Playback TCP/IP Profile Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-14
Appendix A. TCP/IP Data Collection and Reporting Tables . . . . . . . . . . . . . . . . . A-1PLAYBACK Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
PLAYBACK Report Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2PLAYBACK Statistic Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
SOCKETS Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3SOCKETS Report Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4SOCKETS Statistic Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
SCRIPT Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5SCRIPT Report Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5SCRIPT Statistic Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
CONNECTION Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7CONNECTION Report Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7CONNECTION Statistic Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
MESSAGE Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9MESSAGE Report Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9
ix
Appendix B. TCP/IP Report Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
Appendix C. TCP Script Create Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
Appendix D. Customer Support Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-1
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I-1
x Hiperstation for Mainframe Servers User Guide
xi
Figures
2-1. Global Recording - Add Requests Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22-2. Global Recording - Monitor Requests Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32-3. APPC Capture Criteria Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32-4. APPC - Script Content Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-72-5. APPC - Script Datasets Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82-6. APPC - Script Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92-7. Global Recording - Monitor Requests Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102-8. Global Recording - Active Sessions Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-112-9. Review Repository - Dataset List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
2-10. Review Repository - Processing Options Screen. . . . . . . . . . . . . . . . . . . . . . . . . . 2-132-11. Script Processing Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-142-12. Review Repository - Session List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152-13. Script Processing Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-162-14. DCIJCL — Sample JCL to Add or Manage Requests. . . . . . . . . . . . . . . . . . . . . . . 2-182-15. SQQFSAMP Member DCIADXL6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212-16. SQQFSAMP Member SCJCL — Sample JCL to Create Scripts . . . . . . . . . . . . . . . 2-442-17. SQQFSAMP Member SCAPPC — Sample Script Creation Parameters . . . . . . . . . 2-462-18. SQQFSAMP Member MCSREPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-512-19. Capture Summary Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-522-20. Sample Repository Merging JCL: SYSPLEX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-533-1. Generate Unattended Statements Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13-2. Generate APPC Unattended Statements Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23-3. APPC Statement Generation Parameters Screen . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33-4. APPC CONTROL Statement Parameters Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33-5. APPC ALLOCATE/ACCEPT Statement Parameters Screen . . . . . . . . . . . . . . . . . . . 3-43-6. APPC ALLOCATE/ACCEPT Connection Parameters Screen . . . . . . . . . . . . . . . . . 3-53-7. APPC ALLOCATE/ACCEPT Documentation Parameters Screen . . . . . . . . . . . . . . 3-53-8. APPC ALLOCATE/ACCEPT Timing Parameters Screen . . . . . . . . . . . . . . . . . . . . . 3-63-9. APPC ALLOCATE/ACCEPT Security-LUW Parameters Screen . . . . . . . . . . . . . . . . 3-7
3-10. SCRIPT Statement Parameters Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-73-11. Company Statement Parameters Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-83-12. CACHE INCLUDE and EXCLUDE Statement Parameters Screen . . . . . . . . . . . . . 3-83-13. Unattended Statement Build Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-93-14. ISPF EDIT Screen Showing Generated Statements . . . . . . . . . . . . . . . . . . . . . . . . 3-103-15. Unattended JCL Build Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-103-16. ISPF EDIT Screen Showing Generated JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-113-17. Generation Restrictions Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-113-18. ISPF EDIT Screen Showing Restricted Generated Statements . . . . . . . . . . . . . . . 3-124-1. APPC Unattended Playback Statement Sequence . . . . . . . . . . . . . . . . . . . . . . . . 4-174-2. Sample Script Using APPC Application Data REXX Variables . . . . . . . . . . . . . . . 4-374-3. Sample Script Containing the APPC_ACTUAL Variable . . . . . . . . . . . . . . . . . . . 4-374-4. Sample Script Containing the APPC_EXPECTED Variable . . . . . . . . . . . . . . . . . 4-384-5. Sample Script Containing the APPC_ACTUAL_LENGTH Variable . . . . . . . . . . . 4-384-6. Sample Script Containing the ACCP_EXPECTED_LENGTH Variable . . . . . . . . . 4-394-7. APPC Summary Report Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-394-8. JCL to Play Back 100 APPC Conversations, All at Once . . . . . . . . . . . . . . . . . . . 4-414-9. JCL to Play Back 100 APPC Conversations, One Started Every 3 Seconds . . . . . 4-41
4-10. JCL to Play Back 100 Different APPC Conversations. . . . . . . . . . . . . . . . . . . . . . 4-424-11. JCL to Play Back One Lengthened APPC Conversation. . . . . . . . . . . . . . . . . . . . 4-424-12. JCL to Play Back Two Related APPC Conversations. . . . . . . . . . . . . . . . . . . . . . . 4-434-13. JCL to Play Back Several APPC Conversations Started in Various Ways . . . . . . . 4-434-14. Recorded REQUEST Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-464-15. Recorded ADDDATA Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-464-16. Recorded PROCESS Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-474-17. REQUEST Script with Hiperstation for Mainframe Servers REXX Variables . . . . 4-484-18. REQUEST Script with Key Sharing Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-49
xii Hiperstation for Mainframe Servers User Guide
4-19. ADDDATA Script with Key Sharing Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-504-20. PROCESS Script with Key Sharing Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-514-21. ADDDATA Script with Key Replacement Logic . . . . . . . . . . . . . . . . . . . . . . . . . . 4-524-22. PROCESS Script with Key Replacement Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-534-23. REQUEST Script with Request Modification Logic . . . . . . . . . . . . . . . . . . . . . . . 4-544-24. APPC Conversation Log for Example Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-564-25. Control Statements to Play Scripts Back Serially . . . . . . . . . . . . . . . . . . . . . . . . . 4-564-26. JCL for the Example Business Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-574-27. Job Log for a Single Thread, Single Iteration Playback . . . . . . . . . . . . . . . . . . . . 4-574-28. Job Log for a Multiple Thread, Single Iteration Playback . . . . . . . . . . . . . . . . . . 4-584-29. Job Log for a Multiple Thread, Multiple Iteration Playback . . . . . . . . . . . . . . . . 4-594-30. Job Log for a Multiple Thread, Multiple Iteration Playback (Continued) . . . . . . 4-594-31. Store a Shared Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-604-32. Retrieve a Shared Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-614-33. Request String Using Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-624-34. Script Being Played Back. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-634-35. Variable Data Read from the Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-634-36. Table Definition Using LOG Keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-644-37. JCL to Merge and Sort Three LOG Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-644-38. Sample Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-655-1. APPC Summary Report Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26-1. Hiperstation for Mainframe Servers Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26-2. Global Recording Requests Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26-3. Global Recording - Monitor TCP/IP Requests Screen. . . . . . . . . . . . . . . . . . . . . . . 6-36-4. TCP/IP Collect Data - Filtering Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36-5. Portion of Screen Filter Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46-6. TCP/IP Data Collect - Output Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56-7. TCP/IP Collect Data - Filtering Screen with IP Address Errors . . . . . . . . . . . . . . . . 6-76-8. TCP/IP Collect Data Filters Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-76-9. Global Recording - Monitor TCP/IP Requests Screen. . . . . . . . . . . . . . . . . . . . . . . 6-8
6-10. Global Recording - Active TCP/IP Sessions Screen. . . . . . . . . . . . . . . . . . . . . . . . . 6-96-11. DCIJCL — Sample JCL to Add or Manage Requests. . . . . . . . . . . . . . . . . . . . . . . 6-116-12. SQQFSAMP member DCIADXTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-146-13. Sample Repository Merging JCL: SYSPLEX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-247-1. Hiperstation for Mainframe Servers Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . 7-27-2. TCP/IP Create Scripts - Filtering Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-27-3. TCP/IP Create Scripts - DB2 Connect Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-47-4. TCP/IP Create Scripts - DB2 Connect Filter Detail Screen . . . . . . . . . . . . . . . . . . . 7-57-5. TCP/IP Create Scripts - IMS Connect Filters Screen . . . . . . . . . . . . . . . . . . . . . . . . 7-67-6. TCP/IP Create Scripts - IMS Connect Filter Detail Screen . . . . . . . . . . . . . . . . . . . 7-77-7. TCP/IP Create Scripts - CTG Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-77-8. TCP/IP Create Scripts - CTG Filter Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-87-9. TCP/IP Create Scripts - ECI Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
7-10. TCP/IP Create Scripts - ECI Filter Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-97-11. TCP/IP Create Scripts - Filtering IP Addresses Screen. . . . . . . . . . . . . . . . . . . . . . 7-117-12. TCP/IP Create Scripts - Grouping Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-127-13. TCP/IP Create Scripts - Input Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-137-14. TCP/IP Create Scripts - Create Options Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . 7-157-15. TCP/IP Create Scripts - Output Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-167-16. TCP/IP Create Scripts - Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-187-17. TCP/IP Create Scripts - Subset Output Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-197-18. TCP/IP Create Scripts - Process Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-207-19. LOCPOS Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-347-20. BRULE Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-357-21. BRULES Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-358-1. TCP/IP Playback - Selection Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18-2. TCP/IP Playback - Datasets Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28-3. TCP/IP Script Dataset List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28-4. TCP/IP Playback - Script Member List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-38-5. TCP/IP Playback - Setup Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-38-6. TCP/IP Playback - Log File Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
Figures xiii
8-7. Environment Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-58-8. Environment - Processing Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-58-9. Environment - Timing Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
8-10. Environment - Connection Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-78-11. Environment - Data Replacement Options Screen . . . . . . . . . . . . . . . . . . . . . . . . 8-88-12. Socket Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-88-13. Socket - Processing Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-98-14. Socket Timing Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-98-15. Socket - Connection Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-108-16. Socket - Data Replacement Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-108-17. Script Socket Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-118-18. Script Processing Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-118-19. Script Connection Options Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-128-20. TCP/IP Playback - Submit Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-128-21. TCP/IP Playback - Save JCL File Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-138-22. TCP/IP Playback - Save Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-148-23. TCP/IP Reporting - Selection Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-158-24. TCP/IP Reporting Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-158-25. TCP/IP - Basic Reports Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-168-26. Custom Report Parameters Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-178-27. Table Report Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-178-28. Form Report Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-188-29. Custom Report Locations Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-189-1. Sample TCP/IP Connection Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-29-2. TCPRUN-Sample TCP/IP Playback JCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-269-3. TCPPBSRT-Sample JCL to Sort Data Collected During Playback . . . . . . . . . . . . . 9-279-4. Playback Error Summary Report (HTML Format) . . . . . . . . . . . . . . . . . . . . . . . . 9-31
10-1. Sample Message Report in Table Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-410-2. Sample Message Report in Form Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-510-3. Sample Reporting Job ESRJCL4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1510-4. HTML Exception Report Mismatch Summary (Top of Report) . . . . . . . . . . . . . 10-1710-5. HTML Exception Report Mismatch Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1910-6. HTML Script Timing Summary Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2010-7. HTML Response Time Summary Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2211-1. Hiperstation Archive Recording Setup Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-212-1. Hiperstation Profile Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-112-2. APPC Record and Script Create Defaults - Record Settings . . . . . . . . . . . . . . . . . 12-212-3. APPC Record and Script Create Defaults - Script Create Settings . . . . . . . . . . . . 12-412-4. Hiperstation Profile Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-712-5. TCP/IP Global Record/Script Create Defaults - Record Settings. . . . . . . . . . . . . . 12-712-6. TCP/IP Global Record/Script Create Defaults - Script Create Settings . . . . . . . . . 12-912-7. TCP/IP Global Record/Script Create Defaults - Dataset Settings . . . . . . . . . . . . 12-1212-8. Hiperstation Profile Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1312-9. Auditing Defaults for TCP/IP Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-14
12-10. Hiperstation Profile Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1512-11. TCP Interactive Playback Defaults Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
D-1. Hiperstation Diagnostics Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1D-2. Customer Support Diagnostic Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-2
xiv Hiperstation for Mainframe Servers User Guide
xv
Tables
4-1. APPC Playback Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-349-1. Playback Sessions for a SOCKETS statement with COUNT(2) REPEAT(3) . . . . . . 9-289-2. Hiperstation for Mainframe Servers Internal Return Codes . . . . . . . . . . . . . . . . 9-2910-1. Contents of System-Level Reporting Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2B-1. Field Names and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1B-2. Valid Values for RequestHeadernnnn, ResponseHeadernnnn,
ExpResponseHeadernnnn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5C-1. TCP/IP Script Create Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
xvi Hiperstation for Mainframe Servers User Guide
xvii
Introduction Intro
Compuware is committed to providing user-friendly documentation in a variety of electronic formats. This section describes the available formats and how to access them, provides an overview of this manual and describes the conventions used within, and describes the resources available to help you.
Accessing Hiperstation DocumentationThe Hiperstation documentation included in the installation package contains Release Notes in HTML format and manuals in Portable Document Format (PDF):
• Release Notes — Provides recent information for the Hiperstation product. In this file, you can quickly access system requirements, technical notes, customer support contact information, and a list of the new features available in the release. The Release Notes may be updated throughout the life cycle of a release with the most current version located on FrontLine for easy access to the latest product information.
• Hiperstation Installation Guide — Provides installation and customization procedures.
• Hiperstation for VTAM User Guide — Explains how to use Hiperstation for VTAM to test 3270 and LU0 applications.
• Hiperstation for WebSphere MQ User Guide— Explains how to use Hiperstation for WebSphere MQ to test WebSphere MQ applications.
• Hiperstation for Mainframe Servers User Guide — Explains how to use Hiperstation for Mainframe Servers to test APPC and TCP/IP applications.
• Hiperstation Auditor User Guide — Explains how to use the Hiperstation Archive Function.
• Hiperstation Automated Testing Vehicle (ATV) Manager User Guide — Explains how to use the Hiperstation ATV Manager to manage your testing environment and test cases.
• Hiperstation Messages and Codes — Explains the messages and codes that Hiperstation produces.
• Hiperstation Scripting Reference — Introduces advanced script editing concepts and provides reference information for technical users.
• Hiperstation Reference Summary — Summarizes the commands used in Hiperstation for VTAM’s Domain Traveler and Session Demo features.
• Master Index — This file contains the combined index entries from all of the Hiperstation manuals provided in PDF format. To use this file, all of the book files and the master index file must be located in the same directory. Open the master index file and click on an index entry. It will open the appropriate book at the desired page.
View and print these files with Adobe Reader. Download a free copy of the latest version of the reader from Adobe’s web site: http://www.adobe.com.
Note: With a few minor exceptions, PDF files comply with the requirements of section 508 of the Rehabilitation Act of 1973. Refer to the Accessibility preface in any of the user guides for information.
xviii Hiperstation for Mainframe Servers User Guide
For your convenience, Compuware also provides the Hiperstation manuals in the following formats:
• Hypertext Markup Language (HTML)
• BookManager Softcopy (BOO, BKI, BKS)
Access these formats on FrontLine, Compuware’s Customer Support Web site at http://frontline.compuware.com.
1. Log-in.
2. Select the desired product.
3. Click the Documentation link on the left selection bar.
4. Select the desired release. FrontLine presents a documentation index containing links to each of the product’s manuals in all of the available formats.
HTML Files
View HTML files with any standard Web browser. Simply click the HTML link on the selected FrontLine documentation page.
Note: As you review the HTML content, you may encounter the known issue regarding screens and other graphic figures in which the image may be cropped along the left or bottom edge.
BookManager Files
FrontLine provides three types of BookManager files:
• Books (.BOO) — The Hiperstation manuals provided with this release of the product.
• Bookshelf (.BKS) — A bookshelf providing links to all of the Hiperstation books.
• Bookindex (.BKI) — A file that facilitates bookshelf-level searches in BookManager READ, (z/OS platform). Softcopy Reader (PC platform) does not use or recognize this file.
The way you access and use these files depends on the platform on which you intend to use them. This section provides access and use instructions for PC and z/OS platforms. It also describes some known issues that you may encounter on either platform.
PC Access
View BookManager files on the PC with IBM Softcopy Reader. Download a free copy of the reader from IBM’s Web site: http://www.ibm.com.
Note: Several known formatting issues exist with the PC readers. For best results, view the BookManager files on the mainframe. See “Mainframe Access” on page xix for more information.
If the Softcopy Reader is installed, you can view the book files (.BOO) by clicking the BkMgr link on the selected FrontLine Documentation page. However, this method requires logging onto FrontLine each time you need to access a book. Alternatively, you can download all of the .BKS and .BOO files. Whenever you need to access a manual, simply open the bookshelf and double-click the manual title.
Make these files available to the user groups that have PCs by copying them to a shared location on the network.
Introduction xix
Mainframe Access
View BookManager files on the mainframe with IBM BookManager READ.
To make the files available on the mainframe:
1. Download all of the BookManager files.
2. Transfer the bookshelf file as text. Replace the PC file extension with the host file extension BKSHELF.
3. Transfer the book and book index files (BOO and BKI) as binary, fixed block files with a logical record length (LRECL) of 4096. Replace the PC file extensions with the host file extensions BOOK and BKINDEX respectively.
Known-Issues
While using BookManager files on either platform, you may encounter the following known issues:
• Cross-references may have formatting information in plain text after the reference. For example:
"Chapter 2, 'Hiperstation Installation Overview' Title_Chapter[xd3 Default Font".
Also, some or all of the cross-reference text may be missing.
• Screens may be too close to the figure captions above them.
• Screens may not have graphic borders.
• Numbered text within a table may not be formatted properly. Text may be right-justified in cells that should be left-justified.
If you are using the Softcopy Reader on the PC, you may encounter the following additional formatting issues:
• Note text may be preceded by a bullet instead of the word, Note and the first letter may appear in bold text.
• In the navigation frame, the book's Index may appear as a sub-topic under the last chapter.
• Some cross-references may not be hyperlinked or may be missing entirely.
• Text, steps in numbered procedures, and bullets may be improperly indented.
If you are working on a PC, consider using the PDF or HTML files instead.
Using this ManualThis section describes the:
• contents of this manual• notation conventions used throughout the manual• command syntax and syntax diagrams
Manual Contents
This manual describes how to use Hiperstation for Mainframe Servers. It contains the following subjects:
xx Hiperstation for Mainframe Servers User Guide
• Chapter 1, “Hiperstation for Mainframe Servers Overview” provides an overview of the product and testing process.
• Chapter 2, “APPC Global Recording and Scripts” explains how to capture APPC traffic, monitior and modify recording requests, and generate testing scripts.
• Chapter 3, “APPC Unattended Processing” explains how to use Unattended Processing to generate unattended playback statements and JCL for batch testing APPC applications.
• Chapter 4, “Unattended Playback of APPC Scripts” describes how to play back APPC scripts in batch including explanation of script tags, unattended mode statements, and sample JCL.
• Chapter 5, “APPC Reporting” describes how to generate APPC reports using unattended processing statements and keywords, along with examples of the reports.
• Chapter 6, “TCP/IP Global Recording” explains how to create a recording request and how to monitor and maintain existing requests.
• Chapter 7, “TCP/IP Scripts and Subset Repositories” explains how to create scripts and subset repositories from a capture repository, how to edit scripts, and how to review and edit the TCP/IP message data.
• Chapter 8, “TCP/IP Interactive Playback” describes how to play back your scripts interactively.
• Chapter 9, “TCP/IP Unattended Playback” describes how to set up unattended playback of TCP/IP data, including script tags.
• Chapter 10, “TCP/IP Reporting” explains how to create TCP/IP testing reports.
• Chapter 11, “Archive Functions” describes the Archive function.
• Chapter 12, “Hiperstation for Mainframe Servers Profile Defaults” provides information on how to edit your Hiperstation for Mainframe Servers profile settings.
• Appendix A, “TCP/IP Data Collection and Reporting Tables” lists the TCP/IP fields that can be collected and reported.
• Appendix B, “TCP/IP Report Field Definitions” defines fields that appear in TCP/IP reports.
• Appendix C, “TCP Script Create Parameters” provides a list of the TCP script create parameters with a short description of the parameter.
• Appendix D, “Customer Support Diagnostics” explains how to run a Customer Support Diagnostic Report that lists all PTFs applied to your installation.
• “Glossary” provides a description of terms used in this guide.
Notation Conventions
This document uses the following notations to describe Hiperstation screens and the information you enter on those screens:
• Technical revisions made to this document are indicated by revision bars in the left margin, as shown here.
• Sample screens generally show only the information appropriate to the accompanying text, for example:
ZOOM:PF23 ---------------------- Hiperstation ------------------- LINE 1 OF 24 COMMAND ===> record SCROLL ===> HALF Record OFF Play OFF Journal OFF Compare Log OFF autoDoc OFF ***USR2312 WELCOME TO CICS/MVS *** 10:11:42
Introduction xxi
• Blank lines or standard footings, as shown below, are usually omitted from screen illustrations.
Press ENTER to begin recording, Use END to cancel setup.
• Information you enter is printed in boldface.
• Words defined within paragraphs are italicized.
• The phrase “select an option” refers to typing a slash next to one of the presented options and pressing Enter.
Command Syntax
Hiperstation uses statements and commands that you will learn about later. This section describes text conventions used in statement and command descriptions. It also explains how to read syntax diagrams.
• Keywords are shown in UPPERCASE letters. Enter keywords and special characters as shown. If a command or statement name can be abbreviated, the description shows only the abbreviation in uppercase letters.
Find string [NEXT|PREV|ALL]
The uppercase F in the command FIND means that you can enter the FIND command either as FIND or F.
• Variables and generic descriptions of parameter values are shown in lowercase letters.
• Vertical bars (|) are separators between mutually exclusive options.
• Brackets ([ ]) indicate optional parameters. All parameters not enclosed in brackets are required.
• Ellipses (…) indicate that the value can be repeated.
Reading Syntax Diagrams
Syntax diagrams define primary command syntax.
A parameter is either a keyword or a variable.
All KEYWORDs are shown in uppercase characters and must be spelled exactly as shown. You cannot substitute another value. If any part of a KEYWORD is shown in lowercase characters, that part is optional.
Variables are user-specified values and are printed in lowercase italics. For example, dataset-name indicates you are to substitute a value.
The syntax for commands is described in diagrams that help you visualize parameter use. The following example shows a command and a parameter:
Read the diagrams from left to right and from top to bottom. These symbols help you follow the path of the syntax:
indicates the beginning of a statement.
xxii Hiperstation for Mainframe Servers User Guide
Required parameters appear on the horizontal line (the main path). Optional parameters appear below the main path. Default parameters appear above the main path and are optional. The command executes the same regardless of whether the default parameter is included.
Vertically stacked parameters are mutually exclusive. If you must choose a parameter, one item of the stack appears on the main path. If the parameters are optional, the entire stack appears below the main path. If a parameter in a stack is the default, it appears above the main path.
If the same parameters are used with several commands, their syntax may be documented in a separate diagram. In the command syntax, these common parameters are indicated with separators before and after the parameter name.
An arrow returning to the left indicates a repeatable item. If the arrow contains a comma, separate the repeated items with a comma.
AccessibilityIn accordance with section 508 of the Rehabilitation Act of 1973, Compuware has committed to making its products and services easier to use for everyone including people with disabilities.
Hiperstation is a mainframe application that runs on IBM’s OS/390 and z/OS operating systems. It has an ISPF interface that is accessed with IBM 327x-type terminals or with 3270 terminal emulator software. Since the mainframe environment offers few accessibility features, Compuware has focused its attention, with regard to accessibility, on 3270 terminal emulator software running on personal computers (PCs) with Microsoft Windows 2000 or more current. Hiperstation supports, with a few exceptions, Microsoft
indicates the statement is continued on the next line.
indicates the statement is continued from the previous line.
indicates the end of a statement.
Introduction xxiii
Windows accessibility features and Window-based Assistive Technology (AT) software and devices, such as Braille devices, screen readers, magnifiers, etc.
Note: Hiperstation is intended for use by mainframe software developers, programmers, and testers. Much of the input and output used or produced by Hiperstation, such as Job Control Language (JCL) and hexadecimal contents or dumps of memory, are not easily understood by the general public. Unfortunately, as in the case of hexadecimal dumps, data in these formats can be confusing to screen readers and therefore confusing to the people who use them. Effective use of this application requires the specialized knowledge of a mainframe systems software developer or programmer.
Hiperstation accessibility was evaluated using:
• Freedom Scientifics’ JAWS screen reader
• Attachmate Corporation’s myExtra Presentation Services tn3270 emulator
• Microsoft’s Windows accessibility features
• Adobe Reader using the “Read Out Loud” function
This evaluation not only identified accessibility exceptions, but revealed emulator and screen reader compatibility issues that in some cases can be remedied through appropriate configuration.
Installing Windows Accessibility Features
Microsoft Windows operating systems offer several accessibility features to aid individuals who have difficulty typing or using a mouse, who are blind or have low vision, or who are deaf or are hard-of-hearing. Install these features during setup or later using the Windows installation disks. Refer to the “accessibility” topics in the Windows Help system for information on installing and using these features. Visit the Microsoft Web site, http://www.microsoft.com/enable, for additional information and tutorials.
Selecting Font and Font Size
Microsoft Windows and emulator software packages offer font and font size settings to accommodate users with low vision. The emulator software’s tool bars and dialog boxes typically use the font specified in the operating system, while the terminal presentation uses the font and font size specified in the emulator. To change the font or font size:
• Presented on the toolbars and dialog boxes, refer to the Windows Help system.
• Presented in the terminal window, refer to the emulator’s documentation or Help.
Some screen readers recommend certain fonts and font sizes for compatibility. For example, Freedom Scientifics recommends setting the font to a common or “plain” font such as Lucida, Courier, or Times New Roman, and setting the font size to 10 points or smaller. Refer to the screen reader’s documentation or Help for these recommendations.
Changing Color and Contrast
Color and contrast settings can assist users with low vision. ISPF and most emulator software packages offer color and contrast settings. If you are accessing Hiperstation with a terminal, use ISPF settings. Otherwise, adjust the color and contrast in the emulator software. Refer to ISPF Help or the emulator’s documentation or Help.
xxiv Hiperstation for Mainframe Servers User Guide
Setting Cursor Blink Rate
The blink rate of the cursor can affect users with photosensitive epilepsy. Additionally, some screen readers require a specific blink rate. Some readers automatically adjust the blink rate while others expect you to adjust the rate. Refer to:
• The Microsoft Windows Help to find out how to set the cursor blink rate.
• The screen reader’s documentation or Help to find out the recommended blink rate.
Using Keyboard Shortcuts
Keyboard access to application functions support users who cannot use a mouse.
Microsoft Windows provides keyboard access to all functions within the operating system, such as:
• Displaying or hiding the Windows Start Menu
• Showing the Desktop
• Minimizing all windows
• Searching for files
• Accessing the help system
• Controlling the behavior of the Windows accessibility features, for example, toggling the listening status to the microphone, or cycling focus backward and forward.
Most Windows-based applications also provide keyboard access to their functions. The combination of keys required to execute a given function is called a keyboard shortcut. Refer to the “Keyboard Shortcuts” topics in the Windows Help system for a complete list of Windows shortcuts. For a list of the shortcuts that are available in the emulator software or any third-party accessibility tool, such as the JAWS screen reader, refer to the software’s documentation or Help.
Accessibility Exceptions Work Arounds
During Hiperstation accessibility evaluation, some exceptions were encountered where some accessibility features or AT were not fully supported. The causes of and solutions for these exceptions are currently under investigation by Compuware Corporation.
Known Exceptions
Accessibility exceptions include:
• Function Key (F Key) information at the bottom of the screen is not read by the screen reader on some screens. This is believed to be caused by an external interface. See “Solutions” for a viable work-around.
• Some system error and warning messages are not read by the screen reader when issued. Believed to be caused by an external interface. See “Solutions” for a viable work-around.
• Some pop-up dialog boxes or windows do not capture exclusive focus and are not read correctly by the screen reader. This is believed to be caused by an external interface. No known solution is currently available.
• System error and warning messages do not capture visual focus for the screen magnifier. This is believed to be caused by an external interface. No known solution is currently available.
• Some entry and display fields lack individual labels. When entry fields are accessed using the Tab key, the entire individual line is read.
Introduction xxv
• Current Web-based reports are not easily navigated using the keyboard and lack table element coordinate tags. Additionally, some of these reports contain color-coded elements — for example, the color of some elements conveys meaning.
Solutions
When the screen reader fails to read the F Key information upon entry to a new screen, do one of the following:
• Use the arrow keys to move the cursor down to the lines with the F Key information. The screen reader reads each line as the cursor is placed on it.
• Press the Page Up key for the screen reader to reread the entire screen.
When the screen reader fails to read an error or warning message, an audio alert occurs if this feature is enabled on your system. Press the Up key to place the cursor on the line containing the error message, usually on the top or title line. The screen reader reads the line and its error message individually.
Getting Help Compuware provides a variety of support resources to make it easy for you to find the information you need.
FrontLine Support Web Site
You can access online information for Compuware products via our FrontLine support site at http://frontline.compuware.com.
FrontLine provides access to critical information about your Compuware products. You can review frequently asked questions, read or download documentation, access product fixes, or e-mail your questions or comments. The first time you access FrontLine, you are required to register and obtain a password. Registration is free.
Compuware now offers User Communities, online forums to collaborate, network, and exchange best practices with other Compuware solution users worldwide. Go to http://groups.compuware.com to join.
Contacting Customer Support
If you have difficulty with Hiperstation, refer to the information in the appropriate user’s guide for help or consult with the Hiperstation technical representative at your site. If the problem persists, please obtain the following information before calling Compuware:
1. The release number of the product being used
2. The release number of the transaction processing utility (such as CICS, IMS/DC, or ISPF) being used
3. The operating system being used to help determine operating system dependencies
4. If an abend occurs, note the displacement and the module in which it occurs, and if possible, obtain a copy of the system dump.
5. The sequence of issued transactions and/or commands that resulted in the problem and the data type involved.
Phone• USA and Canada: 1-800-538-7822 or 1-313-227-5444.
xxvi Hiperstation for Mainframe Servers User Guide
• All other countries: Contact your local Compuware office. Contact information is available at http://frontline.compuware.com.
Web
You can report issues via the Report and Track Calls tab on the FrontLine home page.
Note: Please report all high-priority issues by phone.
MailHiperstation for Mainframe Servers Customer Support Compuware Corporation One Campus Martius Detroit, MI 48226-5099
Corporate Web Site
To access Compuware’s site on the Web, go to http://www.compuware.com.
The Compuware site provides a variety of product and support information.
Note: Hiperstation provides a report that may help Customer Support diagnose an issue. See Appendix D, “Customer Support Diagnostics” for details. Although it is not required, generating the report before calling may expedite diagnosis.
1-1
Chapter 1.
1Hiperstation for Mainframe Servers Overview Chap 1Hiperstation for Mainframe Servers is a powerful testing tool used to perform a variety of functions. For example:
• Application Developers can unit test new features.
• Quality Assurance personnel can perform system, integration, and regression testing to validate application functions.
• System Programmers can verify database availability for client applications.
• Database Administrators can test database modifications.
• System Security or Audit personnel can record all activity occurring on the system for audit purposes.
Hiperstation for Mainframe Servers offers features for testing SNA and TCP/IP applications. These features support a variety of protocols. The SNA options support 3270, LU0, and APPC. The TCP/IP options support HTTP, HTTPS, ECI, CTG, DB2C, IMSC, and generic TCP/IP.
Applications testing involves:
• Recording activity — Capture all application traffic or record specific activities based on the criteria you specify.
Note: A good practice is to make sure that your browser’s cache is empty before generating HTTP and/or HTTPS traffic for Global Recording to capture, or alternatively, configure your browser to check the Web page for a new version on every visit.
• Creating scripts from recorded activity — Filter captured activity to generate scripts for various types of testing. Scripts contain formatted information that you can read and Hiperstation for Mainframe Servers can process. Add REXX logic to:
– Create dynamic scripts that facilitate data-driven testing. For example, create a script that performs an account inquiry, and then add REXX logic that reads hundreds of account numbers from an external file and performs the inquiry on each account.
– Create a smart script that modifies application flow based on message content. For example, add logic to an account inquiry script to terminate Hiperstation for Mainframe Servers playback if the inquiry returns a “system busy” message.
• Playing back scripts — Play back scripts against the application being tested to compare recorded application responses to live application responses or to ensure that the application can support the expected volume of traffic. You can also use the playback function to build testing baselines or analyze script contents for comparison reporting.
• Reporting — Generate basic, predefined reports, or build custom reports, containing the information you specify, presented the way you indicate. Generate TEXT, CSV, or HTML reports in table or form layout.
Subsequent chapters within this manual detail each of these tasks.
1-2 Hiperstation for Mainframe Servers User Guide
2-1
Chapter 2.
2APPC Global Recording and Scripts Chap 2Testing with Hiperstation for Mainframe Servers involves capturing activity and generating testing scripts from the captured activity. Perform these tasks with the following Hiperstation for Mainframe Servers options:
• Monitor Requests — Create, manage, and monitor Global Recording requests. Record all of the APPC, 3270, or LU0 traffic on the system or specify the logical unit names, network IDs, logmodes, TP names, terminals, applications, or user IDs to record. Set up the recording request to initiate script creation when the recording request ends or suspend script creation and generate scripts later.
• Review Repository — View a list of the sessions captured in a given recording. Generate scripts from selected sessions or for entire capture repositories. Save the specified script creation criteria in the affiliated recording request or discard it after script creation.
• Global Recording Manager — Build lists of applications, terminals, and user IDs to include or exclude from 3270/LU0 recording. Global Recording Manager Lists provide greater flexibility in defining Global Recording requests.
Hiperstation for Mainframe Servers also offers a batch interface to Global Recording. Use it along with a job scheduler to automate recording initiation and termination, as well as script creation. For example, create a job that starts recording, a job that stops recording, and a job that generates scripts. Then schedule them to run every day at the appropriate times.
You can use the interfaces together. For example,
• Schedule request management jobs to capture activity for the same period of time each day. Then use the Review Repository option to select specific sessions for scripting.
• Use the online interface to create Global Recording Manager lists. Then use the lists to govern automated recordings.
Additionally, Hiperstation for Mainframe Servers provides the following features to help you with script creation:
• The Capture Segment Summary report helps you identify the information stored in your capture repositories. It indicates when recording began and ended for each segment of the specified repositories. Use it to select the appropriate segments for script creation. Review the report with a file browsing tool such as ISPF Browse or import it into a spreadsheet or database for easy manipulation.
• The Capture Repository Merging Utility allows you to merge related repositories to minimize script creation time. For example, capturing activity across multiple systems (LPARs), results in at least one repository per system. Rather than generating scripts from each repository, merge them first then generate scripts.
Note: Hiperstation for Mainframe Servers supports disabling of User Key CSA allocation. See the IBM publication, MVS Initialization and Tuning Reference, for more information.
2-2 Hiperstation for Mainframe Servers User Guide
Creating an APPC Global Recording RequestGlobal Recording writes captured activity to a specified dataset or range of datasets called a repository. Testing scripts are generated from the capture repository. If your installer enabled Autostart Script Creation, Global Recording initiates script creation at the end of recording. However, you can suspend script creation and initiate it later using the Review Repository option (page 2-12) or the batch interface (page 2-43). For example, you may want to capture an entire day’s activity, and then generate scripts in the evening when more system resources are available.
To capture activity and potentially generate scripts, create a recording request. If you specify a time-frame for the request, it becomes active at the designated start time. If you do not specify a time-frame, it becomes active immediately. Capture begins when all of the criteria for an active request are met.
Note: The Global Recording started task must be running before the start of the VTAM sessions that you need to record, that is, before the BIND is issued by the communicating applications (for example, CICS or IMS). Global Recording then captures the APPC conversations that begin after the recording request is active. An APPC conversation is the activity that occurs between the ALLOCATE and DEALLOCATE.
Depending on the type of recording request, different Monitor Requests screens appear. For 3270 or LU0 requests, it presents the same screens as the Monitor Requests option in Hiperstation for VTAM. If you need to create a 3270 or LU0 request, refer to the Hiperstation for VTAM User Guide.
This section explains how to use the Monitor Requests option to create an APPC recording request. You can also create and manage recording requests with batch jobs. See “Using the Global Recording Batch Interface” on page 2-17.
To create an APPC Global Recording request:
1. On the Option line of the Hiperstation - Product Menu, type 2 and press Enter.
2. On the Option line of the Hiperstation for Mainframe Servers Main Menu, type 1 and press Enter.
3. If there are no existing requests, the “Global Recording - Add Requests Screen” appears (Figure 2-1). The Type of request to add field defaults to option 1. Type 2 to select APPC and press Enter.
Figure 2-1. Global Recording - Add Requests Screen
Hiperstation -------- Global Recording - Add Requests --------------------- Command ===> Press ENTER to continue, or END to return. ***************************************************************************** * * * No Global Recording Requests were found for your userid. * * * ***************************************************************************** Type of request to add: 2 1. 3270 2. APPC
Notes:
a. The 3270 option presents the same screens as Hiperstation for VTAM. Refer to the Hiperstation for VTAM User Guide for more information.
APPC Global Recording and Scripts 2-3
b. If TN3270 traffic at your site uses its own address space, separate from TCP/IP, use the 3270 option to capture TN3270 activity. Otherwise, use the Monitor TCP/IP Requests option. See “TCP/IP Global Recording” on page 6-1. If you are unsure of the address space configuration, consult your installer.
Otherwise, the “Global Recording - Monitor Requests Screen” appears (Figure 2-2). It shows all of the existing 3270/LU0 and APPC requests that you created. Active requests are highlighted.
Figure 2-2. Global Recording - Monitor Requests Screen
Hiperstation --------- Global Recording - Monitor Requests -------- Row 1 of 1 Command ===> Scroll ===> PAGE Line commands are: (C)ancel, (F)orce, (P)Stop, (R)estart, (D)isable, (S)elect, (U)pdate, (1)Add 3270, (2)Add APPC, or (9)Switch repositories LU Side-A/ Side-B/ Repository S Type Applid Terminal Userid Dataset Users - ---- -------- -------- -------- ------------------------------------- ---- APPC VAP1* VAS4* * USER2312.APPC.REPOS 0 ******************************* BOTTOM OF DATA ********************************
4. In the first request in the S (select) column, type 2 to Add an APPC request and press Enter. The “APPC Capture Criteria Screen” appears (Figure 2-3).
Figure 2-3. APPC Capture Criteria Screen
Hiperstation --------------- APPC - Capture Criteria ------------------------- Command ==> Press ENTER to continue, or PF1 for help, or enter CANCEL to exit. Identify which APPC conversations to record: Netids: (Optional) Side A LU . * (Logical unit name or *) Side A Netid . . XXXXXXXX Side B LU . H40AC* (Logical unit name or *) Side B Netid . . Logmode . . LU62B01 (VTAM logmode name or *) Userid . . * (Userid or *) TP name . . HH : MM : SS MM / DD / YY Start Time . . . 00 : 00 : 00 Start Date . . . 00 / 00 / 00 End Time . . . . 00 : 00 : 00 End Date . . . . 00 / 00 / 00 Repository Dataset . . . 'USER2312.APPC.REPOS' First and last number. . (If wildcard in dataset) Recording options: (Enter "/" to select) Suspend script creation / Normal event notification Re-use repositories / Error event notification FORCE request at 'End Time'
5. Enter the Side A LU and Side B LU. These are the VTAM logical unit (LU) names of the partners that make up the APPC conversations that you need to record. Both fields require one of the following:
– A specific LU name.
– An asterisk (*) to select all LUs. Leaving this field blank also selects all LUs.
– An LU prefix followed by an asterisk to select a group of LUs. For example, VAP1* selects all LUs beginning with VAP1.
If you supply a Side A LU but no Side B LU, or the reverse, all conversations involving the specified LU are recorded. This field holds eight characters.
2-4 Hiperstation for Mainframe Servers User Guide
6. Enter the Side A Netid and Side B Netid. These are the VTAM Network IDs for the Side A LU and Side B LU partners. Use these fields to restrict capture to only the APPC conversations on specific VTAM networks. Both fields require one of the following:
– A specific network ID.
– An asterisk (*) to select all networks. Leaving this field blank also selects all networks.
– A network ID prefix followed by an asterisk to select a group of networks. For example, US* selects all networks beginning with US.
This field holds eight characters.
7. Enter the Logmode (VTAM logon mode name) used by the conversations to be recorded. To specify a range of similar logmodes, use the asterisk (*) wildcard. For example, SNAS* selects all logmode names beginning with SNAS. This field holds eight characters. Leave Logmode empty if you do not want to restrict recording to a specific logmode.
Note: In flight conversation (conversation without VTAM bind) will not be able to filter for logmode.
8. Enter the user sign on ID associated with the conversation to be recorded. Enter one of the following:
– A specific user ID.
– An asterisk (*) to select all users. Leaving the field blank also selects all users.
– A user ID prefix followed by an asterisk to select a group of users. For example, USR* selects all user IDs beginning with USR.
This field holds eight characters.
9. Enter the TPName (transaction program name) associated with the conversations to be recorded. Enclose TP Names that contain spaces in single quotation marks. If the TP name contains non-printable characters, supply it in hexadecimal notation, enclosed in single quotation marks, and prefixed with the letter X (for example, X'0EC1D7C9D5C70F’). This field holds 64 characters. Leave it empty if you do not want to restrict recording to a specific TP name.
10. Enter the start and end date and time. If you provide a start time, a start date is required. If you provide an end time, an end date is required. If you supply a start date, but accept all zeros for the start time, the request activates at midnight at the beginning of the start date.
– To activate the request immediately, accept the default value of all zeros in both the Start Time and Start Date fields.
– To activate or deactivate the request at a specific time, enter start and end times and dates:
• Enter a two-digit hour based on a 24-hour clock. • Enter either a two-digit minute, or press Tab to accept 00. • Enter either a two-digit second, or press Tab to accept 00.• Enter a two-digit month. • Enter a two-digit day. • Enter a two-digit year.
– To keep the request active until you STOP, FORCE, or CANCEL it, accept the default value of all zeros for both the End Time and End Date fields.
Note: If you select the FORCE request at ‘End Time’ option under Recording Options, an End Time is required.
11. In the Repository Dataset field, enter the name of the dataset to use for storing captured information. To create a segmented repository, use the following wildcard
APPC Global Recording and Scripts 2-5
characters in the dataset name field and define a range with the First and last number fields:
– Asterisk (*): Inserts an incremental value into the dataset name qualifier the asterisk appears in. This wildcard pads the incremental value with enough zeros to ensure an eight character qualifier. For example, USER.APPC.REC* with first=1 and last=3 creates capture repositories:
USER.APPC.REC00001 USER.APPC.REC00002 USER.APPC.REC00003
– Question mark (?): Inserts the incremental value into the dataset name qualifier where the question marks appear. Enter at least one question mark for each digit of the greatest value in the range fields. For example, USER.APPC.REC?? with first=9 and last=11 creates capture repositories:
USER.APPC.REC09 USER.APPC.REC10 USER.APPC.REC11
Note: Begin each segment of the dataset name with an alpha character (A-Z) or @#$, including segments with wildcard characters.
12. Enter a beginning and ending value in the First and Last number fields to define the range of numbers if you specified wildcard characters in the Repository Dataset field.
If you did not use wild card characters in the Repository Dataset field, leave these fields blank and go to the next step.
13. Type a slash to select the desired recording options:
– Suspend script creation controls automatic script creation. Select this field to prevent script creation at the end of the recording request. If you leave this field blank you will be guided through the script creation criteria screens prior to your capture request being activated. This will also cause automatic script creation to execute when your capture request is stopped.
– Normal event notification sends all recording request status and error messages to your TSO session. This option is selected by default. If you are recording a large number of sessions, consider disabling this option to reduce the number of messages you receive.
– Re-use repositories applies to segmented repositories only. It causes Global Recording to continue capturing activity after the repository segments are full. After the last segment fills, it begins writing to the first segment again, replacing the oldest captured activity with the newest. If this option is not selected, recording terminates after the last segment is full.
– Error event notification sends only the error messages associated with the request to your TSO session. This option is selected by default. If you are recording a large number of sessions, consider selecting this option and disabling Normal event notification to minimize the number of messages you receive.
Note: Normal event notification sends all messages, including error messages, to your TSO session. If Normal event notification is selected, Global Recording ignores the Error event notification option. To prevent receiving messages altogether, clear both Normal event notification and Error event notification.
– FORCE request at ‘End Time’, issues a FORCE command at the end time specified in the request. FORCE terminates recording of all sessions including in-flight sessions. Script creation begins immediately, unless the Suspend script
2-6 Hiperstation for Mainframe Servers User Guide
creation option is selected. Be aware that you may lose buffered data, resulting in partially recorded sessions.
If you do not select this option, Global Recording issues a STOP command at the request’s specified end time. It stops recording new sessions but continues to record any active sessions. After all in-flight sessions end, recording terminates and script creation begins unless the Suspend script creation option is selected. Although this ensures complete session captures, it may delay script creation.
14. Press Enter to continue. If you specified an existing dataset in the request, the Capture Criteria - Output Options prompt appears.
15. Type 1 to overwrite the existing data (choose this option only if you do not need to retain any data that might exist in the specified dataset) or type 2 to append the existing data and press Enter.
Note: The dataset is overwritten when Global Recording captures and processes activity that matches the request criteria. If no activity matches, the dataset is not overwritten.
If the dataset you specified does not exist, the Allocate Dataset screen appears. Generally, the default parameters are appropriate, but you can modify them as necessary. Press Enter to continue.
If you selected Suspend script creation, request creation is complete. Depending on the request options, your terminal may display messages associated with your request.
16. Press Enter to clear any messages your terminal displays. (You may need to press Enter several times.) After you clear all of the messages, the Monitor Requests screen appears. See “Monitoring and Managing Existing Requests” on page 2-10.
If you did not select Suspend script creation, the “APPC - Script Content Screen” appears (Figure 2-4). See the next section, “Define Script Creation Criteria”.
Define Script Creation Criteria
An APPC script contains all APPC verbs issued by both sides of a single APPC conversation. Some conversations may contain only two verbs: ALLOCATE and DEALLOCATE. Others may contain thousands of verbs.
Define script creation criteria with a series of screens that can be accessed when you create or update a recording request or when you generate scripts with the Review Repository option (page 2-12).
Note: You can also use the batch interface to create scripts (page 2-43).
To define script creation criteria:
1. Access the “APPC - Script Content Screen” (Figure 2-4) using one of the following:
– Monitor Requests option, while creating or updating a recording request. This screen appears after you define capture criteria, if you do not select the Suspend script creation option.
– Review Repository option, while generating scripts. This screen appears if the recording request affiliated with the selected repository does not contain script creation criteria or if you select the Review script create criteria option.
APPC Global Recording and Scripts 2-7
Figure 2-4. APPC - Script Content Screen
Hiperstation ------------------ APPC - Script Content ------------------------- Command ==> Press ENTER to continue, or PF1 for help, or enter CANCEL to exit. Where should details be stored: (Enter number to select) 1 1. Merged into the script 2. Separate from the script, inbound and outbound together 3. Separate from the script, inbound and outbound split What should be recorded: (Enter "/" to select) / Conversation log / Script / Details Dataset processing options: (Enter "/" to select) Replace existing conversation log or members Y Replace existing script members Replace existing detail members
2. Specify where to store the detail data associated with the captured APPC verbs. Storing details in separate files may ease browsing, editing, and managing scripts and detail data. Select one of the following options:
– 1 merges all details into the scripts. This option produces one PDSE member for each script.
– 2 separates the details from the scripts. This option creates two PDSE members for each script: one containing all of the detail data, and one containing the APPC verbs with links to the associated detail.
– 3 separates the inbound and outbound details from each other and from the script. This option creates three PDSE members for each script: one containing the APPC verbs with links to the associated detail, one containing the outbound details, and one containing the inbound details.
When you enter a number, the cursor automatically moves to the Conversation Log option in the next block of fields.
3. Specify which items to generate by typing a slash (/) in the selection field next to the item.
– Conversation Log — A report of each captured APPC conversation containing statements that describe the connections between TPs. Use this report as the input for an unattended playback job. See Chapter 4, “Unattended Playback of APPC Scripts”.
– Script — The APPC verbs from a single conversation. Scripts may also contain the detail data associated with the verbs, depending on the selection in the previous field. Hiperstation for Mainframe Servers generates one script for each captured conversation.
– Details — The inbound and outbound data associated with the captured APPC verbs.
4. Specify which Dataset processing options (dataset members), if any, to overwrite. To replace the conversation log member, script members, or detail data members, type a slash (/) in the selection field next to the applicable options:
– Replace existing conversation log or members– Replace existing script members– Replace existing detail members
5. Press Enter. The “APPC - Script Datasets Screen” appears (Figure 2-5).
2-8 Hiperstation for Mainframe Servers User Guide
Figure 2-5. APPC - Script Datasets Screen
Hiperstation ---------------- APPC - Script Datasets -------------------------- Command ==> Press ENTER to continue, or PF1 for help, or enter CANCEL to exit. Script Datasets: Conversation log: * Prefix: Suffix: 0000000 Script: . . . . * Prefix: Suffix: 0000000 Combined detail: Prefix: Suffix: 0000000 DDname: Outbound detail: Prefix: Suffix: 0000000 DDname: Inbound detail: Prefix: Suffix: 0000000 DDname: Supply dataset names, member name prefixes, and member name suffixes to identify where the recorded data should be stored. Rows marked with * are required because of options you selected on the previous panel.
The fields containing an asterisk (*) are required. The asterisks appear based on the choices you made on the previous screen.
6. Enter the Script Dataset names for the fields containing an asterisk. These datasets are the sequential dataset or PDS(E) that will contain the given item. Enter up to 46 characters. Do not include a member name. If you supply a partially qualified dataset name, Global Recording automatically prefixes it with your TSO prefix or user ID depending on the prefix setting in your TSO profile.
Note: The Conversation Log may be written to a sequential or partitioned dataset. All other items must be written to PDS or PDSE.
Each dataset name field is followed by a Prefix and a Suffix field to supply member naming information for the given item. The Combined detail, Outbound detail, and Inbound detail dataset name fields present an additional field, DDname, after the Suffix field, to supply verb-detail linking information.
– Prefix is a one- to six-character prefix that, in conjunction with the member suffix, forms an eight character member name.
– Suffix is a numeric value that, in conjunction with the member prefix, forms an eight-character member name. Hiperstation for Mainframe Servers increments this value to create new members, for example, each time it creates a new script. It also increments this value if the specified member already exists and you did not elect to replace it.
• If you enter a suffix that is too short, Hiperstation for Mainframe Servers pads the suffix with zeros to the left. For example, if the prefix is OES and the suffix is 10, the first script member name is OES00010, and the next member is OES00011.
• If you enter a suffix that is too long, Hiperstation for Mainframe Servers truncates the digits on the left. For example, if you enter SCRIPT for the prefix and 1234 for the suffix, the first script member is SCRIPT34, and the next member is SCRIPT35.
This field accepts up to seven digits.
– DDname is a data definition name that links the APPC verbs with the associated detail data when the script and details are stored separately. Hiperstation for Mainframe Servers uses this name to locate the appropriate detail data during playback.
APPC Global Recording and Scripts 2-9
A dataset allocation screen appears for each specified dataset that does not exist. Generally, the default values are appropriate. However, you can override any or all values if desired.
7. Press Enter to allocate the dataset. If additional datasets need to be allocated, the next allocation screen appears.
If all of the specified datasets exist, or after all of the new datasets are allocated, the “APPC - Script Options Screen” appears (Figure 2-6).
Figure 2-6. APPC - Script Options Screen
Hiperstation ------------------ APPC - Script Options ------------------------- Command ==> Press ENTER to continue, or PF1 for help, or enter CANCEL to exit. Script options: (Enter "/" to select) Suppress time stamps in script Write script tags in short CPIC format Write all PIU traffic as script comments Include SNA service transactions (logmodes: SNASVCMG, CPSVCMG, CPSVRMGR) Description . . . APPC Test1 scripts
8. The cursor appears in the selection field next to the first option. Type a slash (/) next to the desired options.
– Suppress time stamps in script — omits time stamps from the scripts. If you are reviewing the scripts for debugging purposes, select this option to make the scripts easier to read. If you need to play back the script, do not select this option. Hiperstation for Mainframe Servers uses the time stamps to synchronize playback.
– Write script tags in short CPIC format — writes the APPC verbs in Common Programming Interface for Communications (CPIC) format, rather than Hiperstation proprietary format. For example, a send verb appears in the script as CMSEND rather than SEND_DATA. This option supports readability and has no impact on playback.
– Write all PIU traffic as script comments — Writes VTAM Path Information Units (PIUs) into the script — that is, the 26-byte Transmission Headers (TH), the 3-byte Request Headers (RH), and the variable length Request Units (RU) that are sent between VTAM logical units. In the scripts, this information appears in CONTENT tags under a PIU tag. Although the information does not appear with the traditional comment indicator (*) in column one, playback ignores the PIU block of tags. This option supports debugging VTAM applications.
– Include SNA service transactions — writes special APPC conversations used by subsystems such as VTAM and CICS into the scripts. For example, the Change Number of Session (CNOS) and Exchange Log Name (XLN) transactions appear in the script if you select this option. These conversations use the following logmodes: SNASVCMG, CPSVCMG, or CPSVRMGR. This option supports application debugging and does not impact playback.
9. Enter a Description to be written into the header of each script. This is an optional field that holds 55 characters.
10. If you accessed the Script Criteria screens through the:
– Monitor Requests option, request creation is complete. Depending on the request options, your terminal may display messages associated with your request. Press Enter to clear the messages. You may need to press Enter several times. After you clear all of the messages, the Monitor Requests screen appears. See “Monitoring and Managing Existing Requests” on page 2-10.
2-10 Hiperstation for Mainframe Servers User Guide
– Review Repository option, the “Script Processing Screen” appears next (Figure 2-11 on page 2-14). The cursor starts in the Select processing option field. Type 1 for background processing or 2 for foreground processing. The cursor automatically advances to the Job statement area of the screen. If you selected option 1, enter job statement information. Press Enter. Your terminal may display processing messages. Press Enter to clear the messages and return to the Review Repository screen.
Monitoring and Managing Existing RequestsThe Monitor Requests option (Figure 2-7) presents a list of all existing 3270/LU0 and APPC requests that you created. Active requests appear highlighted.
Use this screen to:
• Stop recording• Add, delete, or update a request• Restart an inactive request• Disable a request to prevent it from automatically restarting• View the sessions being captured• Switch the repository segment so that you can review captured activity without
interrupting recording
1. To access the “Global Recording - Monitor Requests Screen” (Figure 2-7), type 1 on the Option line of the Hiperstation for Mainframe Servers Main Menu and press Enter.
Figure 2-7. Global Recording - Monitor Requests Screen
Hiperstation --------- Global Recording - Monitor Requests -------- Row 1 of 1 Command ===> Scroll ===> PAGE Line commands are: (C)ancel, (F)orce, (P)Stop, (R)estart, (D)isable, (S)elect, (U)pdate, (1)Add 3270, (2)Add APPC, or (9)Switch repositories LU Side-A/ Side-B/ Repository S Type Applid Terminal Userid Dataset Users - ---- -------- -------- -------- ------------------------------------- ---- APPC VAP1* VAS4* * USER2312.APPC.REPOS 0 ******************************* BOTTOM OF DATA ********************************
2. Position the cursor in the S column next to the desired request, type the appropriate line command, and press Enter. Following is a description of the line commands:
(C)ancel
Cancels and deletes the request. All buffered information is also deleted, which may result in partially recorded business transactions. To avoid losing important data, STOP the request first. Wait for recording to terminate before issuing the CANCEL command. Use ISPF file management tools to delete any repository or repository segments created by the request.
(F)orce
Forces termination of capture and deactivates the request. Since this option immediately terminates capture, it may result in partially recorded business transactions. To stop capturing new sessions, but allow capture to finish for in-flight sessions, use STOP instead. If script criteria are specified within the request, script creation begins immediately.
APPC Global Recording and Scripts 2-11
Note: If the request specifies segmented repositories, the Force command will cause an automatic switch to a new segment.
(P) Stop
Stops capture of new sessions and deactivates the request. Global Recording continues to capture all sessions that are in-flight at the time the STOP is issued.
(R)estart
Restarts the request. The request becomes active as soon as the time frame specified within the request is met. Use this option to activate an inactive request.
(D)isable
Disables the request. All requests, except disabled requests, are restarted when the Global Recording started task is brought up. An asterisk (*) appears to the left of the repository dataset indicating the request is disabled. STOP or FORCE the request and wait for the request to terminate prior to disabling it.
(S)elect
Displays the “Global Recording - Active Sessions Screen” (Figure 2-8), which lists all APPC conversations or 3270/LU0 sessions being recorded.
(U)pdate
Presents request information for update. Recording must be terminated and the request must be inactive. Issue a STOP or FORCE to terminate recording and deactivate the request. After you finish editing, issue a RESTART command to reactivate the request.
(1) Add 3270
Adds a new 3270 or LU0 Global Recording request. This option is detailed in the Hiperstation for VTAM User Guide.
(2) Add APPC
Adds a new APPC Global Recording request. See“Creating an APPC Global Recording Request” on page 2-2.
(9) Switch Repositories
Closes the repository segment that is currently being written and open the next segment. If you did not specify a wildcard character in the Repository Dataset field, this option is not available.
View Active Sessions
The “Global Recording - Active Sessions Screen” (Figure 2-8) displays a list of all sessions currently being recorded for a given request.
1. To access this screen, type S (select) next to the appropriate request on the Monitor Requests screen and press Enter.
Figure 2-8. Global Recording - Active Sessions Screen
------------------- Global Recording * Active APPC Sessions ------- Row 1 of 2 COMMAND ===> SCROLL ===> PAGE SLU PLU Userid Start Time Last Update InB OutB Lost K01DSDS K01M2EP 11/21 00:25:51 11/21 00:25:51 0002 0001 0000 TPNAME=KBBRPSRV ******************************* BOTTOM OF DATA ********************************
2-12 Hiperstation for Mainframe Servers User Guide
2. Enter the secondary logical unit (SLU) in the conversation — the LU that initiated the session.
3. Enter the primary logical unit (PLU) in the conversation — the LU that is being accessed by the SLU.
4. Enter the user sign-on ID associated with the conversation being recorded. Not all APPC conversations have an associated User ID.
5. Enter the start time and date that the SLU initiated the conversation or the time the first transaction was recorded for the given session.
6. Enter the last time Global Recording flushed and processed the captured information from the ECSA buffers. This indicates the age of the counts displayed in the InB, OutB, and Lost fields.
Note: If this field indicates a significant lag, or sessions are being recorded that are not appearing on this screen, contact your MVS Systems Programmer. The Hiperstation Installation Guide provides instructions for optimizing Global Recording performance.
– InB is the number of inbound data steams received by the PLU.
– OutB is the number of outbound data streams sent by the PLU.
– Lost is the number of transactions (PIUs) lost. Slow processing or full buffers can result in lost messages.
Note: If this field reports lost messages, your MVS Systems Programmer can resolve the issue by optimizing Global Recording performance as described in the Hiperstation Installation Guide.
7. Press End to return to the Monitor Requests screen.
Reviewing Repositories and Creating ScriptsUse the Review Repository option to review the sessions captured in a given repository and to generate scripts. Create scripts from selected sessions or from all session in the repository.
To use the Review Repository option:
1. On the Option line of the Hiperstation for Mainframe Servers Main Menu, type 2 for Review Repository and press Enter. The “Review Repository - Dataset List Screen” appears (Figure 2-9).
Figure 2-9. Review Repository - Dataset List Screen
Hiperstation --------- Review Repository - Dataset List ----------- Row 1 of 2 Command ===> Scroll ===> PAGE Specify a repository dataset name or select a repository from the list below and press ENTER to process it, or END to return. Repository dataset . . . First and last number. . (If wildcard in dataset) Line commands are: (S)elect S Repository datasets Volser Referred Type Owner - -------------------------------------------- ------ -------- ---- -------- USER2312.APPC.REPOSIT SU9007 09/28/07 APPC USER2312 USER2312.XXXXXX SU9005 09/28/07 3270 USER2312 ******************************* BOTTOM OF DATA ********************************
APPC Global Recording and Scripts 2-13
2. If the repository dataset does not appear in the repository list, or to apply temporary script creation criteria:
– Type the dataset name in the Repository dataset field. If the dataset name includes wildcard characters, the first and last wildcard values to use for selecting the applicable segments are required. For example, entering MY.DATASET.CAP?? (with values 1 and 5) selects segments CAP01 through CAP05. The script criteria you provide are discarded after script creation.
– Otherwise, select the dataset name from the dataset list. You can use the UP and DOWN PF keys or the FIND and RFIND commands to locate the desired dataset. The dataset list contains a list of all of the 3270/LU0 and APPC repositories you have created. In administrator mode, discussed on page 2-16, the list shows repositories created by all users on the system. If you select a repository from the list, and you own the repository, any script creation criteria you supply is saved in the associated Global Recording request.
Note: Select as many repositories as you like. Review Repository presents the appropriate screens for each selection.
The Volser column contains the serial number of the volume where the given repository is stored. This field shows MIGRAT for migrated datasets. Referred is the MVS reference date associated with the repository dataset. It indicates the last time the dataset was modified. Type specifies the type of Global Recording request, 3270 or APPC, that captured the information in the repository dataset. Owner is the ID of the user who created the request associated with the repository dataset. Owner primarily supports administrator access to Global Recording. See “Accessing Global Recording Administration” on page 2-16.
3. Press Enter to continue. The Review Repository - Processing Options prompt appears (Figure 2-10).
– Type 1 to generate 3270 or LU0 scripts for all of the sessions captured in the selected repository. Refer to the Hiperstation for VTAM User Guide for more information on this option.
– Type 2 to generate APPC scripts for the selected repository. See “Generate Scripts from a Selected Repository” on page 2-14.
– Leave the selection field empty to access a list of all sessions captured in the selected repository. Use this option to review repository contents, generate scripts from selected sessions, and review or modify script creation criteria. See “Generate Scripts from Selected Sessions” on page 2-14.
Note: To review or modify existing script creation criteria, leave the field empty even if you intend to generate scripts from all of the captured sessions. The Session List screen allows you to review and modify script criteria.
Figure 2-10. Review Repository - Processing Options Screen
Hiperstation------------ Review Repository - Dataset List --------------------- C +-----------------------------------------------------------------+ ==> PAGE | ----------- Review Repository - Processing Options ----------- | S | Command ===> | b | | | You specified a repository dataset or selected one from the | R | dataset list to process. Press ENTER to review the sessions | F | captured to this repository, or select an option below and | | press ENTER to create scripts for all sessions of that type | L | from this repository, or END to return. | | | S | Script creation option: (Enter number to select) | wner - | 2 1. Record ALL 3270 sessions | ------- | 2. Record ALL APPC sessions | SER2312 | | SER2312 * +-----------------------------------------------------------------+
2-14 Hiperstation for Mainframe Servers User Guide
4. Press Enter. Continue with the following section, “Generate Scripts from a Selected Repository” or “Generate Scripts from Selected Sessions” on page 2-14 depending on the option you selected.
Generate Scripts from a Selected Repository
This section describes the screens that appear after you select the Record ALL APPC sessions option on the “Review Repository - Processing Options Screen” (Figure 2-10).
The APPC - Script Criteria screen appears if:
• No script creation criteria are defined. If you selected the repository dataset name from the list on the “Review Repository - Dataset List Screen” (Figure 2-9 on page 2-12), the criteria you specify is saved within the associated Global Recording request.
• You entered the repository dataset name in the Repository dataset field on the “Review Repository - Dataset List Screen” (Figure 2-9 on page 2-12). The script criteria you specify are discarded after the scripts are generated.
See “Define Script Creation Criteria” on page 2-6.
Otherwise, the “Script Processing Screen” appears (Figure 2-11).
Figure 2-11. Script Processing Screen
Hiperstation ----------------- Script Processing ------------------------------ Command ===> Select the way you want the script creation process to run. Press ENTER to create your scripts, or END to return, or enter CANCEL to exit. Select processing option: (Enter number to select) 2 1. Submit batch job 2. TSO Job statement information for batch job: ===> //JOBNAME JOB (ACCOUNT),'NAME' ===> //* ===> //* ===> //*
1. In the Select processing option field, type 1 for background processing or 2 for foreground processing. The cursor automatically advances to the job statement area of the screen. If you selected background processing, enter job statement information.
2. Press Enter.
Depending on your selection, Review Repository either submits the job or initiates processing. If you selected foreground processing, messages are sent to your TSO session.
3. Press Enter to clear the messages and return to the Review Repository screen.
Generate Scripts from Selected Sessions
This section describes the screens that appear if, on the “Review Repository - Processing Options Screen” (Figure 2-10), you elect to review the sessions captured in the repository and generate scripts from selected sessions.
Review Repository processes the repository dataset to create the list of sessions. It presents a processing status message that disappears when processing is complete. The length of time the message appears depends on the size of the repository.
APPC Global Recording and Scripts 2-15
Note: Interrupt session processing by pressing the ATTN key.
When the processing message disappears, the “Review Repository - Session List Screen” appears (Figure 2-12).
Figure 2-12. Review Repository - Session List Screen
Hiperstation--------- Review Repository - Session List ----------- Row 1 of 5 Command ===> Scroll ===> PAGE Select a session and press ENTER to process it, or END to return. Repository dataset . . : USER2312.APPC.CAP01.WSCRPT Script creation option: (Enter "/" to select) Review script create criteria Line commands are: (R)ecord S LU Type Applid/Side-A Termid/Side-B Userid Start Date Start Time - ------- ------------- ------------- -------- ---------- ---------- APPC H01AC054 H01AC055 JOB 11/16/06 00:04:00 APPC H06APPC9 H01APPC9 USER2312 11/16/06 10:54:12 APPC H01APPC9 H06APPC9 USER2312 11/16/06 14:57:26 APPC H01APPC9 H06APPC9 USER2312 11/16/06 11:06:19 APPC H06APPC9 H01APPC9 USER2312 11/16/06 10:55:40
You can use the UP and DOWN PF keys or the FIND and RFIND commands to locate the desired sessions. After the cursor is in the list, use the Tab and Back Tab keys to move the cursor up and down the list.
The Repository dataset field is prefilled with the name of the repository dataset selected on the previous screen.
1. Enter an R (Record) in the selection column next to each session you want to create a script for. Record generates a script for each selected session. Sessions selected for recording are highlighted when scrolling the Session list.
2. Enter a slash in the Review script create criteria field to invoke the script criteria screens allowing you to review or modify the existing script criteria.
If you entered the repository dataset name in the Repository dataset field on the “Review Repository - Dataset List Screen” (Figure 2-9 on page 2-12), your script criteria changes are discarded after the scripts are created. If you selected the repository dataset from the list, your changes are saved in the associated Global Recording request.
If necessary, see the online help for a description of the session columns.
3. After you finish selecting sessions, press Enter.
– The APPC script criteria screens appear (see “Define Script Creation Criteria” on page 2-6) if:
• No script creation criteria are defined within the associated Global Recording request.
• You entered the repository dataset name in the Repository dataset field on the “Review Repository - Dataset List Screen” (Figure 2-9 on page 2-12).
• You selected the Review script create criteria field on the Session List screen.
– Otherwise, Review Repository displays the “Script Processing Screen” (Figure 2-13). In the Select processing option field:
• Type 1 for background processing or 2 for foreground processing.
• If you selected background processing, enter job statement information.
2-16 Hiperstation for Mainframe Servers User Guide
• Press Enter.
Depending on your selection, Review Repository either submits the job or initiates processing. If you selected foreground processing, messages are sent to your TSO session.
4. Press Enter to clear the messages and return to the Review Repository screen.
Figure 2-13. Script Processing Screen
Hiperstation ----------------- Script Processing ------------------------------ Command ===> Select the way you want the script creation process to run. Press ENTER to create your scripts, or END to return, or enter CANCEL to exit. Select processing option: (Enter number to select) 2 1. Submit batch job 2. TSO Job statement information for batch job: ===> //JOBNAME JOB (ACCOUNT),'NAME' ===> //* ===> //* ===> //*
Defining Global Recording Manager ListsWithin a 3270 or LU0 Global Recording request, you either specify the terminals, applications, and user IDs to capture or you specify a Global Recording Manager List. A Global Recording Manager List defines the terminals, applications, and user IDs to record or exclude from recording.
Use Global Recording Manager Lists to save time and work. For example, if the users you need to record do not have similar user IDs where you can use wildcards for selection, you can either create a separate request for each user ID or you can define a Global Recording Manager List and create a single request that uses that list.
The Hiperstation for VTAM User Guide describes all functions related to 3270 and LU0 Global Recording requests. Refer to it to learn how to create, copy, or modify a Global Recording Manger List.
Accessing Global Recording AdministrationGlobal Recording Administration provides:
• Access to all APPC, 3270, or LU0 recording requests on the system.• Access to all capture repositories created by the requests on the system.• Authority to edit and delete any Global Recording Manager List.
To access Global Recording Administration, type ADMIN on the Option line of the Hiperstation for Mainframe Servers Main Menu and press Enter. The word “Administration” appears after the menu title.
Note: Access to Global Recording Administration requires the proper authority. If you receive a security error, contact your Hiperstation installer or security administrator.
Options 1 through 3 behave the same in administration mode, except the Monitor Request screen shows all of the requests on the system, the Review Repository option lists
APPC Global Recording and Scripts 2-17
the repositories created by all of the requests on the system, and the Global Recording Manager allows you to edit and delete lists created by any user on the system.
Using the Global Recording Batch InterfaceHiperstation for Mainframe Servers provides a batch interface to Global Recording. Use it along with a job scheduler to automate capture initiation and termination. For example, to initiate recording every morning at 8:00 AM and terminate it at 5:00 PM, create a job to RESTART the request and a job to STOP the request. Use a job scheduler to submit the jobs at the appropriate times.
The Global Recording batch interface also provides a script creation function. Set up the recording request to initiate script creation when the request ends or suspend script creation and schedule it to run at a later time. For example, if you are recording a large volume of traffic, schedule a job to create scripts in the evening when more system resources are available.
Use the online and batch interfaces together. For example:
• Create a recording request with the online interface, and then manage it with scheduled jobs.
• Initiate recording with the batch interface, and then use the Monitor Requests option to view a list of sessions being capture.
Create a Global Recording Request
Global Recording writes captured activity to a specified dataset or range of datasets called a capture file or a repository. Testing scripts are generated from the capture repository. Global Recording can initiate script creation at the end of the recording request, or you can initiate it later with a separate job (see “Create Scripts” on page 2-43) or with the Review Repository option in the online interface (see “Reviewing Repositories and Creating Scripts” on page 2-12). For example, capture an entire day’s activity and generate scripts in the evening when more system resources are available, or use Review Repository to generate scripts from selected sessions.
To capture activity and potentially generate scripts, create a recording request. If you specify a time-frame for the request, it becomes active at the designated start time. If you do not specify a time-frame, it becomes active immediately. Capture begins when all of the criteria for an active request are met.
Note: Global Recording does not support VTAM compressed data streams.
Creating a Global Recording request with the batch interface involves defining the parameters of the request. Parameters are defined in extensible markup language (XML). The batch interface’s XML parser provides limited syntax support. Be sure to review “Global Recording Request Parameter Syntax” on page 2-18 prior to writing or modifying parameters.
This section describes adding an APPC Global Recording request. The procedures for adding a request are the same regardless of the type of request. However, the request parameters that are the input for the job are specific to the protocol. If you need parameter information for adding a 3270 or LU0 request, refer to the Hiperstation for VTAM User Guide.
Create a Global Recording Request with the Batch Interface
To create a Global Recording request with the batch interface:
1. Define the Global Recording request parameters. See “Global Recording Request Parameters” on page 2-20.
2-18 Hiperstation for Mainframe Servers User Guide
2. Use SQQFSAMP member DCIJCL (Figure 2-14) to execute the ADD request function.
Figure 2-14. DCIJCL — Sample JCL to Add or Manage Requests
********************************* Top of Data ********************************** //* INSERT JOB CARD HERE............................................... /*JOBPARM SYSAFF=sysn //********************************************************************* //* JCL TO ADD OR MODIFY 3270, APPC, TCP/IP, OR MQSERIES GLOBAL * //* RECORD REQUESTS. * //* * //* UPROCS: DATASET THAT CONTAINS THE DCIPROC. * //* * //* FEEDBACK: OUTPUT XML THAT MAY BE USED AS INPUT TO SUBSEQUENT * //* STEPS. * //* * //* SYSTSIN: TSO BACKGROUND INPUT STREAM. * //* ISPSTART PGM(QACDCIP) - EXECUTE THE GLOBAL RECORD * //* BATCH INTERFACE (GRBI) * //* PARM(command) - IS THE COMMAND PASSED TO THE GRBI * //* * //* SYSIN: XML INPUT. * //* * //********************************************************************* //UPROCS JCLLIB ORDER=('COMPWARE.QQF800.SQQFSAMP') <-REVIEW //DCI EXEC PROC=DCIPROC //FEEDBACK DD * //SYSTSIN DD * ISPSTART PGM(QACDCIP) PARM(ADD) <-REVIEW /* //SYSIN DD DISP=SHR,DSN=COMPWARE.QQF800.SQQFSAMP(DCIADXL6) <-REVIEW ******************************** Bottom of Data ********************************
3. Insert job statement information at the top of the sample.
4. Ensure the UPROCS statement points to the procedures library that contains DCIPROC.
5. After the request is created, the batch interface returns a request key that contains information about the request. Use the request key as input for request management jobs (see “Manage Existing Requests” on page 2-40). The key is written to the location specified on the FEEDBACK DD. To save the key in your personal library, specify a sequential dataset, PDS(E) and member, or a generation data group (GDG).
Note: Allocate the dataset or GDG with a fixed block record format and an 80-byte record length.
6. On the SYSTSIN DD statement, ensure ADD is specified on the PARM keyword.
7. On the SYSIN DD statement, either supply the name of the dataset containing the request parameters or enter the parameters in-line.
Note: In-stream parameters cannot exceed 80 bytes. If you edited the parameters on a PC and copied them back to a dataset exceeding 80 bytes, point the DD to the dataset rather than pasting the parameters into the job.
8. Schedule or submit the job.
Note: DCI produces real return codes, as opposed to always returning a zero value. This allows you to determine whether global record or archive record requests started. It also allows JCL creation where job steps may or may not be executed based on whether the DCI request succeeded.
Global Recording Request Parameter Syntax
Global Recording request parameters are defined in XML. Write the parameters from scratch or start with a sample or a generated parameter set. Store the parameters in a
APPC Global Recording and Scripts 2-19
dataset or paste them right into the JCL. Use a standard file editing tool to modify the parameters.
Note: The batch interface contains a proprietary XML parser that supports a limited set of XML elements. It recognizes only the syntax described in this section.
Most recording request XML parameters are comprised of an opening tag, followed by a value and a closing tag. Opening and closing tags must be contained in angle brackets. The closing tag must be preceded by a backslash inside the angle brackets. For example:
<Terminal> '*' </Terminal>
If the parameter’s value contains spaces, it must be placed in single quotation marks. In the samples and generated parameter sets, the parameter values always appears inside single quotes.
Some parameters require a format indicator followed by a value supplied in single quotation marks. For example, the Request ID tag accepts a hexadecimal or character value. Specify the format of the value by placing an X or a C before the value, outside of the quotation marks.
<Request_ID> C'QA_REQ'</Request_ID>
The batch interface ignores spaces between the tag and the tag’s value. For example, the following parameter is interpreted the same way as the previous terminal parameter example:
<Terminal> '*' </Terminal>
To make the samples and generated parameter sets easier to read, most parameters are formatted with the opening tag and value on one line and the closing tag on the following line.
XML parameters are hierarchal. That is, some parameters have a group of related sub-parameters. For example, the Start_Time, End_Time, Start_Date and End_Date are sub-parameters of the Scheduled_Capture parameter. Sub-parameters must be nested within opening and closing parent parameter tags. For example,
<Scheduled_Capture> <Start_Date> '00/00/0000' </Start_Date> <Start_Time> '00:00:00' </Start_Time> <End_Date> '00/00/0000' </End_Date> <End_Time> '00:00:00' </End_Time> </Scheduled_Capture>
Depending on the request you are creating, there may be several levels of nesting. For example, all of the APPC Global Recording request parameters are sub-parameters of the <APPC> protocol parameter. The start and end time and date parameters are sub-parameters of Scheduled_Capture, which is a sub-parameter of the <APPC> protocol parameter.
<APPC> <Request_ID> C’MY_REQ’ </Reqeust_ID> <Scheduled_Capture> <Start_Date> '00/00/0000' </Start_Date> <Start_Time> '00:00:00' </Start_Time> </Scheduled_Capture> </APPC>
2-20 Hiperstation for Mainframe Servers User Guide
Note: This example shows tag nesting. It is not a complete set of request parameters.
Indenting nested tags is not necessary. However, it makes editing much easier. In the samples and generated parameter sets, each level of nesting is indented one space.
Finally, an XML stream can contain comments that the batch interface ignores. Comment text must be prefixed with an opening angle bracket, an exclamation point and two dashes and followed with two dashes and closing angle bracket. For example:
<!--This is an XML comment. -->
Global Recording Request Parameters
Global Recording request parameters are defined in XML. For syntax rules, see “Global Recording Request Parameter Syntax” on page 2-18.
Start with one of the following:
• The parameters from an existing request. See “Retrieve the Parameters of an Existing Request” on page 2-42.
• A parameters skeleton. See “Generate a Request Parameters Skeleton” on page 2-43.
• SQQFSAMP member DCIADXL6: Contains all available APPC Global Recording request parameters.
• SQQFSAMP member DCIADDL6: Contains a subset of commonly used APPC recording request parameters.
Store the parameters in a sequential dataset or a PDS member in your personal library or write them directly in the JCL. Use a standard file editing tool such as ISPF Edit to write or modify the parameters.
Notes:
1. XML tags are case-sensitive. Make sure the ISPF Caps function is set to off when editing the parameters. Type CAPS OFF on the Command line and press Enter
2. To work with a parameters file on the PC:
– Use the IBM utility IEBGENER to copy the dataset into an HFS file.
– FTP the file to the PC. To avoid EBCDIC to ASCII translation issues, transfer the file as 'text'.
Use an XML editor, such as Notepad, to edit the tags. Pay attention to syntax interpretation. The Global Recording batch interface may not recognize tags that have been reformatted based on the viewer’s interpretation. For example, some editors format tags that have no values as follows <tag/>. Encase blank values in single quotes to avoid this particular interpretation issue. All tags must conform to the syntax rules described on page 2-18.
To avoid record truncation when transferring the parameters back to the mainframe, copy them into a fixed block dataset with a logical record length that supports the longest record.
This section provides an illustration of sample DCIADXL6, showing parameter hierarchy, (Figure 2-15) and, following the figure, defines all of the available APPC Global Recording request parameters.
APPC Global Recording and Scripts 2-21
Figure 2-15. SQQFSAMP Member DCIADXL6
********************************* Top of Data ********************************** <APPC> <Request_ID> X'000000000000' </Request_ID> <SideA_LU> '*' </SideA_LU> <SideB_LU> '*' </SideB_LU> <User_ID> '*' </User_ID> <SideA_Netid> '*' </SideA_Netid> <SideB_Netid> '*' </SideB_Netid> <Logmode> '' </Logmode> <TPname> X'00000000' </TPname> <Scheduled_Capture> <Start_Date> '00/00/0000' </Start_Date> <Start_Time> '00:00:00' </Start_Time> <End_Date> '00/00/0000' </End_Date> <End_Time> '00:00:00' </End_Time> </Scheduled_Capture> <Capture_File> <Dataset> 'COMPWARE.SAMPLE.CAPTURE.FILE*' </Dataset> <First_Number> '1' </First_Number> <Last_Number> '10' </Last_Number> <!-- Valid 'Initial_Disposition' values are APPEND or OVERWRITE --> <Initial_Disposition> 'APPEND' </Initial_Disposition> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Block_Size> '9004' </Block_Size> </Allocation> </Capture_File> <Recording_Options> <Suspend_Script_Create> 'NO' </Suspend_Script_Create> <Reuse_Capture_File> 'NO' </Reuse_Capture_File> <Force_At_End_Time> 'NO' </Force_At_End_Time> <!-- Valid 'Event_Notification' values are YES, NONE, or ERROR --> <Event_Notification> 'YES' </Event_Notification> </Recording_Options>
2-22 Hiperstation for Mainframe Servers User Guide
<Script_Criteria> <Description> 'Compuware Global Record Batch Interface' </Description> <Recording_Script> <Dataset> 'COMPWARE.SAMPLE.SCRIPTS' </Dataset> <Member_Prefix> 'SCR' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <Replace_Members> 'NO' </Replace_Members> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Recording_Script> <Script_Create_Options> <!-- Valid 'Detail_Store_Type' values; MERGED, COMBINED, SPLIT --> <Detail_Store_Type> 'MERGED' </Detail_Store_Type> <Record_Conv_Log> 'YES' </Record_Conv_Log> <Record_Script> 'YES' </Record_Script> <Record_Detail> 'YES' </Record_Detail> <Suppress_Time_Stamps> 'NO' </Suppress_Time_Stamps> <Tags_Short_CPIC> 'NO' </Tags_Short_CPIC> <PIU_As_Comments> 'NO' </PIU_As_Comments> <Inc_SNA_SVC_Trans> 'NO' </Inc_SNA_SVC_Trans> </Script_Create_Options> <Conversation_Log> <Dataset> 'COMPWARE.SAMPLE.CNVLOG' </Dataset> <Member_Prefix> 'LOG' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <Replace_Members> 'NO' </Replace_Members> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class>
APPC Global Recording and Scripts 2-23
<Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Conversation_Log> <Combined_Detail> <Dataset> 'COMPWARE.SAMPLE.DETAIL.COMBINED' </Dataset> <Member_Prefix> 'CDT' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <Replace_Members> 'NO' </Replace_Members> <DDName> 'DETAILCB' </DDName> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Combined_Detail> <Inbound_Detail> <Dataset> 'COMPWARE.SAMPLE.DETAIL.INBOUND' </Dataset> <Member_Prefix> 'IDT' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <Replace_Members> 'YES' </Replace_Members> <DDName> 'DETAILIB' </DDName>
2-24 Hiperstation for Mainframe Servers User Guide
<Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Inbound_Detail> <Outbound_Detail> <Dataset> 'COMPWARE.SAMPLE.DETAIL.OUTBOUND' </Dataset> <Member_Prefix> 'ODT' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <DDName> 'DETAILOB' </DDName> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Outbound_Detail> </Script_Criteria> </APPC>
Protocol Parameter Tag
APPC
Identifies the type of Global Recording request to add. This is a parent tag to all other parameters described in this section. Begin and end the XML input stream with opening and closing APPC tags.
APPC Global Recording and Scripts 2-25
General Request Parameter Tags
Request ID
Specifies the ID of the Global Recording request. To assign a request ID, supply a six-byte hexadecimal or character value in single quotes. Place a format indicator in front of the value outside of the quotation marks. X specifies hexadecimal values and C specifies character values. For example:
– <Request_ID> X'010203040506' </Request_ID>
– <Request_ID> C'QAREQ1'</Request_ID>
The batch interface pads hexadecimal values that are fewer than six bytes with zeros and character values that are fewer than six bytes with spaces.
This tag is optional. If you do not supply a request ID, the system assigns one when the request is created.
SideA_LU and SideB_LU
The VTAM logical unit (LU) names of the partners that make up the APPC conversations that you need to record. Both fields require one of the following:
– A specific LU name.
– An asterisk (*) to select all LUs. Leaving this field blank also selects all LUs.
– An LU prefix followed by an asterisk to select a group of LUs. For example, VAP1* selects all LUs beginning with VAP1.
If you supply a SideA_LU but no SideB_LU, or the reverse, all conversations involving the specified LU are recorded. This field holds eight characters.
User_ID
The user sign on ID associated with the conversation you need to record. Enter one of the following:
– A specific user ID.
– An asterisk (*) to select all users. Leaving this field blank also selects all LUs.
– A user ID prefix followed by an asterisk to select a group of users. For example, USR* selects all user IDs beginning with USR.
This field holds eight characters.
SideA_Netid and SideB_Netid
The VTAM Network ID for the Side A LU and Side B LU partners. Use these tags to restrict capture to only the APPC conversations on specific VTAM networks. Both tags require one of the following:
– A specific network ID.
– An asterisk (*) to select all networks. Leaving this field blank also selects all networks.
– A network ID prefix followed by an asterisk to select a group of networks. For example, US* selects all networks beginning with US.
This field holds eight characters.
Logmode
The VTAM logon mode name used by the conversations you need to record. To specify a range of similar logmodes, use the asterisk (*) wildcard. For example, SNAS* selects all logmode names beginning with SNAS. Omit this tag if you do not want to restrict recording to a specific logmode.
2-26 Hiperstation for Mainframe Servers User Guide
TPname
The transaction program name associated with the conversations you need to record. Enclose TP Names in single quotation marks. If the TP name contains non-printable characters, supply it in hexadecimal notation, enclosed in single quotation marks, and prefixed with the letter X (for example, X'0EC1D7C9D5C70F’). This tag accepts up to 64 characters. Omit this tag if you do not want to restrict recording to a specific TP name.
Scheduled Capture Parameter Tags
Scheduled_Capture
Sets a start time and duration for the request. The request activates at the defined start time and date and remains active until the specified end time and date, unless the capture repository fills up and the Reuse_Capture_File tag is set to 'NO'.
Omit this entire block of tags for capture to begin immediately and remain active indefinitely.
The following parameters are Scheduled_Capture sub-parameters. Supply the applicable parameters between the opening and closing Scheduled_Capture tags.
Start_Date
The date the request is to be activated. Specify a two digit month, a two digit day, and a four digit year separated by slashes: 'MM/DD/YYYY'.
If you specify a start date with no time, the request activates at the beginning of the given day — that is, midnight (00:00:00).
Start_Time
The time the request is to be activated. Specify a two digit hour, a two digit minute, and a two digit second separated by colons: 'HH:MM:SS'.
If you specify a start time, a start date is required. If you do not specify a start time or date, the request activates immediately.
End_Date
The month, day, and year to deactivate the request. Specify a two digit month, a two digit day, and a four digit year separated by slashes: 'MM/DD/YYYY'.
If you specify an end date with no time, the request deactivates at the end of the given day — that is, midnight (24:00:00).
If you set the Force_At_End_Time recording option to 'Y', an end time and date are required.
End_Time
The time the request is to be deactivated. Specify a two digit hour, a two digit minute, and a two digit second separated by colons: 'HH:MM:SS'.
If you do not specify an end time or date, the request remains active until you STOP, FORCE, or CANCEL it or until the repository is full if you did not set the Reuse_Capture_File tag to 'YES'.
If you specify an end time, an end date is required.
If you set the Force_At_End_Time recording option to 'YES', an end time and date are required.
Capture File Parameter Tags
Capture_File
Defines the dataset to use for storing the captured data.
The following parameters are Capture_File sub-parameters. Supply the applicable parameters between the opening and closing Capture_File tags.
APPC Global Recording and Scripts 2-27
Dataset
The name of the dataset to use for storing captured information. This required parameter accepts 44 characters.
To create a segmented capture file, use either of the following wildcard characters in the dataset name. Define a range for the wildcard characters with the First_Number and Last_Number tags:
• Asterisk (*): Inserts an incremental value into the dataset name qualifier the asterisk appears in. This wildcard pads the incremental value with enough zeros to ensure an eight character qualifier. For example, USER.APPC.REC* with first=1 and last=3 creates capture datasets:
USER.APPC.REC00001 USER.APPC.REC00002 USER.APPC.REC00003
• Question mark (?): Inserts the incremental value into the qualifier where the question marks appear. Enter at least one question mark for each digit of the value supplied on the Last_Number tag. For example, USER.APPC.REC?? with first=9 and last=11 creates capture datasets:
USER.APPC.REC09 USER.APPC.REC10 USER.APPC.REC11
Note: Begin each segment of the dataset name with an alpha character (A-Z) or @#$, including segments with wildcard characters.
First_Number and Last Number
Defines the first value and last value to use for wildcard characters specified on the Dataset tag. For each tag, supply a value up to seven digits. If you did not use a wildcard, do not include these tags.
Initial Disposition
Specifies whether to append or overwrite data contained in the specified dataset. Valid values are 'APPEND' or 'OVERWRITE'. This tag is unnecessary if the specified dataset does not exist. If the specified dataset does exist, and you do not provide an initial disposition value, the batch interface appends the new data to the existing data.
Note: The dataset is overwritten when Global Recording captures and processes activity that matches the request criteria. If no activity matches, the dataset is not overwritten.
Allocation
Allocation parameters for the capture file dataset. If you do not supply allocation parameters and the specified dataset does not exist, the batch interface allocates it with default values set by the installer. Generally, the default values are appropriate. However, you can override any or all of the default parameters by using the following Allocation sub-parameters.
Supply the applicable parameters between the opening and closing Allocation tags.
Management_Class
The management class to apply to the new dataset. Management classes are defined by the storage administrator at your site.
Storage_Class
The storage class to apply to the new dataset. Storage classes are defined by the storage administrator at your site.
2-28 Hiperstation for Mainframe Servers User Guide
Volume_Serial
The serial number of the volume where the dataset is to be stored.
Device_Type
The type of device that the dataset is to be stored on. Device_Type can be a generic unit such as 'SYSDA'.
Data_Class
The data class to apply to the new dataset. Data classes are defined by the storage administrator at your site.
Space_Units
The type of units used to store the data. Valid values include: TRKS (Tracks), CYLS (Cylinders), BLKS (Blocks), BYTES, KB (kilobytes), or MB (megabytes). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
Primary_Quantity
The number of space units to allocate initially. After Global Recording fills the primary quantity, it allocates the secondary quantity.
Secondary_Quantity
The number of space units to allocate after the primary quantity is full.
Block_Size
The maximum length, in bytes, of the blocks of data that the system reads in as it processes a dataset.
Recording Option Parameter Tags
Recording_Options
Defines recording request actions.
The following parameters are Recording_Options sub-parameters. Supply the applicable parameters between the opening and closing Recording_Options tags.
Suspend_Script_Create
Suspends script creation. Supply this tag with a value of:
• 'YES' to create scripts later.
• 'NO' to automatically initiate script creation when the recording request ends. Be sure to supply script creation criteria.
If you omit this tag, the batch interface suspends script creation.
Reuse_Capture_File
This parameter applies only to segmented capture files. It causes Global Recording to continue capturing activity after the capture file segments are full. After the last segment fills, Global Recording begins writing to the first segment again, replacing the oldest captured activity.
To enable this option, supply this tag with a value of 'YES'. If you omit this tag or supply it with a value of 'NO', recording terminates after the last segment is full.
Force_At_End_Time
Issues a FORCE command at the end time specified in the request. FORCE terminates recording of all sessions including active sessions. Script creation begins immediately, unless you elected to suspend script creation. Be aware that you may lose buffered data, resulting in partially recorded sessions.
To enable this option, supply this tag with a value of 'YES'. Be sure to supply End_Time and End_Date values enclosed in Scheduled_Capture tags.
APPC Global Recording and Scripts 2-29
If you omit this tag or supply it with a value of 'NO', Global Recording issues a STOP command at the request’s specified end time. It stops recording new sessions, but continues to record all in-flight sessions. When all active sessions end, recording is terminated and script creation begins unless you elected to suspend script creation. This option ensures complete session captures. However, it may delay script creation.
Event_Notification
Defines the type of messages sent to your TSO session. Supply a value of:
• 'ERROR' to receive error messages only.
• 'YES' to receive status and error messages.
• 'NONE' to disable event notification.
If you are recording a large number of sessions, consider disabling this option or selecting error notification to reduce the number of messages you receive. If you omit this tag, Global Recording sends all recording and script creation messages.
Note: To see the messages that the batch interface produces, such as parameter verification messages or the return code for the request creation job, review the PRGLOG DD in the JES job log. See “Troubleshoot Failed Jobs” on page 2-50.
General Script Criteria Tags
If you supply the Suspend_Script_Create tag with a value of 'NO', script creation criteria are required.
Script_Criteria
Defines script creation parameters. The rest of the parameters described in the section are all sub-parameters of this tag. Supply the applicable parameters between opening and closing Script_Criteria tags.
Description
A string of up to 55 characters that appears in the header section of the script. This tag is optional.
Recording Script Tags
Recording_Script
The batch interface writes each script to a separate member of a PDS or PDSE. This block of tags defines the attributes of the PDS(E).
The following parameters are Recording_Script sub-parameters. Supply the applicable parameters between the opening and closing Recording_Script tags.
Dataset
The PDS(E) to contain the scripts. This is a required parameter. It accepts up to 44 characters.
Member_Prefix
One to six character prefix that, in conjunction with the member suffix, forms the member name for each script created. This is a required parameter.
Member_Suffix
A numeric value that, in conjunction with the member prefix, forms the member name for each script created. The batch interface increments this value each time it creates a new script. Supply a suffix that in combination with the prefix equals eight characters.
2-30 Hiperstation for Mainframe Servers User Guide
• If you supply a suffix that is too short, the batch interface pads the suffix with zeros to the left. For example, if the prefix is OES and the suffix is 10, the first script member name is OES00010, and the next member is OES00011.
• If you supply a suffix that is too long, the batch interface truncates the digits on the left. For example, if you enter SCRIPT for the prefix and 1234 for the suffix, the first script member is SCRIPT34, and the next member is SCRIPT35.
This is a required parameter. It accepts up to seven digits.
Replace_Members
Overwrites existing members that have the same names as the Dataset, Member_Prefix, and Member_Suffix tags.
To enable this option, supply this tag with a value of 'YES'. If you omit this tag or supply it with a value of 'NO', the batch interface does not overwrite existing members.
Allocation
Allocation parameters for the recording script dataset. If you do not supply allocation parameters and the specified dataset does not exist, the batch interface allocates it with default values set by the installer. Generally, the default values are appropriate. However, you can override any or all of the default parameters by using the following Allocation sub-parameters.
Supply the applicable parameters between the opening and closing Allocation tags.
Management_Class
The management class to apply to the new dataset. Management classes are defined by the storage administrator at your site.
Storage_Class
The storage class to apply to the new dataset. Storage classes are defined by the storage administrator at your site.
Volume_Serial
The serial number of the volume where the dataset is to be stored.
Device_Type
The type of device that the dataset is to be stored on. It can be a generic unit such as 'SYSDA'.
Data_Class
The data class to apply to the new dataset. Data classes are defined by the storage administrator at your site.
Space_Units
The type of units used to store the data. Valid values are: TRKS (Tracks), CYLS (Cylinders), BLKS (Blocks), BYTES, KB (kilobytes), or MB (megabytes). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
Primary_Quantity
The number of space units to allocate initially. After Global Recording fills the primary quantity, it allocates the secondary quantity.
Secondary_Quantity
The number of space units to allocate after the primary quantity is full.
Directory_Blocks
APPC Global Recording and Scripts 2-31
The number of blocks to use for a PDS directory. If the dataset is a PDSE, the batch interface ignores this value.
Block_Size
The maximum length, in bytes, of the blocks of data that the system reads in as it processes a dataset.
Record_Length
The maximum length, in bytes, provided for each record in the dataset. Script datasets must be minimally 105 bytes. The record length must be at least four less than the block size.
Dataset_Name_Type
The type of dataset to contain the scripts. Supply this tag with a value of 'PDS' or 'LIBRARY' (PDSE). If you omit this tag, the batch interface allocates the script file as a PDS.
Script Creation Option Tags
Script_Create_Options
Defines the format and content of the scripts.
The following are Script_Create_Options sub-parameters. Supply the applicable parameters between the opening and closing Script_Create_Options tags.
Detail_Store_Type
Defines where to store the detail data associated with the captured APPC verbs. Storing details in separate files may ease browsing, editing, and managing scripts and detail data. Supply this tag with a value of:
• 'MERGED', to merge the detail with the APPC verbs. This option createS one PDSE member for each script.
• 'COMBINED' to separate the details from the scripts. This option creates two PDSE members for each script: one containing all of the detail data, and one containing the APPC verbs with links to the associated detail. If you specify this option, supply the Record_Detail tag with a value of 'YES' and the Combined_Detail block of tags. See “Combined Detail Tags” on page 2-34.
• 'SPLIT' to separate the inbound and outbound details from each other and from the script. This option creates three PDSE members for each script: one containing the APPC verbs with links to the associated detail, one containing the outbound details, and one containing the inbound details. If you specify this option, supply the Record_Detail tag with a value of 'YES' and the Inbound_Detail and Outbound_Detail blocks of tags. See “Inbound Detail Tags” on page 2-36 and “Outbound Detail Tags” on page 2-38.
This is a required tag.
Record_Conv_Log
Generates a conversation log, which is a report of each captured APPC conversation. Conversation logs contain the bulk of the input required for Unattended Playback jobs. You can save time when preparing the playback job by starting with the log. See Chapter 4, “Unattended Playback of APPC Scripts” to learn about the playback statements you may need to add or modify.
If you need a conversation log, supply this tag with a value of 'YES' and include the Conversation_Log block of tags. See “Conversation Log Tags” on page 2-32. Otherwise, supply a value of 'NO' or omit the tag altogether.
Record_Script
Generates one script for each captured conversation.
2-32 Hiperstation for Mainframe Servers User Guide
To create scripts, supply this tag with a value of 'YES'. Otherwise, supply a value of 'NO' or omit the tag altogether.
Record_Detail
Generates the inbound and outbound data associated with the captured APPC verbs.
To generate details, supply this tag with a value of 'YES' and include the appropriate detail dataset block of tags.
• If you specified 'COMBINED' on the Detail_Store_Type tag, include the Combined_Detail block of tags (see page 2-34).
• If you specified 'SPLIT' on the Detail_Store_Type tag, include the Inbound_Detail (see page 2-36) and Outbound_Detail (see page 2-38) blocks of tags.
Otherwise, supply a value of 'NO' or omit the tag altogether.
Suppress_Time_Stamps
Omits time stamps from the scripts. If you are reviewing the scripts for debugging purposes, supply this tag with a value of 'YES' to make the scripts easier to read. If you need to play back the script, do not enable this option. Hiperstation for Mainframe Servers uses the time stamps to synchronize play back.
Tags_Short_CPIC
Writes the APPC verbs in Common Programming Interface for Communications (CPIC) format, rather than Hiperstation proprietary format. For example, a send verb appears in the script as CMSEND rather than SEND_DATA. This option supports readability and has no impact on playback. To enable this option, supply this tag with a value of 'YES'.
PIU_As_Comments
Writes VTAM Path Information Units (PIUs) into the script — that is, the 26-byte Transmission Headers (TH), the 3-byte Request Headers (RH), and the variable length Request Units (RU) that are sent between VTAM logical units. In the scripts, this information appears in CONTENT tags under a PIU tag. Although the information does not appear with the traditional comment indicator (* in column one), playback ignores the PIU block of tags. This option supports debugging VTAM applications. To enable this option, supply this tag with a value of 'YES'.
Inc_SNA_SVC_Trans
Writes special APPC conversations used by subsystems such as VTAM and CICS into the scripts. For example, the Change Number of Session (CNOS) and Exchange Log Name (XLN) transactions appear in the script if you select this option. These conversations use the following logmodes: SNASVCMG, CPSVCMG, or CPSVRMGR. This option support application debugging and does not impact playback. To enable this option, supply this tag with a value of 'YES'.
Conversation Log Tags
The batch interface writes the conversation log into a member of a PDS or PDSE. This block of tags defines the attributes of the PDS(E). It is required if you supplied a value a value of 'YES' on the Record_Conv_Log tag.
The following parameters are Conversation_Log sub-parameters. Supply the applicable parameters between the opening and closing Conversation_Log tags.
Dataset
The PDS(E) to contain the conversation log. This is a required parameter. It accepts up to 44 characters.
APPC Global Recording and Scripts 2-33
Member_Prefix
One to six character prefix that, in conjunction with the member suffix, forms the member name for the conversation log. This is a required parameter.
Member_Suffix
A numeric value that, in conjunction with the member prefix, forms the member name for the conversation log. The batch interface increments this value each time it creates a new member. For example, if you save all of your conversation logs to the same dataset, it increments this value to create a unique member name each time you generate a new log, unless you elect to Replace_Members, discussed next. Supply a suffix that in combination with the prefix equals eight characters.
– If you supply a suffix that is too short, the batch interface pads the suffix with zeros to the left. For example, if the prefix is OES and the suffix is 10, the first script member name is OES00010, and the next member is OES00011.
– If you supply a suffix that is too long, the batch interface truncates the digits on the left. For example, if you enter CONLOG for the prefix and 1234 for the suffix, the first script member is CONLOG34, and the next member is CONLOG35.
This is a required parameter. It accepts up to seven digits.
Replace_Members
Overwrites existing members that have the same names as those specified with the Dataset, Member_Prefix, and Member_Suffix tags.
To enable this option, supply this tag with a value of 'YES'. If you omit this tag or supply it with a value of 'NO', the batch interface does not overwrite existing members.
Allocation
Allocation parameters for the conversation log dataset. If you do not supply allocation parameters and the specified dataset does not exist, the batch interface allocates it with default values set by the installer. Generally, the default values are appropriate. However, you can override any or all of the default parameters by using the following Allocation sub-parameters.
Supply the applicable parameters between the opening and closing Allocation tags.
Management_Class
The management class to apply to the new dataset. Management classes are defined by the storage administrator at your site.
Storage_Class
The storage class to apply to the new dataset. Storage classes are defined by the storage administrator at your site.
Volume_Serial
The serial number of the volume where the dataset is to be stored.
Device_Type
The type of device that the dataset is to be stored on. Can be a generic unit such as 'SYSDA'.
Data_Class
The data class to apply to the new dataset. Data classes are defined by the storage administrator at your site.
Space_Units
2-34 Hiperstation for Mainframe Servers User Guide
The type of units used to store the data. Valid values are: TRKS (Tracks), CYLS (Cylinders), BLKS (Blocks), BYTES, KB (kilobytes), or MB (megabytes). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
Primary_Quantity
The number of space units to allocate initially. After Global Recording fills the primary quantity, it allocates the secondary quantity.
Secondary_Quantity
The number of space units to allocate after the primary quantity is full.
Directory_Blocks
The number of blocks to use for a PDS directory. If the dataset is a PDSE, the batch interface ignores this value.
Block_Size
The maximum length, in bytes, of the blocks of data that the system reads in as it processes a dataset.
Record_Length
The maximum length, in bytes, provided for each record in the dataset. Conversation log datasets must be minimally 105 bytes. The record length must be at least four less than the block size.
Dataset_Name_Type
The type of dataset to contain the scripts. Supply this tag with a value of 'PDS' or 'LIBRARY' (PDSE). If you omit this tag, the batch interface allocates the script file as a PDS.
Combined Detail Tags
If you elected to store the detail and the script separately, the batch interface writes each script’s detail to a separate member of a PDS or PDSE. This block of tags defines the attributes of the PDS(E). It is required if you supplied a value of 'COMBINED' on the Detail_Store_Type tag and a value of 'YES' on the Record_Detail tag.
The following parameters are Combined_Detail sub-parameters. Supply the applicable parameters between the opening and closing Combined_Detail tags.
Dataset
The PDS(E) to contain the detail data. This is a required parameter. It accepts up to 44 characters.
Member_Prefix
One to six character prefix that, in conjunction with the member suffix, forms the member name for the detail data associated with each script created. This is a required parameter.
Member_Suffix
A numeric value that, in conjunction with the member prefix, forms the member name for each detail dataset created. The batch interface increments this value each time it creates a new detail data member. Supply a suffix that in combination with the prefix equals eight characters.
– If you supply a suffix that is too short, the batch interface pads the suffix with zeros to the left. For example, if the prefix is OES and the suffix is 10, the first script member name is OES00010, and the next member is OES00011.
– If you supply a suffix that is too long, the batch interface truncates the digits on the left. For example, if you enter DETAIL for the prefix and 1234 for the suffix, the first script member is DETAIL34, and the next member is DETAIL35.
APPC Global Recording and Scripts 2-35
This is a required parameter. It accepts up to seven digits.
Replace_Members
Overwrites existing members that have the same names as those specified with the Dataset, Member_Prefix, and Member_Suffix tags.
To enable this option, supply this tag with a value of 'YES'. If you omit this tag or supply it with a value of 'NO', the batch interface does not overwrite existing members.
DDName
Data definition name that links the APPC verbs with the associated detail data when the script and details are stored separately. Hiperstation for Mainframe Servers uses this name to locate the appropriate detail data during playback. This is a required tag. Supply a one to eight character DD name.
Allocation
Allocation parameters for the detail dataset. If you do not supply allocation parameters and the specified dataset does not exist, the batch interface allocates it with default values set by the installer. Generally, the default values are appropriate. However, you can override any or all of the default parameters by using the following Allocation sub-parameters.
Supply the applicable parameters between the opening and closing Allocation tags.
Management_Class
The management class to apply to the new dataset. Management classes are defined by the storage administrator at your site.
Storage_Class
The storage class to apply to the new dataset. Storage classes are defined by the storage administrator at your site.
Volume_Serial
The serial number of the volume where the dataset is to be stored.
Device_Type
The type of device that the dataset is to be stored on. Can be a generic unit such as 'SYSDA'.
Data_Class
The data class to apply to the new dataset. Data classes are defined by the storage administrator at your site.
Space_Units
The type of units used to store the data. Valid values are: TRKS (Tracks), CYLS (Cylinders), BLKS (Blocks), BYTES, KB (kilobytes), or MB (megabytes). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
Primary_Quantity
The number of space units to allocate initially. After Global Recording fills the primary quantity, it allocates the secondary quantity.
Secondary_Quantity
The number of space units to allocate after the primary quantity is full.
Directory_Blocks
The number of blocks to use for a PDS directory. If the dataset is a PDSE, the batch interface ignores this value.
Block_Size
2-36 Hiperstation for Mainframe Servers User Guide
The maximum length, in bytes, of the blocks of data that the system reads in as it processes a dataset.
Record_Length
The maximum length, in bytes, provided for each record in the dataset. Detail datasets must be minimally 105 bytes. The record length must be at least four less than the block size.
Dataset_Name_Type
The type of dataset to contain the scripts. Supply this tag with a value of 'PDS' or 'LIBRARY' (PDSE). If you omit this tag, the batch interface allocates the script file as a PDS.
Inbound Detail Tags
If you elected to store inbound and outbound detail separately, the batch interface writes each script’s inbound detail to a separate member of a PDS or PDSE. This block of tags defines the attributes of the PDS(E). It is required if you supplied a value of 'SPLIT' on the Detail_Store_Type tag and a value of 'YES' on the Record_Detail tag.
The following parameters are Inbound_Detail sub-parameters. Supply the applicable parameters between the opening and closing Inbound_Detail tags.
Dataset
The PDS(E) to contain the inbound detail data. This is a required parameter. It accepts up to 44 characters.
Member_Prefix
One to six character prefix that, in conjunction with the member suffix, forms the member name for the inbound detail data associated with each script created. This is a required parameter.
Member_Suffix
A numeric value that, in conjunction with the member prefix, forms the member name for each inbound detail dataset created. The batch interface increments this value each time it creates a new detail data member. Supply a suffix that in combination with the prefix equals eight characters.
– If you supply a suffix that is too short, the batch interface pads the suffix with zeros to the left. For example, if the prefix is OES and the suffix is 10, the first script member name is OES00010, and the next member is OES00011.
– If you supply a suffix that is too long, the batch interface truncates the digits on the left. For example, if you enter INBDET for the prefix and 1234 for the suffix, the first script member is INBDET34, and the next member is INBDET35.
This is a required parameter. It accepts up to seven digits.
Replace_Members
Overwrites existing members that have the same names as those specified with the Dataset, Member_Prefix, and Member_Suffix tags. This setting applies to both inbound and outbound detail data members.
To enable this option, supply this tag with a value of 'YES'. If you omit this tag or supply it with a value of 'NO', the batch interface does not overwrite existing members.
DDName
Data definition name that links the APPC verbs with the associated detail data when the script and details are stored separately. Hiperstation for Mainframe Servers uses this name to locate the appropriate detail data during playback. This is a required tag. Supply a one to eight character DD name.
APPC Global Recording and Scripts 2-37
Allocation
Allocation parameters for the inbound detail dataset. If you do not supply allocation parameters and the specified dataset does not exist, the batch interface allocates it with default values set by the installer. Generally, the default values are appropriate. However, you can override any or all of the default parameters by using the following Allocation sub-parameters.
Supply the applicable parameters between the opening and closing Allocation tags.
Management_Class
The management class to apply to the new dataset. Management classes are defined by the storage administrator at your site.
Storage_Class
The storage class to apply to the new dataset. Storage classes are defined by the storage administrator at your site.
Volume_Serial
The serial number of the volume where the dataset is to be stored.
Device_Type
The type of device that the dataset is to be stored on. Can be a generic unit such as 'SYSDA'.
Data_Class
The data class to apply to the new dataset. Data classes are defined by the storage administrator at your site.
Space_Units
The type of units used to store the data. Valid values are: TRKS (Tracks), CYLS (Cylinders), BLKS (Blocks), BYTES, KB (kilobytes), or MB (megabytes). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
Primary_Quantity
The number of space units to allocate initially. After Global Recording fills the primary quantity, it allocates the secondary quantity.
Secondary_Quantity
The number of space units to allocate after the primary quantity is full.
Directory_Blocks
The number of blocks to use for a PDS directory. If the dataset is a PDSE, the batch interface ignores this value.
Block_Size
The maximum length, in bytes, of the blocks of data that the system reads in as it processes a dataset.
Record_Length
The maximum length, in bytes, provided for each record in the dataset. Detail datasets must be minimally 105 bytes. The record length must be at least four less than the block size.
Dataset_Name_Type
The type of dataset to contain the scripts. Supply this tag with a value of 'PDS' or 'LIBRARY' (PDSE). If you omit this tag, the batch interface allocates the script file as a PDS.
2-38 Hiperstation for Mainframe Servers User Guide
Outbound Detail Tags
If you elected to store inbound and outbound detail separately, the batch interface writes each script’s inbound detail to a separate member of a PDS or PDSE. This block of tags defines the attributes of the PDS(E). It is required if you supplied a value of 'SPLIT' on the Detail_Store_Type tag and a value of 'YES' on the Record_Detail tag.
The following parameters are Outbound_Detail sub-parameters. Supply the applicable parameters between the opening and closing Outbound_Detail tags.
Dataset
The PDS(E) to contain the outbound detail data. This is a required parameter. It accepts up to 44 characters.
Member_Prefix
One to six character prefix that, in conjunction with the member suffix, forms the member name for the outbound detail data associated with each script created. This is a required parameter.
Member_Suffix
A numeric value that, in conjunction with the member prefix, forms the member name for each outbound detail dataset created. The batch interface increments this value each time it creates a new detail data member. Supply a suffix that in combination with the prefix equals eight characters.
– If you supply a suffix that is too short, the batch interface pads the suffix with zeros to the left. For example, if the prefix is OES and the suffix is 10, the first script member name is OES00010, and the next member is OES00011.
– If you supply a suffix that is too long, the batch interface truncates the digits on the left. For example, if you enter INBDET for the prefix and 1234 for the suffix, the first script member is INBDET34, and the next member is INBDET35.
This is a required parameter. It accepts up to seven digits.
DDName
Data definition name that links the APPC verbs with the associated detail data when the script and details are stored separately. Hiperstation for Mainframe Servers uses this name to locate the appropriate detail data during playback. This is a required tag. Supply a one to eight character DD name.
Allocation
Allocation parameters for the outbound detail dataset. If you do not supply allocation parameters and the specified dataset does not exist, the batch interface allocates it with default values set by the installer. Generally, the default values are appropriate. However, you can override any or all of the default parameters by using the following Allocation sub-parameters.
Supply the applicable parameters between the opening and closing Allocation tags.
Management_Class
The management class to apply to the new dataset. Management classes are defined by the storage administrator at your site.
Storage_Class
The storage class to apply to the new dataset. Storage classes are defined by the storage administrator at your site.
Volume_Serial
The serial number of the volume where the dataset is to be stored.
Device_Type
APPC Global Recording and Scripts 2-39
The type of device that the dataset is to be stored on. Can be a generic unit such as 'SYSDA'.
Data_Class
The data class to apply to the new dataset. Data classes are defined by the storage administrator at your site.
Space_Units
The type of units used to store the data. Valid values are: TRKS (Tracks), CYLS (Cylinders), BLKS (Blocks), BYTES, KB (kilobytes), or MB (megabytes). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
Primary_Quantity
The number of space units to allocate initially. After Global Recording fills the primary quantity, it allocates the secondary quantity.
Secondary_Quantity
The number of space units to allocate after the primary quantity is full.
Directory_Blocks
The number of blocks to use for a PDS directory. If the dataset is a PDSE, the batch interface ignores this value.
Block_Size
The maximum length, in bytes, of the blocks of data that the system reads in as it processes a dataset.
Record_Length
The maximum length, in bytes, provided for each record in the dataset. Detail datasets must be minimally 105 bytes. The record length must be at least four less than the block size.
Dataset_Name_Type
The type of dataset to contain the scripts. Supply this tag with a value of 'PDS' or 'LIBRARY' (PDSE). If you omit this tag, the batch interface allocates the script file as a PDS.
Check the Status of Existing Requests
Use the KEYS function to:
• Check the status of a specific Global Recording request.
• Generate status information for all of your existing Global Recording requests. You can also use this feature to locate a forgotten request ID.
Each request has an associated request key that consists of the following information:
• Protocol — The protocol of the activity that the request is to record — APPC for APPC requests and LU2 for 3270 or LU0 requests.
• Status — The status of the request (Stopped, Active, or Disabled).
• Request ID — The six byte ID assigned to the request.
• Capture File — Name of the capture file (also known as Repository Dataset).
This is the same information that the batch interface returns when you create a request. In fact, if you are checking the status of a specific request, use the returned request key as the input for the KEYS function.
Use SQQFSAMP member DCIJCL (Figure 2-14 on page 2-18) to execute the KEYS function.
2-40 Hiperstation for Mainframe Servers User Guide
1. Insert job statement information at the top of the sample.
2. Make sure that the UPROCS statement points to the procedures library that contains DCIPROC.
3. Keys are written to the location defined by the FEEDBACK DD statement. To save the keys in your personal library, specify a sequential dataset, PDS(E) and member, or a generation data group (GDG).
Note: Allocate the GDG with a fixed block record format and an 80 byte record length.
4. On the SYSTSIN DD statement, specify KEYS on the PARM keyword.
5. KEYS function parameters are also defined in XML. The parameters required differ depending on the information you need to produce.
– To check the status of a specific request, the KEYS function requires the protocol, request ID, and capture file associated with the request. On the SYSIN DD, either supply the name of the dataset containing the request key or enter the parameters in-line. For example:
// SYSIN DD * <APPC> <Request_ID> C'QA_REQ’ </Request_ID> <Capture_File> <Dataset>‘USR2503.APPC.QA.REC??’ </Dataset> </Capture_File> </APPC>
If the ADD request FEEDBACK went to SYSOUT, copy and paste the request key from the JES job log.
– To generate status information for all of the existing APPC requests that you created, the KEYS function requires the protocol parameter. For example:
// SYSIN DD * <APPC> </APPC>
6. Submit the job.
Manage Existing Requests
Use the batch interface request management functions to:
• Stop recording.
• Delete or update a request.
• Restart an inactive request.
• Disable a request to prevent it from automatically restarting.
• Switch the capture file segment to review captured activity without interrupting recording.
All of these functions require information found in the request key that the batch interface returns when you create a request. If you do not have the request key but you know the request ID and capture file name, write the parameters directly into the job. If you do not know this information, use the KEYS function to produce a list of existing requests. See “Check the Status of Existing Requests” on page 2-39.
Use SQQFSAMP member DCIJCL (Figure 2-14 on page 2-18) to execute request management functions.
APPC Global Recording and Scripts 2-41
Note: DCIJCL contains the FEEDBACK DD statement that supports request creation. Request management functions do not write output to this DD. To see request modification messages, review the PRGLOG DD in the JES job log.
1. Insert job statement information at the top of the sample.
2. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
3. On the SYSTSIN DD statement, specify one of the following request management functions on the PARM keyword:
CANCEL Cancels and deletes the request. All buffered information is also deleted, which may result in partially recorded business transactions. To avoid losing important data, STOP the request first. Wait until the request terminates before issuing the CANCEL command.
Use ISPF file management tools to delete any repository or repository segments created by the request.
FORCE Terminates recording immediately and deactivates the request. This option may result in partially recorded business transactions. To terminate capture of new sessions, but allow capture to finish for in-flight sessions, use STOP instead.
If a request contains script criteria and the suspend script creation option is not selected, script creation begins immediately.
STOP Stops capture of new sessions and deactivates the request. Global Recording continues to capture all sessions that are in-flight at the time the STOP is issued.
RESTART Restarts the request. The request becomes active as soon as the time frame specified within the request is met. Use this option to activate an inactive request.
DISABLE Disables the request. When the Global Recording started task is brought up, all requests, except disabled requests, are restarted.
Note: STOP or FORCE the request prior to disabling it.
SWITCH Closes the capture file segment that is currently being written and opens the next segment. This option is only available if the capture file dataset name contains a wildcard character (* or ?).
4. The request management functions require the protocol, request ID, and capture file associated with the request. On the SYSIN DD, either supply the name of the dataset containing the request key or enter the parameters in-line. For example:
// SYSIN DD * <APPC> <Request_ID> C'QA_REQ’ </Request_ID> <Capture_File> <Dataset>‘USR2503.APPC.QA.REC??’ </Dataset> </Capture_File> </APPC>
5. Submit the job.
Note: The batch interface does not supply an update function. Use a combination of other functions to modify a request.
2-42 Hiperstation for Mainframe Servers User Guide
1. Use the VIEW function to retrieve the parameters from the request. See “Retrieve the Parameters of an Existing Request” on page 2-42.
2. Modify the parameters. See “Global Recording Request Parameters” on page 2-20 for parameter definitions.
3. Use the STOP, FORCE, or CANCEL functions to stop recording.
4. If you use STOP or FORCE to stop recording, wait for recording to terminate. Then use CANCEL to delete the request.
5. Use the ADD function to create a new request using the modified parameters.
Execute steps 3-5 as separate jobs or separate steps within a single job.
Retrieve the Parameters of an Existing Request
The VIEW function writes the parameters from a specified request to a location you define. Use it to:
• Review or validate a request’s parameters.
• Save time when adding a new request. Rather than writing Global Recording request parameters from scratch, retrieve the parameters from a similar request and modify them to meet your needs.
• Update a request. Retrieve the parameters from the request you need to update. Modify the parameters. STOP the request. CANCEL the request. ADD a new request using the modified parameters.
Note: If there are no existing requests, you do not specify a request ID, or the specified request ID does not exist, the VIEW function produces a request parameters skeleton, which is a complete set of parameters with default values.
Use SQQFSAMP member DCIJCL (Figure 2-14 on page 2-18) to execute the VIEW function.
1. Insert job statement information at the top of the sample.
2. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
3. The batch interface writes VIEW function output to the location specified on the FEEDBACK DD. To save the VIEW output in your personal library, specify a sequential dataset, PDS(E) and member, or a generation data group (GDG).
Note: Allocate the GDG with a fixed block record format and an 80-byte record length.
4. On the SYSTSIN DD statement, specify VIEW on the PARM keyword.
5. When retrieving parameters from a specific request, the VIEW function requires the protocol, request ID, and capture file associated with the request. On the SYSIN DD, either supply the name of the dataset containing the request key or enter the parameters in-line. For example:
// SYSIN DD * <APPC> <Request_ID> C'QA_REQ’ </Request_ID> <Capture_File> <Dataset>‘USR2503.APPC.QA.REC??’ </Dataset> </Capture_File> </APPC>
6. Submit the job.
APPC Global Recording and Scripts 2-43
Generate a Request Parameters Skeleton
If there are no existing requests, you do not specify a request ID, or the specified request ID is not found, the VIEW function produces a request parameters skeleton. A request parameters skeleton is a complete set of Global Recording parameters with default values. Generate a skeleton to:
• Save time when creating a new request. • See all of the available parameters.• Reference the syntax of a particular tag.
Use SQQFSAMP member DCIJCL (Figure 2-14 on page 2-18) to execute the VIEW function.
1. Insert job statement information at the top of the sample.
2. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
3. The batch interface writes VIEW function output to the location specified on the FEEDBACK DD. To save the VIEW output in your personal library, specify a sequential dataset, PDS(E) and member, or a generation data group (GDG).
Note: Allocate the GDG with a fixed block record format and an 80 byte record length.
4. On the SYSTSIN DD statement, specify VIEW on the PARM keyword.
5. On the SYSIN DD, supply the opening and closing protocol tags for the type of request you need to create. For 3270 or LU0 requests:
// SYSIN DD * <LU2> </LU2>
For APPC requests:
// SYSIN DD * <APPC> </APPC>
Create Scripts
To maximize flexibility, the batch interface provides a script create function allowing you to:
• Generate scripts at any time. For example, if you are unsure of script creation criteria when you create the recording request, suspend script creation and run it later.
• Schedule script creation to run when maximum system resources are available. For example, if you are recording large volumes of traffic, schedule a script creation job to run in the evening.
• Create scripts with parameters other than the parameters specified in the recording request. For example, the script criteria in the recording request are set up to generate stress testing scripts. However, you also need to generate unit testing scripts. Run an independent script create with the appropriate criteria.
• Create scripts before recording ends, if the capture file is segmented. For example, to create a script for a recently recorded session, SWITCH repository segments and run a script creation job against the closed segment.
To create scripts with the batch interface:
1. Define the script creation parameters. See “Script Creation Parameters” on page 2-44.
2-44 Hiperstation for Mainframe Servers User Guide
2. Use SQQFSAMP member SCJCL (Figure 2-16) to execute the SCRIPTS function.
3. Insert job statement information at the top of the sample. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
4. On the SYSTSIN DD statement, make sure SCRIPTS is specified on the PARM keyword.
5. On the SYSIN DD statement, either supply the name of the dataset containing the script creation parameters or enter the parameters in-stream.
Notes:
a. In-stream parameters cannot exceed 80 bytes. If you edited the parameters on a PC and copied them back to a dataset exceeding 80 bytes, point the DD to the dataset rather than pasting the parameters into the job.
b. If you plan to submit the job with a REXX queue command, place the parameters in an external file and remove all blank lines. Otherwise, parameter values are converted to uppercase and you may receive error messages.
Figure 2-16. SQQFSAMP Member SCJCL — Sample JCL to Create Scripts
********************************* Top of Data ********************************** //* INSERT JOB CARD HERE............................................... /*JOBPARM SYSAFF=sysn //********************************************************************* //* JCL TO CREATE 3270 OR APPC SCRIPTS INDEPENDENT FROM THE USER * //* INTERFACE. * //* * //* UPROCS: DATASET THAT CONTAINS THE DCIPROC. * //* * //* * //* SYSTSIN: TSO BACKGROUND INPUT STREAM. * //* ISPSTART PGM(QACDCIP) - EXECUTE THE DCI PROGRAM * //* PARM(command) - IS THE COMMAND PASSED TO THE DCI * //* * //* SYSIN: XML INPUT. * //* * //********************************************************************* //UPROCS JCLLIB ORDER=('COMPWARE.QQF800.SQQFSAMP') <-REVIEW //DCI EXEC PROC=DCIPROC //SYSTSIN DD * ISPSTART PGM(QACDCIP) PARM(SCRIPTS) /* //SYSIN DD DISP=SHR,DSN=COMPWARE.QQF800.SQQFSAMP(SCAPPC) <-REVIEW ******************************** Bottom of Data ********************************
6. Schedule or submit the job.
Script Creation Parameters
Like Global Recording request parameters, Script Creation parameters are defined in XML. For syntax rules, see “Global Recording Request Parameter Syntax” on page 2-18.
A script creation job requires a protocol parameter, capture file specification parameters, and script criteria parameters. Recording requests contain all of these parameters. You can use the parameters from an existing recording request as the input for a script creation job. For example, if script criteria was specified in the recording request, but script creation was suspended, use the VIEW function to retrieve the parameters (page 2-42). Then use the output from the VIEW as the input for the script creation job. The script create function ignores irrelevant parameters.
If you intend to modify the script criteria or the request does not contain script criteria, start with sample SCAPPC located in SQQFSAMP.
Store the parameters in a sequential dataset or a PDS member in your personal library or write them directly in the JCL. Use a standard file editing tool such as ISPF Edit to write or modify the parameters.
APPC Global Recording and Scripts 2-45
Notes:
1. XML tags are case-sensitive. Make sure the ISPF Caps function is set to off when editing the parameters. Type CAPS OFF on the Command line and press Enter.
2. To work with a parameters file on the PC:
– Use the IBM utility IEBGENER to copy the dataset into an HFS file.
– FTP the file to the PC. To avoid EBCDIC to ASCII translation issues, transfer the file as 'text'.
Use an XML editor, such as Notepad, to edit the tags. Pay attention to syntax interpretation. The Global Recording batch interface may not recognize tags that have been reformatted based on the viewer’s interpretation. For example, some editors format tags that have no values as follows <tag/>. Encase blank values in single quotes to avoid this particular interpretation issue. All tags must conform to the syntax rules described on page 2-18.
To avoid record truncation when transferring the parameters back to the mainframe, copy them into a fixed block dataset with a logical record length that supports the longest record.
This section provides an illustration of sample SCAPPC (Figure 2-17) and defines all of the script creation parameters available.
Parameter hierarchy is shown in Figure 2-17 and defined within the parameter definitions.
2-46 Hiperstation for Mainframe Servers User Guide
Figure 2-17. SQQFSAMP Member SCAPPC — Sample Script Creation Parameters
<APPC> <Capture_File> <Dataset> 'COMPWARE.SAMPLE.CAPTURE.FILE*' </Dataset> <First_Number> '1' </First_Number> <Last_Number> '20' </Last_Number> </Capture_File> <Recording_Options> <!-- Valid 'Event_Notification' values are YES, NONE, or ERROR --> <Event_Notification> 'NONE' </Event_Notification> </Recording_Options> <Script_Criteria> <Description> 'Compuware Independent Script Create' </Description> <Recording_Script> <Dataset> 'COMPWARE.SAMPLE.SCRIPTS' </Dataset> <Member_Prefix> 'SCR' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <Replace_Members> 'NO' </Replace_Members> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Recording_Script> <Script_Create_Options> <!-- Valid 'Detail_Store_Type' values; MERGED, COMBINED, SPLIT --> <Detail_Store_Type> 'SPLIT' </Detail_Store_Type> <Record_Conv_Log> 'YES' </Record_Conv_Log> <Record_Script> 'YES' </Record_Script> <Record_Detail> 'YES' </Record_Detail> <Suppress_Time_Stamps> 'NO' </Suppress_Time_Stamps> <Tags_Short_CPIC> 'NO' </Tags_Short_CPIC> <PIU_As_Comments> 'NO' </PIU_As_Comments> <Inc_SNA_SVC_Trans> 'NO' </Inc_SNA_SVC_Trans> </Script_Create_Options>
APPC Global Recording and Scripts 2-47
<Conversation_Log> <Dataset> 'COMPWARE.SAMPLE.CNVLOG' </Dataset> <Member_Prefix> 'LOG' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <Replace_Members> 'NO' </Replace_Members> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Conversation_Log> <Combined_Detail> <Dataset> 'COMPWARE.SAMPLE.DETAIL.COMBINED' </Dataset> <Member_Prefix> 'CDT' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <Replace_Members> 'NO' </Replace_Members> <DDName> 'DETAILCB' </DDName> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Combined_Detail>
2-48 Hiperstation for Mainframe Servers User Guide
<Inbound_Detail> <Dataset> 'COMPWARE.SAMPLE.DETAIL.INBOUND' </Dataset> <Member_Prefix> 'IDT' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <Replace_Members> 'YES' </Replace_Members> <DDName> 'DETAILIB' </DDName> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Inbound_Detail> <Outbound_Detail> <Dataset> 'COMPWARE.SAMPLE.DETAIL.OUTBOUND' </Dataset> <Member_Prefix> 'ODT' </Member_Prefix> <Member_Suffix> '1' </Member_Suffix> <DDName> 'DETAILOB' </DDName> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Directory_Blocks> '25' </Directory_Blocks> <Block_Size> '9004' </Block_Size> <Record_Length> '256' </Record_Length> <!-- Valid 'Dataset_Name_Type' values are PDS or LIBRARY --> <Dataset_Name_Type> 'PDS' </Dataset_Name_Type> </Allocation> </Outbound_Detail> </Script_Criteria> </APPC>
APPC Global Recording and Scripts 2-49
Protocol Parameter Tag
APPC
Identifies the type of scripts to create. This is a parent tag to all other parameters described in this section. Begin and end the XML input stream with an opening and closing APPC tag.
Capture File Specification Tags
Capture_File
Specifies the dataset containing the captured information.
The following parameters are Capture_File sub-parameters. Supply the applicable parameters between the opening and closing Capture_File tags.
Dataset
The name of the dataset that contains the captured information. This is a required parameter.
If the capture file is segmented, supply a First_Number and Last_Number tag.
First_Number
The first value to use for resolving the wildcard characters specified on the Dataset tag. If the dataset name does not contain a wildcard character, this tag is unnecessary.
Last_Number
The last value to use for resolving wildcard characters specified on the Dataset tag. If the dataset name does not contain a wildcard character, this tag is unnecessary.
Event Notification Tags
Recording_Options
Provides the Event_Notification setting. This function uses the same event notification feature as the recording request ADD function. This is why the Event_Notification tag is nested within opening and closing Recording _Options tags. If you omit this block of tags, the batch interface sends all script creation messages to your TSO session.
Event_Notification
Defines the type of script creation messages sent to your TSO session. Supply a value of:
• 'ERROR' to receive error messages only.
• 'YES' to receive script creation status and error messages.
• 'NONE' to disable event notification.
If you are generating a large number of scripts, consider disabling this option or selecting error notification to reduce the number of messages you receive. Regardless of this setting, the batch interface sends a copy of all script creation messages to the JESMSGLG DD in the JES Job Log. The SYSPRINT DD summarizes script creation job messages. Access the job log at your convenience.
Note: To see the messages that the batch interface produces, such as parameter verification messages or the return code for the script creation job, review the PRGLOG DD in the JES job log. See “Troubleshoot Failed Jobs” on page 2-50.
2-50 Hiperstation for Mainframe Servers User Guide
Script Criteria Tags
Defines script creation parameters. These are the same parameters as the script criteria parameters described in “Global Recording Request Parameters”. See “General Script Criteria Tags” on page 2-29 through “Outbound Detail Tags” on page 2-38.
Troubleshoot Failed Jobs
An ISPF background task initiates and terminates the Global Recording batch interface. ISPF issues a return code for the background task. Do not confuse this return code with the Global Recording batch interface’s return code. The batch interface writes its return code to the PRGLOG DD. If your installer accepted the default, PRGLOG resides in the JES job log.
The rest of this section provides information to help you troubleshoot recording request errors and script create errors.
Recording Request Errors
The Global Recording batch interface adds and modifies recording requests based on the parameters you supply. The Global Recording started task executes the requests. The batch interface reports status and error messages pertaining to request creation or modification, while the started task reports status and error messages pertaining to recording.
The batch interface reports its status and error messages to the PRGLOG in the JES job log.
The started task writes recording error and status message in the JES job log and SYSTEM log. However, the logs contain messages from all recording requests. To see the message pertaining to your requests, set the recording request Event_Notification parameter, discussed on page 2-29, to 'YES' or 'ERROR'. Global Recording sends the applicable messages to your TSO session.
Script Create Errors
The Global Recording batch interface initiates the script create function. If it cannot initiate script creation, it writes errors to the PRGLOG. For example, if a required parameter is missing or the syntax of a parameter is incorrect. Otherwise, it writes a single message to the PRGLOG indicating that script create completed with or without errors. If the message indicates that it completed with errors, review:
• JESMSGLG in the JES job log to see script creation status and error messages.
• SYSPRINT in the JES job log to see a script creation summary.
Generating a Capture Segment SummaryThe Capture Segment Summary report shows when recording began and ended for each segment of one or more specified capture repositories. Use it to help you identify the information contained in each segment. For example, if you need to script activity that was captured on Monday morning from 8:00 am to 12:00 pm, but you are not sure which repository segment contains the information, generate this report.
Import the report into a spreadsheet or database for easy manipulation. For example, generate the report against every repository on the system, import it into a spreadsheet, and use it as an index. Sort the spreadsheet by repository name or dates.
To generate a Capture Summary Report:
APPC Global Recording and Scripts 2-51
1. Locate sample member MCSREPT (Figure 2-18) in the Hiperstation samples library, SQQFSAMP, or in your site’s JCL library.
2. Insert job statement information at the top of the sample.
3. Make sure the STEPLIB DD statement points to the Hiperstation load library at your installation.
4. To write the report to a new or existing dataset, replace SYSOUT=* on the CAPSUM DD statement with the appropriate dataset information. The logical record length of the dataset must be minimally 132 bytes.
5. Supply report creation parameters after the SYSIN DD * statement. Place each parameter on a separate line. Parameter definitions follow Figure 2-18.
Figure 2-18. SQQFSAMP Member MCSREPT
********************************* Top of Data ********************************** //*....... JOB ...PLACE YOUR INSTALLATION'S JOBCARD HERE... //******************************************************************** //*---------------------------------------------------------------- * //* * //* HIPERSTATION MANAGE CAPTURE SEGMENTS REPORT EXECUTION * //* * //*---------------------------------------------------------------- * //******************************************************************** //* * //* THE FOLLOWING ITEM MUST BE CHANGED FOR SITE SPECIFICS: * //* * //* NOTE 1: NAME OF THE HIPERSTATION LOAD LIBRARY. * //* * //* SYSIN DD IS USED TO PROVIDE REPORT PARAMETERS * //* * //* NOTE 2: LIST THE REPORT PARAMETERS INCLUDING * //* THE REPOSITORY OR REPOSITORIES YOU WISH TO REPORT ON * //* * //******************************************************************** //REPORT EXEC PGM=MCSREPT //STEPLIB DD DISP=SHR,DSN=COMPWARE.QQF800.SQQFLOAD <==NOTE 1 //SYSPRINT DD SYSOUT=* //CAPSUM DD SYSOUT=* //SYSIN DD * <==NOTE 2 GMT DSN=USERID.TEST.MULTSEG.REPOSIT* FIRST=1 LAST=3 DSN=USERID.TEST.REPOSITX ******************************** Bottom of Data ********************************
– The optional NORECALL parameter prevents recall of migrated datasets for report creation. This parameter, if specified, must precede all DSN parameters.
– The optional GMT parameter reports timestamps in Greenwich Mean Time (GMT). If omitted, Hiperstation reports the time values based on the system’s local time. If you are reporting on repositories captured on systems in different time zones, include the GMT parameter to avoid confusion over time adjustment. For example, a repository that was captured at 8:00 AM EST is sent to an office in California. If the report is run in California without the GMT parameter, the start time shows 05:00:00 due to adjustment for the three hour difference in time zones. With the GMT parameter, the report shows 13:00:00 regardless of the system on which the report is generated. This parameter, if specified, must precede all DSN parameters.
– The DSN parameter specifies the name of the capture repository. To report on multiple segments of a given repository, specify the dataset name with the same wildcard characters as specified in the Global Recording request. Then supply the FIRST and LAST parameters. To report on multiple repositories, include a DSN parameter, and, if applicable, a FIRST and LAST parameter for each repository. The FIRST and LAST parameters must follow the dataset name to which they apply. For example,
2-52 Hiperstation for Mainframe Servers User Guide
DSN=USER25.MQ.REPOS?? FIRST=01 LAST=10 DSN=USER25.TCPIP.REPOS08 DSN=USER25.3270.REPOS?? FIRST=01 LAST=05
– The FIRST parameter is the first value used and the LAST parameter is the last value used to resolve the wildcards in the repository name specified on the preceding DSN parameter.
6. Submit the job.
Review the Report
Review the report with a file browsing tool such as ISPF Browse. If the report is large, consider importing it into a spreadsheet or database application for easy manipulation. For example, import it into a spreadsheet and sort by start time.
If you include the GMT parameter on the report creation job, ‘ALL TIMES GMT’ appears at the top of the start date and time column.
Figure 2-19. Capture Summary Report
HIPERSTATION - CAPTURE SEGMENT SUMMARY ALL TIMES GMT USER25.TEST1.REPOS01 12/21/06 20:08:23 12/21/06 20:10:14 USER25.TEST1.REPOS02 12/21/06 20:10:39 12/21/06 20:23:14 USER25.TEST1.REPOS03 12/21/06 20:23:18 12/21/06 20:31:35
Note: The reported timestamps reflect when the first and last records were written to each repository dataset. Records are written to a repository dataset when Global Recording flushes and processes the captured information from the ECSA buffers. Depending on the size of the buffers and the volume of traffic on your system, there may be a minor difference between the timestamps shown in the report and the actual transaction times shown in the scripts. If there is a significant difference, contact your Global Recording administrator or your installer. The Hiperstation Installation Guide provides instructions for tuning your buffer to optimize Global Recording performance. In addition, a recorded session may span multiple segments. If the activity you need to script is near the beginning or end of a given repository segment, script the neighboring segment as well.
Merging APPC Capture RepositoriesHiperstation for Mainframe Servers provides an MVS batch utility that combines the information in two or more specified repositories. It orders the activity by time stamp. If you need to generate scripts from multiple repositories, you can save time by merging the repositories first. For example, rather than generating scripts four times from repositories captured on four different systems (LPARs), merge the repositories and generate scripts once.
To merge two or more repositories:
1. Copy member SYSPLEX from the samples library, typically SQQFSAMP, to your personal JCL library.
2. Open SYSPLEX (Figure 2-20) with a standard editing tool such as ISPF Edit.
APPC Global Recording and Scripts 2-53
3. Place job statement information at the top of the sample.
4. Make sure the STEPLIB DD points to the Hiperstation load library and the C and C++ LE datasets at your installation.
5. On the REPIN DD statement, specify the repositories to be merged. Place each fully qualified repository dataset name on a separate line. If the repository is segmented, supply the repository name with the appropriate wildcard characters, followed by a space, then a ‘first’ value, a space, and a ‘last’ value. ‘First’ and ‘last’ are numeric values between 1 and 9999999. ‘First’ must be lower than ‘last’. These values are used to resolve the repository segment dataset names.
6. On the SYSIN DD statement, supply the job parameters, as shown in the sample, or the name of the dataset containing the job parameters. Whether the parameters are defined inline or in an external dataset, place each parameter on a separate line. For the parameters that require a value, follow the parameter name with a space, then an equals sign (=), another space, and then the value.
Parameter definitions follow Figure 2-20.
7. Submit or schedule the job. To submit the job immediately, type SUB on the Command line and press Enter.
Figure 2-20. Sample Repository Merging JCL: SYSPLEX
********************************* Top of Data ********************************** //*....... JOB ...PLACE YOUR INSTALLATION'S JOBCARD HERE... //********************************************************************* //********************************************************************* //SYSPLEX EXEC PGM=SYSPLEXM,REGION=0M,PARM='0' //STEPLIB DD DSN=COMPWARE.QQF800.SQQFLOAD,DISP=SHR // DD DISP=SHR,DSN=CEE.SCEECPP // DD DISP=SHR,DSN=CEE.SCEERUN //SYSPRINT DD SYSOUT=* //CEEDUMP DD SYSOUT=* //********************************************************************* //* REPIN IS WHERE THE REPOSITORY SETS TO BE MERGED ARE ENTERED. //* EACH SET IS ENTERED ON A NEW LINE WITH THE FORMAT: //* <DATASET_SPECIFICATION> <FIRST_INTEGER> <LAST_INTEGER> <IGNORED> //********************************************************************* //REPIN DD * COMPWARE.SYS1.REPOS1* 1 10 COMPWARE.SYS2.REPOS2* 1 10 COMPWARE.SYS3.REPOS3* 1 10 COMPWARE.SYS4.REPOS4* 1 10 /* //********************************************************************* //* REQUIRED: //* REP_MERGE = FULLY QUALIFIED REPOSITORY SET SPECIFICATION, USING //* * (ASTERISK) AND ? (QUESTION MARK) AS APPROPRIATE. //* EXAMPLE: USR2503.HTTP1*.REPOS //* OPTIONAL: //* FIRST = REPOSITORY SET SPECIFICATION FIRST NUMBER. DEFAULT 0. //* LAST = REPOSITORY SET SPECIFICATION LAST NUMBER. DEFAULT 0. //* REP_SPACE = CAPTURE FILE SPACE UNIT. MUST BE TRK(DEFAULT) OR CYL. //* REP_UNIT = CAPTURE FILE UNIT NAME. DEFAULT IS SYSDA. //* REP_PRI = CAPTURE FILE PRIMARY SPACE, IN CAP_SPACE UNITS. //* REP_SEC = CAPTURE FILE SECONDARY SPACE, IN CAP_SPACE UNITS. //* REP_STORCLAS = CAPTURE FILE SMS STORAGE CLASS - SYSTEM DEFAULT. //* REP_DATACLAS = CAPTURE FILE SMS DATA CLASS - SYSTEM DEFAULT. //* REP_MGMTCLAS = CAPTURE FILE SMS MANAGEMENT CLASS - SYSTEM DEFAULT. //* MAX_MSG_SIZE = MAXIMUM SIZE UNSEGMENTED REPOSITORY MESSAGE HANDLED //* BY CONVERTER. UNITS ARE 1K, DEFAULT IS 32 (32,768). //* TCP = ALLOWS TCP REPOSITORIES TO BE USED. APPC AND MQ //* ARE ALSO VALID VALUES. DEFAULT MQ. //********************************************************************* //SYSIN DD * REP_MERGE = COMPWARE.MERGED.NEWREP* /* ******************************** Bottom of Data ********************************
2-54 Hiperstation for Mainframe Servers User Guide
SYSPLEX Job Input Parameters
REP_MERGE
The dataset to contain the merged repositories. This parameter is required. Specify a fully qualified repository dataset name. The utility dynamically allocates this dataset, so be sure to supply a dataset name that does not already exist. To segment the new repository, specify the dataset name with the appropriate wildcard characters and supply a FIRST and LAST parameter (discussed next). For information regarding repository name wildcard characters, see “In the Repository Dataset field, enter the name of the dataset to use for storing captured information. To create a segmented repository, use the following wildcard characters in the dataset name field and define a range with the First and last number fields:” on page 2-4.
FIRST
The first value to use for resolving the wildcard characters specified in the repository name. Supply a value between 1 and 999999999. The default value is 0. If the specified repository name does not contain a wildcard character (* or ?), do not supply this parameter.
LAST
The last value to use for resolving the wildcard characters specified in the repository name. Supply a value between 1 and 999999999. The default value is 0. If the specified repository name does not contain a wildcard character (* or ?), do not supply this parameter.
REP_SPACE
The type of units used to store the data. Valid values are: TRK (Tracks) or CYL (Cylinders). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
REP_UNIT
The type of device that the dataset is to be stored on. This value can be up to eight characters long. The default value, if the parameter is not specified, is SYSDA.
REP_PRI
The number of space units (tracks or cylinders) to allocate initially. Specify a value between 1 and 99999. If not specified, the default value of 1 is used. After the utility fills the primary quantity, it allocates the secondary quantity (REP_SEC).
REP_SEC
The number of space units to allocate after the primary quantity is full. Specify a value between 1 and 99999. If not specified, the default value of 1 is used.
REP_STORCLAS
The storage class to apply to the output dataset as defined by the storage administrator at your site. This optional parameter has no default value.
REP_DATACLAS
The data class to apply to the output dataset as defined by the storage administrator at your site. Your storage administrator provides default values for dataset definition parameters such as SPACE, RECFM, and LRECL. This optional parameter has no default value.
REP_MGMTCLAS
The management class to apply to the output dataset as defined by the storage administrator at your site. Your storage administrator controls attributes of SMS managed datasets such as migration, back up, compression, retention period, and space reclamation. This optional parameter has no default value.
APPC Global Recording and Scripts 2-55
MAX_MSG_SIZE
The maximum size of an application message handled by this utility. Specify the size, in kilobytes, of the largest message expected. Valid values are 1 to 99999. For example, MAX_MSG_SIZE 64 specifies that the first 65,536 bytes of each message will be processed. This is an optional parameter. If not specified, the utility uses 32K as the default.
TCP/APPC/MQ
The record-type selection parameter. This utility supports Hiperstation for Mainframe Servers and Hiperstation for WebSphere MQ, so you must specify the type of record to select from the input repository, in this case APPC. If you omit the parameter, the utility uses the default value of MQ.
2-56 Hiperstation for Mainframe Servers User Guide
3-1
Chapter 3.
3APPC Unattended Processing Chap 3Hiperstation for Mainframe Servers offers unattended playback for batch testing applications that use APPC. This function requires unattended processing statements and JCL to run the unattended statements. Hiperstation for Mainframe Servers also offers a facility that generates these statements and the necessary JCL for you. This chapter explains how to use Unattended Processing to generate:
• CONTROL statements• ALLOCATE/ACCEPT statements• SCRIPT statements• COMPANY statements• CACHE INCLUDE and CACHE EXCLUDE statements
It also explains how to build the JCL necessary for running the unattended processing statements. Chapter 4, “Unattended Playback of APPC Scripts” explains how to run an unattended playback, describes unattended playback statements, and provides JCL examples for common unattended testing functions.
Note: You can also generate 3270 statements from the Unattended Processing facility in Hiperstation for Mainframe Servers. Append APPC statements to previously generated 3270 statements or vice versa. For detailed information on generating 3270 statements, see the Hiperstation for VTAM User Guide.
Starting Unattended ProcessingStart Unattended Processing by selecting option 2 on the Hiperstation Product Menu, and option 4 on the Hiperstation for Mainframe Servers Main Menu. The “Generate Unattended Statements Screen” appears (Figure 3-1).
Figure 3-1. Generate Unattended Statements Screen
------------------ Hiperstation * Generate Unattended Statements ------------- Command ===> What to generate: 1. Generate Statements for Unattended 3270 2. Generate Statements for Unattended APPC Enter "/" to select options Add several script statements Append new Log to end of an existing Log (Add control cards generated in this execution to the end of those created via a previous execution) Enter END command to return to Main Menu.
Use this screen to generate unattended processing statements for 3270 or APPC. You can also add script statements to the end of existing unattended playback statements or append unattended playback statements to an existing file by entering a slash (/) in the corresponding field. Use the Append feature to run APPC and 3270 playbacks in the same unattended processing run. For detailed information on generating 3270 statements, see the Hiperstation for VTAM User Guide.
3-2 Hiperstation for Mainframe Servers User Guide
Generating APPC Unattended Processing StatementsSelect option 2 to access the “Generate APPC Unattended Statements Screen” (Figure 3-2).
Figure 3-2. Generate APPC Unattended Statements Screen
-------------- Hiperstation * Generate APPC Unattended Statements ------------- Command ===> What to generate: _ 1. Select the APPC unattended statements you wish to generate 2. Generate APPC unattended statements for each member in the script dataset 3. Generate APPC unattended statements using a standard script profile Enter END command to return to the previous panel
The following options let you access three primary functions from the “Generate APPC Unattended Statements Screen”:
1. Option 1 — Use this option to select which statements to generate. You can then navigate various screens and enter information Hiperstation for Mainframe Servers uses to generate unattended playback statements. For more information, see “Setting Unattended Statement Parameters” on page 3-2.
2. Option 2 — Use this option to choose a script dataset and generate unattended processing statements for all scripts in that dataset. Also use this option to do a mass generation. Based on your entries to option 1, Hiperstation for Mainframe Servers generates unattended playback statements for all scripts in the datasets you choose. For more information, see “Building Unattended Statements and JCL” on page 3-8.
3. Option 3 — Use this option to restrict the generation of unattended playback statements to a subset of the scripts contained in a dataset. Use this option to narrow the generation of statements based on either sender/receiver or script prefix. You can also use this option to include pre and postprocessing scripts, which lets you “sandwich” each of your scripts between two others, such as logon and logoff scripts. For more information, see “Restrict Specified Script Datasets” on page 3-11.
Note: See the online help for a description of the commands available on this screen.
Setting Unattended Statement Parameters
Select option 1 to display the “APPC Statement Generation Parameters Screen” (Figure 3-3).
APPC Unattended Processing 3-3
Figure 3-3. APPC Statement Generation Parameters Screen
--------------- Hiperstation * APPC Statement Generation Parameters ---------- Command ===> Select the APPC Statement Type you wish to include in your unattended job 1. CONTROL Statement parameters 2. ALLOCATE/ACCEPT Statement parameters 3. SCRIPT Statement parameters 4. COMPANY Statement parameters 5. CACHINCL and CACHEXCL Statement parameters Enter END command to return to previous panel
The “APPC Statement Generation Parameters Screen” allows you to select the type of APPC unattended playback statement to define or modify.
After you select the type of statement you want to build, a screen appears where you can provide the necessary information. The information you enter is saved and used when you request generation of control cards and JCL.
You can also modify your unattended processing statements before generating control cards and JCL. For example, you might define CONTROL information first, and then ALLOCATE information or vice versa. The sequence in which the statements are defined has no effect on the generation of the unattended playback statements.
CONTROL Statement Parameters
Select option 1 to display the “APPC CONTROL Statement Parameters Screen” (Figure 3-4).
Figure 3-4. APPC CONTROL Statement Parameters Screen
------------------ Hiperstation * APPC CONTROL Statement Parameters--------------- Command ===> Connection Information: LU62 Prefix. . . . HS62___ LU62 Suffix. . . . 4 LU Alias==> 3 1. Uservar 2. Generic 3. None Documentation Generation Options: Trace. . . . . . . Use MM/DD/YY?. . . Y Msgform . . . . N Timing Options: No Resp Time-Out. 45______ Use Start Time. N No FMH5 Time-Out. 300_____ Processing Options: Unit. . . . . . . ________ Caching?. . . . Y Volume. . . . . . ________ Using REXX? . . Y Enter END command to return to the previous panel
Use this screen to alter the default settings for APPC CONTROL statements. Modify or add a parameter by typing in the appropriate field. Press Enter without entering a command to validate the current entries without leaving this screen.
For descriptions of the parameters and the commands you can use on this screen, see the online help.
3-4 Hiperstation for Mainframe Servers User Guide
ALLOCATE/ACCEPT Statement Parameters
Select option 2 to display the “APPC ALLOCATE/ACCEPT Statement Parameters Screen” (Figure 3-5).
Figure 3-5. APPC ALLOCATE/ACCEPT Statement Parameters Screen
------------- Hiperstation * APPC ALLOCATE/ACCEPT Statement Parameters ---------- Command ===> Choose the ALLOCATE/ACCEPT parameters you wish to include 1. Connection information includes: Application, Sender and Receiver definitions, type of protocol, number of conversations, synchronization level and the number of times to repeat this request. 2. Documentation Generation includes: Trace, Summary, VTAM Trace and REXX Log. 3. Timing Options includes: Logon Delay, Start Delay, Think Time, Think Time Percent, Synchronize, All Sync and Time Sync. 4. Security/Unit of Work includes: Logical Unit of Work Name, Logical Unit of Work instance, Security Profile, Security Type, User and Password. Enter END command to return to the previous panel
Use this screen to access four other screens where you can alter default settings for APPC ALLOCATE/ACCEPT statements. Parameters for the ALLOCATE/ACCEPT statement are divided into four categories:
• Connection• Documentation• Timing• Security and logical unit of work
Enter the appropriate option for the category of parameters to be defined.
Parameter settings are saved in your profile and retained from session to session.
Connection ALLOCATE/ACCEPT Statement Parameters
Select option 1 on the “APPC ALLOCATE/ACCEPT Statement Parameters Screen” (Figure 3-5), to alter default settings for APPC ALLOCATE/ACCEPT Connection Parameters (Figure 3-6).
APPC Unattended Processing 3-5
Figure 3-6. APPC ALLOCATE/ACCEPT Connection Parameters Screen
---------- Hiperstation * APPC ALLOCATE/ACCEPT Connection Parameters ---------- Command ===> Request Type==> 1 1. Allocate 2. Accept TP Name . _______________________ Logmode. . . . ________ Receiver. *_____________________ Receiver Alias _______________________ Sender. . ______________________ Sender Alias . _______________________ Repeat. . 1 Count. . . . . 1 PIP . . . _____________________________________________________________ Protocol Type==> 1. Mapped 2. Basic 3. Full Duplex Mapped 4. Full Duplex Basic Sync Level==> 1. None 2. Confirm 3. Syncpt Other ALLOCATE/ACCEPT Statement Parameters==> 1. Connection parameters 2. Documentation parameters 3. Timing parameters 4. Security/Unit of Work parameters Enter END command to return to the previous panel
Modify or add a parameter by typing in the appropriate field. Press Enter without entering a command or typing an option in the Other ALLOCATE/ACCEPT Statement Parameters field to validate current entries without leaving this screen.
To transfer directly to one of the other ALLOCATE/ACCEPT parameters screens, type the number of the desired option in the Other ALLOCATE/ACCEPT Statement Parameters field and press Enter. Hiperstation for Mainframe Servers validates the current entries and the selected screen appears.
For descriptions of the parameters and the commands you can use on this screen, see the online help.
Documentation ALLOCATE/ACCEPT Statement Parameters
Select option 2 on the “APPC ALLOCATE/ACCEPT Statement Parameters Screen” (Figure 3-5 on page 3-4), to alter default settings for APPC ALLOCATE/ACCEPT Documentation Parameters (Figure 3-7).
Figure 3-7. APPC ALLOCATE/ACCEPT Documentation Parameters Screen
----------- Hiperstation * APPC ALLOCATE/ACCEPT Documentation Parameters -------- Command ===> Summary. REXX Log Trace. APPC.TRACE VTAM? Other ALLOCATE/ACCEPT Statement Parameters==> 1. Connection parameters 2. Documentation parameters 3. Timing parameters 4. Security/Unit of Work parameters Enter END command to return to the previous panel
Modify or add a parameter by typing in the appropriate field. Press Enter without entering a command or typing an option in the Other ALLOCATE/ACCEPT Statement Parameters field to validate current entries without leaving this screen.
3-6 Hiperstation for Mainframe Servers User Guide
To transfer directly to one of the other ALLOCATE/ACCEPT parameters screens, type the number of the desired option in the Other ALLOCATE/ACCEPT Statement Parameters field and press Enter. Hiperstation for Mainframe Servers validates the current entries and the selected screen appears.
For descriptions of the parameters and the commands you can use on this screen, see the online help.
Timing ALLOCATE/ACCEPT Statement Parameters
Select option 3 on the “APPC ALLOCATE/ACCEPT Statement Parameters Screen” (Figure 3-5 on page 3-4), to alter default settings for APPC ALLOCATE/ACCEPT statement timing parameters (Figure 3-8).
Figure 3-8. APPC ALLOCATE/ACCEPT Timing Parameters Screen
------------ Hiperstation * APPC ALLOCATE/ACCEPT Timing Parameters ------------ Command ===> Logon Delay. . . . Time Sync. . . . . . Start Delay. . . . Serialize? . . . . . N Start Time . . . . Synchronization Options==> 1 1. None 2. Sync within Group 3. Sync across Groups Think Time Option==> 1. Play at full speed 2. Think time recorded on script 3. User-specified think time Think Time(mm,ss) , Think Time Percent Other ALLOCATE/ACCEPT Statement Parameters==> 1. Connection parameters 2. Documentation parameters 3. Timing parameters 4. Security/Unit of Work parameters Enter END command to return to the previous panel
Modify or add a parameter by typing in the appropriate field. Press Enter without entering a command or typing an option in the Other ALLOCATE/ACCEPT Statement Parameters field to validate current entries without leaving this screen.
To transfer directly to one of the other ALLOCATE/ACCEPT parameters screens, type the number of the desired option in the Other ALLOCATE/ACCEPT Statement Parameters field and press Enter. Hiperstation for Mainframe Servers validates the current entries, and the selected screen appears.
For descriptions of the parameters and the commands you can use on this screen, see the online help.
Security and LUW ALLOCATE/ACCEPT Statement Parameters
Select option 4 on the “APPC ALLOCATE/ACCEPT Statement Parameters Screen” (Figure 3-5 on page 3-4), to alter default settings for APPC ALLOCATE/ACCEPT statement security and logical unit of work (LUW) parameters (Figure 3-9).
APPC Unattended Processing 3-7
Figure 3-9. APPC ALLOCATE/ACCEPT Security-LUW Parameters Screen
------------ Hiperstation * APPC ALLOCATE/ACCEPT Security-LUW Parameters--------- Command ===> Logical Unit of Work: LUW Name . . . . . . _____________________ LUW Instance Number. ____________ ____ Security==> _ 1. None 2. Same 3. Pgm 4. Prst 5.Sameprst Security Options: Security Profile . . _____________________ User . . . . . . . . _____________________ Password . . . . . . _____________________ Other ALLOCATE/ACCEPT Statement Parameters==> _ 1. Connection parameters 2. Documentation parameters 3. Timing parameters 4. Security/Logical Unit of Work parameters Enter END command to return to the previous panel
Also use this screen to alter LUW parameters. Modify or add a parameter by typing in the appropriate field. Press Enter without entering a command or typing an option in the Other ALLOCATE/ACCEPT Statement Parameters field to validate current entries without leaving this screen.
To transfer directly to one of the other ALLOCATE/ACCEPT parameters screens, type the number of the desired option in the Other ALLOCATE/ACCEPT Statement Parameters field and press Enter. Hiperstation for Mainframe Servers validates the current entries and the selected screen appears.
For descriptions of the parameters and the commands you can use on this screen, see the online help.
Hiperstation for Mainframe Servers does not retain dubbing information from session to session.
SCRIPT Statement Parameters
Select option 3 on the “APPC Statement Generation Parameters Screen” (Figure 3-3 on page 3-3) to display the “SCRIPT Statement Parameters Screen” (Figure 3-10).
Figure 3-10. SCRIPT Statement Parameters Screen
-------------------- Hiperstation * SCRIPT Statement Parameters --------------- Command ===> Dub?. . . . . .. N Replace Member?. N Repeat . . . . . 1 Stop On. . . . . Skip Compare . . Wait for Input . Enter END command to return to the previous panel
Use this screen to alter default settings for APPC SCRIPT statements. Modify or add a parameter by typing in the appropriate field. Press Enter without entering a command to validate current entries without leaving this screen.
For descriptions of the parameters and the commands you can use on this screen, see the online help.
3-8 Hiperstation for Mainframe Servers User Guide
COMPANY Statement Parameters
Select option 4 on the “APPC Statement Generation Parameters Screen” (Figure 3-3 on page 3-3 to display the “Company Statement Parameters Screen” (Figure 3-11).
Figure 3-11. Company Statement Parameters Screen
-------------------- Hiperstation * Company Statement Parameters ----------------- Command ===> Company . . Enter END command to return to previous panel
Enter your company’s name in the Company field. Enclose it in single quotes if it includes dashes or blanks. The name you define will print on your batch reports. If you do not specify a name, Hiperstation for Mainframe Servers uses Compuware Corporation as the default.
Leave the Dub Title field blank as it does not apply to APPC statements.
For descriptions of the parameters and the commands you can use on this screen, see the online help.
CACHE INCLUDE and EXCLUDE Statement Parameters
Select option 5 on the “APPC Statement Generation Parameters Screen” (Figure 3-3 on page 3-3 to display the CACHE INCLUDE and EXCLUDE Statement Parameters screen (Figure 3-12).
Figure 3-12. CACHE INCLUDE and EXCLUDE Statement Parameters Screen
---------- Hiperstation * CACHE INCLUDE and EXCLUDE Statement Parameters ------ Command ===> CACHINCL Statement: APPCINCL CACHEXCL Statement: Enter END command to return to the previous panel
Use this screen to alter default settings for APPC CACHINCL and CACHEXCL statements. Modify or add a parameter by typing in the appropriate field. Press Enter without entering a command to validate current entries without leaving this screen.
For descriptions of the parameters and the commands you can use on this screen, see the online help.
Building Unattended Statements and JCL
Select option 2 on the “Generate APPC Unattended Statements Screen” (Figure 3-2 on page 3-2), to display the “Unattended Statement Build Screen” (Figure 3-13).
APPC Unattended Processing 3-9
Figure 3-13. Unattended Statement Build Screen
------------------- Hiperstation * Unattended Statement Build ----------------- Command ===> Please supply the name of the dataset containing the scripts, and the name of the dataset and member which will contain the generated statements. Script Dataset: Project . . . USER2312 Group . . . . TEST Type . . . . SCRIPTS Other Partitioned Dataset: Dataset Name. . . . Enter a "/" above to define more than one Script Dataset Batch Statement Dataset Name: Project . . . USER2312 Group . . . . UNATTND Type . . . . CONTROL Member. . . . APPCTEST Other Partitioned Dataset: Dataset Name. . . . Press ENTER to generate Unattended Playback statements END to exit.
Use the “Unattended Statement Build Screen” to enter the name of the dataset containing the scripts you want to generate unattended statements for.
Type the dataset information in the Script Dataset fields or the Other Partitioned Dataset field.
You can define more than one dataset (up to seven) by typing a / in the Dataset Name field. Hiperstation processes any additional datasets after the dataset defined on this screen. Specify at least one dataset on this screen.
Hiperstation examines each of the members in the selected dataset and determines their domain destination or sender/receiver. Hiperstation flags as 3270 those script members that Hiperstation can identify a domain destination for. Hiperstation excludes these members from APPC-type requests.
Use the Batch Statement Dataset Name fields to enter the name of the dataset and member to store generated statements in. If the member exists, Hiperstation for Mainframe Servers overwrites it unless you selected the Append option on the initial “Generate Unattended Statements Screen” (Figure 3-1 on page 3-1).
For descriptions of the commands you can use on this screen, see the online help.
When you press Enter without entering a command, Hiperstation for Mainframe Servers validates the screen entries, generates unattended statements in the chosen dataset member, and then displays that member on the ISPF EDIT screen (Figure 3-14).
3-10 Hiperstation for Mainframe Servers User Guide
Figure 3-14. ISPF EDIT Screen Showing Generated Statements
File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------- EDIT USER2312.UNATTND.CONTROL(APPCTEST) - 01.00 Columns 00001 00072 Command ===> Scroll ===> PAGE ****** ***************************** Top of Data ****************************** 000001 CACHINCL - 000002 APPCINCL 000003 CONTROL - 000004 LU62PFX(HS62) - 000005 LU62SFX(4) - 000006 LUALIAS(NONE) - 000007 NORESPTO(45) - 000008 NOFMH5TO(300) - 000009 USDATE(YES) 000010 ALLOCATE - 000011 RECEIVER(A) - 000012 REPEAT(1) - 000013 COUNT(1) - 000014 THOPT(1) 000015 SCRIPT(RT000003) - 000016 REPEAT(1) 000017 SCRIPT(RT000002) - 000016 REPEAT(1) 000017 SCRIPT(RT000001) -
After you make any changes, enter the END command to access Hiperstation for Mainframe Servers’ “Unattended JCL Build Screen” (Figure 3-15).
Building JCL
Use the “Unattended JCL Build Screen” to create JCL for running the unattended statements just generated.
Figure 3-15. Unattended JCL Build Screen
----------------------- Hiperstation * Unattended JCL Build ------------------- Command ===> Please supply the dataset and member into which the batch JCL will be written. JCL Dataset Name: Project . . . ACMJET0 Group . . . . TSO Type . . . . JCL Member. . . . UNATTEND Other Partitioned Dataset: Dataset Name. . . . Job Statement Information: //ACMJET0G JOB (’OHPBAS5.2DSP’,84),’J.TESTER’,MSGCLASS=R, // REGION=2048K,CLASS=P,NOTIFY=ACMJET0 //* //* ENTER to generate the Unattended Playback JCL END key to terminate.
Use either the JCL Dataset Name fields or the Other Partitioned Dataset field to choose the dataset and member where Hiperstation for Mainframe Servers writes the generated JCL.
Enter your standard job statements in the Job Statement Information area.
When you press Enter, Hiperstation for Mainframe Servers:
APPC Unattended Processing 3-11
• Validates screen entries• Generates JCL in the chosen dataset member• Displays the generated JCL on the ISPF EDIT screen (Figure 3-16).
Figure 3-16. ISPF EDIT Screen Showing Generated JCL
File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------- EDIT ACMJET0.TSO.JCL(APPCPB) - 01.00 Columns 00001 00072 Command ===> Scroll ===> PAGE ****** ***************************** Top of Data ****************************** 000001 //ACMJET0G JOB (’OHPBAS5.2DSP’,84),’J.TESTER’,MSGCLASS=R, 000002 // REGION=2048K,CLASS=P,NOTIFY=ACMJET0 000003 //* 000004 //* 000005 //* 000006 //STEP1 EXEC PGM=EHSBATCH 000007 //SYSPRINT DD SYSOUT=* 000008 //STEPLIB DD DISP=SHR,DSN=ACMJET0.VP.R600.LOADLIB 000009 //SYSLIB DD DISP=SHR,DSN=ACMJET0.TEST.SCRIPTS 000010 //SYSIN DD DISP=SHR,DSN=ACMJET0.UNATTND.CONTROL(APPCTEST) ****** **************************** Bottom of Data ****************************
After you make any changes, either save the JCL for later use or enter the SUBMIT command to run the unattended playback job immediately.
Restrict Specified Script Datasets
Select option 3 on the “Generate APPC Unattended Statements Screen” (Figure 3-2 on page 3-2) to display the “Unattended Statement Build Screen” (Figure 3-13 on page 3-9).
Use this screen as described in “Building Unattended Statements and JCL” on page 3-8. The only difference is that when you press Enter without entering a command, Hiperstation for Mainframe Servers validates the screen entries, generates unattended statements in the chosen dataset member, and then displays the “Generation Restrictions Screen” (Figure 3-17).
Figure 3-17. Generation Restrictions Screen
----------------------- Hiperstation * Generation Restrictions ---------------- Command ===> _ Pre-process scripts - run these scripts prior to each of the scripts selected below. APPCSTRT ________ ________ ________ ________ Restrict the generation of unattended statements to script names beginning with the prefix, and/or scripts for a particular application. Script selection options: Generate statements for scripts prefixed by . . . . RT Generate statements for scripts for application . . Post-process scripts - run these script after each of the scripts selected above. APPCTERM ________ ________ ________ ________ Press the ENTER key to continue, the END key to terminate
Use the Generation Restriction screen to narrow down the number of scripts to generate unattended statements for. If you enter a prefix, Hiperstation for Mainframe Servers only includes script member names beginning with those characters. If you enter an application, Hiperstation for Mainframe Servers only includes script members with that sender/receiver in unattended statement generation.
3-12 Hiperstation for Mainframe Servers User Guide
You can also choose scripts, such as logon and logoff scripts, to run before and/or after the generated statements.
For descriptions of the commands you can use on this screen, see the online help.
When you press Enter without entering a command, Hiperstation for Mainframe Servers validates the screen entries, generates unattended statements in the dataset member entered on the Unattended Statement Build screen, and then displays that member on the ISPF EDIT screen (Figure 3-18).
Figure 3-18. ISPF EDIT Screen Showing Restricted Generated Statements
File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------- EDIT ACMJET0.UNATTND.CONTROL(APPCTEST) - 01.00 Columns 00001 00072 Command ===> Scroll ===> PAGE ****** ***************************** Top of Data ****************************** 000001 CACHINCL - 000002 APPCINCL 000003 CONTROL - 000004 LU62PFX(HS62) - 000005 LU62SFX(4) - 000006 LUALIAS(NONE) - 000007 NORESPTO(45) - 000008 NOFMH5TO(300) - 000009 USDATE(YES) 000010 ALLOCATE - 000011 RECEIVER(A) - 000012 REPEAT(1) - 000013 COUNT(1) - 000014 THOPT(1) 000015 SCRIPT(APPCSTRT) 000016 SCRIPT(RT000002) - 000017 REPEAT(1)
After you make any changes, enter the END command to access Hiperstation for Mainframe Servers’ “Unattended JCL Build Screen” (Figure 3-15 on page 3-10). Refer to “Building JCL” on page 3-10 for information on using this screen to create JCL for running your generated unattended statements.
4-1
Chapter 4.
4Unattended Playback of APPC Scripts Chap 4Using Unattended PlaybackUnattended playback processing works through coded batch statements run by the Hiperstation EHSBATCH program. Unattended mode processing allows you to perform stress, regression, and concurrent testing easily and without intervention. Play back multiple scripts against one or more applications, simultaneously or serially.
Note: You can also perform unattended playback of 3270 and LU0 scripts captured with Hiperstation for Mainframe Servers. Refer to the “Unattended Playback, Dubbing, and Comparison for 3270 and LU0 Scripts” chapter of the Hiperstation for VTAM User Guide.
Step 1. Review Storage Requirements for Unattended Mode Processing
Ensure your virtual and caching storage are sufficient for your processing needs. The Hiperstation Installation Guide lists MVS storage requirements for unattended processing.
Step 2. Record the Scripts
Unattended playback executes the activity in the APPC script. If Global Record was used previously for APPC recording, usable scripts already exist. Locate the PDSs where the scripts reside and define them to unattended playback through the SYSLIB DD statement.
Step 3. Identify the Application
The ALLOCATE and ACCEPT statements identify the conversations for a particular APPC LU name.
Step 4. Identify the Scripts To Run
The SCRIPT statement identifies the names of the scripts to run and the number of times to repeat each script.
Note: All files used during unattended mode must be available for allocation before submitting the batch job.
Step 5. Submit the Batch Job
Hiperstation for Mainframe Servers requires JCL to identify the program to run, the datasets where the scripts reside, an output message dataset, and the input dataset containing the Hiperstation for Mainframe Servers control statements. The JCL statements required for unattended playback include:
EXEC
The program name (PGM=EHSBATCH). Set the region to about 4096 KB to test 50 simultaneous conversations.
4-2 Hiperstation for Mainframe Servers User Guide
SYSPRINT
Message dataset for output for unattended playback. The logical record length of the SYSPRINT dataset is 133.
SYSLIB
Identifies the datasets containing the scripts to run.
SYSCNTL
Identifies the input control dataset containing the Hiperstation for Mainframe Servers control statements. The record length of this dataset (LRECL) must be 80. Use this dataset to contain CONTROL and COMPANY statements defined during installation. This allows the systems programmer to set up a procedure with this information already defined.
SYSIN
Identifies the input dataset containing the Hiperstation for Mainframe Servers control statements.
Note: The JCL submitted for an unattended mode job cannot contain sequence numbers in columns 73-80.
Playing Back APPC DatastreamsTo play back a recorded APPC datastream, submit a batch job using unattended playback. Using information taken from the conversation log to control playback, Hiperstation for Mainframe Servers reads the previously recorded script, connects to a real application, and plays back the APPC data. During playback, Hiperstation for Mainframe Servers assumes the role of one side of the APPC conversation.
Note: The conversation log identifies the APPC conversations to play back. It is generated during script creation if you select the Conversation Log option on the “APPC - Script Content Screen” (Figure 2-4).
As long as expected responses such as SENDs and ALLOCATEs are received, playback continues. However, if the application sends unexpected commands or data, playback terminates.
Hiperstation for Mainframe Servers displays an informational message when the length of the data received from the partner application is different from the expected length. However, it does not examine the content of the data received from the partner application to report comparison information. Add REXX variables to the script to generate data comparison reports. See “APPC REXX Variables” on page 4-35.
Before you begin testing, determine whether the application expects to initiate APPC conversations or expects to receive conversations initiated by other applications.
If the application expects to receive APPC conversations, the conversation log that you play back should contain ALLOCATE statements. However, if the application expects to initiate APPC conversations, the conversation log that you play back should contain ACCEPT statements.
An ALLOCATE statement in the conversation log tells Hiperstation for Mainframe Servers to initiate conversations with the application named in the RECEIVER keyword.
An ACCEPT statement in the conversation log prepares Hiperstation for Mainframe Servers to accept conversations initiated by the application named in the SENDER keyword. An ACCEPT statement in the conversation log requires you to initiate an APPC conversation between an application and Hiperstation for Mainframe Servers. Otherwise, Hiperstation for Mainframe Servers waits (not running any scripts) until an application initiates an APPC conversation. After Hiperstation for Mainframe Servers receives a
Unattended Playback of APPC Scripts 4-3
request for an APPC conversation from an application, the ACCEPT and SCRIPT statements that match the incoming conversation start. The match is based on logical unit names, logmode name, and TP name.
Timing Issues
Hiperstation for Mainframe Servers offers a number of options for controlling the various timing aspects of playback. If you do not choose any of these options, the playback proceeds as quickly as possible.
Think-Time Parameters
Three think-time keyword parameters are available: THINK, THOPT, and THPCT. These parameters let you control the release of data to the application. Using these parameters, you can tell Hiperstation for Mainframe Servers to send data to the partner application:
• As fast as possible (the default)
• At the same time intervals as during recording
• At a set fixed time interval
• At a percentage of the time intervals as during recording (for example, halve the playback time by entering 50%, double the playback time by entering 200%).
Refer to “ALLOCATE and ACCEPT Statements” on page 4-22 for a more detailed description of these parameters and their usage.
Control and Timing Parameters
Four other parameters provide control over the start of conversations and the timing of the data sent from each conversation: USESTIME, TIMESYNC, LOGD, and STARTDLY.
LOGD
If you start multiple conversations under a single ALLOCATE statement by supplying the COUNT parameter, all conversations start at the same time, by default. You can, delay the start of each conversation by supplying the LOGD parameter. LOGD sets the number of seconds to elapse between the start of each conversation defined on the COUNT keyword. For more information, refer to “LOGD(ss)” on page 4-25.
STARTDLY
If you want an ALLOCATE statement to become active only after a set time has elapsed during the playback job, use the STARTDLY parameter. STARTDLY sets the number of seconds to elapse during playback before the associated ALLOCATE is activated. For more information, refer to “STARTDLY(ss)” on page 4-26.
Note: Although STARTDLY and STIME provide similar functionality, there is more overhead in Hiperstation for Mainframe Servers when STARTDLY is used. If you have difficulty playing back large numbers of terminals, use STIME to get better results.
STIME
If USESTIME is specified, the STIME date and time value controls the activation of the ALLOCATE statement. STIME is ignored if USESTIME is not on the CONTROL statement.
TIMESYNC
The TIMESYNC parameter on more than one ALLOCATE or ACCEPT statement tells Hiperstation for Mainframe Servers to send the data in all scripts controlled by the TIMESYNC parameter in the order of the time stamps found within the scripts. The time stamps are treated as sequencing instructions to determine which data to send
4-4 Hiperstation for Mainframe Servers User Guide
to the partner applications next. For more information, refer to “TIMESYNC” on page 4-28.
Note: If USESTIME is used with TIMESYNC, only USESTIME is recognized. If the two parameters are used together, Hiperstation for Mainframe Servers issues error EHSB074I - KEYWORD(TIMESYNC) IGNORED - USESTIME SPECIFIED ON CONTROL STATEMENT, ignores the TIMESYNC parameter, and continues with playback.
USESTIME
The USESTIME parameter on the CONTROL statement specifies that ALLOCATE statements start at the time interval set on their respective STIME keywords, rather than at the beginning of the playback job. If the USESTIME parameter is not present on the CONTROL statement, all ALLOCATE statements start when the playback job begins. See “SCRIPT Statement” on page 4-32 for details on USESTIME.
Notes:
1. If USESTIME is used with TIMESYNC, only USESTIME is recognized. If the two parameters are used together, Hiperstation for Mainframe Servers issues error EHSB074I - KEYWORD(TIMESYNC) IGNORED - USESTIME SPECIFIED ON CONTROL STATEMENT, ignores the TIMESYNC parameter, and continues with playback.
2. Using sub-second STIME intervals with USESTIME is not recommended. One second should be the smallest STIME amount used.
Unattended Playback
When Hiperstation for Mainframe Servers plays back APPC conversations, it can use a single VTAM LU for one side of each APPC conversation. This logical unit is defined to VTAM with an APPL statement, typically in a member of the SYS1.VTAMLST dataset. SQQFSAMP member APPC100 provides a sample definition.
Editing APPC ScriptsAt playback time, you can add to, replicate, or merge recording scripts by changing the keywords within the recording script and conversation log. The keywords identify the recording scripts used in the playback and the number of times a recording script is repeated. The conversation log can be in the batch job stream as a SYSIN dataset. However, it is typically a PDS member, although it does not have to be in the same PDS where the recording scripts reside.
APPC Statement Descriptions
APPC input control statements control the number of conversations and the recording scripts to run.
APPC Control Script Tags
You can opt to have Global Record automatically create scripts, or you can write them from scratch. A script contains a symbolic representation of all traffic that occurred between two APPC TPs. Hiperstation for Mainframe Servers uses the following script tags.
Unattended Playback of APPC Scripts 4-5
<VERSION> Tag
Identifies the version of the Hiperstation for Mainframe Servers script creation program that created the script.
The VERSION tag appears only once in a script.
Notes:
1. Do not modify the version tag value. Doing so can cause unpredictable results during playback.
2. The version number may be different than the product release number.
<CONTENT> Tag
Identifies detail data associated with a previous CMDEAL, CMSEND, CMSNDX, CMSERR, PIU, or UNKNOWN tag.
LABEL
If a detail file is used by this script, LABEL identifies the record in the detail file that is associated with this occurrence of the tag.
The CONTENT tag appears as many times as necessary to contain all of the detail data associated with the previous tag. The number of times the CONTENT tag appears depends on the record length of the file that contains the detail data. For example, if detail data is being written to a separate detail file and that file has a large LRECL, only a single CONTENT tag might be needed.
Writing a long detail value to a file with a small LRECL requires the use of multiple CONTENT tags. Each subsequent CONTENT tag is a continuation of the previous CONTENT tag.
Note: “Contents of APPC Detail Data” on page 4-14 describes the record layouts of Hiperstation for Mainframe Servers’ detail file.
<DETAIL> Tag
Specifies where detail data is located. If the DETAIL tag is not in a script before a tag that has associated content, all tag contents are in the recording script rather than in a separate detail file.
COMBINED
Forces both inbound and outbound data to be contained in a single PDS member.
4-6 Hiperstation for Mainframe Servers User Guide
INBOUND
Identifies the dataset where inbound data is stored.
OUTBOUND
Identifies the dataset where outbound data is stored.
Each of these attributes can have a value of either an asterisk (*) or ddname(member). The * value specifies that the detail data is contained in the current script member. The ddname(member) value specifies that the detail data is contained within an external file with the defined DDname and dataset member name.
If the ddname(member) value is present, the dataset identified by ddname must be a dataset with no member defined in the JCL. For example:
//DATA01 DD DISP=SHR,DSN=USR2503.PDS (where DSORG=PO)
<ERROR> Tag
Indicates that an error was detected during datastream evaluation or during script generation. This tag is followed by an error message describing the problem that Hiperstation for Mainframe Servers encountered.
<EXTDATA> Tag
Specifies which record, in a detail file, the next CONTENT tag should retrieve. This tag does not have any associated content.
RETRIEVE=NEXT
Tells Hiperstation for Mainframe Servers to retrieve the next sequential record from the external file.
RETRIEVE=PREV
Tells Hiperstation for Mainframe Servers to reuse the most recently retrieved record.
<INBOUND> Tag
Identifies a collection of data that was sent from the ALLOCATE receiver to the ALLOCATE sender. This tag needs an associated end tag.
Unattended Playback of APPC Scripts 4-7
<OUTBOUND> Tag
Identifies a collection of data that was sent from the ALLOCATE sender to the ALLOCATE receiver. This tag needs an associated end tag.
<PIU> Tag
Tells Hiperstation for Mainframe Servers to ignore certain APPC traffic during playback. The traffic is either a
• VTAM BIND,
• CINIT,
• RSP(BIND),
• RSP(CINIT) PIU,
• VTAM FMH5 PIU,
• or a PIU produced as a result of an:
– APPC Send_Data,
– Send_Error,
– Send_Expedited_Data,
– Prepare_to_Receive,
– Confirm,
– Confirmed,
– Request_to_Send,
– or Deallocate verb
The PIU tag represents a complete PIU, which consists of a transmission header (TH), a request header (RH), and a request unit (RU). PIU tags are present if the Write all traffic as script comments and interpreted values debugging options were selected. All request and response PIUs are included before the <CMxxxx> (for the CPIC forms) tag they apply to.
The content of this tag (contained in subsequent CONTENT tags) is a complete PIU.
LABEL
If a detail file is used by this script, LABEL identifies the record in the detail file that is associated with this occurrence of the tag.
<REPLACE> Tag
The REPLACE tag replaces the information within the APPC data streams during playback. Use this tag to supply new data, such as account numbers, user names, etc.
The REPLACE tag may be applied to the CONTENT of a single CMSEND, CMSNDX, CMSERR, or CMDEAL tag or to a range of tags. If applied to a range, the REPLACE tag acts on all of the CMSEND, CMSNDX, CMSERR, and CMDAL tags within the range.
4-8 Hiperstation for Mainframe Servers User Guide
Insert the REPLACE tag before the CMSEND, CMSNDX, CMSERR, or CMDEAL tag or group of tags it applies to. To establish a range, specify ALL on the TYPE parameter of the REPLACE tag and insert another REPLACE tag at the end of the range. Specify DELETE on the TYPE parameter of the closing REPLACE tag to terminate the action of the previous REPLACE tag.
Notes:
1. If the CMSEND, CMSNDX, CMSERR or CMDEAL data stream is longer than the LRECL of the script dataset, the data stream is broken into multiple CONTENT records (lines). The REPLACE tag applies to the entire logical value — that is, all CONTENT records — of the subsequent CMSEND, CMSNDX, CMSERR or CMDEAL tags.
2. When a script is created without CPIC format, the <CMSEND> tag is recorded as <SEND-DATA> tag (see “<SEND_DATA> Tag” on page 4-13 for a description of the tag).
FIELD
Identifies the byte offset and new value of a field within the datastream that will be replaced at playback time. (The field value is not changed within the script or detail file.)
The offset value is zero-based and applies to the entire “traffic” portion of a detail data record. The offset value does not consider the length, type, or label portions of a detail file record. For example, <REPLACE FIELD=(0,‘CAT’)> specifies that the first byte following the label portion of a detail file record is the start of three bytes to be replaced with the character string ‘CAT’.
Specify one or more FIELD attributes on a given REPLACE tag as shown below:
<REPLACE FIELD=(0,’CAT’) FIELD=(20,’DOG’)>
Notes:
1. Hiperstation provides macros for easily determining offset values. These macros are especially helpful when determining the offset for a multi-record CONTENT tag. Although these macros are documented in the TCP/IP portion of the manual, they apply to APPC scripts as well. See “Offset and Length Determination Macros” on page 7-33 for more information.
2. Multiple REPLACE tags are not allowed.
If a playback table entry is used instead of a literal value or REXX variable, add an ampersand (&) as a prefix to the value and define the playback table with TABLE statements having appropriate ID parameters. If the appropriate table is not defined, the value after the ampersand (&) will be treated as a literal. For example, if TABLE1 is not defined, &TABLE1 will be considered a literal. The table ID is prefixed with an ampersand (&) and may be enclosed in single quotes ('), but the quotes are not required. For example,
<REPLACE FIELD=(0,‘&IFBRACCT’)>
and
<REPLACE FIELD=(0,&IFBRACCT)>
are both valid.
Unattended Playback of APPC Scripts 4-9
The table data will be retrieved using the current PORT and GRPCYCLE information.
Assume TABLEDEF and TABLE are stated as follows:
TABLEDEF PORTS(p) DATADSN(USERID.APPC.TABLE.DATA)
TABLE ID(TABLE1) REPEATS(r) DATALEN(d)
The cell index will be calculated with the formula:
index = ((GRPCYCLE - 1)//r) * p + PORT
where // represents mod (the remainder of the amount divided by r).
Following is an example where p = 3, r = 5 (ports = 3, repeats = 5):
Cell index PORT GRPCYCLETABLE1 [1] = 1 1,6,11,16 ...TABLE1 [2] = 2 1,6,11,16 ...TABLE1 [3] = 3 1,6,11,16 ...TABLE1 [4] = 1 2,7,12,17 ...TABLE1 [5] = 2 2,7,12,17 ...TABLE1 [6] = 3 2,7,12,17 ...TABLE1 [7] = 1 3,8,13,18 ...TABLE1 [8] = 2 3,8,13,18 ...TABLE1 [9] = 3 3,8,13,18 ...TABLE1 [10] = 1 4,9,14,19 ...TABLE1 [11] = 2 4,9,14,19 ...TABLE1 [12] = 3 4,9,14,19 ...TABLE1 [13] = 1 5,10,15,20 ...TABLE1 [14] = 2 5,10,15,20 ...TABLE1 [15] = 3 5,10,15,20 ...
The DATALEN(d) will be the literal data length.
TYPE
Specifies how to apply the data replacement.
– TYPE=ONE applies the data replacement to the next CMSEND, CMSNDX, CMSERR, or CMDEAL message. This is the default.
– TYPE=ALL applies the data replacement to all subsequent CMSEND, CMSNDX, CMSERR, or CMDEAL messages. This is a global data replacement.
– TYPE=DELETE disables the global data replacement established by a previous replace tag with the TYPE=ALL parameter.
LENGTH
Sets the length of the replacement data stream. LENGTH=n, where n specifies the number of bytes. If n is greater than the value defined on the FIELD parameter, Hiperstation for Mainframe Servers pads the value with binary zeros (X'00'). If the replacement value is shorter than the original message content, use the LENGTH parameter to ensure the entire message is replaced. For example, if you are replacing 'ABC Corporation' with 'Smith Inc.' and you do not specify a length, the result of the replacement is 'Smith Inc.ation'.
Note: Hiperstation provides macros for easily determining length values. These macros are especially helpful when determining the length of a value that spans multiple CONTENT tags. Although these macros are documented in the TCP/IP portion of the manual, they apply to APPC scripts as well. See “Offset and Length Determination Macros” on page 7-33 for more information.
4-10 Hiperstation for Mainframe Servers User Guide
<EXTRACT> Tag
The EXTRACT tag extracts the information within the APPC data streams during playback.
Insert the EXTRACT tag before the CMSEND, CMSNDX, CMSERR, or CMDEAL tag or group of tags it applies to. To establish a range, specify ALL on the TYPE parameter of the EXTRACT tag and insert another EXTRACT tag at the end of the range. Specify DELETE on the TYPE parameter of the closing EXTRACT tag to terminate the action of the previous EXTRACT tag.
FIELD
Identifies the byte offset and playback table identification (TABLE ID(member_name)). The offset value is zero-based and applies to the entire inbound data record. Since the EXTRACT tag does not have a length parameter, the length will be determined by the TABLE DATALEN(n).
The table ID is prefixed with an ampersand (&) and may be enclosed in single quotes ('), but the quotes are not required. For example,
<EXTRACT FIELD=(0,‘&TABLE1’)>
and
<EXTRACT FIELD=(0,&TABLE1)>
are both valid.
If table ID is not defined during playback, EXTRACT will not be performed and no error message will be produced.
The extracted data will be stored in the table using PORT and GRPCYCLE information.
Assume TABLEDEF and TABLE are stated as follows:
TABLEDEF PORTS(p) DATADSN(USR2503.APPC.TABLE.DATA)
TABLE ID(TABLE1) REPEATS(r)
The cell index will be calculated with the formula:
index = ((GRPCYCLE - 1)//r) * p + PORT
where // represents mod (the remainder of the amount divided by r).
Let's take an example of p = 3, r = 5 (ports = 3, repeats = 5):
Cell index PORT GRPCYCLETABLE1 [1] = 1 1,6,11,16 ...TABLE1 [2] = 2 1,6,11,16 ...TABLE1 [3] = 3 1,6,11,16 ...TABLE1 [4] = 1 2,7,12,17 ...TABLE1 [5] = 2 2,7,12,17 ...TABLE1 [6] = 3 2,7,12,17 ...TABLE1 [7] = 1 3,8,13,18 ...TABLE1 [8] = 2 3,8,13,18 ...TABLE1 [9] = 3 3,8,13,18 ...
Unattended Playback of APPC Scripts 4-11
Specify one or more FIELD attributes on a given EXTRACT tag:
<EXTRACT FIELD=(0,’&TABLE1’) FIELD=(20,&TABLE2) TYPE=ONE>
<TIME> Tag
Provides a time stamp for the immediately following tag. You can use the TIME tag during playback for script synchronization.
The content of this tag is a time stamp with the format: YYYY/MM/DD_HH:MM:SS.SSSSS. For example: <TIME>2006/07/28_13:02:42.246413.
<UNKNOWN> Tag
Identifies data that Hiperstation for Mainframe Servers did not understand and was unable to interpret. The content of this tag (contained in subsequent CONTENT tags) is the portion of the VTAM Request Unit (RU) that was not understood.
You cannot play back a script containing the UNKNOWN tag. Script execution ends if Hiperstation for Mainframe Servers encounters an UNKNOWN tag during playback.
LABEL
If a detail file is used by this script, LABEL identifies the record in the detail file that is associated with this occurrence of the tag.
APPC Verb Script Tags
You can use the tags in this section either via their APPC form, which is given in the individual headings, or via their CPIC form. CPIC forms are shown under the APPC forms in the syntax diagrams.
<CONFIRM> Tag
Represents a confirm request from a TP. It has a CPIC form of CMCFM. This tag does not have any associated content.
TABLE1 [10] = 1 4,9,14,19 ...TABLE1 [11] = 2 4,9,14,19 ...TABLE1 [12] = 3 4,9,14,19 ...TABLE1 [13] = 1 5,10,15,20 ...TABLE1 [14] = 2 5,10,15,20 ...TABLE1 [15] = 3 5,10,15,20 ...
Cell index PORT GRPCYCLE
4-12 Hiperstation for Mainframe Servers User Guide
<CONFIRMED> Tag
Represents a confirmed response from a TP. It has a CPIC form of CMCFMD. This tag does not have any associated content.
<ALLOCATE> Tag
For a description of this tag, refer to “ALLOCATE and ACCEPT Statements” on page 4-22.
Notes:
The list of parameters on page 4-23 are valid on an ALLOCATE in the conversation log/replay JCL, but are invalid on an ALLOCATE in the APPC script.
The ALLOCATE tag in the script can also be known by its CPI-C alias, CMALLC, as with other APPC verbs in the script.
<DEALLOCATE> Tag
Represents a deallocate request from a TP. It has a CPIC form of CMDEAL. The content of this tag (contained in subsequent CONTENT tags) is any LOGDATA that is present.
TYPE
Identifies the type of deallocation request made by the TP. Valid values are FLUSH, CONFIRM, and ABEND.
SENSE
The four-byte SNA sense data produced by the deallocation request.
LOGDATA
Indicates whether error log data is present.
LABEL
If a detail file is used by this script, LABEL identifies the record in the detail file that is associated with this occurrence of the tag.
<FLUSH> Tag
Represents a flush request. Accumulated data not yet sent is sent immediately. It has a CPIC form of CMFLUS.
Unattended Playback of APPC Scripts 4-13
<PREPARE_TO_RECEIVE> Tag
Represents a Prepare_to_Receive request from a TP. It has a CPIC form of CMPTR. This tag does not have any associated content.
TYPE
Identifies the type of Prepare_to_Receive request made by the TP. Valid values are FLUSH and CONFIRM.
LOCKS
Identifies the TP value for the LOCKS parameter. Valid values are SHORT and LONG.
<REQUEST_TO_SEND> Tag
Represents a Request_to_Send request from a TP. It has a CPIC form of CMCRTS. This tag does not have any associated content.
<SEND_DATA> Tag
Indicates that the TP sent some type of application data. The TP can send normal data, user control data, error data, and presentation services data. This tag has a CPIC form of CMSEND. The content of this tag (contained in subsequent CONTENT tags) is the data that was sent.
DATATYPE
APPLDATA:
Indicates that normal data was sent.
PSDATA:
Indicates whether presentation services data was sent. Presentation services data is the form used for PREPARE, COMMIT, and ROLLBACK synchpoint requests.
UCDATA:
Indicates whether user control data was sent.
ERDATA:
Indicates whether error data was sent.
4-14 Hiperstation for Mainframe Servers User Guide
Note: The absence of PSDATA, UCDATA, and ERDATA indicates that normal application data was sent.
MAPNAME
Specifies the name of any map that was sent along with the data.
ENCRYPT
Indicates whether the data is encrypted.
LABEL
If a detail file is used by this script, LABEL identifies the record in the detail file that is associated with this occurrence of the tag.
<SEND_ERROR> Tag
Indicates that the TP sent an error response to the other side of the conversation. This tag has a CPIC form of CMSERR. The content of this tag (contained in subsequent CONTENT tags) is any LOGDATA that is present.
SENSE
The four-byte SNA sense data associated with the CMSERR request.
LOGDATA
Indicates whether error log data is present.
LABEL
If a detail file is used by this script, LABEL identifies the record in the detail file that is associated with this occurrence of the tag.
<SEND_EXPEDITED_DATA> Tag
Indicates that the TP sent expedited data. It has a CPIC form of CMSNDX. The content of this tag (contained in subsequent CONTENT tags) is the expedited data that was sent.
LABEL
If a detail file is used by this script, LABEL identifies the record in the detail file that is associated with this occurrence of the tag.
Contents of APPC Detail Data
This section describes the contents associated with the following Hiperstation for Mainframe Servers detail data script tags:
• CMSEND,• CMSERR,• CMSNDX,• CMDEAL,• PIU, and
Unattended Playback of APPC Scripts 4-15
• UNKNOWN.
This information can follow either the CONTENT tag delimiter ( > ), or it can be contained in a file separate from the tag. The content of a tag is typically application-defined data sent by a transaction program. The content can also be error log data, user control data, complete PIUs, and so on.
Syntax
Whether the detail data is contained within a script or in a separate detail file, the record format of the detail data is the same:
Fields: L L T T C C C C C C C C V ... Offset: 0 1 2 3 4 5 6 7 8 9 A B C ...
There are four fields within the detail data structure:
Length (LL)
The first field (LL) is at offset 0 and is two bytes in length. The high-order bit is always set to zero and the remaining bits indicate the length of the record, which includes the length of the LL, TT, and CCCCCCCC fields.
The LL value can be from x‘000C’ to x‘7FF8’ (12 to 32760, decimal). These limits are reduced if the customer uses a record format of V or VB or if an LRECL of less than 32760 is supplied for the dataset.
The LL field is usually equal to the current logical record length (LRECL) of the record as recognized by the access method, and as stored in the RDW for RECFM=V datasets. However, if you use a text editor such as ISPF/PDF, which removes trailing blanks from RECFM=V records, to edit and save the detail data dataset, the LL field can be different than the record’s LRECL. Hiperstation for Mainframe Servers assumes that the LL field is correct: if LL is less than the LRECL, only the LL portion is used; if LL is larger than the LRECL, Hiperstation for Mainframe Servers pads the record with blanks to reach the LL value.
Padding the record with blanks eliminates the problem introduced by the ISPF/PDF editor for RECFM=V datasets. This padding process does not actually alter the detail data dataset, the padding takes place within Hiperstation for Mainframe Servers buffers at playback time.
Type (TT)
The second field (TT) is at offset two and is two bytes in length. This field indicates the format of the fields that follow. The values are assigned as follows:
B’0000 xxxx xxxx xxxx’ - Version number of this detail data B’xxxx 1xxx xxxx xxxx’ - 1 = First in chain, 0 = Not first in chain B’xxxx x1xx xxxx xxxx’ - 1 = Last in chain, 0 = Not last in chain B’xxxx xx0x xxxx xxxx’ - Reserved, must be zero B’xxxx xxx1 xxxx xxxx’ - 1 = Data is inbound, 0 = Data is outbound B’xxxx xxxx 0000 0001’ - Basic conversation application data (1) B’xxxx xxxx 0000 0010’ - Mapped conversation application data (2) B’xxxx xxxx 0000 0011’ - Presentation services data (3) B’xxxx xxxx 0000 0100’ - User control data (4) B’xxxx xxxx 0000 0101’ - Error log data (5) B’xxxx xxxx 0000 0110’ - Error data (6) B’xxxx xxxx 0000 0111’ - Null data (7) B’xxxx xxxx 0000 1000’ - Expedited data (8)
4-16 Hiperstation for Mainframe Servers User Guide
B’xxxx xxxx 0000 1001’ - Unknown data (9) B’xxxx xxxx 0000 1010’ - PIU (10) B’xxxx xxxx 0000 1011’ - FMH5+PIP PIU (11) B’xxxx xxxx 0000 1100’ - BIND PIU (12) B’xxxx xxxx 0000 1101’ - BIND response PIU (13) B’xxxx xxxx 0000 1110’ - CINIT PIU (14) B’xxxx xxxx 0000 1111’ - CINIT response PIU (15)
Label (CCCCCCCC)
The third field (CCCCCCCC) is at offset four and is eight bytes in length. This field is a character format label that matches a label found within the associated script. If the detail data is included in the recording script rather than in a separate detail file, no “LABEL=label” attribute is contained on any of the script tags. This label field contains human-readable numbers (as opposed to hex), starting with c‘00000001’ (x‘F0F0F0F0F0F0F0F1’) and incrementing by one for each new record.
Value (V)
The fourth field is at offset 12 and is from 0 through 32748 bytes in length (or less if the LRECL is more restrictive). If the field is of 0 length (an LL value of x‘000C’) a transaction program issued a Send_Data with a 0 length data value.
For each of the 15 types of data (B‘xxxx xxxx 0000 0001’ through B‘xxxx xxxx 0000 1111’) indicated in the TT field, this fourth field contains the following, where ll represents a field length byte and xx represents an arbitrary data byte:
x’ll ll xx ...’ - Basic conversation (GDS prefix) x’xx ...’ - Mapped conversation (No GDS prefix) x’00 01 ...’ - Presentation services (Complete RU) x’xx ...’ - User control data (No GDS prefix) x’ll ll 12 E1 xx ...’ - Error log data (GDS prefix) x’ll ll 12 F4 xx ...’ - Error data (GDS prefix) x’ll ll 12 F1’ - Null data (GDS prefix) x’03 xx ll ll xx ...’ - Expedited data (Complete RU) x’xx ...’ - Unknown data (Portion of RU) x’xx ...’ - PIU (Complete PIU) x’xx ...’ - FMH5+PIP PIU (Complete PIU) x’xx ...’ - BIND PIU (Complete PIU) x’xx ...’ - BIND response PIU (Complete PIU) x’xx ...’ - CINIT PIU (Complete PIU) x’xx ...’ - CINIT response PIU (Complete PIU)
APPC Unattended Playback StatementsAPPC Unattended Playback statements provide processing rules and define what conversations (scripts) to play back.
Following introductory information on the sequencing of statements for APPC testing, the statements are presented in hierarchal order.
Statement Sequence
Enter statements into your JCL in the sequence shown in Figure 4-1.
Unattended Playback of APPC Scripts 4-17
Figure 4-1. APPC Unattended Playback Statement Sequence
CONTROL STATEMENT ALLOCATE STATEMENT SCRIPT STATEMENT SCRIPT STATEMENT … ACCEPT STATEMENT SCRIPT STATEMENT SCRIPT STATEMENT …
There is no limit to the number of ALLOCATE, ACCEPT, or APPCGRP statements or the number of SCRIPT statements that can follow. The statements have no column dependence. Continue statements on multiple lines by using the continuation character: a dash (–). However, the continuation character cannot be used to separate a keyword and its operand value.
Insert a comment after the continuation character as long as the dash and comment are separated by at least one blank space.
APPC Unattended Playback Statement Summary
CONTROL: Defines environmental data to Hiperstation for Mainframe Servers. See “SCRIPT Statement” on page 4-32 for APPC-specific information.
CACHINCL: Identifies which scripts Hiperstation for Mainframe Servers loads into memory during initialization. See “CACHINCL Statement” on page 4-20 for information.
CACHEXCL: Identifies which scripts Hiperstation for Mainframe Servers will not store in memory. See “CACHEXCL Statement” on page 4-20 for more information.
COMPANY: Defines an alternative company name to use in the title of the batch Hiperstation for Mainframe Servers reports. See “COMPANY Statement” on page 4-21 for information.
TABLEDEF: Defines the playback table using the following parameters: PORTS, DATADSN, and LOGDSN. See “TABLEDEF Statement” on page 4-21 for more information.
TABLE: Specifies the playback table name to be read in and/or written out. It defines the data length and number of cells in the table. See “TABLE Statement” on page 4-22 for more information.
ALLOCATE and ACCEPT: Identify a number of conversations connected to a particular APPC LU name. See “ALLOCATE and ACCEPT Statements” on page 4-22 for information.
APPCGRP: Similar to the ALLOCATE statement, APPCGRP allows multiple SCRIPT statements containing the <ALLOCATE> tag. See “APPCGRP Statement” on page 4-29 for information.
SCRIPT: Identifies a script to run for the conversations defined on the preceding ALLOCATE or ACCEPT statement. One or more SCRIPT statements follow an ALLOCATE or ACCEPT statement. See “SCRIPT Statement” on page 4-32 for more information.
* (asterisk): Identifies a comment statement.
4-18 Hiperstation for Mainframe Servers User Guide
CONTROL Statement
The CONTROL statement sets the options that control the operation of all subsequent ALLOCATE and ACCEPT statements.
CACHEOFF
When used, Hiperstation for Mainframe Servers does not store scripts in memory. Eliminating this type of processing results in higher I/O for scripts that are run more than once.
DEFER
When used, Hiperstation for Mainframe Servers forces report consolidation for less than 50 reports to be written onto DASD by a CONTROL parameter. Report consolidation saves memory during playbacks where a large number of terminals are used and memory might be an issue.
LU62PFX(hs62|n)
The one to seven character prefix used to define Hiperstation for Mainframe Servers APPC APPLIDs during installation. The default prefix value is HS62. Only change this variable if your site changed the node names during installation. Otherwise, the default value is acceptable.
LU62SFX(4|n)
The length of the suffix used to define Hiperstation for Mainframe Servers APPC APPLIDs during installation. The default suffix value is four. Only change this variable if your site changed the node names during installation; otherwise, the default value is acceptable.
LUALIAS(USERVAR|GENERIC|NONE)
Prepares Hiperstation for Mainframe Servers to send and expect to receive alias LU names. An LU has a real name and may have an alias name. The real name is defined to VTAM with an APPL statement in SYS1.VTAMLST. Hiperstation for Mainframe Servers creates the alias name dynamically using the VTAM USERVAR or generic resource.
Unattended Playback of APPC Scripts 4-19
The default value is LUALIAS(USERVAR), which indicates that Hiperstation for Mainframe Servers uses any values on the SNDALIAS and RCVALIAS parameters as VTAM USERVARS. For more information on these options, see the SNA Programmer’s LU 6.2 Guide, IBM document number SC31-8811.
MSGFORM
When used, Hiperstation for Mainframe Servers time stamps messages in the SYSPRINT dataset. The default is no time stamps.
NODEFER
When used, Hiperstation for Mainframe Servers suppresses report consolidation. Report consolidation is programatically turned on when 50 or more reports are to be written onto DASD. Report consolidation saves memory during playbacks where a large number of terminals are used and memory could be an issue.
NOFMH5TO(300|sss)
(No FMH5 Time Out) The number of seconds for Hiperstation for Mainframe Servers to wait for an FMH5 from the APPC partner. This is measured in whole seconds, with a 300 seconds (5 minutes) default. If the conversation log has ACCEPT statements and the partner applications might not initiate all conversations within the default amount of time, make this value larger than the default.
NORESPTO(45|sss)
(No Response Time Out) The number of seconds for Hiperstation for Mainframe Servers to wait for a response from the APPC partner. This is measured in whole seconds, with a 45 second default. If the partner application normally takes more than 45 seconds to respond, make this value larger than the default.
If the time expires without a response from the partner, Hiperstation for Mainframe Servers issues an informational message and the play process continues.
REXXOFF
When used, Hiperstation for Mainframe Servers does not preprocess scripts using REXX. Eliminating this preprocessing results in more efficient (CPU and memory) running of scripts. Only use this parameter if your scripts do not contain REXX.
TRACE(sysout_class|dataset)
If this keyword is present, Hiperstation for Mainframe Servers prints internal information. The amount of material printed can be substantial, and the trace material format is not documented.
CAUTION:This option traces internal Hiperstation for Mainframe Servers information. Do not use TRACE without guidance from Hiperstation for Mainframe Servers Customer Support.
USDATE(YES|NO)
The format of the date field. Enter YES (default) for MM/DD/YY. Enter NO for YY/MM/DD.
USESTIME
(Use Start Time) If present, each ALLOCATE statement containing an STIME parameter starts at a time interval after the start of the playback job, rather than immediately. If the USESTIME parameter is not supplied, or if an ALLOCATE statement does not contain an STIME parameter, the ALLOCATE statements start when the playback job begins.
With USESTIME supplied, the ALLOCATE statement containing the earliest STIME value starts when the playback job begins. The ALLOCATE statement with the next chronological STIME value then starts only after the amount of time indicated by the
4-20 Hiperstation for Mainframe Servers User Guide
difference in STIME values has elapsed. For example, assume the following playback job begins at exactly 9:00 AM:
CONTROL USESTIME * ALLOCATE ... STIME(‘2006/07/19_12:05:00.000000’) SCRIPT(AAA) * ALLOCATE ... STIME(‘2006/07/19_12:00:00.000000’) SCRIPT(BBB)
Script BBB starts at 9:00 AM and script AAA starts at 9:05 AM.
Note: If USESTIME is used with TIMESYNC, only USESTIME is recognized. If the two parameters are used together, Hiperstation for Mainframe Servers issues error EHSB074I - KEYWORD(TIMESYNC) IGNORED - USESTIME SPECIFIED ON CONTROL STATEMENT, ignores the TIMESYNC parameter, and continues with playback.
UNIT(unit)
The unit on which Hiperstation dynamically allocates the journal or log datasets.
VOL(volume)
The DASD volume on which Hiperstation dynamically allocates the journal or log datasets.
Note: SMS, or other DASD management tools, can override the value specified on the VOL parameter.
CACHEXCL Statement
The CACHEXCL statement identifies scripts to not store in memory. You can use one or more CACHEXCL statements.
ddname(script)
The script not to store in memory.
CACHINCL Statement
The CACHINCL statement identifies the scripts that Hiperstation for Mainframe Servers preloads into memory at initialization. You can use one or more CACHINCL statements.
Unattended Playback of APPC Scripts 4-21
ddname(script)
The script name and location. If you do not enter a ddname, Hiperstation for Mainframe Servers assumes SYSLIB is the ddname.
COMPANY Statement
A COMPANY statement identifies a company name for all of the batch reports.
companyname
Identifies a company name up to 40 bytes long. The default is Compuware Corporation. If the company name includes dashes or blanks, enclose the name in single quotes.
TABLEDEF Statement
The TABLEDEF statement defines the number of ports that will be used with your playback tables and specifies the dataset names for the input (DATADSN) and output (LOGDSN) files.
PORTS(n)
Specifies the total number of ports that will be used in the playback. This is the total number of APPC ALLOCATES. A port is assigned to each ALLOCATE/APPCGRP in the playback, but a playback table cannot be assigned to a specific ALLOCATE/APPCGRP. Therefore, a table must contain all possible ports that will be assigned during playback. This parameter is required.
DATADSN(datasetname)
Specifies the dataset name of your input table. Input data is used to import external data into a table that will be used with the <REPLACE> tag. The maximum length is 260 (256 bytes of data plus four bytes for the RDW (record descriptor word)). DATADSN must be a PDSE file. This parameter is required.
LOGDSN(datasetname)
Specifies the dataset name of the log file where your output data will be put. The maximum length for log data is the length specified in DATADSN plus 50 or 310 (256 bytes of data plus four bytes for the RDW plus 50). LOGDSN must be a PDSE file. This parameter is required.
4-22 Hiperstation for Mainframe Servers User Guide
TABLE Statement
The table specified using the TABLE statement
ID(membername)
Specifies the table’s name, which is a member name of DATADSN and/or LOGDSN. This parameter is required.
REPEATS(n)
This value is used in conjunction with the PORTS parameter in the TABLEDEF statement to define the number of entries in the table. REPEATS is a required parameter since there is no default number of repeats. This parameter is required.
DATALEN(n)
Sets the length of the replacement data stream. The maximum length is 256 bytes. This parameter is required.
DATAIN
This reads the DATADSN member into the playback table.
LOG
Writes the contents of the table into the LOGDSN member.
INIT(NULL|SPACE|ZERO)
Initializes the playback table. Sets the table entry’s default to a null value (x‘00’), a space (x‘40’), or a zero (x‘F0’). NULL is the default.
ALLOCATE and ACCEPT Statements
The ALLOCATE and ACCEPT statements set APPC control and conversation-specific values. ALLOCATE sends an APPC allocation. ACCEPT receives an APPC allocation.
Control-specific values must appear on ALLOCATE and ACCEPT statements in the conversation log. They are not valid in the script.
ALLOCATE conversation-specific values can appear in either the conversation log or the script. ACCEPT conversation-specific values must appear in the conversation log. The ALLOCATE statement (with or without conversation-specific values) must always be present in the conversation log, since its subparameter SCRIPT contains the script name. The script can then contain an ALLOCATE statement with additional conversation-specific values.
Note: There can be only one ALLOCATE statement in a script.
Before running playback, the conversation log must be changed so that each ALLOCATE statement names a Hiperstation for Mainframe Servers LU. This name is different from the LU name originally recorded in the conversation log (in most situations).
Replace the ALLOCATE keyword in the conversation log with the ACCEPT statement if Hiperstation for Mainframe Servers is to receive rather than send an APPC allocation.
Data defined in the conversation log overrides any data defined in the script.
Unattended Playback of APPC Scripts 4-23
Control and conversation-specific values of the ALLOCATE and ACCEPT statements are shown in the following syntax diagram. Parameter values are described after the diagram. The following parameters are valid in the conversation log, but are invalid in the script:
• ALLSYNCH • SYNCH
• COUNT • THINK
• LOGD • THOPT
• RLOG • THPCT
• SERIAL • TIMESYNC
• STARTDLY • TRACE
• SUMMARY • VTAMTRCE
4-24 Hiperstation for Mainframe Servers User Guide
Required ParametersLOGMODE(modename)
Identifies the VTAM session logmode used for this conversation. When you use the ACCEPT statement, you must enter a LOGMODE value.
RECEIVER(luname)
On an ALLOCATE statement, RECEIVER identifies the logical unit (LU) to which Hiperstation sends the ALLOCATE request (an FMH5). On an ACCEPT statement, RECEIVER identifies the LU name representing Hiperstation for Mainframe Servers.
TPNAME(tpname)
Identifies the transaction program being invoked. When you use the ACCEPT statement, you must enter a TPNAME value.
Optional ParametersALLSYNCH
Tells Hiperstation for Mainframe Servers to send each new APPC verb in unison for every ALLOCATE and ACCEPT statement containing the ALLSYNCH parameter. That is, for each script controlled by an ALLOCATE or ACCEPT statement containing the ALLSYNCH parameter, Hiperstation for Mainframe Servers waits for all required responses from the partner applications before sending any new data.
With this technique, all scripts controlled by the ALLSYNCH parameter are played using the speed of the “slowest” application. New data is not sent to any application until all applications have responded.
Portions of a script that require no response from the application (for example, two SEND_DATA verbs back-to-back) cause Hiperstation for Mainframe Servers to issue the next APPC verb in each script without delay.
ALLSYNCH must be supplied on more than one ALLOCATE or ACCEPT statement in a conversation log. Use ALLSYNCH when the scripts being played back on the ALLOCATE and ACCEPT statements in a conversation log are identical.
Using ALLSYNCH to keep multiple-identical scripts in unison is a useful way to stress the communications network, not your applications.
Use the SYNCH parameter, instead of ALLSYNCH, to run conversations on a single ALLOCATE or ACCEPT statement in a synchronized manner.
COUNT(nnn)
Sets the number of conversations to be started or accepted by the ALLOCATE or ACCEPT statement. The maximum number of conversations that can be run depends on the amount of virtual storage available to the playback job. If the COUNT parameter is not supplied, a single conversation is started. COUNT is similar to the TERM(nn) parameter on the GROUP statement, which starts multiple sessions.
Use the COUNT parameter to run several identical conversations under a single ALLOCATE or ACCEPT statement. By default, all conversations defined on an ALLOCATE statement with the COUNT parameter are started at the same instant. To start each of the conversations with a time interval, use the LOGD parameter in conjunction with the COUNT parameter.
The COUNT and REPEAT parameters can appear on the same statement. The total number of conversations that run reflects the product of the COUNT and REPEAT values.
FTIME(timestamp)
(Finish Time). Sets the end-date and end-time of the originally recorded conversation. The FTIME value is not used during playback.
Unattended Playback of APPC Scripts 4-25
LOGD(ss)
(Logon Delay). Sets the number of seconds between the start of each new conversation defined by the COUNT parameter. If LOGD is not supplied on an ALLOCATE statement that contains a COUNT parameter, all conversations are started as soon as the ALLOCATE statement becomes active (after STARTDLY or STIME processing, if any).
LOGD enables the start of identical conversations over a period of time, rather than all at once. Supplying the LOGD parameter on an ALLOCATE statement that does not contain a COUNT parameter has no effect.
LUWINST(instance_no)
Sets the logical unit of work instance number (6 bytes) for this conversation.
LUWNAME(luwname)
Defines the logical unit of work name for this conversation. The LUWNAME is not the same entity as the LUs used in the conversation. A logical unit of work represents a resource that is recoverable by an application such as CICS, IMS, or DB2.
LUWSEQ(sequence_no)
Sets the logical unit of work sequence number (2 bytes) for this conversation.
PIP(pip_value)
Supplies program initialization parameters. You can supply multiple PIP parameters. PIP data is used by some APPC applications to send initialization parameters to a partner application.
RCVALIAS(lualias)
Identifies an alias name for the RECEIVER LU name.
REPEAT(1|nnn)
Sets the number of times to start the conversations controlled by the ALLOCATE statement. The scripts controlled by an ALLOCATE statement that contains the REPEAT parameter runs n times sequentially. The default is 1 (one). There is no maximum limit.
Note: REPEAT is not supported on the ACCEPT statement. Use the COUNT parameter instead.
REPEAT starts a new conversation after the previous conversation on the same ALLOCATE statement has finished. The COUNT parameter, in contrast, starts new conversations all at once (unless modified by the LOGD parameter).
Both the REPEAT and COUNT parameters can appear on the same statement. The total number of conversations that run is the product of the REPEAT and COUNT values.
RLOG(sysout_class|dataset)
Indicates that Hiperstation for Mainframe Servers allocates a REXX log for each APPC conversation in the group. If the value is a single character, Hiperstation for Mainframe Servers allocates the REXX log to SYSOUT in the class set by that single character. If the value is more than one character, Hiperstation for Mainframe Servers allocates the REXX log to a permanent file. By default, the REXX output is directed to the SYSPRINT dataset.
The dataset value can be either a dataset name by itself or a dataset name with a member name:
RLOG(dataset) RLOG(dataset(member))
The dataset or member or both can contain wildcard characters (* or ?).
4-26 Hiperstation for Mainframe Servers User Guide
If a dataset name is supplied with no member and no wildcards, a dataset is created with the name dsn.Pnnnn, where nnnn is the port number assigned to the conversation.
SECPROF(sec_profile)
The security profile for this conversation.
SECPSWD(password|DECRYPT(password))
The password for the supplied user ID. Use DECRYPT to decrypt the password in the script. If users change the password, they have the option of editing the script and putting the password in plain text (omitting the DECRYPT()).
SECURITY(NONE|SAME|PGM|PRST|SAMEPRST)
The type of conversation level security in use by this conversation:
NONE: No security is in use.
SAME: A user has already been verified.
PGM: Verify the user ID and password using a security program.
PRST: Implement persistent verification and require user signon
SAMEPRST: Implement persistent verification and do not require user signon
SECUSER(userid)
The security user ID for this conversation.
SENDER(luname)
The LU name that Hiperstation for Mainframe Servers uses as the sender of the ALLOCATE request. Some transaction programs that receive an ALLOCATE may be sensitive to the LU the ALLOCATE originated from. This parameter lets you control the originating LU (the ALLOCATE sender).
When SENDER appears on an ALLOCATE statement, the value is the LU name that Hiperstation for Mainframe Servers uses to represent itself. This LU name must not be in use by any other application while the playback job is running. This LU name must be defined to VTAM on the MVS system where the playback job runs, and the logical unit must be activated, which is done automatically at some sites or can be done manually with the MVS VARY command.
Before running playback, the conversation log must be changed so that each ALLOCATE statement names a Hiperstation for Mainframe Servers LU. This name is different from the LU name originally recorded in the conversation log (in most situations).
When the SENDER parameter appears on an ACCEPT statement, the value is the LU name in use by the partner application (the application that initiates the APPC conversation with Hiperstation for Mainframe Servers).
SERIAL
If this keyword is present, all requests made to VTAM are serialized. Each request finishes before the next starts. SERIAL ensures, on a job-wide basis, that no two ports have an APPC verb in progress at the same time.
SINGLE
Allows support for single session APPC devices.
SNDALIAS(lualias)
An alias name for the SENDER LU name.
STARTDLY(ss)
Sets the number of seconds between the start of the playback job and the start of the ALLOCATE statement containing this STARTDLY parameter. If the USESTIME
Unattended Playback of APPC Scripts 4-27
parameter is not supplied on the CONTROL statement, all conversations defined on an ALLOCATE statement begin when the playback job begins. STARTDLY delays the start of an ALLOCATE statement until the set number of seconds has elapsed.
The STIME parameter on an ALLOCATE statement used in conjunction with the USESTIME parameter on the CONTROL statement provides a similar activity.
If defined by the LOGD parameter, the conversation starts after the sum of LOGD and STARTDLY expires.
STIME(‘timestamp’)
Indicates the date and time when Hiperstation for Mainframe Servers recorded the ALLOCATE request (unless you have edited the STIME value directly). When you use USESTIME on the CONTROL statement, an STIME value can be used to control the activation of an ALLOCATE statement.
The STIME value is ignored if the USESTIME parameter is not supplied on the CONTROL statement.
Note: Using sub-second STIME intervals with USESTIME is not recommended. One second should be the smallest STIME amount used.
SUMMARY(sysout_class|dataset)
Tells Hiperstation for Mainframe Servers to generate a summary report for the group. If the value is a single character, Hiperstation for Mainframe Servers allocates the summary report to SYSOUT in the class set by that single character. If the value is more than one character, Hiperstation for Mainframe Servers allocates the summary report to a permanent file. By default, no summary report is produced.
The dataset value can be either a dataset name by itself or a dataset name with a member name:
SUMMARY(dataset) SUMMARY(dataset(member))
To allocate a PDSE at the same time, use the format:
SUMMARY(dataset*(member*))
The dataset must be either a sequential file or a PDSE. You cannot use a PDS as a summary report file because playback can write multiple members at the same time, a function not supported by PDSs.
The dataset or member or both can contain wildcard characters (* or ?).
If a dataset name is supplied with no wildcards, no suffix is added to the dataset name.
SYNCH
Controls when data is sent by Hiperstation for Mainframe Servers to the partner application for all conversations running under the current ALLOCATE or ACCEPT statement. To run multiple conversations in parallel, use the COUNT parameter along with SYNCH.
SYNCH tells Hiperstation for Mainframe Servers to send each new APPC verb for this ALLOCATE or ACCEPT statement in unison. For each conversation running under this ALLOCATE or ACCEPT statement, Hiperstation for Mainframe Servers waits for all required responses from the partner applications before sending any new data.
With this technique, the playback of conversations under the ALLOCATE or ACCEPT statement is at the speed of the “slowest” application. New data is not sent to any application until all applications have responded.
For portions of a script that do not require a response from the application (for example, two SEND_DATA verbs back-to-back), Hiperstation for Mainframe Servers
4-28 Hiperstation for Mainframe Servers User Guide
has nothing to wait for from the application; it issues the next APPC verb in each script without waiting.
The ALLSYNCH parameter can be used instead of SYNCH to run conversations under several ALLOCATE and ACCEPT statements in this synchronized manner.
SYNCLVL(NONE|CONFIRM|SYNCPT)
Indicates the type of synchpoint protocol used in the conversation. For more information on the NONE, CONFIRM, and SYNCPT options, see the SNA Programmer’s LU 6.2 Guide, IBM document number SC31-8811.
THINK(mm,ss)
Sets a think time, which is the amount of time that Hiperstation for Mainframe Servers waits before sending the next APPC verb. This parameter is only valid in conjunction with THOPT(3). For example, the statement: ALLOCATE... THOPT(3) THINK(0,1) play back a script with one second between each APPC verb that Hiperstation for Mainframe Servers sends to the partner.
THOPT(1|2|3)
Controls the speed at which APPC conversations are played.
1. Play at full speed. The data is played back as fast as the system can run. This is the default.
2. Think time recorded in the script. Think time is represented by the <TIME> tag recorded in the script.
3. User-specified think time. Tells Hiperstation for Mainframe Servers to use the think time set by the THINK(minutes,seconds) parameter.
THPCT(nnn)
Sets a think time percentage. This parameter is only valid in conjunction with THOPT(2|3). For example, the statement: ALLOCATE … THOPT(2) THPCT(25) plays back the script at 25 percent of the original think time recorded in the script. The APPC data sent to the partner by Hiperstation for Mainframe Servers is sent after waiting for 25 percent of the amount of time recorded in the script.
THPCT values of less than 100 cause the script to be played back with a think time less than originally recorded. THPCT values greater than 100 cause the script to be played back with a think time greater than originally recorded.
TIMESYNC
When supplied on more than one ALLOCATE or ACCEPT statement, indicates that the data in all scripts controlled by the TIMESYNC parameter is sent in the order of the time stamps found on the APPC verbs within the scripts. The time stamps are treated as sequencing instructions to decide which data to send to the partner applications next.
TIMESYNC single-threads the sending of data to the partner applications and guarantees that the data is sent in the same sequence as originally recorded.
TIMESYNC, by itself, does not control how “fast” the playback takes place, only the order of data sent among several conversations. Use the THOPT, THINK, and THPCT parameters to control the speed of the playback.
Supplying the TIMESYNC parameter on only a single ALLOCATE or ACCEPT statement has no effect.
Note: If USESTIME is used with TIMESYNC, only USESTIME is recognized. If the two parameters are used together, Hiperstation for Mainframe Servers issues error EHSB074I - KEYWORD(TIMESYNC) IGNORED - USESTIME SPECIFIED ON CONTROL STATEMENT, ignores the TIMESYNC parameter, and continues with playback.
Unattended Playback of APPC Scripts 4-29
TRACE(sysout_class|dataset)
This option traces internal Hiperstation for Mainframe Servers information. Do not use TRACE without guidance from Hiperstation for Mainframe Servers Customer Support.
If used, Hiperstation for Mainframe Servers allocates a trace for each APPC conversation. Trace contains the actual APPC datastreams that flowed between the application and the Hiperstation for Mainframe Servers transaction program. If the value is a single character, the trace is allocated to SYSOUT in the class set by that single character. If the value is more than one character, the trace is allocated to a permanent file.
By default, no trace is allocated.
The dataset value can be either a dataset name by itself or a dataset name with a member name:
TRACE(dataset) TRACE(dataset(member))
The dataset or member or both can contain wildcard characters (* or ?).
If a dataset name is supplied with no member and no wildcards, a dataset is created with the name dsn.Pnnnn, where nnnn is the port number assigned to the conversation.
TYPE(MAPPED|BASIC|FDMAPPED|FDBASIC)
Indicates whether the conversation uses the MAPPED, BASIC, full-duplex MAPPED, or full-duplex BASIC protocol. For more information on these options, see the SNA Programmer’s LU 6.2 Guide, IBM document number SC31-8811.
VTAMTRCE
Tells Hiperstation for Mainframe Servers that the trace contains additional VTAM data such as the bind, RPLs, and response and bracket conditions.
APPCGRP Statement
The APPCGRP statement is similar to the ALLOCATE statement, but it allows multiple SCRIPT statements containing the <ALLOCATE> tag. While the APPCGRP statement can use all of the keywords and parameters listed for the ALLOCATE/ACCEPT statements, it is recommended that special care be given when using keywords not shown on the APPCGRP syntax diagram.
4-30 Hiperstation for Mainframe Servers User Guide
APPCGRP starts conversations specified in script statements in sequence. As a result, only one conversation is active at any one time. Each APPCGRP statement uses one parallel session. Multiple script statements within APPCGRP run in serial, one at a time.
Required ParametersRECEIVER (luname)
RECEIVER identifies the logical unit (LU) to which Hiperstation sends the APPCGRP request (an FMH5), most likely the same receiver the original ALLOCATE statement contained.
SENDER (luname)
The LU name that Hiperstation for Mainframe Servers uses as the sender of the ALLOCATE request. Some transaction programs that receive an ALLOCATE request may be sensitive to the LU the ALLOCATE originated from. This parameter lets you control the originating LU (the ALLOCATE sender).
The value is the LU name that Hiperstation for Mainframe Servers uses to represent itself. This LU name must not be in use by any other application while the playback job is running. This LU name must be defined to VTAM on the MVS system where the playback job runs, and the logical unit must be activated, which is done automatically at some sites, or can be done manually with the MVS VARY command.
Optional ParametersCOUNT(nnn)
Sets the number of instances for the APPCGRP statement. The maximum number of APPCGRP statements that can be run depends on the amount of virtual storage available to the playback job. If the COUNT parameter is not supplied, a single conversation is started.
Use the COUNT parameter to run several identical series of conversations under a single APPCGRP statement. The first conversations defined on an APPCGRP statement with the COUNT parameter are started at the same instant, and subsequent conversations run serially. To start each of the APPCGRP statements with a time interval, use the LOGD parameter in conjunction with the COUNT parameter.
The COUNT and REPEAT parameters can appear on the same statement. The total number of APPCGRP statements or instances of the APPCGRP statement that run reflects the product of the COUNT and REPEAT values.
LOGD(ss)
(Logon Delay). Sets the number of seconds between the start of each new APPCGRP statement set by the COUNT parameter. If LOGD is not supplied on an APPCGRP
Unattended Playback of APPC Scripts 4-31
statement that contains a COUNT parameter, all instances of the APPCGRP statement started immediately (after any STARTDL processing).
LOGD enables the start of all instances of the APPCGRP parameter over a period of time, rather than all at once. Supplying the LOGD parameter on an APPCGRP statement that does not contain a COUNT parameter has no effect.
REPEAT (1|nnn)
Sets the number of times to start the APPCGRP statements. The scripts, controlled by an APPCGRP statement that contains the REPEAT parameter, run n times sequentially. The default is 1 (one). There is no maximum limit.
REPEAT starts a new conversation after the previous conversation on the same APPCGRP statement has finished. The COUNT parameter, in contrast, starts new conversations all at once (unless modified by the LOGD parameter.
Both the REPEAT and COUNT parameters can appear on the same statement. The total number of APPCGRP statements that run is the product of the REPEAT and COUNT values.
SKIPPERR
Continues playback at the next script within an APPCGRP if an APPC process error occurs. This means that processing does not stop if an APPC processing error occurs, only the script containing the error is not processed. The return code will be set with the highest return code within the APPCGRP. The REPEAT count for the APPCGRP will be executed as long as the last script does not get any error. An empty script will execute without an error and, therefore, it can be used as the last script for proper APPCGRP REPEAT(nn).
STARTDLY(ss)
Sets the number of seconds between the start of the playback job and the start of the APPCGRP statement containing the STARTDLY parameter. STARTDLY delays the start of an APPCGRP statement until the set number of seconds elapses. If defined by the LOGD parameter, the APPCGRP statement starts after the sum of LOGD and STARTDLY expires.
SUMMARY (sysout_class|dataset)
Tells Hiperstation for Mainframe Servers to generate a summary report for the group. If the value is a single character, Hiperstation for Mainframe Servers allocates the summary report to SYSOUT in the class set by that single character. If the value is more than one character, Hiperstation for Mainframe Servers allocates the summary report to a permanent file. By default, no summary report is produced.
The dataset value can be either a dataset name by itself, or a dataset name with a member name:
SUMMARY(dataset) SUMMARY(dataset(member))
To allocate a PDSE at the same time, use the format:
SUMMARY(dataset*(member*))
The dataset must be either a sequential file or PDSE. You cannot use a PDS as a summary report file because playback can write multiple members at the same time, a function not supported by PDSs.
The dataset or member or both can contain wildcard characters (* or ?).
If a dataset name is supplied with no wildcards, no suffix is added to the dataset name.
4-32 Hiperstation for Mainframe Servers User Guide
SCRIPT Statement
A SCRIPT statement identifies a script to be played back, and optionally indicates the number of times to run the script.
Required Parameterscriptname
Identifies the SCRIPT (member name from the SYSLIB) to be played back.
Optional ParametersREPEAT(1|nnn)
Identifies the number of times a script plays back. The default is 1 (one).
STOPON(n)
Tells Hiperstation for Mainframe Servers to stop processing when it reaches the specified number (n) of mismatches for that run. If there are fewer than the set number of mismatches, script processing continues to the end.
Note: The message displayed for script termination is the same one that appears when the script has no mismatches. For this reason, make sure you check all messages for the playback and/or comparison.
Script Not Found Messages
It is possible that when Hiperstation for Mainframe Servers issues message EMTRM016: SCRIPT SPECIFIED DOES NOT EXIST, REXX may issue the following messages:
IRX0554E
Explanation: The EXEC load file DDname is not allocated. The REXX EXEC cannot be loaded.
User Response: Verify that the script name is correct. Check the SYSLIB to see if it defines the correct dataset. Verify that inappropriate REXX CALL statements have not run.
IRX0110I
Explanation: The REXX EXEC cannot be interpreted.
User Response: Verify that the script name is correct. Check the SYSLIB to ensure that it defines the correct dataset. Verify that inappropriate REXX CALL statements have not run.
IRX0112I
Explanation: The REXX EXEC cannot be loaded.
User Response: Verify that the script name is correct. Check the SYSLIB to ensure that it defines the correct dataset. Verify that inappropriate REXX CALL statements have not run.
Unattended Playback Return CodesHiperstation for Mainframe Servers reports an MVS return code for each step of a playback job. The return code is a numeric value that indicates whether the job step completed successfully and to what degree. See Table 4-1 on page 4-34 for a complete list of APPC return codes.
Unattended Playback of APPC Scripts 4-33
Note: For more definitive playback results, you can add REXX logic to a script to return a specific value based on criteria you supply. This is called a ‘script’ or ‘custom’ return code. Refer to the Hiperstation Scripting Reference to learn how to define custom return codes.
The location of your return codes is dependent on your system configuration. On some systems, with the correct job statement parameter, return codes display in the user’s TSO session. On others, return codes are written to a job log. If you need help locating your return codes, see your systems administrator.
Hiperstation for Mainframe Servers also writes the following informational messages to the SYSPRINT upon job completion:
EHSB098I MAXIMUM SCRIPT RC=rc, INTERNAL RC=rc
This message, in most cases, reports the highest script and internal return code values. The larger of these two values is returned as the job step completion code.
Note: If you did not define custom return codes, this message reports 0 for the SCRIPT RC value.
If the GROUP statement has multiple scripts, Hiperstation for Mainframe Servers returns the value set by the last script processed. For example, Hiperstation for Mainframe Servers reports the return code from the LOGOFF script in the following GROUP.
GROUP SCRIPT(LOGON) SCRIPT(TEST) SCRIPT(LOGOFF)
Due to this processing rule, the EHSB098I message may not report the highest return code value for this type of playback job. For example, if the TEST script returned an internal return code value of 4, and the LOGOFF script returned a value of 0, EHSB098I reports and a value of 0 for the INTERNAL RC.
If the GROUP statement has a COUNT parameter, which initiates concurrent playback sessions, or a REPEAT parameter, which initiates consecutive playback sessions, Hiperstation for Mainframe Servers returns the highest value of all of the sessions. For example, a GROUP statement with COUNT(2) and REPEAT(3) invokes two concurrent playback sessions, repeated three times consecutively. If the first repeat returns a code of 0 for one playback session and 12 for the other, the second repeat yields 4 and 0, and the third repeat yields 0 and 0, as shown in the table below, Hiperstation for Mainframe Servers returns 12 for the job step completion code.
REPEAT
Session 1 Session 2
Scripts in GROUP RC Scripts in GROUP RC
1 Script 0 Script 12
2 Script 4 Script 0
3 Script 0 Script 0
If a GROUP statement contains multiple SCRIPT statements, and has a COUNT parameter, Hiperstation for Mainframe Servers compares the return code set by the last script processed in each session and returns the highest value. For example, the following playback statements result in two concurrent playback sessions in which LOGON, TEST and LOGOFF are played consecutively.
GROUP COUNT(2) SCRIPT(LOGON) SCRIPT(TEST) SCRIPT(LOGOFF)
4-34 Hiperstation for Mainframe Servers User Guide
If the last script processed in the first session yields a code of 4, and the last script processed in the second session yields a code of 12, as shown in the table below, Hiperstation for Mainframe Servers returns a job step completion code of 12.
Session 1 Session 2
Scripts in GROUP RC Scripts in GROUP RC
LOGON 0 LOGON 0
TEST 0 TEST 4
LOGOFF 4 LOGOFF 12
In addition to the EHSB098I message, Hiperstation for Mainframe Servers writes status, error, and warning messages to SYSPRINT. If the playback job step returns a non-zero code, review the return code description provided in Table 4-1. Then review the warning and error messages to determine the cause of the problem. Refer to the Hiperstation Messages and Codes for help with error resolution.
Table 4-1. APPC Playback Return Codes
Code Description
0 All scripts ran successfully.
4 Warning: Any miscomparison caused by APPC processing. This includes:
• Expected and actual record data lengths not equal
• Expected and actual log data lengths not equal
• Expected and actual sense data values not equal
• An ACCEPT did not receive an ALLOCATE by the time the NOFMH5TO expired
• A conversation log statement was rejected.
12 Error: APPC unattended playback process contains exceptions at the record level. For example:
• One or more corresponding record lengths not equal
• Sense data not equal on one or more records
• Log data not the same length for corresponding records.
16 Error: Invalid script statement found.
20 Serious Error:
• Port could not be started because APPC application is not valid or active
• Port started, but could not be initialized
• REXX EXEC/script not found.
24 Serious Error: The first port to start could not get started — the unattended playback process is terminated.
Unattended Playback of APPC Scripts 4-35
APPC REXX VariablesHiperstation for Mainframe Servers provides several predefined REXX variables that return information during playback. Incorporate the variables into REXX logic that you can optionally add to your scripts. The following sections provide definitions for the REXX variables.
To learn more about using the variables, including detailed examples, refer to the Hiperstation Scripting Reference.
APPC Error Determination REXX Variables
The following variables provide information pertaining to an error encountered during script processing. During playback, Hiperstation for Mainframe Servers issues VTAM macros to perform operations indicated in the script. Return codes from these macros are placed into the following REXX variables.
Many of these variables provide data from the Request Parameter List (RPL). These values are the character representations of binary values.
28 SEVERE ERROR: Port subtask could not be started.
• SYSPRINT could not be opened or error processing SYSPRINT
• SYSIN could not be opened or error processing SYSIN
• SYSCNTL could not be opened or error processing SYSCNTL
• User failed security authorization
• APPC pool names could not be built from the provided prefix and suffix values
• Product is not licensed for APPC unattended mode processing
• APPC is not supported for APPC scripts
• Trace could not be initialized
• No terminals found to be played back
• VTAM initialization error.
• A syntax error exists on the JOURNAL, LOG, XLOG, RLOG, AUTODOC, SUMMARY, or TRACE keywords on the CONTROL, GROUP, ALLOCATE, or COMPARE statements.
32 SERIOUS ERROR: A print file is full or could not be processed. The print files are the JOURNAL, LOG, XLOG, RLOG, AUTODOC, SUMMARY, and TRACE files.
36 Playback Error: Any playback table related error will set return code 36.
40 SEVERE ERROR: Hiperstation for Mainframe Servers is about to expire or has expired. Contact Hiperstation for Mainframe Servers Customer Support for a date extension and new release availability information.
44 SECURITY ERROR: Hiperstation for Mainframe Servers detected an unauthorized default parameter table. Contact your systems programmer.
Table 4-1. APPC Playback Return Codes
Code Description
REXX Variables Description
Cpicrc Contains the equivalent CPIC return code for the error. If there is no error, the CPICRC is zero.
4-36 Hiperstation for Mainframe Servers User Guide
APPC Environment Data REXX Variables
The following variables provide information pertaining to the APPC conversation. These variables cannot be used to set their corresponding conversation values. These are read-only informational variables available for review while a script is running.
REXX Variables Description
Convcorr Contains the conversation correlator.
Logmode Contains the name of the logmode.
Luwinst Contains the logical unit of work instance number for the conversation.
Luwname Contains the logical unit of work name for the conversation.
Luwseq Contains the logical unit of work sequence number for the conversation.
Opnrcdes Contains the feedback code from the CNOS.
Opnrtncd Contains the return code from the CNOS.
Receiver Contains the LU name receiving the ALLOCATE.
Secuser Contains the userID used for security purposes.
Sender Contains the LU name sending the ALLOCATE.
Tpname Contains the transaction program name.
APPC Application Data REXX Variables
The following variables provide values for both the expected and the actual data received from an application during playback. The variables are read-only and are set after normal or expedited data is received from the partner application. The values are usable only immediately after the set of <CONTENT> tags associated with the <SEND_DATA> or <SEND_EXPEDITED_DATA> verb.
The variables represent the data received from the partner application. They must be examined in the context of an <INBOUND> group of verbs in a Hiperstation for Mainframe Servers-allocated conversation, or in an <OUTBOUND> group of verbs in a Hiperstation for Mainframe Servers-accepted conversation.
For example, an ALLOCATE statement in the conversation log runs the script shown in Figure 4-2 on page 4-37. In this example, the first REXX SAY statement lists a null value (0 length string) because Hiperstation for Mainframe Servers has not received data from the partner application. However, the four REXX SAY statements in the <INBOUND> group produce meaningful output.
Errmsgno Contains the Hiperstation for Mainframe Servers error message number of the error condition.
Rplfbk2 Contains the feedback code from the previous APPC operation. It is the register 0 value.
Rplrtncd Contains the return code from the previous APPC operation. It is the register 15 value.
Rpl6ccst Contains the conversation state from the VTAM RPL of the previous APPC operation.
Rpl6rcpr Contains the primary reason code from the VTAM RPL of the previous APPC operation.
Rpl6rcsc Contains the secondary reason code from the VTAM RPL of the previous APPC operation.
Rpl6snsi Contains the sense data from the VTAM RPL of the previous APPC operation.
Rpl6what Contains the “what received” value from the VTAM RPL of the previous APPC operation.
REXX Variables Description
Unattended Playback of APPC Scripts 4-37
Figure 4-2. Sample Script Using APPC Application Data REXX Variables
<VERSION>8 <ALLOCATE> <OUTBOUND> <SEND_DATA> <CONTENT>....00000001This is outbound data say appc_actual /* This is not meaningful, a null value is displayed. */ <PREPARE_TO_RECEIVE> </OUTBOUND> <INBOUND> <SEND_DATA> <CONTENT>....00000002This is inbound data say appc_actual /* The actual data received (up to 2048 bytes). */ say appc_expected /* The data we expect to receive (complete). */ say appc_actual_length /* The length of the actual data (may be more than 2048). */ say appc_expected_length /* The length of data we expect to receive (complete). */ <PREPARE_TO_RECEIVE> </INBOUND> <OUTBOUND> <DEALLOCATE> </OUTBOUND>
APPC_ACTUAL
The APPC_ACTUAL variable contains the data most recently received from the partner application. This data can either be normal data from a <SEND_DATA> verb or expedited data from a <SEND_EXPEDITED_DATA> verb. If the application sends more than 2048 bytes of data, only the first 2048 bytes are available in this variable.
The variable contains only a relevant value immediately after the set of <CONTENT> tags associated with <SEND_DATA> or <SEND_EXPEDITED_DATA> verbs. This value is reset as soon as another script tag is encountered. Likewise, the variable is only meaningful following APPC verbs that represent data received by Hiperstation for Mainframe Servers. Examining the variable in a section of the script where Hiperstation for Mainframe Servers is sending data is not meaningful.
The example below shows the APPC_ACTUAL variable used to produce meaningful data after the set of a <CONTENT> tag that is associated with a <SEND_DATA> verb.
Figure 4-3. Sample Script Containing the APPC_ACTUAL Variable
<INBOUND> <SEND_DATA> <CONTENT>....00000002This is inbound data say appc_actual /* The actual data received (up to 2048 bytes). */ <PREPARE_TO_RECEIVE> say appc_actual /* A 0 length string is displayed. */ </INBOUND>
APPC_EXPECTED
The APPC_EXPECTED variable contains the data that Hiperstation for Mainframe Servers expects to receive from the partner application as a result of the most recently issued <SEND_DATA> or <SEND_EXPEDITED_DATA> verb. The value represents the data contained in the script or the associated detail file. The complete expected value is placed in the variable, even if it exceeds 2048 bytes (in contrast to the APPC_ACTUAL variable).
The variable contains a relevant value only immediately following the set of <CONTENT> tags that is associated with the <SEND_DATA> or <SEND_EXPEDITED_DATA> verb, and its value is reset when the next script tag is encountered. The variable generates useful data only when it is set after APPC verbs that represent data received by Hiperstation for Mainframe Servers. Consequently, using the variable in a section of the script where Hiperstation for Mainframe Servers is sending data will not produce meaningful data.
4-38 Hiperstation for Mainframe Servers User Guide
The example below shows the APPC_EXPECTED variable used to produce meaningful data after the <CONTENT> tag associated with the <SEND_DATA> verb.
Figure 4-4. Sample Script Containing the APPC_EXPECTED Variable
<INBOUND> <SEND_DATA> <CONTENT>....00000002This is inbound data say appc_expected /* Displays‘This is inbound data’. */ <PREPARE_TO_RECEIVE> say appc_expected /* A 0 length string is displayed. */ </INBOUND>
APPC_ACTUAL_LENGTH
The APPC_ACTUAL_LENGTH variable contains the length of the data most recently received from the partner application. This value can be obtained from either the normal data from a <SEND_DATA> verb or from expedited data from a <SEND_EXPEDITED_DATA> verb. This variable contains the exact length of the data received from the partner, even if it exceeds 2048 bytes. Consequently, this value may be larger than the result of the REXX built-in: LENGTH(APPC_ACTUAL).
The APPC_ACTUAL_LENGTH variable contains a relevant value only immediately following the set of <CONTENT> tags that is associated with the <SEND_DATA> or the <SEND_EXPEDITED_DATA> verb, and its value is reset when the next script tag is encountered. The variable generates useful data only when it is set after APPC verbs that represent data received by Hiperstation for Mainframe Servers. As a result, using the variable in a section of the script where Hiperstation for Mainframe Servers is sending data will not produce meaningful data.
The example below shows the APPC_ACTUAL_LENGTH variable used to produce meaningful data after the <CONTENT> tag associated with the <SEND_DATA> verb.
Figure 4-5. Sample Script Containing the APPC_ACTUAL_LENGTH Variable
<INBOUND>8 <SEND_DATA> <CONTENT>....00000002This is inbound data say appc_actual_length /* The length of the actual data (may be more than 2048). */ <PREPARE_TO_RECEIVE> say appc_actual_length /* A 0 value is displayed.*/ </INBOUND>
APPC_EXPECTED_LENGTH
The APPC_EXPECTED_LENGTH variable contains the length of the data that Hiperstation for Mainframe Servers expects to receive from the partner application. This can either be normal data from a <SEND_DATA> verb or expedited data from a <SEND_EXPEDITED_DATA> verb. The value is the length of the data contained in the script or associated detail file. The length does not include any of the Hiperstation for Mainframe Servers header information that appears on <CONTENT> tags (the first 12 bytes).
This variable contains a relevant value only immediately following the set of <CONTENT> tags associated with the <SEND_DATA> or the <SEND_EXPEDITED_DATA> verb. Its value is reset when the next script tag is encountered. The variable generates useful data when it is set after APPC verbs that represent data received by Hiperstation for Mainframe Servers. Consequently, using the variable in a section of the script where Hiperstation for Mainframe Servers is sending data will not produce meaningful data.
The example below shows the APPC_EXPECTED_LENGTH variable used to produce meaningful data after the set of a <CONTENT> tag associated with a <SEND_DATA> verb.
Unattended Playback of APPC Scripts 4-39
Figure 4-6. Sample Script Containing the ACCP_EXPECTED_LENGTH Variable
<INBOUND>8 <SEND_DATA> <CONTENT>....00000002This is inbound data say appc_expected_length /* The length of data expcted to receve (20 bytes). */ <PREPARE_TO_RECEIVE> say appc_expected_length /* A 0 value is displayed. */ </INBOUND>
APPC General REXX Variables
The following variables return general playback information.
CYCLE
Returns the repeat value of the script. This value is set to one when a script begins execution.
GRPCYCLE
Returns the repeat value of the ALLOCATE or APPCGRP statement. This value is set to one when an ALLOCATE or APPCGRP statement begins execution.
The variable is increased by one each time an ALLOCATE or APPCGRP statement finishes all of its scripts. You can use the REPEAT keyword on the ALLOCATE or APPCGRP statement in batch processing.
The GRPCYCLE variable can be used to provide a unique value during each iteration of an ALLOCATE or APPCGRP statement’s execution.
PORT
Returns a value listing the port assigned to each ALLOCATE or APPCGRP statement. The variable is increased by one for each ALLOCATE or APPCGRP statement. You can use the COUNT keyword on an ALLOCATE or APPCGRP statement in batch processing.
APPC Summary ReportThe APPC summary report (Figure 4-7) lists performance and mismatch information from the execution of scripts using unattended playback.
Figure 4-7. APPC Summary Report Example
HIPERSTATION- SUMMARY REPORT TERMINAL ID: ** NA ** TPF NAME: H01APPCI TIME: 15:35:37 DATE: 06/06/27 PAGE: 000 -------------OUTBOUND---------------- ---------------- INBOUND --------------- SCRIPT PORT NUMBER MINIMUM AVERAGE MAXIMUM NUMBER MINIMUM AVERAGE MAXIMUM ELAPSED ------------------------------------------------------------------------------------------------------------------ SCR1003 3 1 00:00.298 00:00.298 00:00.298 1 00:00.095 00:00.095 00:00.095 00:00:06.007 SCR1003 3 1 00:00.007 00:00.007 00:00.007 1 00:00.017 00:00.017 00:00.017 00:00:06.692 SCR1003 3 1 00:00.013 00:00.013 00:00.014 1 00:00.014 00:00.014 00:00.014 00:00:06.538 SCR1003 3 1 00:00.007 00:00.007 00:00.007 1 00:00.026 00:00.026 00:00.026 00:00:06.377 *GRP-TOT 4 00:00.007 00:00.081 00:00.298 4 00:00.014 00:00.038 00:00.095 00:00:06.692
4-40 Hiperstation for Mainframe Servers User Guide
General InformationScript
The script being run. Two special script names, *SCR-TOT and *GRP-TOT, denote script and group totals, respectively.
Port
Each terminal is assigned a port ID. A port ID is associated with the script.
Outbound Performance InformationNumber
Number of SENDs or ALLOCATEs processed by the terminal for the script.
Minimum
Minimum response time for the SENDs or ALLOCATEs processed by the terminal for the script.
Average
Outbound average is calculated from the sum of all response times for the port, divided by the number of outbound transactions for that port.
Maximum
Maximum response time for the SENDs and ALLOCATEs processed by the terminal for the script.
Inbound Performance InformationNumber
Number of RECEIVEs or ACCEPTs processed by the terminal for the script.
Minimum
Minimum response time for the RECEIVEs or ACCEPTs processed by the terminal for the script.
Average
Inbound average is calculated from the sum of all think times for the port, divided by the number of inbound transactions for that port.
Maximum
Maximum response time for the RECEIVEs and ACCEPTs processed by the terminal for the script.
Elapsed TimeElapsed
Elapsed time is calculated based on the total amount of time it took the port and the application to process the total number of transactions. For *SCR-TOT, this is the maximum elapsed time of the individual scripts. For *GRP-TOT this is the sum of the *SCR-TOT elapsed times.
APPC Unattended Playback Example JobsThis section contains several example setups that illustrate how to play Hiperstation for Mainframe Servers APPC scripts using unattended playback.
Unattended Playback of APPC Scripts 4-41
Example 1: Play Back 100 APPC Conversations All at Once
This example is designed to stress test a CICS region by playing a previously recorded APPC conversation 100 times, with all conversations starting simultaneously. The COUNT(100) parameter starts multiple conversations with an application, all started when the ALLOCATE statement becomes active.
In this example, the ALLOCATE statement becomes active at the start of the playback job. Activating the ALLOCATE statement can be delayed using the USESTIME parameter on the CONTROL statement or the STARTDLY parameter on the ALLOCATE statement.
Figure 4-8. JCL to Play Back 100 APPC Conversations, All at Once
//HIPER EXEC PGM=EHSBATCH,REGION=8192K //STEPLIB DD DSN=HIPER.LOAD,DISP=SHR //SYSLIB DD DSN=MY.SCRIPTS,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSIN DD * CONTROL ALLOCATE SENDER(HS620001) RECEIVER(CICSA) COUNT(100) SCRIPT(CICS10)
Example 2: Play Back 100 APPC Conversations Started Every 3 Seconds
This example is designed to stress test a CICS region by using one previously recorded APPC conversation and playing it back 100 times. This time, however, rather than starting all of the conversations at once, Hiperstation for Mainframe Servers starts one every 3 seconds (perhaps to represent 100 users starting transactions at different times). The COUNT(100) parameter causes Hiperstation for Mainframe Servers to start multiple conversations, and the LOGD(3) parameter tells Hiperstation for Mainframe Servers to let three seconds elapse between the start of each conversation.
Figure 4-9. JCL to Play Back 100 APPC Conversations, One Started Every 3 Seconds
CONTROL ALLOCATE SENDER(HS620001) RECEIVER(CICSA) COUNT(100) LOGD(3) SCRIPT(CICS10)
Example 3: Play Back 100 APPC Conversations Started at Intervals
This example is designed to simulate a load on the CICS region similar to what existed at recording time. The USESTIME parameter on the CONTROL statement tells Hiperstation for Mainframe Servers to start these conversations at the same relative time intervals as originally recorded.
The ALLOCATE statement with the earliest STIME value is started when the playback job begins. The conversation that begins next is the one with the next higher STIME value. Because the STIME values cover a period from 7:00 AM through 11:30 AM, the playback job runs for 4.5 hours.
The USESTIME parameter only controls the start of a conversation; after a conversation has started, it runs at full speed, waiting only for any responses from the partner application found in the script. Using the THOPT(2) parameter on an ALLOCATE statement causes Hiperstation for Mainframe Servers to run its side of the conversation at the same speed as at recording time, rather than at full speed.
4-42 Hiperstation for Mainframe Servers User Guide
Figure 4-10. JCL to Play Back 100 Different APPC Conversations
CONTROL USESTIME ALLOCATE SENDER(HS620001) RECEIVER(CICSA) - STIME(‘2007/01/01_07:00:00.000000’) SCRIPT(CICS0001) ALLOCATE SENDER(HS620001) RECEIVER(CICSA) - STIME(‘2007/01/01_07:01:22.000000’) SCRIPT(CICS0002) . . (more ALLOCATE statements) . ALLOCATE SENDER(HS620001) RECEIVER(CICSA) - STIME(‘2007/01/01_11:30:00.000000’) SCRIPT(CICS0100)
Example 4: Play Back One Lengthened APPC Conversation
This example is designed to take a single APPC conversation and make it “longer” than the original recording. The purpose of this test is to see if the partner application in the CICS region can handle a high rate of inquiries contained within a single conversation.
An editor was used to create three scripts from the one script that was originally recorded.
• The START script contains only the <VERSION> and <ALLOCATE> tags.
• The BIGDATA script contains the <VERSION> tag, and the APPC verb tags are repeatedly sent to the application.
Note: The application must be able to run properly with the increased and repeated data. An inquiry program may be a likely candidate for such testing, but an update program may not be. Understanding how your target application operates is important when deciding if such a test is relevant and valid.
• The FINISH script contains only the <VERSION>, <OUTBOUND>, <DEALLOCATE>, and </OUTBOUND> tags.
This example causes the contents of the BIGDATA script to be sent to the CICSA application 1000 times. To successfully accomplish this, the BIGDATA script must contain APPC verbs in a sequence that the application can understand and process repeatedly.
Figure 4-11. JCL to Play Back One Lengthened APPC Conversation
ALLOCATE SENDER(HS620001) RECEIVER(CICSA) SCRIPT(START) SCRIPT(BIGDATA) REPEAT(1000) SCRIPT(FINISH)
Example 5: Play Back Two Related APPC Conversations
This example is designed to test an application that uses two physical APPC conversations to support a single, “logical” conversation. Each partner in the application uses one of the conversations as a “SEND” side and the other conversation as a “RECEIVE” side. This technique simulates a “full-duplex” conversation, where each side of the conversation is always able to send information without waiting for permission from the other side.
Because two physical conversations (the two scripts) are related by logic within the partner application, Hiperstation for Mainframe Servers must adhere to the time stamps in each script so that one participant of the logical conversation does not get ahead of
Unattended Playback of APPC Scripts 4-43
the other. The TIMESYNC parameter on the ALLOCATE statements tells Hiperstation for Mainframe Servers to send data from the scripts in the order shown by the time stamps. The TIMESYNC parameter must appear on each ALLOCATE (or ACCEPT) statement that participates in this cross-script sequencing.
Figure 4-12. JCL to Play Back Two Related APPC Conversations
CONTROL ALLOCATE SENDER(HS620001) RECEIVER(CICSA) TIMESYNC SCRIPT(CICSSND) ALLOCATE SENDER(HS620001) RECEIVER(CICSA) TIMESYNC SCRIPT(CICSRCV)
Example 6: Play Back APPC Conversations Started in Various Ways
This example is designed to demonstrate many of the timing parameters available for APPC scripts and to explain the effects. The parameters we describe are:
• USESTIME• COUNT• REPEAT• SYNCH• STIME• LOGD• STARTDLY• THOPT
The USESTIME parameter on the CONTROL statement causes Hiperstation for Mainframe Servers to start the ALLOCATE statements at the time interval indicated by the STIME parameter, which is on the ALLOCATE statement.
The ALLOCATE statement with the lowest STIME value is started when the playback job is started. The ALLOCATE statement that has the next higher STIME value is started after waiting the amount of time indicated by the difference in STIME values. An ALLOCATE statement without an STIME parameter is started as soon as the playback job starts.
A description of each ALLOCATE statement follows the example in Figure 4-13.
Figure 4-13. JCL to Play Back Several APPC Conversations Started in Various Ways
CONTROL USESTIME * * Allocate 1 * ALLOCATE SENDER(HS620001) RECEIVER(CICSA) COUNT(10) SYNCH - STIME(‘2006/07/19_12:00:00.000000’) SCRIPT(CICS1) * * Allocate 2 * ALLOCATE SENDER(HS620001) RECEIVER(CICSA) COUNT(10) LOGD(3) - STIME(‘2006/07/19_12:05:00.000000’) SCRIPT(CICS1) * * Allocate 3 * ALLOCATE SENDER(HS620001) RECEIVER(CICSA) REPEAT(5) THOPT(2) SCRIPT(CICS1) * * Allocate 4 * ALLOCATE SENDER(HS620001) RECEIVER(CICSA) COUNT(100) REPEAT(5) STARTDLY(30) SCRIPT(CICS1)
4-44 Hiperstation for Mainframe Servers User Guide
Allocate 1
The COUNT(10) parameter on ALLOCATE 1 causes ten conversations to start at once, as soon as the STIME value permits. Because the SYNCH parameter is supplied, those ten conversations do not run at full speed, but instead run at the speed of the “slowest” conversation.
Hiperstation for Mainframe Servers sends the first SEND_DATA verb in each of the ten conversations at the same instant. If a response is expected from the application, the second SEND_DATA verb in each conversation is not issued until the application issues its response to all ten conversations. Each subsequent verb that Hiperstation for Mainframe Servers issues is sent at the same instant for all ten conversations (after waiting for the ten responses from the application).
This technique for keeping all data sent from Hiperstation for Mainframe Servers in step across multiple conversations is most useful in stress testing individual parts of an application program. The SYNCH parameter ensures that the ten running application instances all receive their data from Hiperstation for Mainframe Servers at the same time.
Allocate 2
This ALLOCATE statement starts five minutes after the first ALLOCATE statement because its STIME value is five minutes later. The COUNT(10) parameter specifies that ten conversations are to start and the LOGD(3) parameter tells Hiperstation to start them three seconds apart. After the conversations start, they run at full speed.
Allocate 3
This ALLOCATE statement starts as soon as the playback job is started because no STIME parameter is present. The REPEAT(5) parameter tells Hiperstation for Mainframe Servers to start the five conversations one at a time, each new conversation starting after the previous one has ended.
After a conversation starts, the THOPT(2) parameter tells Hiperstation for Mainframe Servers to send data at the same time intervals as the original recording. This is controlled by the time stamps found within the script.
Hiperstation for Mainframe Servers does not have control over the speed of the partner application’s response, only the speed that the data is sent to the partner.
Allocate 4
This ALLOCATE statement starts thirty seconds after the playback job is started due to the presence of the STARTDLY(30) parameter. The COUNT(100) parameter indicates that 100 conversations start simultaneously. Those conversations run at full speed, affected by system resources. As soon as one conversation ends, a new conversation starts in its place, a total of five times. This ALLOCATE statement causes 500 conversations to run.cc
APPC Data-Driven Testing Example Using REXXThis section illustrates data-driven testing with a series of APPC conversations that together form a complete “business transaction”. The transaction in this example includes three APPC conversations. The first, generates a unique record key that the subsequent conversations use to retrieve and process data. To ensure a successful testing:
• The conversations must be played back in the correct sequence and each conversation must be completed before the next begins.
• The record key recorded in the scripts must be replaced with the key that is generated by the server during playback.
Unattended Playback of APPC Scripts 4-45
Review the scripts for a thorough understanding of the business transaction’s data flow (next), then learn how to:
• Extract the information generated by the server that is used in all of the conversations, page 4-47.
• Share the extracted information with all of the scripts. This requires passing the information to and retrieving it from shared storage, page 4-48.
• Replace the recorded information with the stored information during each iteration of the playback, page 4-51.
• Alter the initial request string during each iteration of playback to exercise the application with unique requests, page 4-53.
• Play back the script serially to ensure a successful playback, and play back the script multiple times to stress or volume test the application, page 4-54.
Review the Scripts
The business transaction sited in this example is comprised of three APPC conversations, each using information from the previous conversation.
Hiperstation for Mainframe Servers creates a separate script for each recorded APPC conversation. It gives each script a unique name based on prefix and suffix specified on the “APPC - Script Datasets Screen” (Figure 2-5 on page 2-8). However, following the example is easier if the scripts have meaningful names. Therefore, the scripts are referred to as:
1. REQUEST shown in Figure 4-14 The client sends a request string to a CICS server. The CICS server transaction stores the request internally and returns a unique key to the client.
2. ADDDATA shown in Figure 4-15 The client sends the key returned by the REQUEST conversation to a second CICS server transaction, which uses the key to retrieve the stored request and add a timestamp to the request. The server returns the modified request to the client and stores a copy of the request internally for future processing.
3. PROCESS shown in Figure 4-16 The client sends the same key to a third CICS server transaction. The server uses the passed key to retrieve the request string (signon ID+timestamp). It then destroys the internal store, processes the request, and delivers the results to the client. Processing results in a reversed request string.
The activity was recorded from the client perspective. Therefore, “Outbound” represents flows from the client to the CICS server transactions. “Inbound” represents flows into the client from the server.
4-46 Hiperstation for Mainframe Servers User Guide
Figure 4-14. Recorded REQUEST Script
<VERSION>8 <DETAIL COMBINED='*'> <TIME>2006/07/21_09:51:00.523225 <ALLOCATE TPNAME=H4S SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.523225' FTIME='2006/07/21_09:51:00.614087', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.523225 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER0001 <TIME>2006/07/21_09:51:00.523225 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.614087 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000006HPER045C <TIME>2006/07/21_09:51:00.614087 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
<CONTENT> 00000004 shows the initial request coming from the client.
<CONTENT> 00000006 shows the unique key that the server generated and returned (HPER045C).
Figure 4-15. Recorded ADDDATA Script
<VERSION>8 <DETAIL COMBINED='*'> <ALLOCATE TPNAME=H4M SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.617627' FTIME='2006/07/21_09:51:00.763590', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.617627 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000002HPER045C <TIME>2006/07/21_09:51:00.617627 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.763590 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER000109:51:01 <TIME>2006/07/21_09:51:00.763590 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
<CONTENT> 00000002 shows the key, which was initially returned from the server in the REQUEST transaction, being sent by the client to the CICS server to retrieve the request record.
<CONTENT> 00000004 shows the server’s response, which is the initial request string concatenated with a timestamp suffix.
Unattended Playback of APPC Scripts 4-47
Figure 4-16. Recorded PROCESS Script
<VERSION>8 <DETAIL COMBINED='*'> <TIME>2006/07/21_09:51:00.768107 <ALLOCATE TPNAME=H4T SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.768107' FTIME='2006/07/21_09:51:00.921482', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.768107 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000002HPER045C <TIME>2006/07/21_09:51:00.768107 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.921482 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 0000000410:15:901000REVEROF NOTREVE <TIME>2006/07/21_09:51:00.921482 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
<CONTENT> 00000002 shows the REQUEST key again being forwarded to the CICS server by the client to request processing.
<CONTENT> 00000004 shows the processed data being returned from the server, that is, the reversed concatenated request string.
Extract the Key
Playing back the testing scripts initiates a new business transaction, which causes the server to generate a new key. Propagate the newly generated key through all of the scripts, for each iteration of playback, to prevent the application from producing an error and playback from failing.
Use the following Hiperstation for Mainframe Servers REXX variables to extract the newly generated key:
• APPC_ACTUAL — Returns the content of received APPC data.
• APPC_ACTUAL_LENGTH — Returns the length of the received APPC data.
Hiperstation for Mainframe Servers destroys the contents of these variables when the conversation terminates (indicated with the <DEALLOCATE> tag), so create your own variables that assume the values of the REXX variables. For example, actual_data = APPC_ACTUAL.
In the <INBOUND> section of the REQUEST script, after the <SEND_DATA> and its associated <CONTENT> tag, insert the REXX APPC variable assignments and a “SAY” instruction to present the actual data and the actual data length in the job log.
Figure 4-17 shows the modified REQUEST script. Additions are indicated with bold text.
4-48 Hiperstation for Mainframe Servers User Guide
Figure 4-17. REQUEST Script with Hiperstation for Mainframe Servers REXX Variables
<VERSION>8 <DETAIL COMBINED='*'> <TIME>2006/07/21_09:51:00.523225 <ALLOCATE TPNAME=H4S SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.523225' FTIME='2006/07/21_09:51:00.614087', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.523225 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER0001 <TIME>2006/07/21_09:51:00.523225 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.614087 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000006HPER045C actual_data = APPC_ACTUAL actual_data_length = APPC_ACTUAL_LENGTH say “APPC actual data is:” APPC_ACTUAL “Length:” APPC_ACTUAL_LENGTH <TIME>2006/07/21_09:51:00.614087 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
Share the Key
Sharing the extracted key is the next step in replacing the key that is recorded in the scripts with the newly generated key. This requires:
• Adding logic to the REQUEST script to pass the extracted key to a common storage area.
• Adding logic to the ADDDATA and PROCESS scripts to retrieve the key from the shared area.
To share the key:
1. Add the USERDATA DD statement to the JCL to define the amount of shared storage. For example,
//USERDATA DD DUMMY,BUFNO=1,BUFL=800
BUFNO is the number of buffers. BUFL is the length of each buffer. BUFNO multiplied by BUFL equals the total bytes of storage defined.
Note: Do not use the first 8 bytes of this area, as Hiperstation for Mainframe Servers uses it for internal purposes. However, these instructions provide for this consideration.
2. Copy the HSGET and HSPUT routines from the Hiperstation samples library, SQQFSAMP, into the dataset containing the APPC scripts.
Note: SQQFSAMP member HSNOTE1 provides functional descriptions of these routines.
3. Insert an HSPUT() call, without parameters, into the beginning of the REQUEST script, just after the <VERSION> and <DETAIL> tags, to initialize the shared area. Include an IF statement to validate successful completion of the call based on the return code. A return code of 1 indicates success. Use the REXX EXIT instruction to terminate playback if the call fails.
Note: Although, initialization is required only once, the HSPUT() call is executed each time the script plays back. The return code for a successful HSPUT
Unattended Playback of APPC Scripts 4-49
initialization is one. The return code for subsequent successful HSPUT calls is zero. Any return code greater than one indicates call failure.
The bold text at the top of Figure 4-18 on page 4-49 shows this logic.
4. Insert another HSPUT call at the end of the REQUEST script, after the closing </INBOUND> tag, to copy the extracted key to the stored area. This time include the following parameters:
– actual_data — Returns the extracted key value.
– offset — Defines where in the shared area to begin writing the key value. These scripts can be played back multiple times concurrently. If the offset is defined as a static value, the routine overwrites the key each time the group of scripts plays back. Use the Hiperstation PORT variable to define a unique offset. Hiperstation for Mainframe Servers assigns a unique port number to each thread in an APPCGRP replay. For example, if three instances of the group of scripts play back concurrently (COUNT(3)), the port in the first instance is one, the second is two, and the third is three. Since the key is eight bytes, set the offset=PORT*8. This also preserves the first eight bytes for Hiperstation for Mainframe Servers internal use.
Again, include an IF statement to validate successful completion of the HSPUT call. Remember, all successful HSPUT calls that occur after initialization produce a return code of zero, so set the IF condition to RETC>0. Use the EXIT instruction to terminate playback if the call fails. The bold text at the bottom of Figure 4-18 on page 4-49 shows this logic.
Figure 4-18. REQUEST Script with Key Sharing Logic
<VERSION>8 <DETAIL COMBINED='*'> RETC = HSPUT() IF RETC>1 THEN DO SAY “Initial HSPUT failed with return code:” retc EXIT END <TIME>2006/07/21_09:51:00.523225 <ALLOCATE TPNAME=H4S SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.523225' FTIME='2006/07/21_09:51:00.614087', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.523225 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER0001 <TIME>2006/07/21_09:51:00.523225 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.614087 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000006HPER045C actual_data = APPC_ACTUAL actual_data_length = APPC_ACTUAL_LENGTH say “APPC actual data is:” APPC_ACTUAL “Length:” APPC_ACTUAL_LENGTH <TIME>2006/07/21_09:51:00.614087 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND> offset = PORT*8 RETC = HSPUT(actual_data,offset) IF retc>0 THEN DO SAY “HSPUT storage of data on port” PORT “failed. Return code:” RETC EXIT END
5. Insert an HSPUT() call, without parameters, into the beginning of the ADDDATA and PROCESS scripts, just after the <VERSION> and <DETAIL> tags, to verify that the shared area exists. Include an IF statement to validate successful completion of the
4-50 Hiperstation for Mainframe Servers User Guide
call based on a return code of zero. Use the REXX EXIT instruction to terminate playback if the call fails.
The bold text at the top of Figure 4-19 on page 4-50 and Figure 4-20 on page 4-51 shows this logic.
6. Below the HSPUT() call in the ADDDATA and PROCESS scripts, insert HSGET(offset,8) to retrieve the key from shared storage.
– “offset” indicates where to find the key in the storage area. Provide the same definition for offset here as was defined in storing the key (offset=PORT*8).
– “8” indicates the length of the data to retrieve.
Assign a variable to the HSGET(offset,8) value to use for validation. HSGET returns a null string if the call fails. Using the variable assigned to the HSGET value, create an IF statement that compares the length of the returned key to zero. Include a SAY instruction:
– To print a failure message in the job log if the length is zero. Terminate the playback with the REXX EXIT instruction.
– To print the returned key value and length in the job log if the length is not zero.
Finally, use the REXX substring instruction to ensure the returned key is eight characters long.
The bold text beneath the second asterisk (*) in Figure 4-19 on page 4-50 and Figure 4-20 on page 4-51 shows this logic.
Figure 4-19. ADDDATA Script with Key Sharing Logic
<VERSION>8 <DETAIL COMBINED='*'> * RETC = HSPUT() IF RETC>0 THEN DO SAY “ADDDATA initialization of HSPUT failed with return code:” RETC EXIT END * offset = PORT*8 key_field = HSGET(offset,8) IF LENGTH(key_field) = 0 THEN DO SAY “ADDDATA HSGET retrieval of data failed” EXIT END ELSE SAY “Retrieved HSGET data is:” key_field “Length:” LENGTH(key_field) key=substr(key_field,1,8) <ALLOCATE TPNAME=H4M SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.617627' FTIME='2006/07/21_09:51:00.763590', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.617627 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000002HPER045C <TIME>2006/07/21_09:51:00.617627 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.763590 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER000109:51:01 <TIME>2006/07/21_09:51:00.763590 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
Unattended Playback of APPC Scripts 4-51
Figure 4-20. PROCESS Script with Key Sharing Logic
<VERSION>8 <DETAIL COMBINED='*'> * RETC = HSPUT() IF RETC>0 THEN DO SAY “PROCESS initialization of HSPUT failed with return code:” RETC EXIT END * offset = PORT*8 key_field = HSGET(offset,8) IF LENGTH(key_field) = 0 THEN DO SAY “PROCESS HSGET retrieval of data failed” EXIT END ELSE SAY “Retrieved HSGET data is:” key_field “Length:” LENGTH(key_field) key=substr(key_field,1,8) <TIME>2006/07/21_09:51:00.768107 <ALLOCATE TPNAME=H4T SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.768107' FTIME='2006/07/21_09:51:00.921482', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.768107 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000002HPER045C <TIME>2006/07/21_09:51:00.768107 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.921482 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 0000000410:15:901000REVEROF NOTREVE <TIME>2006/07/21_09:51:00.921482 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
Replace the Key
Now it is time to add logic to replace the recorded key with the newly generated key. Insert the Hiperstation REPLACE verb in the <OUTBOUND> section of the ADDDATA and PROCESS scripts, after the <TIME> tag and before the <SEND_DATA> tag. This verb has two parameters:
• FIELD(offset,data) — “offset” indicates where to begin replacing data. Since the only data being sent is the key, set “offset” to 0 (zero) to replace data starting with the first byte. The “data” value is the string or REXX variable that replaces the specified information. In this case, set “data” to “key” as that is the variable assigned to the retrieved key by the substring instruction.
• TYPE — Stipulates alteration of next or all subsequent <SEND_DATA> <CONTENT> values. In this example, the next <SEND_DATA> is the only value requiring data replacement, so set TYPE=ONE.
See “<REPLACE> Tag” on page 4-7 for more information. Figure 4-21 and Figure 4-22 show this logic in bold text.
4-52 Hiperstation for Mainframe Servers User Guide
Figure 4-21. ADDDATA Script with Key Replacement Logic
<VERSION>8 <DETAIL COMBINED='*'> * RETC = HSPUT() IF RETC>0 THEN DO SAY “ADDDATA initialization of HSPUT failed with return code:” RETC EXIT END * offset = PORT*8 key_field = HSGET(offset,8) IF LENGTH(key_field) = 0 THEN DO SAY “ADDDATA HSGET retrieval of data failed” EXIT END ELSE SAY “Retrieved HSGET data is:” key_field “Length:” LENGTH(key_field) key=substr(key_field,1,8) <ALLOCATE TPNAME=H4M SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.617627' FTIME='2006/07/21_09:51:00.763590', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.617627 <REPLACE FIELD=(0,key) TYPE=ONE> <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000002HPER045C <TIME>2006/07/21_09:51:00.617627 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.763590 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER000109:51:01 <TIME>2006/07/21_09:51:00.763590 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
Unattended Playback of APPC Scripts 4-53
Figure 4-22. PROCESS Script with Key Replacement Logic
<VERSION>8 <DETAIL COMBINED='*'> * RETC = HSPUT() IF RETC>0 THEN DO SAY “PROCESS initialization of HSPUT failed with return code:” RETC EXIT END * offset = PORT*8 key_field = HSGET(offset,8) IF LENGTH(key_field) = 0 THEN DO SAY “PROCESS HSGET retrieval of data failed” EXIT END ELSE SAY “Retrieved HSGET data is:” key_field “Length:” LENGTH(key_field) key=substr(key_field,1,8) <TIME>2006/07/21_09:51:00.768107 <ALLOCATE TPNAME=H4T SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.768107' FTIME='2006/07/21_09:51:00.921482', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.768107 <REPLACE FIELD(0,key) TYPE=ONE> <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000002HPER045C <TIME>2006/07/21_09:51:00.768107 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.921482 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 0000000410:15:901000REVEROF NOTREVE <TIME>2006/07/21_09:51:00.921482 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
Alter the Request String
The group of scripts forming the business transaction plays back successfully at this point. However, the scripts, as they exist, repeatedly execute the same request: EVERTON FOREVER0000.
Use the Hiperstation:
• REPLACE verb to modify the request string each time the group of scripts play back.
• REXX variables PORT and GRPCYCLE to provide a unique value for request string data replacement. As previously discussed, PORT returns the value of the COUNT playback parameter — that is, the unique number assigned to each thread in the APPCGRP replay. GRPCYCLE returns the value of the REPEAT playback parameter, which denotes the iteration of playback.
In the REQUEST script:
• Just above the <OUTBOUND> block, insert a variable assignment based on the PORT and GRPCYCLE variables. Use standard REXX functions to identify the portion of the PORT and GRPCYCLE counts to return. In this case, the two digits from the right of each count. Indicate a character to pad the returned value with if the value is not two digits. This example pads the value on the left with zeros. Concatenate the returned values with the REXX concatenation operator || to create a unique four-digit value.
• In the <OUTBOUND> block, after the <TIME> tag, insert the Hiperstation REPLACE verb with an “offset” value of 15 and “data” value of the variable assigned to the PORT||GRPCYCLE concatenation.
4-54 Hiperstation for Mainframe Servers User Guide
This results in a unique request string for each instance and iteration of the playback. For example, if you play back the script twice concurrently and repeat the playback three times, the request string increments as follows:
• EVERTON FOREVER0101• EVERTON FOREVER0201• EVERTON FOREVER0102• EVERTON FOREVER0202• EVERTON FOREVER0103• EVERTON FOREVER0203
The bold text in Figure 4-23 on page 4-54 shows this logic.
Figure 4-23. REQUEST Script with Request Modification Logic
<VERSION>8 <DETAIL COMBINED='*'> RETC = HSPUT() IF RETC>1 THEN DO SAY “Initial HSPUT failed with return code:” retc EXIT END <TIME>2006/07/21_09:51:00.523225 <ALLOCATE TPNAME=H4S SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.523225' FTIME='2006/07/21_09:51:00.614087', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> newiter=right(PORT,2,’0’)||right(GRPCYCLE,2,’0’) <OUTBOUND> <TIME>2006/07/21_09:51:00.523225 <REPLACE FIELD=(15,newiter) TYPE=ONE> <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER0001 <TIME>2006/07/21_09:51:00.523225 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.614087 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000006HPER045C actual_data = APPC_ACTUAL actual_data_length = APPC_ACTUAL_LENGTH say “APPC actual data is:” APPC_ACTUAL “Length:” APPC_ACTUAL_LENGTH <TIME>2006/07/21_09:51:00.614087 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND> offset = PORT*8 RETC = HSPUT(actual_data,offset) IF retc>0 THEN DO SAY “HSPUT storage of data on port” PORT “failed. Return code:” RETC EXIT END
Play Scripts Serially and Concurrently
Hiperstation for Mainframe Servers offers three input statements for designating which scripts (conversations) to play back and how to play them back:
• ALLOCATE — Use this statement to play back a single APPC conversation with Hiperstation for Mainframe Servers initiating the conversation.
• ACCEPT — Use this statement to play back a single APPC conversation with Hiperstation for Mainframe Servers receiving the conversation.
• APPCGRP — Use this statement to play multiple APPC conversations back.
See “APPC Unattended Playback Statements” on page 4-16, for more information.
All three of these statements offer the COUNT and REPEAT parameters to play the scripts back multiple times for stress or volume testing.
Unattended Playback of APPC Scripts 4-55
• COUNT(n) plays back the scripts within the ALLOCATE/ACCEPT/APPCGRP n times concurrently.
• REPEAT(n) plays the scripts within the ALLOCATE/ACCEPT/APPCGRP n times, one after the other.
Use them together to play multiple threads repeatedly. For example, COUNT(2) REPEAT(3), plays back two instances of the script at the same time, three times in a row. Couple this with the APPCGRP statement to repeatedly play back multiple threads of a series of APPC conversations, such as the business transaction described in this example.
The rest of this discussion provides an example of the playback control statements and JCL necessary to repeatedly play back multiple threads of this business transaction. It also shows the resulting job logs.
Create Playback Control Statements for the Business Transaction
Manually build playback control statements or generate a conversation log during script creation to use as the SYSIN for the job.
In the conversation log, Hiperstation for Mainframe Servers creates a separate ALLOCATE statement for each APPC conversation. Generating the log is the easiest method if you need to play the conversations back concurrently. However, if you need to play multiple conversations back serially, manually building the statements is less work than modifying the log.
Figure 4-24 on page 4-56 shows the conversation log generated for the scripts in this example. Figure 4-25 on page 4-56 shows the playback control statements necessary to play the scripts back serially, which is required to complete the business transaction successfully.
In this example, SENDER and RECEIVER are the only common parameters between the APPCGRP statement and the generated ALLOCATE statements. This is due to the statement hierarchy. That is, the parameters defined on the ALLOCATE or APPCGRP statement override the parameters recorded in the scripts under the given statement. Since the scripts within the APPCGRP statement contain information from different conversations, the control parameters may be different from script to script. For example, the TPNAME for each conversation is different. Hiperstation retrieves the necessary information from the scripts during playback.
In the conversation log:
• The SENDER and RECEIVER values reflect the client and server VTAM LU names. During playback, Hiperstation assumes the role of the sender or the receiver depending on the selected playback control statement and the SENDER and RECEIVER parameters. For example, if you want Hiperstation to initiate the conversation, use the ALLOCATE or APPCGRP statement and specify Hiperstation’ VTAM LU name on the SENDER parameter. If you want Hiperstation to receive the conversation, use the ACCEPT or APPCGRP statement and specify the appropriate LU name on the RECEIVER parameter.
• The script names reflect the names generated by Hiperstation. In this example, the script members were renamed for easy recognition. Make sure the values specified in the SCRIPT statements reflect the actual member names as shown in manually built control statements (Figure 4-25).
The manually built playback control information (Figure 4-25) also includes a:
• CONTROL statement with the MSGFORM parameter, which prints timestamps in the job log.
• COUNT parameter with a value of 2 on the APPCGRP statement. This initiates two threads of the business transaction. That is, it plays the same group of scripts twice concurrently.
4-56 Hiperstation for Mainframe Servers User Guide
• REPEAT parameter with a value of 2 on the APPCGRP statement. This causes playback of the two threads to repeat a second time.
Figure 4-24. APPC Conversation Log for Example Scripts
********************************* Top of Data ********************************** * LOG STARTED ON 2006/12/18 AT 17:05:10 * DESC: * * ALLOCATE NUMBER(1) * ALLOCATE TPNAME(H4S) SENDER(USCWXN01.H01AC079) RECEIVER(USCWXN01.H01AC127)- LOGMODE(#INTER) TYPE(MAPPED) SYNCLVL(NONE) SECURITY(NONE)- STIME('2006/09/18_08:50:59.713241') FTIME('2006/09/18_08:50:59.804103')- CONVCORR('-AD1') LUWNAME(USCWXN01.TCW00567) LUWINST('0AB30B1787D5'X)- LUWSEQ('0001'X) SCRIPT(TST00002) * * ALLOCATE NUMBER(2) * * ALLOCATE TPNAME(H4M) SENDER(USCWXN01.H01AC079) RECEIVER(USCWXN01.H01AC127)- LOGMODE(#INTER) TYPE(MAPPED) SYNCLVL(NONE) SECURITY(NONE)- STIME('2006/09/18_08:50:59.807643') FTIME('2006/09/18_08:50:59.953606')- CONVCORR('-AD1') LUWNAME(USCWXN01.TCW00567) LUWINST('0AB30B1787D5'X)- LUWSEQ('0001'X) SCRIPT(TST00003) * * ALLOCATE NUMBER(3) * * ALLOCATE TPNAME(H4T) SENDER(USCWXN01.H01AC079) RECEIVER(USCWXN01.H01AC127)- LOGMODE(#INTER) TYPE(MAPPED) SYNCLVL(NONE) SECURITY(NONE)- STIME('2006/09/18_08:50:59.958123') FTIME('2006/09/18_08:51:00.111498') - CONVCORR('-AD1')LUWNAME(USCWXN01.TCW00567) LUWINST('0AB30B1787D5'X)- LUWSEQ('0001'X) SCRIPT(TST00004) * * LOG FINISHED ON 2006/12/18 AT 17:05:11 * ******************************** Bottom of Data ********************************
Figure 4-25. Control Statements to Play Scripts Back Serially
********************************* Top of Data ********************************** CONTROL MSGFORM APPCGRP SENDER(UXCWXN01.H01APPCP) RECEIVER(USCWXN01.H01AC127) COUNT(2) REPEAT(2) SCRIPT(REQUEST) SCRIPT(ADDDATA) SCRIPT(PROCESS) ******************************** Bottom of Data ********************************
Create JCL to Play Back the Business Transaction
The following illustration shows standard Hiperstation for Mainframe Servers playback JCL with the addition of the USERDATA DD defining the shared storage area for the key replacement logic depicted in this example. See “Step 5. Submit the Batch Job” on page 4-1, for all other DD statement definitions. This sample also shows in-line control statements. You can store them in a dataset, if you like, and reference the dataset name on the SYSIN DD.
Unattended Playback of APPC Scripts 4-57
Figure 4-26. JCL for the Example Business Transaction
//HIPER EXEC PGM=EHSBATCH,REGION=4096K //STEPLIB DD DSN=SYS2.COMPWARE.QQF800.SQQFLOAD,DISP=SHR //SYSLIB DD DSN=USR2503.APPC.SCRIPT,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //USERDATA DD DUMMY,BUFNO=1,BUFL=800 //SYSIN DD * CONTROL MSGFORM * * ALLOCATE NUMBER(1) * APPCGRP SENDER(USCWXN01.H01APPCP) RECEIVER(USCWXN01.H01AC127)- COUNT(1) SCRIPT(REQUEST) SCRIPT(ADDDATA) SCRIPT(PROCESS)
Review the Playback Job Logs
This section shows the job logs resulting from a single thread, single iteration playback; a multiple thread, single iteration playback; and a multiple thread, multiple iteration playback.
Figure 4-27 shows the job log for a single thread, single iteration playback of the example business transaction.
The REXX SAY statements generated by the REQUEST script show the key (HPER055C) generated by the CICS Server at replay time.
The SAY statements generated by the ADDDATA script show that the:
• Correct key value was retrieved by HSGET.
• Original request was returned with the timestamp concatenation, which verifies that the second CICS Server transaction completed successfully.
• Original request string was successfully updated with the concatenated, two-digit PORT and GRPCYCLE values (0101). If you recall, the first two digits reflect the count value (thread) and the last two reflect the repeat value (iteration).
The SAY statements generated by the PROCESS script show that the:
• HSGET correctly retrieved the replay key.
• Request string was returned in reverse, which verifies that the third CICS server transaction completed successfully
Figure 4-27. Job Log for a Single Thread, Single Iteration Playback
10:21:25 GROUP MSTR PORT MSTR EHSB018I INPUT CONTROL STATEMENT SCAN COMPLETE 10:21:25 GROUP MSTR PORT MSTR EHSB910I REPLAY STARTING: 09/18/06 AT 10:21:25 10:21:25 GROUP MSTR PORT MSTR EHSB000I ALL PORTS ATTACHED 10:21:25 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT REQUEST PLAY OUTBOUND 10:21:26 GROUP 0001 PORT 0001 APPC actual data is: HPER055C Length: 8 10:21:26 GROUP 0001 PORT 0001 Actual data is: HPER055C Length: 8 10:21:26 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT REQUEST 10:21:26 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT ADDDATA PLAY OUTBOUND 10:21:26 GROUP 0001 PORT 0001 retrieved HSGET data is: HPER055C Length: 8 10:21:26 GROUP 0001 PORT 0001 APPC actual data: EVERTON FOREVER010110:21:27 Length: 27 10:21:26 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT ADDDATA 10:21:26 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT PROCESS PLAY OUTBOUND 10:21:26 GROUP 0001 PORT 0001 retrieved HSGET data is: HPER055C Length: 8 10:21:26 GROUP 0001 PORT 0001 PROCESS data returned: 72:12:011010REVEROF NOTREVE Length: 27 10:21:26 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT PROCESS 10:21:26 GROUP 0001 PORT 0001 EHSB024I BEING TERMINATED 10:21:26 GROUP 0001 PORT 0001 EHSB003I PORT TERMINATED 10:21:26 GROUP MSTR PORT MSTR EHSB004I GROUP 0001 TERMINATED 10:21:26 GROUP MSTR PORT MSTR EHSB020I ALL PORTS TERMINATED
4-58 Hiperstation for Mainframe Servers User Guide
Now examine Figure 4-28 to see how initiating a second thread (increasing the COUNT parameter value to two) impacts the job log. Notice that the first two digits of the request string suffix reflect the playback thread. See how they match the reported PORT number.
Figure 4-28. Job Log for a Multiple Thread, Single Iteration Playback
10:24:23 GROUP MSTR PORT MSTR EHSB018I INPUT CONTROL STATEMENT SCAN COMPLETE 10:24:24 GROUP MSTR PORT MSTR EHSB910I REPLAY STARTING: 09/18/06 AT 10:24:24 10:24:24 GROUP MSTR PORT MSTR EHSB000I ALL PORTS ATTACHED 10:24:24 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT REQUEST PLAY OUTBOUND 10:24:24 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT REQUEST PLAY OUTBOUND 10:24:24 GROUP 0001 PORT 0002 APPC actual data is: HPER062C Length: 8 10:24:24 GROUP 0001 PORT 0002 Actual data is: HPER062C Length: 8 10:24:24 GROUP 0001 PORT 0001 APPC actual data is: HPER063C Length: 8 10:24:24 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT REQUEST 10:24:24 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT ADDDATA PLAY OUTBOUND 10:24:24 GROUP 0001 PORT 0001 Actual data is: HPER063C Length: 8 10:24:24 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT REQUEST 10:24:24 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT ADDDATA PLAY OUTBOUND 10:24:24 GROUP 0001 PORT 0002 retrieved HSGET data is: HPER062C Length: 8 10:24:24 GROUP 0001 PORT 0001 retrieved HSGET data is: HPER063C Length: 8 10:24:24 GROUP 0001 PORT 0001 APPC actual data: EVERTON FOREVER010110:24:25 Length: 27 10:24:24 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT ADDDATA 10:24:24 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT PROCESS PLAY OUTBOUND 10:24:24 GROUP 0001 PORT 0002 APPC actual data: EVERTON FOREVER020110:24:25 Length: 27 10:24:24 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT ADDDATA 10:24:24 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT PROCESS PLAY OUTBOUND 10:24:24 GROUP 0001 PORT 0001 retrieved HSGET data is: HPER063C Length: 8 10:24:24 GROUP 0001 PORT 0002 retrieved HSGET data is: HPER062C Length: 8 10:24:24 GROUP 0001 PORT 0001 PROCESS data returned: 52:42:011010REVEROF NOTREVE Length: 27 10:24:24 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT PROCESS 10:24:24 GROUP 0001 PORT 0001 EHSB024I BEING TERMINATED 10:24:24 GROUP 0001 PORT 0002 PROCESS data returned: 52:42:011020REVEROF NOTREVE Length: 27 10:24:24 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT PROCESS 10:24:24 GROUP 0001 PORT 0002 EHSB024I BEING TERMINATED 10:24:24 GROUP 0001 PORT 0001 EHSB003I PORT TERMINATED 10:24:24 GROUP 0001 PORT 0002 EHSB003I PORT TERMINATED 10:24:24 GROUP MSTR PORT MSTR EHSB004I GROUP 0001 TERMINATED 10:24:24 GROUP MSTR PORT MSTR EHSB020I ALL PORTS TERMINATED
Figure 4-29 shows a truncated job log from a multiple thread, multiple iteration playback. Each iteration of the APPCGRP REPEAT increments the supplied GRPCYCLE REXX variable, starting at 1 on the first iteration. Examine the job log to see how using GRPCYCLE makes each request unique across business transaction iterations.
This time, the LOGD, or Logon Delay, parameter was added to the APPCGRP statement to offset the start time of each thread. In this case, the parameter is LOGD(1), or one second. The job log shows that port (Thread) two started one second after port (Thread) one.
Unattended Playback of APPC Scripts 4-59
Figure 4-29. Job Log for a Multiple Thread, Multiple Iteration Playback
10:27:41 GROUP MSTR PORT MSTR EHSB018I INPUT CONTROL STATEMENT SCAN COMPLETE 10:27:41 GROUP MSTR PORT MSTR EHSB910I REPLAY STARTING: 09/18/06 AT 10:27:41 10:27:41 GROUP 0001 PORT 0002 EHSB054I START SYNCHRONIZATION AND/OR DELAY REQUESTED 10:27:41 GROUP MSTR PORT MSTR EHSB000I ALL PORTS ATTACHED 10:27:41 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT REQUEST PLAY OUTBOUND 10:27:41 GROUP 0001 PORT 0001 APPC actual data is: HPER072C Length: 8 10:27:41 GROUP 0001 PORT 0001 Actual data is: HPER072C Length: 8 10:27:41 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT REQUEST 10:27:41 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT ADDDATA PLAY OUTBOUND 10:27:41 GROUP 0001 PORT 0001 retrieved HSGET data is: HPER072C Length: 8 10:27:41 GROUP 0001 PORT 0001 APPC actual data: EVERTON FOREVER010110:27:42 Length: 27 10:27:41 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT ADDDATA 10:27:41 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT PROCESS PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0001 retrieved HSGET data is: HPER072C Length: 8 10:27:42 GROUP 0001 PORT 0001 PROCESS data returned: 24:72:011010REVEROF NOTREVE Length: 27 10:27:42 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT PROCESS 10:27:42 GROUP 0001 PORT 0001 EHSB024I BEING TERMINATED 10:27:42 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT REQUEST PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0001 APPC actual data is: HPER075C Length: 8 10:27:42 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT REQUEST 10:27:42 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT ADDDATA PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0001 retrieved HSGET data is: HPER075C Length: 8 10:27:42 GROUP 0001 PORT 0001 APPC actual data: EVERTON FOREVER010210:27:42 Length: 27 10:27:42 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT ADDDATA 10:27:42 GROUP 0001 PORT 0001 EHSB011I BEGINNING SCRIPT PROCESS PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0001 retrieved HSGET data is: HPER075C Length: 8 10:27:42 GROUP 0001 PORT 0001 PROCESS data returned: 24:72:012010REVEROF NOTREVE Length: 27 10:27:42 GROUP 0001 PORT 0001 EHSB019I COMPLETED SCRIPT PROCESS 10:27:42 GROUP 0001 PORT 0001 EHSB024I BEING TERMINATED 10:27:42 GROUP 0001 PORT 0001 EHSB003I PORT TERMINATED 10:27:42 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT REQUEST PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0002 APPC actual data is: HPER078C Length: 8 10:27:42 GROUP 0001 PORT 0002 Actual data is: HPER078C Length: 8 10:27:42 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT REQUEST 10:27:42 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT ADDDATA PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0002 retrieved HSGET data is: HPER078C Length: 8 10:27:42 GROUP 0001 PORT 0002 APPC actual data: EVERTON FOREVER020110:27:43 Length: 27 10:27:42 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT ADDDATA 10:27:42 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT PROCESS PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0002 retrieved HSGET data is: HPER078C Length: 8 10:27:42 GROUP 0001 PORT 0002 PROCESS data returned: 34:72:011020REVEROF NOTREVE Length: 27
Figure 4-30. Job Log for a Multiple Thread, Multiple Iteration Playback (Continued)
10:27:42 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT PROCESS 10:27:42 GROUP 0001 PORT 0002 EHSB024I BEING TERMINATED 10:27:42 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT REQUEST PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0002 APPC actual data is: HPER081C Length: 8 10:27:42 GROUP 0001 PORT 0002 Actual data is: HPER081C Length: 8 10:27:42 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT REQUEST 10:27:42 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT ADDDATA PLAY OUTBOUND 10:27:42 GROUP 0001 PORT 0002 retrieved HSGET data is: HPER081C Length: 8 10:27:43 GROUP 0001 PORT 0002 APPC actual data: EVERTON FOREVER020210:27:43 Length: 27 10:27:43 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT ADDDATA 10:27:43 GROUP 0001 PORT 0002 EHSB011I BEGINNING SCRIPT PROCESS PLAY OUTBOUND 10:27:43 GROUP 0001 PORT 0002 retrieved HSGET data is: HPER081C Length: 8 10:27:43 GROUP 0001 PORT 0002 PROCESS data returned: 34:72:012020REVEROF NOTREVE Length: 27 10:27:43 GROUP 0001 PORT 0002 EHSB019I COMPLETED SCRIPT PROCESS 10:27:43 GROUP 0001 PORT 0002 EHSB024I BEING TERMINATED 10:27:43 GROUP 0001 PORT 0002 EHSB003I PORT TERMINATED 10:27:43 GROUP MSTR PORT MSTR EHSB004I GROUP 0001 TERMINATED
APPC Data-Driven Testing Example Using Playback Tables
This section illustrates data-driven testing with a series of APPC conversations described in the previous section, “APPC Data-Driven Testing Example Using REXX” on page 4-44.
However, this section will describe using playback tables instead of using REXX code within the APPC. The benefit of using Playback tables over REXX is much faster processing time.
4-60 Hiperstation for Mainframe Servers User Guide
Playback Tables
Playback tables are defined as follows:
TABLEDEF PORTS(n) DATADSN(dataset_name) LOGDSN(dataset_name) TABLE ID(member_name) REPEATS(n) DATALEN(n) DATAIN LOG INIT(NULL|SPACE|ZERO) TABLE ID(member_name) REPEATS(n) DATALEN(n) DATAIN TABLE ID(member_name) REPEATS(n) DATALEN(n) LOG TABLE ID(member_name) REPEATS(n) DATALEN(n)
For a description of the parameters for TABLEDEF and TABLE see “TABLEDEF Statement” and “TABLE Statement” on page 4-22
Extract the Key
When using playback tables, both the <EXTRACT> tag and the <REPLACE> tag are used.
<EXTRACT> Tag
<EXTRACT FIELD=(0,'&REVERSED') TYPE=ONE> <EXTRACT FIELD=(0,'&SHAREKEY') TYPE=ONE>
<REPLACE> Tag
<REPLACE FIELD=(0,'&SHAREKEY') TYPE=ONE>
See “<REPLACE> Tag” on page 4-7 and “<EXTRACT> Tag” on page 4-10 for a description of these tags and their parameters.
Store a Shared Key
Figure 4-31 is an example showing how to store a shared key.
Figure 4-31. Store a Shared Key
<VERSION>8 <DETAIL COMBINED='*'> <TIME>2006/07/21_09:51:00.523225 <ALLOCATE TPNAME=H4S SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.523225' FTIME='2006/07/21_09:51:00.614087', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.523225 <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER0001 <TIME>2006/07/21_09:51:00.523225 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.614087 <EXTRACT FIELD=(0,'&SHAREKEY') TYPE=ONE> <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000006HPER045C <TIME>2006/07/21_09:51:00.614087 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
Retrieve a Shared Key
Figure 4-31 is an example showing how to retrieve a shared key and use the key in a playback.
Unattended Playback of APPC Scripts 4-61
Figure 4-32. Retrieve a Shared Key
<VERSION>8 <DETAIL COMBINED='*'> <TIME>2006/07/21_09:51:00.768107 <ALLOCATE TPNAME=H4T SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.768107' FTIME='2006/07/21_09:51:00.921482', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.768107 <REPLACE FIELD=(0,'&SHAREKEY') TYPE=ONE> <== Note '=' missing after FIELD <SEND_DATA DATATYPE=APPLDATA> and extra space before '&SHAREKEY' <CONTENT> 00000002HPER045C above errors were corrected. <TIME>2006/07/21_09:51:00.768107 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.921482 <EXTRACT FIELD=(0,'&REVERSED') TYPE=ONE> <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 0000000410:15:901000REVEROF NOTREVE <TIME>2006/07/21_09:51:00.921482 <DEALLOCATE TYPE=FLUSH LOGDATA=NO> </INBOUND>
Alter the Request String
In the previous section using REXX, REXX code is used in the script.
When using tables, the request string is prepared in the TABLEDSN using the DATAIN keyword. Figure 4-34 is an example of how to prepare a request string.
4-62 Hiperstation for Mainframe Servers User Guide
Figure 4-33. Request String Using Tables
HLQ = SYSVAR(SYSUID) /* YOU MAY REASSIGN HLQ with SOMETHING OTHER THAN SYSUID */ DDN_04CHAR = HLQ || '.BOC.TABLE.DATA(REQUEST)' DDN_19CHAR = HLQ || '.BOC.TABLE.DATA(REQUESTX)' ADDRESS TSO 'ALLOCATE DATASET('''DDN_04CHAR''') SHR FILE(RDM04)' 'ALLOCATE DATASET('''DDN_19CHAR''') SHR FILE(RDM19)' Ports = 2 Repeats = 05 i=0 DO GRPCYCLE = 1 to Repeats DO PORT = 1 TO Ports i = i + 1 A.i = right(PORT,2,'0')||right(GRPCYCLE,2,'0') B.i = 'EVERTON FOREVER' || A.i END END "EXECIO * DISKW RDM04 (stem A. FINIS)" "EXECIO * DISKW RDM19 (stem B. FINIS)" 'FREE FILE(RDM04)' 'FREE FILE(RDM19)' RETURN 0 VIEW USR2503.BOC.TABLE.DATA(REQUEST) - 01.00 Command ===> ****** ******************************* Top of Data * 000001 0101 000002 0201 000003 0102 000004 0202 000005 0103 000006 0203 000007 0104 000008 0204 000009 0105 000010 0215 VIEW USR2503.BOC.TABLE.DATA(REQUESTX) - 01.00 Command ===> ****** ******************************* Top of Data ** 000001 EVERTON FOREVER0101 000002 EVERTON FOREVER0201 000003 EVERTON FOREVER0102 000004 EVERTON FOREVER0202 000005 EVERTON FOREVER0103 000006 EVERTON FOREVER0203 000007 EVERTON FOREVER0104 000008 EVERTON FOREVER0204 000009 EVERTON FOREVER0105 000010 EVERTON FOREVER0215
With these files prepared before the APPC playback, the script in Figure 4-34 will be played back.
Unattended Playback of APPC Scripts 4-63
Figure 4-34. Script Being Played Back
<VERSION>8 <DETAIL COMBINED='*'> <TIME>2006/07/21_09:51:00.523225 <ALLOCATE TPNAME=H4S SENDER=USCWXN01.H01AC079, RECEIVER=USCWXN01.H01AC127, LOGMODE=#INTER TYPE=MAPPED SYNCLVL=NONE SECURITY=NONE, STIME='2006/07/21_09:51:00.523225' FTIME='2006/07/21_09:51:00.614087', CONVCORR='-AD1' LUWNAME=USCWXN01.TCW00567 LUWINST=, '0AB30B1787D5'X LUWSEQ='0001'X> <OUTBOUND> <TIME>2006/07/21_09:51:00.523225 <REPLACE FIELD=(15,'&REQUEST') TYPE=ONE> or This is same as REXX example <REPLACE FIELD=(0,'&REQUESTX') TYPE=ONE> <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000004EVERTON FOREVER0001 <TIME>2006/07/21_09:51:00.523225 <PREPARE_TO_RECEIVE TYPE=FLUSH> </OUTBOUND> <INBOUND> <TIME>2006/07/21_09:51:00.614087 <EXTRACT FIELD=(0,'&SHAREKEY') TYPE=ONE> <SEND_DATA DATATYPE=APPLDATA> <CONTENT> 00000006HPER045C <TIME>2006/07/21_09:51:00.614087 <DEALLOCATE TYPE=FLUSH LOGDATA=NO>
Getting Playback Information
Figure 4-35. Variable Data Read from the Table
VIEW USR2503.BOC.TABLE.DATA(REQUEST) - 01.00 Command ===> ****** ******************************* Top of Data * 000001 0101 000002 0201 000003 0102 000004 0202 000005 0103 000006 0203 000007 0104 000008 0204 000009 0105 000010 0215 VIEW USR2503.BOC.TABLE.DATA(REQUESTX) - 01.00 Command ===> ****** ******************************* Top of Data ** 000001 EVERTON FOREVER0101 000002 EVERTON FOREVER0201 000003 EVERTON FOREVER0102 000004 EVERTON FOREVER0202 000005 EVERTON FOREVER0103 000006 EVERTON FOREVER0203 000007 EVERTON FOREVER0104 000008 EVERTON FOREVER0204 000009 EVERTON FOREVER0105 000010 EVERTON FOREVER0215
In Figure 4-35, C= refers to the reference counter, which tells how many times it has been used for <REPLACE> and <EXTRACT>. L= refers to the data length for the table. REQUESTX, SHAREKEY, RESPTIME, and REVERSED are table names.
When using tables, key information is written using the LOG keyword. See Figure 4-36 for an example of the table definition.
4-64 Hiperstation for Mainframe Servers User Guide
Figure 4-36. Table Definition Using LOG Keyword
TABLEDEF PORTS(2) - DATADSN(USR2503.BOC.TABLE.DATA) - LOGDSN(USR2503.BOC.TABLE.LOG) TABLE ID(REQUEST) REPEATS(05) DATALEN(04) DATAIN LOG TABLE ID(SHAREKEY) REPEATS(05) DATALEN(08) LOG TABLE ID(RESPTIME) REPEATS(05) DATALEN(27) LOG TABLE ID(REVERSED) REPEATS(05) DATALEN(27) LOG
Use the JCL in Figure 4-37 to merge and sort three LOG file.
Figure 4-37. JCL to Merge and Sort Three LOG Files
//SORT EXEC PGM=SORT,COND=(0,LT) //SYSOUT DD SYSOUT=* //*SORTOUT DD SYSOUT=*,DCB=(RECFM=VB,LRECL=130) //SORTOUT DD DISP=SHR,DSN=USR2503.BOC.TABLE.LOG(SAMPLE1) //SORTIN DD DISP=SHR,DSN=USR2503.BOC.TABLE.LOG(REQUEST) // DD DISP=SHR,DSN=USR2503.BOC.TABLE.LOG(SHAREKEY) // DD DISP=SHR,DSN=USR2503.BOC.TABLE.LOG(RESPTIME) // DD DISP=SHR,DSN=USR2503.BOC.TABLE.LOG(REVERSED) //* LOG DATASET IS VARIABLE RECORD //* THEREFORE, SORT CONTROL LOCATION STARTS AT 5 //* ADD 5 TO REAL DATA LOCATION FOR SORT CONTROL //SYSIN DD * SORT FIELDS=(5,26,CH,A) //
Sample Output
Figure 4-38 shows sample output from a Sort job after your Playback.
Unattended Playback of APPC Scripts 4-65
Figure 4-38. Sample Output
000001 PORT=00001,GRPCYCLE=000001,C=001,L=019,REQUESTX='EVERTON FOREVER0101' 000002 PORT=00001,GRPCYCLE=000001,C=003,L=008,SHAREKEY='HPER117C' 000003 PORT=00001,GRPCYCLE=000001,C=001,L=027,RESPTIME='EVERTON FOREVER010114:31:44' 000004 PORT=00001,GRPCYCLE=000001,C=001,L=027,REVERSED='44:13:411010REVEROF NOTREVE' 000005 PORT=00001,GRPCYCLE=000002,C=001,L=019,REQUESTX='EVERTON FOREVER0102' 000006 PORT=00001,GRPCYCLE=000002,C=003,L=008,SHAREKEY='HPER126C' 000007 PORT=00001,GRPCYCLE=000002,C=001,L=027,RESPTIME='EVERTON FOREVER010214:31:45' 000008 PORT=00001,GRPCYCLE=000002,C=001,L=027,REVERSED='54:13:412010REVEROF NOTREVE' 000009 PORT=00001,GRPCYCLE=000003,C=001,L=019,REQUESTX='EVERTON FOREVER0103' 000010 PORT=00001,GRPCYCLE=000003,C=003,L=008,SHAREKEY='HPER132C' 000011 PORT=00001,GRPCYCLE=000003,C=001,L=027,RESPTIME='EVERTON FOREVER010314:31:48' 000012 PORT=00001,GRPCYCLE=000003,C=001,L=027,REVERSED='84:13:413010REVEROF NOTREVE' 000013 PORT=00001,GRPCYCLE=000004,C=001,L=019,REQUESTX='EVERTON FOREVER0104' 000014 PORT=00001,GRPCYCLE=000004,C=003,L=008,SHAREKEY='HPER138C' 000015 PORT=00001,GRPCYCLE=000004,C=001,L=027,RESPTIME='EVERTON FOREVER010414:31:48' 000016 PORT=00001,GRPCYCLE=000004,C=001,L=027,REVERSED='84:13:414010REVEROF NOTREVE' 000017 PORT=00001,GRPCYCLE=000005,C=001,L=019,REQUESTX='EVERTON FOREVER0105' 000018 PORT=00001,GRPCYCLE=000005,C=003,L=008,SHAREKEY='HPER144C' 000019 PORT=00001,GRPCYCLE=000005,C=001,L=027,RESPTIME='EVERTON FOREVER010514:31:48' 000020 PORT=00001,GRPCYCLE=000005,C=001,L=027,REVERSED='84:13:415010REVEROF NOTREVE' 000021 PORT=00002,GRPCYCLE=000001,C=001,L=019,REQUESTX='EVERTON FOREVER0201' 000022 PORT=00002,GRPCYCLE=000001,C=003,L=008,SHAREKEY='HPER116C' 000023 PORT=00002,GRPCYCLE=000001,C=001,L=027,RESPTIME='EVERTON FOREVER020114:31:44' 000024 PORT=00002,GRPCYCLE=000001,C=001,L=027,REVERSED='44:13:411020REVEROF NOTREVE' 000025 PORT=00002,GRPCYCLE=000002,C=001,L=019,REQUESTX='EVERTON FOREVER0202' 000026 PORT=00002,GRPCYCLE=000002,C=003,L=008,SHAREKEY='HPER125C' 000027 PORT=00002,GRPCYCLE=000002,C=001,L=027,RESPTIME='EVERTON FOREVER020214:31:45' 000028 PORT=00002,GRPCYCLE=000002,C=001,L=027,REVERSED='54:13:412020REVEROF NOTREVE' 000029 PORT=00002,GRPCYCLE=000003,C=001,L=019,REQUESTX='EVERTON FOREVER0203' 000030 PORT=00002,GRPCYCLE=000003,C=003,L=008,SHAREKEY='HPER131C' 000031 PORT=00002,GRPCYCLE=000003,C=001,L=027,RESPTIME='EVERTON FOREVER020314:31:48' 000032 PORT=00002,GRPCYCLE=000003,C=001,L=027,REVERSED='84:13:413020REVEROF NOTREVE' 000033 PORT=00002,GRPCYCLE=000004,C=001,L=019,REQUESTX='EVERTON FOREVER0204' 000034 PORT=00002,GRPCYCLE=000004,C=003,L=008,SHAREKEY='HPER137C' 000035 PORT=00002,GRPCYCLE=000004,C=001,L=027,RESPTIME='EVERTON FOREVER020414:31:48' 000036 PORT=00002,GRPCYCLE=000004,C=001,L=027,REVERSED='84:13:414020REVEROF NOTREVE' 000037 PORT=00002,GRPCYCLE=000005,C=001,L=019,REQUESTX='EVERTON FOREVER0205' 000038 PORT=00002,GRPCYCLE=000005,C=003,L=008,SHAREKEY='HPER143C' 000039 PORT=00002,GRPCYCLE=000005,C=001,L=027,RESPTIME='EVERTON FOREVER020514:31:48' 000040 PORT=00002,GRPCYCLE=000005,C=001,L=027,REVERSED='84:13:415020REVEROF NOTREVE'
4-66 Hiperstation for Mainframe Servers User Guide
5-1
Chapter 5.
5APPC Reporting Chap 5Hiperstation for Mainframe Servers offers the following reports:
• APPC Summary Report provides performance statistics and comparison results.
• REXX Log reports the text from the REXX SAY statements.
Hiperstation for Mainframe Servers generates requested reports during playback if your playback job ALLOCATE/ACCEPT statement includes the appropriate keywords.
This chapter explains how to generate each report and describes the fields on the reports.
Summary ReportInclude the SUMMARY keyword on your ALLOCATE/ACCEPT statement to produce a summary report (refer to the syntax diagram in the “ALLOCATE and ACCEPT Statements” discussion, on page 4-22). The APPC summary report details performance and comparison check information from the execution of scripts using unattended playback.
SUMMARY(class|dsn)
Tells Hiperstation for Mainframe Servers to generate a summary report for the group. If the value is a single character, Hiperstation for Mainframe Servers allocates the summary report to SYSOUT in the class set by that single character. If the value is more than one character, Hiperstation for Mainframe Servers allocates the summary report to a permanent file. By default, no summary report is produced.
The dataset value can be either a dataset name by itself or a dataset name with a member name:
SUMMARY(dataset) SUMMARY(dataset(member))
To allocate a PDSE at the same time, use the format:
SUMMARY(dataset*(member*))
The dataset must be either a sequential file or a PDSE. You cannot use a PDS as a summary report file because playback can write multiple members at the same time, a function not supported by PDSs.
The dataset or member or both can contain wildcard characters (* or ?).
If a dataset name is supplied with no wildcards, no suffix is added to the dataset name.
5-2 Hiperstation for Mainframe Servers User Guide
Figure 5-1. APPC Summary Report Example
HIPERSTATION- SUMMARY REPORT TERMINAL ID: ** NA ** TPF NAME: H01APPCI TIME: 15:35:37 DATE: 06/06/27 PAGE: 000 -------------OUTBOUND---------------- ---------------- INBOUND --------------- SCRIPT PORT NUMBER MINIMUM AVERAGE MAXIMUM NUMBER MINIMUM AVERAGE MAXIMUM ELAPSED ------------------------------------------------------------------------------------------------------------------ SCR1003 3 1 00:00.298 00:00.298 00:00.298 1 00:00.095 00:00.095 00:00.095 00:00:06.007 SCR1003 3 1 00:00.007 00:00.007 00:00.007 1 00:00.017 00:00.017 00:00.017 00:00:06.692 SCR1003 3 1 00:00.013 00:00.013 00:00.014 1 00:00.014 00:00.014 00:00.014 00:00:06.538 SCR1003 3 1 00:00.007 00:00.007 00:00.007 1 00:00.026 00:00.026 00:00.026 00:00:06.377 *GRP-TOT 4 00:00.007 00:00.081 00:00.298 4 00:00.014 00:00.038 00:00.095 00:00:06.692
General InformationScript
The script being run. Two special script names, *SCR-TOT and *GRP-TOT, denote script and group totals, respectively.
Port
Each terminal is assigned a port ID that is associated with the script.
Outbound Performance InformationNumber
Number of SENDs or ALLOCATEs processed by the terminal for the script.
Minimum
Minimum response time for the SENDs or ALLOCATEs processed by the terminal for the script.
Average
Outbound average is calculated from the sum of all response times for the port, divided by the number of outbound transactions for that port.
Maximum
Maximum response time for the SENDs and ALLOCATEs processed by the terminal for the script.
Inbound Performance InformationNumber
Number of RECEIVEs or ACCEPTs processed by the terminal for the script.
Minimum
Minimum response time for the Receives or ACCEPTs processed by the terminal for the script.
Average
Inbound average is calculated from the sum of all think times for the port, divided by the number of inbound transactions for that port.
Maximum
Maximum response time for the RECEIVEs and ACCEPTs processed by the terminal for that script.
APPC Reporting 5-3
Elapsed TimeElapsed
Elapsed time is calculated based on the total amount of time it took the port and the application to process the total number of transactions. For *SCR-TOT, this is the maximum elapsed time of the individual scripts. For *GRP-TOT, this is the sum of the *SCR-TOT elapsed times.
REXX LogInclude the RLOG keyword on your ALLOCATE/ACCEPT statements to produce a REXX Log (refer to the syntax diagram in the “ALLOCATE and ACCEPT Statements” discussion, on page 4-22). The REXX log reports the text of REXX SAY statements, which are most often used to track the progress of a script.
RLOG(class|dsn)
Indicates that Hiperstation for Mainframe Servers allocates a REXX log for each APPC conversation in the group. If the value is a single character, Hiperstation for Mainframe Servers allocates the REXX log to SYSOUT in the class set by that single character. If the value is more than one character, Hiperstation for Mainframe Servers allocates the REXX log to a permanent file. By default, the REXX output is directed to the SYSPRINT dataset.
The dataset value can be either a dataset name by itself or a dataset name with a member name:
RLOG(dataset) RLOG(dataset(member))
The dataset or member or both can contain wildcard characters (* or ?).
If a dataset name is supplied with no member and no wildcards, a dataset is created with the name dsn.Pnnnn, where nnnn is the port number assigned to the conversation.
5-4 Hiperstation for Mainframe Servers User Guide
6-1
Chapter 6.
6TCP/IP Global Recording Chap 6Recording TCP/IP activity is the first step of TCP/IP application testing. Use the Monitor TCP/IP Requests option or the Global Recording Batch Interface to create and monitor recording requests.
Recorded activity is written to a sequential dataset or series of datasets referred to as a capture repository. Testing scripts are then generated from the capture repository. You can save time by merging related repositories before generating scripts. For example, capturing activity across multiple systems (LPARs), results in at least one repository per system. Rather than generating scripts from each repository, merge them first, and then generate scripts.
Note: Hiperstation for Mainframe Servers now supports disabling of User Key CSA allocation. See the IBM publication, MVS Initialization and Tuning Reference, for more information.
Adding a Global Recording RequestImportant Note: Repository datasets may contain sensitive information such as account numbers, payroll information, credit card information, or clear text passwords. The scripts generated from the repositories are formatted for browsing as well as playback. Ensure security by implementing external security rules for all repository, script, and detail datasets.
Capture all TCP/IP activity on the LPAR (logical partition) for the duration of the Global Recording Started Task or limit capture to any or all of the following criteria:
• Time frame • Client IP Address • Client Port • Server IP Address • Server Port
Note: Global Record provides limited support of TCP/IP compressed data streams. Though compressed activity may be captured, Hiperstation for Mainframe Servers cannot generate scripts from the recorded activity. However, you can record this type of activity to validate that your application is sending data to the correct port.
To add a recording request:
1. From the Hiperstation Product Menu, select option 2 Hiperstation for Mainframe Servers. The Hiperstation for Mainframe Servers Main Menu appears (Figure 6-1).
6-2 Hiperstation for Mainframe Servers User Guide
Figure 6-1. Hiperstation for Mainframe Servers Main Menu
--------------- Hiperstation for Mainframe Servers - Main Menu --------------- Option ===> Product Release: 08.00.01 SNA (3270, LU0, APPC) 1 Monitor Requests Add/Review your Global Record requests 2 Review Repository Create scripts from a repository 3 Global Record Manager Manage Include/Exclude filter lists 4 Unattended Processing Setup Unattended Playback and Compare JCL TCP/IP 5 Archive Requests Add, Review or Terminate archive requests 6 Monitor TCP/IP Requests Add/Review your Global Record requests 7 Create TCP/IP Scripts Create scripts from a repository 8 Playback TCP/IP Scripts Execute playbacks of TCP/IP scripts 9 TCP/IP Playback Reporting Report on database created from playback 10 Archive Web Reporting Manage TCP/IP archive web reports
Note: If TN3270 traffic at your site shares an address space with TCP/IP, use the Monitor TCP/IP Requests option to record TN3270 activity. Otherwise, use the SNA Monitor Requests, 3270 option. The 3270 option presents the same screens as Hiperstation for VTAM’s Global Record. Refer to the Hiperstation for VTAM User Guide for more information. If you are unsure of the address space configuration, consult your installer.
2. Select option 6 Monitor TCP/IP Requests.
– If no recording requests exist for your user ID, the “Global Recording Requests Screen” appears (Figure 6-2). Press Enter to add a request.
Figure 6-2. Global Recording Requests Screen
------------------------- Global Recording * Requests ------------------------- COMMAND ===> ****************************************************************************** * * * No Global Recording Requests were found for your userid. * * * ****************************************************************************** Enter END to exit, ENTER to add a new request.
– If your user ID has existing requests, the “Global Recording - Monitor TCP/IP Requests Screen” (Figure 6-3) appears. Place the cursor on the line next to any existing request, type A (Add) and press Enter.
TCP/IP Global Recording 6-3
Figure 6-3. Global Recording - Monitor TCP/IP Requests Screen
Hiperstation ----- Global Recording - Monitor TCP/IP Requests ----- Row 1 of 1 COMMAND ===> SCROLL ===> PAGE Line commands are: (C)ancel, (F)orce, (P)Stop, (R)estart, (D)isable, (S)elect, (U)pdate, (A)dd, (V)iew, or (9)Switch repositories Request Active Total Repository Owner Sessions Sessions Dataset ------- -------- -------- -------------------------------------------- USER251 238 239 USER251.TCPIP.CAPALL.REP11 ******************************* BOTTOM OF DATA ********************************
The “TCP/IP Collect Data - Filtering Screen” appears (Figure 6-4). These panels limit the amount of TCP/IP data you record and identify where the raw data should be stored during the Global Recording process.
Figure 6-4. TCP/IP Collect Data - Filtering Screen
Hiperstation --------- TCP/IP Collect Data - Filtering ------- Row 1 to 1 of 1 Command ===> Scroll ===> PAGE Identify the data to collect, then type OK on the Command line. Restrict collection to certain times (optional): HH : MM : SS MM / DD / YYYY Start Time . . 00 : 00 : 00 Start Date . . 00 / 00 / 0000 End Time . . . 00 : 00 : 00 End Date . . . 00 / 00 / 0000 Collect data that match these filters (use * for wildcards): Line commands are: (S)elect, (R)epeat, (D)elete, or (I)nsert - --- --------------- Client ------------- -------------- Server -------------- S Ftr IP Address Port IP Address Port * *** ****************************** ***** ****************************** ***** 001 172.22.173.* * 10.10.0.200 * ******************************* Bottom of data ********************************
3. To limit capture to a specific time frame, enter a start and end time and date.
For example, the following range records activity for 28 hours beginning at 9:00 am on May 10th and ending at 1:00 pm on May 11th.
Start Time = 09:00:00 Start Date 05/10/10 End Time = 13:00:00 End Date 05/11/10
To begin recording immediately and terminate the recording at your request, leave these fields blank. Valid date ranges are from January 1, 2001 through December 31, 2040.
4. Create filters to capture activity based on Client IP address, Client Port, Server IP Address, and/or Server Port. Hiperstation for Mainframe Servers records activity that matches all of the criteria on any of the filters. Enter at least one filter.
– IPV4: Client IP Address or Server IP Address: Consists of four numeric segments separated by periods. Each segment’s value can be 0-255. Leading zeros are not required in any segment. Specify a range of addresses by entering a wildcard (*) for any or all nodes of the address. For example, 172.22.*.* indicates that the activity on all addresses beginning with 172.22 is subject to capture, or 172.*.173.165 indicates that all addresses beginning with 172 and ending with 173.165 are subject to capture.
6-4 Hiperstation for Mainframe Servers User Guide
– IPV6: Client IP Address or Server IP Address: An IPv6 IP address is 16 bytes long and, in textual form, consists of eight two-byte segments. Each two-byte segment is defined as a four-digit hexadecimal XXXX (0..9,A..F) value and segments are separated by colons. Specify a range of addresses by entering a wildcard (*) for any or all nodes of the address. Given that many of these segments could have a zero value, IPv6 defines a shorthand representation to prevent the repetitive entering of :0. Use double colon (::), to represent one or more consecutive zero segments. Thus, an Ipv6 address of FE80:0:0:0:0:0:0:A0A could be written as FE80::A0A. For more information about valid IP address filters, see “Filtering IP Addresses” on page 7-9.
– Client Port or Server Port: A numeric field whose value can be 0-65535. Leading zeros are not required. Specify a port or enter an asterisk (*) wildcard to capture all ports associated with the specified IP addresses.
Notes:
• To add, copy, or delete a filter, enter the applicable line command (Insert, Repeat, or Delete) in the filter number area and press Enter.
• Global Record cannot accurately determine the Client/Server assignment if the initial CONNECT message for a specific session is not present. To ensure proper capture of data in instances where the initial CONNECT message is not present, create a duplicate filter with the Client and Server data reversed. Example: (filter 000001 was the initial filter, 000002 is the duplicate):
Figure 6-5. Portion of Screen Filter Sample
Line commands are: (S)elect, (R)epeat, (D)elete, or (I)nsert - --- --------------- Client ------------- -------------- Server -------------- S Ftr IP Address Port IP Address Port * *** ****************************** ***** ****************************** ***** _ 001 172.22.173.*_________________ *___ 10.10.0.200 __________________ 2770_ _ 002 10.10.0.200__________________ *___ 172.22.173.*__________________ 515__ ******************************* Bottom of data ********************************
5. After you have finished entering filtering criteria, type OK on the command line to accept filters as entered and press Enter to continue (or type CANCEL on the command line and press Enter to leave the screen without saving any information). Your IP Address is checked for validity.
– If the address is valid the “TCP/IP Data Collect - Output Screen” appears (Figure 6-6).
– If the IP Address is invalid, a question mark appears in the selection column. See “Correcting Invalid IP Address Errors” on page 6-6 to correct your errors and then return to Figure 6-6 to continue.
– A warning, specified as a “W” will appear if you omit the FFFF and enter an IP address in the format:
::10.10.0.32
Type an S over the W to select that IP address and you will navigate to the “TCP/IP Collect Data Filters Screen” where you will get a message stating “Deprecated IPV4 mapped IPV6 will capture only IPV6 address. On this screen, you can modify your IP address if desired.
TCP/IP Global Recording 6-5
Figure 6-6. TCP/IP Data Collect - Output Screen
Hiperstation ----------- TCP/IP Collect Data - Output ------------------------- Command ===> Choose where to store the data, then press Enter to continue. Repository dataset: Dataset name . . . . . 'USER2312.TCPIP.CAPALL.REP??' First and last number . 0000011 15 (Needed if wildcard in dataset name) Re-use repository options: (Enter "/" to select) Delete existing data / Append to existing data Overwrite existing data when all segments are full Amount of data to keep: Data from client . . . ALL (ALL or number of bytes) Data from server . . . ALL (ALL or number of bytes)
This screen specifies where to store captured data, whether to append or overwrite existing data, and limits the number of client and server message bytes to capture.
You can store all captured data in one large sequential dataset or segment the dataset to make data more accessible. After a segment is full, Global Recording closes that segment and begins writing captured data to the next specified segment. You can switch segments during recording to access recently captured data without interrupting recording. See “Monitoring and Maintaining Existing Requests” on page 6-8.
6. In the Dataset name field, enter the name of the repository dataset to use for storing captured information. To create a segmented dataset, use either of the following wildcard characters (* or ?) in the dataset name field and define a range with the First and last number fields:
– Asterisk (*): Inserts an incremental value into the dataset name qualifier where the asterisk appears. This wildcard pads the incremental value with enough zeros to ensure an eight character qualifier. For example, enter USER.REP*.DATABASE with first=1 and last=3 to create capture repositories:
USER.REP00001.DATABASE USER.REP00002.DATABASE USER.REP00003.DATABASE
– Question mark (?): Inserts an incremental value into the qualifier where the question marks appear. Enter at least one question mark for each digit of the value supplied in the last Number field. For example, enter USER. REP??.DATABASE with first=9 and last=11 to create capture repositories:
USER.REP09.DATABASE USER.REP10.DATABASE USER.REP11.DATABASE
Note: Each segment of the dataset name must begin with an alpha character (A-Z) or @#$ (including segments containing wildcard characters).
7. Select one of the following Re-use repository options:
– Delete existing data allows capture to start writing data to the begining of the repository or the first segment of a repository set. Any data that exists will be overwritten. Mutually exclusive with append to existing data. Use this option to replace existing repository datasets.
– Append to existing data allows capture to add data to the repository or the last segment of a repository set that was capturing data. Any data that exists will be preserved. Mutually exclusive with delete existing data.
6-6 Hiperstation for Mainframe Servers User Guide
– Overwrite existing data when all segments are full allows captured data to continue writing data to the first segment of a repository set when the last segment fills up. This option is only valid when using a repository set. If you do not select this option, recording terminates when the last segment is full.
Note: Overwrite deletes all existing data in a segment before writing new data to that segment. It does not delete data until Global Recording locates and processes activity that matches the request criteria. If no activity matches, the dataset is not overwritten.
8. Specify an Amount of data to keep, in bytes, of data to capture from each client and server datastream.
Hiperstation can record any TCP/IP data that passes through this MVS system and matches your filtering criteria. To record all of that data, specify ALL in both of these fields. Otherwise, any non-zero numeric value will limit the amount of data recorded from a single message.
These options support application debugging and reduce the demand on system resources. For example, if you need to inspect the first 200 bytes of message data for debugging purposes, specify 200 on both sub-parameters. If you are testing transaction speed and want to avoid storing and processing unnecessary data, limit capture of server messages. If your testing requires comparing actual and expected values during playback, enter 'ALL'.
9. Press Enter to continue.
– If you specified a dataset that does not exist, the Allocate a TCP/IP Repository screen appears. If necessary, modify the default values and press Enter to allocate the dataset. All repository segments are allocated with the same settings.
– If you specified a dataset that has been migrated, the Recover Migrated Data Set screen appears. Press Enter to recover the dataset or END to cancel recovery and reenter dataset information.
– Otherwise, the Global Recording - Monitor TCP/IP Requests screen appears. See the next section, “Monitoring and Maintaining Existing Requests”.
Correcting Invalid IP Address Errors
If you enter an invalid IP address filter and press Enter, the line with the error will contain a question mark (?) in the Selection column. The IP address will be considered invalid if you enter data outside the allowed range or if you enter too many or too few address nodes for the IPv4 or IPv6 IP address format. See Figure 6-7 for an example of an invalid IP address.
Note: For information on how to create valid IP filters, see “Filtering IP Addresses” on page 7-9.
TCP/IP Global Recording 6-7
Figure 6-7. TCP/IP Collect Data - Filtering Screen with IP Address Errors
Hiperstation --------- TCP/IP Collect Data - Filtering ------- Row 1 to 2 of 2 Command ===> Scroll ===> PAGE Identify the data to collect, then type OK on the Command line. Restrict collection to certain times (optional): HH : MM : SS MM / DD / YYYY Start Time . . 00 : 00 : 00 Start Date . . 00 / 00 / 0000 End Time . . . 00 : 00 : 00 End Date . . . 00 / 00 / 0000 Collect data that match these filters (use * for wildcards): Line commands are: (S)elect, (R)epeat, (D)elete, or (I)nsert - --- --------------- Client ------------- -------------- Server -------------- S Ftr IP Address Port IP Address Port * *** ****************************** ***** ****************************** ***** ? 001 10.22.115.555 1868 10.10.0.200 23 002 172.22.115.* 1869 10.10.0.200 24 003 FE80::* 1867 FE80:0:0:0:0:0:0:A0A 25 ******************************* Bottom of data ********************************
If you are unsure of what is wrong, you can type S to select the invalid IP address filter. When you press Enter, the “TCP/IP Collect Data Filters Screen” appears (Figure 6-8).
Figure 6-8. TCP/IP Collect Data Filters Screen
Hip +-------------------------------------------------------------------------+ Com | Hiperstation ----------- TCP/IP Collect Data Filters ------------------ | | Command ===> Scroll ===> PAGE | Ide | | | Review and/or edit. Use END when done, PF1 for help or SKIP to exit | Res | | | TCP Filter Number . . 001 of 002 | Sta | | End | Field Name Filtering Criteria | | ********************* ********************************************* | Col | Client IP Address . . ? 10.22.115.555________________________________ | | Client Port . . . . . 1868_ | Lin | Server IP Address . . 10.10.0.200__________________________________ | | Server Port . . . . . 23___ | - - | | S F | | * * | | s 0 | | 0 | | *** +-------------------------------------------------------------------------+
The “TCP/IP Collect Data Filters Screen” shows a question mark (?) for the field with the error. If you cannot figure out what the error is from looking at this screen, press PF1 to open the online help. Scroll forward to the description of the field containing the error for more information.
In this example, the fourth node of the Client IP Address is too large. The number must be between 0-255. When you enter a correct node address and press Enter, the question mark will disappear.
Another possible reason for the question mark to appear would be if you enter an IPv6 address on the “TCP/IP Collect Data - Filtering Screen” (Figure 6-4) that is too long to fit in the available field. The fact that the IP address is incomplete would cause the question mark (?) to appear. If your error is marked with an ‘R’, it designates a security error indicating that the IP adddress and port are restricted.
You cannot mix IPV4 and IPV6 IP addresses. The client IP address and the server IP address must both be IPV4 or both be IPV6. You can use an asterisk (*) to specify either an IPV4 or IPV6 IP address, but you cannot use blank as an IP address.
6-8 Hiperstation for Mainframe Servers User Guide
You must correct all IP address errors before you can continue to the next screen. Correct your IP address errors and return to Figure 6-6 on page 6-5 to continue. The correction you make on the “TCP/IP Collect Data Filters Screen” will be carried over to the “TCP/IP Collect Data - Filtering Screen”.
If you cannot figure out how to correct your IP address, you can use the SKIP command to exit the “TCP/IP Collect Data Filters Screen” and return to your previous screen. You cannot exit using END if there are errors on this screen. For more information on how to create valid IP filters, see “Filtering IP Addresses” on page 7-9.
Monitoring and Maintaining Existing RequestsThe “Global Recording - Monitor TCP/IP Requests Screen” (Figure 6-9) typically displays all of the recording requests that you created. However, if you access this screen as an administrator, it displays all existing recording requests created by all users. See “Monitor All Existing Requests (Administrator Access)” on page 6-10. Active recording requests are highlighted.
Figure 6-9. Global Recording - Monitor TCP/IP Requests Screen
Hiperstation ------- Global Recording - Monitor TCP/IP Requests --- Row 1 of 4 COMMAND ===> SCROLL ===> PAGE Line commands are: (C)ancel, (F)orce, (P)Stop, (R)estart, (D)isable, (S)elect, (U)pdate, (A)dd, (V)iew, or (9)Switch repositories Request Active Total Repository Owner Sessions Sessions Dataset ------- -------- -------- -------------------------------------------- USER2312 199 325 USER2312.TCPIP.CAPALL.REP14 USER2312 USER2312.TCPIP.CAPALL.REP13 ******************************* BOTTOM OF DATA ********************************
Use this screen to:
• Add, cancel, force, stop, restart, disable, update, or view a recording request.• Switch capture repository segments.• View session information.
The Active Sessions column displays the number of active TCP/IP connections at the time the Monitor TCP/IP Request screen is accessed. The Total Sessions column displays the total number of TCP/IP connections captured. These values fluctuate as new connections are established and existing connections are closed. Hiperstation for Mainframe Servers updates this count as it processes buffered information. If the request is active, press Enter to refresh the screen.
The Repository Dataset column displays, for active requests, the dataset that data is currently being written to. For inactive requests written to segmented repositories, this is the first dataset in the repository set.
Place the applicable line command next to the selected request and press Enter. Following is a description of the line commands available on this screen.
• (C)ancel cancels and deletes the request. All buffered information is also deleted, which may result in partially recorded business transactions. To avoid losing important data, STOP the request and wait until the request terminates before issuing the CANCEL command. Use ISPF file management tools to delete any repository or repository segments created by the request.
TCP/IP Global Recording 6-9
• (F)orce terminates recording immediately and deactivates the request. This option may result in partially recorded business transactions. To terminate capture of new sessions, but allow capture to finish for in-flight sessions, use STOP (P) instead.
• (P) Stop stops capture of new sessions and deactivates the request. Global Recording continues to capture all sessions that are in-flight at the time the STOP is issued.
• (R)estart restarts the selected request after using the D, F, or P line commands.
• (D)isable disables the selected request and prevents it from automatically starting when the Global Recording started task is brought up or when the request’s start time is reached. Disabled requests present an asterisk (*) next to the dataset name. STOP or FORCE the request prior to disabling it.
• (S)elect displays a list of all TCP/IP connections currently being captured. See the next section, “View Session Information”.
• (U)pdate presents request information for update. Recording must be terminated and the request must be inactive. Issue a STOP or FORCE to terminate recording and deactivate the request. When editing is complete, issue a RESTART command to reactivate the request.
• (A)dd adds a request. See “Adding a Global Recording Request” on page 6-1.
• (V)iew views the selected request. The request cannot be modified in view mode.
• (9) Switch Repositories closes the current repository segment and begins writing to the next segment. Use this line command to access recently recorded information without interrupting capture. If you selected Overwrite existing data when all segments are full (Figure 6-6 on page 6-5), Hiperstation for Mainframe Servers begins writing data to the first segment after the last segment is full. If the first segment is in use, Hiperstation for Mainframe Servers produces a “Dataset Full” message and begins writing to the next segment.
View Session Information
You can view an active request’s session information to verify recording criteria. If you see activity you did not intend to capture, Cancel, Force, or Stop the request. If you Force the request, you can Update it and Restart it.
To view session information, type S next to an active request on the “Global Recording - Monitor TCP/IP Requests Screen” (Figure 6-9 on page 6-8) and press Enter. The “Global Recording - Active TCP/IP Sessions Screen” appears (Figure 6-10). Press End to return to the Monitor TCP/IP Requests screen.
Figure 6-10. Global Recording - Active TCP/IP Sessions Screen
Hiperstation ---- Global Recording - Active TCP/IP Sessions ---- Row 1 of 1000 Command ===> SCROLL ===> PAGE ------- Client ------ ------- Server ------ Session Start Last Update at Total IP Address Port IP Address Port MM/DD HH:MM:SS MM/DD HH:MM:SS Bytes --------------------- --------------------- -------------- -------------- ----- 10.10.0.204 2770 172.22.19.28 515 03/17 14:04:20 03/17 14:04:21 5580 10.14.89.163 1648 10.10.0.200 17300 03/17 14:04:15 03/17 14:04:59 1905 10.20.16.126 4837 10.10.0.200 23 03/17 14:03:45 03/17 14:05:03 31K 172.22.115.157 1868 10.10.0.200 23 03/17 14:03:29 03/17 14:05:04 5449 10.10.0.207 3684 10.10.0.200 1410 03/17 14:02:59 03/17 14:02:59 56 10.10.0.204 2618 10.10.0.205 1410 03/17 14:02:59 03/17 14:02:59 56 10.10.0.204 2768 172.22.19.28 515 03/17 14:02:31 03/17 14:02:32 5580 172.22.103.191 3110 10.10.0.200 23 03/17 14:02:14 03/17 14:05:03 27K
The information that appears on this screen includes Client and Server IP Address and Port, the time when the connection was established, the time of the most recent activity within the connection, and total bytes of message data recorded for the given connection. ‘K’ indicates the value is in thousands, ‘M’ indicates millions.
6-10 Hiperstation for Mainframe Servers User Guide
Monitor All Existing Requests (Administrator Access)
If you have the appropriate authority, you can access the Monitor TCP/IP Requests option as an administrator. You can use this feature to monitor and manage all existing recording requests. See your Hiperstation installer if you need administrator access.
Note: If you need to update or restart a request, you may also require authority to update the script and/or repository datasets specified in the recording request. Your Hiperstation installer enables the security validation — your Security Administrator maintains the authorities.
To view all of the existing recording requests:
1. On the Command line of the Hiperstation for Mainframe Servers - Main Menu, type ADMIN and press Enter. The screen title updates to indicate administrator access mode.
2. Select the Monitor TCP/IP Requests option and press Enter. The “Global Recording - Monitor TCP/IP Requests Screen” appears (Figure 6-9 on page 6-8).
Using the Global Recording Batch InterfaceHiperstation for Mainframe Servers provides a batch interface to Global Recording. Use it along with a job scheduler to automate capture initiation and termination. For example, to initiate recording every morning at 8:00 AM and terminate it at 5:00 PM, create a job to RESTART the request and a job to STOP the request. Use a job scheduler to submit the jobs at the appropriate times.
You can use the online and batch interfaces together. For example:
• Create a recording request with the online interface and then manage it with scheduled jobs.
• Initiate recording with the batch interface and then use the Monitor TCP/IP Requests option to view a list of sessions being captured.
Create a Global Recording Request
Global Recording writes captured activity to a specified dataset or range of datasets called a capture file or a repository. Testing scripts are generated from the capture repository.
To capture activity, create a recording request. If you specify a time-frame for the request, it becomes active at the designated start time. If you do not specify a time-frame, it becomes active immediately. Capture begins when all of the criteria for an active request are met.
Creating a Global Recording request with the batch interface involves defining the parameters of the request. Parameters are defined in extensible markup language (XML). The batch interface’s XML parser provides limited syntax support. Be sure to review “Global Recording Request Parameter Syntax” on page 6-11 prior to writing or modifying parameters.
To create a Global Recording request with the batch interface:
1. Define the Global Recording request parameters. See “Global Recording Request Parameters” on page 6-13.
2. Use SQQFSAMP member DCIJCL (Figure 6-11) to execute the ADD request function.
a. Insert job statement information at the top of the sample.
b. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
TCP/IP Global Recording 6-11
c. When the request is created, the batch interface returns a request key that contains information about the request. Use the request key as input for request management jobs (see “Manage Existing Requests” on page 6-20). The key is written to the location specified on the FEEDBACK DD. To save the key in your personal library, specify a sequential dataset, PDS(E) and member, or a generation data group (GDG).
Note: Allocate the dataset or GDG with a fixed block record format and an 80-byte record length.
d. On the SYSTSIN DD statement, make sure ADD is specified on the PARM keyword.
e. On the SYSIN DD statement, either supply the name of the dataset containing the request parameters or enter the parameters in-line.
Note: In-stream parameters cannot exceed 80 bytes. If you edited the parameters on a PC and copied them back to a dataset exceeding 80 bytes, point the DD to the dataset rather than pasting the parameters into the job.
Figure 6-11. DCIJCL — Sample JCL to Add or Manage Requests
********************************* Top of Data ********************************** //* INSERT JOB CARD HERE............................................... /*JOBPARM SYSAFF=sysn //********************************************************************* //* JCL TO ADD OR MODIFY 3270, APPC, TCP/IP, OR MQSERIES GLOBAL * //* RECORD REQUESTS. * //* * //* UPROCS: DATASET THAT CONTAINS THE DCIPROC. * //* * //* FEEDBACK: OUTPUT XML THAT MAY BE USED AS INPUT TO SUBSEQUENT * //* STEPS. * //* * //* SYSTSIN: TSO BACKGROUND INPUT STREAM. * //* ISPSTART PGM(QACDCIP) - EXECUTE THE GLOBAL RECORD * //* BATCH INTERFACE (GRBI) * //* PARM(command) - IS THE COMMAND PASSED TO THE GRBI * //* * //* SYSIN: XML INPUT. * //* * //********************************************************************* //UPROCS JCLLIB ORDER=('COMPWARE.QQF800.SQQFSAMP') <-REVIEW //DCI EXEC PROC=DCIPROC //FEEDBACK DD * //SYSTSIN DD * ISPSTART PGM(QACDCIP) PARM(ADD) <-REVIEW /* //SYSIN DD DISP=SHR,DSN=COMPWARE.QQF800.SQQFSAMP(DCIADXTP) <-REVIEW ******************************** Bottom of Data ********************************
3. After the job is prepared, submit it in one of the following ways:
– Submit the job from the ISPF Edit session to execute it immediately. Type SUB on the Command line and press Enter.
– Schedule the job to run at a specific time. See your job scheduler’s documentation for help.
Global Recording Request Parameter Syntax
Global Recording request parameters are defined in XML. Write the parameters from scratch or start with a sample or a generated parameter set. Store the parameters in a dataset or paste them right into the JCL. Use a standard file editing tool to modify the parameters.
6-12 Hiperstation for Mainframe Servers User Guide
Note: The batch interface contains a proprietary XML parser that supports a limited set of XML elements. It recognizes only the syntax described in this section.
Most recording request XML parameters are comprised of an opening tag, followed by a value and a closing tag. Opening and closing tags must be contained in angle brackets. The closing tag must be preceded by a back slash inside the angle brackets. For example:
<Client_IP_Address> '*' </Client_IP_Address>
If the parameter value contains spaces, it must be placed in single quotation marks. In the samples and generated parameter sets, the parameter values always appear inside single quotes.
Some parameters require a format indicator followed by a value supplied in single quotation marks. For example, the Request ID tag accepts a hexadecimal or character value. Indicate the format of the value by placing an X or a C before the value, outside of the quotation marks.
<Request_ID> C'QA_REQ'</Request_ID>
The batch interface ignores spaces between the tag and the tag’s value. For example, the following parameter is interpreted the same way as the previous Client IP Address parameter example:
<Client_IP_Address> '*' </Client_IP_Address>
To make the samples and generated parameter sets easier to read, most parameters are formatted with the opening tag and value on one line and the closing tag on the following line.
XML parameters are hierarchal. That is, some parameters have a group of related sub-parameters. For example, the Start_Time, End_Time, Start_Date and End_Date are sub-parameters of the Scheduled_Capture parameter. Sub-parameters must be nested within opening and closing parent parameter tags. For example,
<Scheduled_Capture> <Start_Date> '00/00/0000' </Start_Date> <Start_Time> '00:00:00' </Start_Time> <End_Date> '00/00/0000' </End_Date> <End_Time> '00:00:00' </End_Time> </Scheduled_Capture>
Depending on the request you are creating, there may be several levels of nesting. For example, all of the TCP/IP Global Recording request parameters are sub-parameters of the <TCP> protocol parameter. The start and end time and date parameters are sub-parameters of Scheduled_Capture, which is a sub-parameter of the <TCP> protocol parameter.
<TCP> <Request_ID> C'MY_REQ' </Request_ID> <Scheduled_Capture> <Start_Date> '00/00/0000' </Start_Date> <Start_Time> '00:00:00' </Start_Time> </Scheduled_Capture> </TCP>
Note: This example shows tag nesting. It is not a complete set of request parameters.
TCP/IP Global Recording 6-13
Indenting nested tags is not necessary. However, it makes editing much easier. In the samples and generated parameter sets, each level of nesting is indented one space.
Finally, an XML stream can contain comments that the batch interface ignores. Comment text must be prefixed with an opening angle bracket, an exclamation point, and two dashes. The comment text is entered and is followed by two dashes and a closing angle bracket. For example:
<!--This is an XML comment. -->
Global Recording Request Parameters
Global Recording request parameters are defined in XML. For syntax rules, see “Global Recording Request Parameter Syntax” on page 6-11.
Start with one of the following:
• The parameters from an existing request. See “Retrieve the Parameters of an Existing Request” on page 6-21.
• A parameters skeleton. See “Generate a Request Parameters Skeleton” on page 6-22.
• SQQFSAMP member DCIADXTP, which contains all available TCP/IP Global Recording request parameters.
• SQQFSAMP member DCIADDTP, which contains a subset of commonly used TCP/IP recording request parameters.
Store the parameters in a sequential dataset or a PDS member in your personal library, or write them directly in the JCL. Use a standard file editing tool such as ISPF Edit to write or modify the parameters.
Notes:
1. XML tags are case-sensitive. Make sure the ISPF Caps function is set to off when editing the parameters. Type CAPS OFF on the Command line and press Enter
2. To work with a parameters file on the PC:
– Use the IBM utility IEBGENER to copy the dataset into an HFS file.
– FTP the file to the PC. To avoid EBCDIC to ASCII translation issues, transfer the file as 'text'.
Use an XML editor, such as Notepad, to edit the tags. Pay attention to syntax interpretation. The Global Recording batch interface may not recognize tags that have been reformatted based on the viewer’s interpretation. For example, some editors format tags that have no values as follows <tag/>. Encase blank values in single quotes to avoid this particular interpretation issue. All tags must conform to the syntax rules described on page 6-11.
To avoid record truncation when transferring the parameters back to the mainframe, copy them into a fixed block dataset with a logical record length that supports the longest record.
This section provides an illustration of sample DCIADXTP (Figure 6-12) and defines all of the available TCP/IP Global Recording request parameters.
Parameter hierarchy is shown in Figure 6-12 and defined within the parameter definitions.
6-14 Hiperstation for Mainframe Servers User Guide
Figure 6-12. SQQFSAMP member DCIADXTP
********************************* Top of Data ********************************** <TCP> <Request_ID> X'000000000000' </Request_ID> <Scheduled_Capture> <Start_Date> '00/00/0000' </Start_Date> <Start_Time> '00:00:00' </Start_Time> <End_Date> '00/00/0000' </End_Date> <End_Time> '00:00:00' </End_Time> </Scheduled_Capture> <Capture_File> <Dataset> 'COMPWARE.SAMPLE.CAPTURE.FILE*' </Dataset> <First_Number> '1' </First_Number> <Last_Number> '10' </Last_Number> <!--Valid 'Initial_Disposition' values are APPEMD or OVERWRITE --> <Initial_Disposition> 'APPEND' </Initial_Disposition> <Allocation> <Management_Class> '' </Management_Class> <Storage_Class> '' </Storage_Class> <Volume_Serial> '' </Volume_Serial> <Device_Type> 'SYSDA' </Device_Type> <Data_Class> '' </Data_Class> <Space_Units> 'TRKS' </Space_Units> <Primary_Quantity> '10' </Primary_Quantity> <Secondary_Quantity> '5' </Secondary_Quantity> <Block_Size> '9004' </Block_Size> </Allocation> </Capture_File> <Recording_Options> <Reuse_Capture_File> 'NO' </Reuse_Capture_File> </Recording_Options> <Data_To_Keep> <Data_From_Client> 'ALL' </Data_From_Client> <Data_From_Server> 'ALL' </Data_From_Server> </Data_To_Keep> <TCP_Capture_Filters> <Filter Record="1"> <Client_IP_Address> '*' </Client_IP_Address> <Client_Port> '*' </Client_Port> <Server_IP_Address> '*' </Server_IP_Address> <Server_Port> '*' </Server_Port> </Filter> </TCP_Capture_Filters> </TCP> ******************************** Bottom of Data ********************************
TCP/IP Global Recording 6-15
Protocol Parameter Tag
TCP
Identifies the type of Global Recording request to add. This is a parent tag to all other parameters described in this section. Begin and end the XML input stream with opening and closing TCP tags.
General Request Parameter Tag
Request ID
Specifies the ID of the Global Recording request. To assign a request ID, supply a six-byte hexadecimal or character value in single quotes. Place a format indicator in front of the value outside of the quotation marks. X indicates hexadecimal values and C indicates character values. For example:
<Request_ID> X'010203040506' </Request_ID> <Request_ID> C'QAREQ1'</Request_ID>
The batch interface pads hexadecimal values that are fewer than six bytes with zeros and character values that are fewer than six bytes with spaces.
This tag is optional. If you do not supply a request ID, the system assigns one when the request is created.
Scheduled Capture Parameter Tags
Scheduled_Capture
Sets a start time and duration for the request. The request activates at the defined start time and date and remains active until the specified end time and date, unless the capture repository fills up and the Reuse_Capture_File tag is set to 'NO'.
Omit this entire block of tags for capture to begin immediately and remain active indefinitely.
The following parameters are Scheduled_Capture sub-parameters. Supply the applicable parameters between the opening and closing Scheduled_Capture tags.
Start_Date and End_Date
The month, day, and year to activate or deactivate the request. Specify a two digit month, a two digit day, and a four digit year separated by slashes: 'MM/DD/YYYY'.
If you specify a start date with no time, the request activates at the beginning of the given day — that is, midnight (00:00:00). If you specify an end date with no time, the request deactivates at the end of the given day — that is, midnight (24:00:00).
If you set the Force_At_End_Time recording option to 'Y', an end time and date are required.
Start_Time and End_Time
The time to activate or deactivate the request. Specify a two-digit hour, a two-digit minute, and a two-digit second separated by colons: 'HH:MM:SS'.
If you specify a start time, a start date is required. If you do not specify a start time or date, the request activates immediately.
If you specify an end time, an end date is required. If you do not specify an end time or date, the request remains active until you STOP, FORCE or CANCEL it or until the repository is full if you did not set the Reuse_Capture_File tag to 'YES'.
If you set the Force_At_End_Time recording option to 'YES', an end time and date are required.
6-16 Hiperstation for Mainframe Servers User Guide
Capture File Parameter Tags
Capture_File
Defines the dataset to use for storing the captured data.
The following parameters are Capture_File sub-parameters. Supply the applicable parameters between the opening and closing Capture_File tags.
Dataset
The name of the dataset to use for storing captured information. This required parameter accepts 44 characters.
To create a segmented capture file, use either of the following wildcard characters in the dataset name. Define a range for the wildcard characters with the First_Number and Last_Number tags:
• Asterisk (*): Inserts an incremental value into the dataset name qualifier where the asterisk appears. This wildcard pads the incremental value with enough zeros to ensure an eight character qualifier. For example, USER.TCP.REC* with first=1 and last=3 creates capture datasets:
USER.TCP.REC00001 USER.TCP.REC00002 USER.TCP.REC00003
• Question mark (?): Inserts the incremental value into the qualifier where the question marks appear. Enter at least one question mark for each digit of the value supplied on the Last_Number tag. For example, USER.TCP.REC?? with first=9 and last=11 creates capture datasets:
USER.TCP.REC09 USER.TCP.REC10 USER.TCP.REC11
Note: Begin each segment of the dataset name with an alpha character (A-Z) or @#$, including segments with wildcard characters.
First_Number and Last_Number
Defines the first value and last value to use for wildcard characters specified on the Dataset tag. For each tag, supply a value up to seven digits. If you did not use a wildcard, do not include these tags.
Initial Disposition
Specifies whether to append or overwrite data contained in the specified dataset. Valid values are 'APPEND' or 'OVERWRITE'. This tag is unnecessary if the specified dataset does not exist. If the specified dataset does exist, and you do not provide an initial disposition value, Global Recording appends the new data to the existing data.
Note: The dataset is overwritten when Global Recording captures and processes activity that matches the request criteria. If no activity matches, the dataset is not overwritten.
Allocation
Allocation parameters for the capture file dataset. If you do not supply allocation parameters and the specified dataset does not exist, the batch interface allocates it with default values set by the installer. Generally, the default values are appropriate. However, you can override any or all of the default parameters by using the following Allocation sub-parameters.
Supply the applicable parameters between the opening and closing Allocation tags.
TCP/IP Global Recording 6-17
Management_Class
The management class to apply to the new dataset. Management classes are defined by the storage administrator at your site.
Storage_Class
The storage class to apply to the new dataset. Storage classes are defined by the storage administrator at your site.
Volume_Serial
The serial number of the volume where the dataset is to be stored.
Device_Type
The type of device where the dataset is to be stored. Device_Type can be a generic unit such as 'SYSDA'.
Data_Class
The data class to apply to the new dataset. Data classes are defined by the storage administrator at your site.
Space_Units
The type of units used to store the data. Valid values include: TRKS (Tracks), CYLS (Cylinders), BLKS (Blocks), BYTES, KB (kilobytes), or MB (megabytes). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
Primary_Quantity
The number of space units to allocate initially. After Global Recording fills the primary quantity, it allocates the secondary quantity.
Secondary_Quantity
The number of space units to allocate after the primary quantity is full.
Block_Size
The maximum length, in bytes, of the blocks of data that the system reads in as it processes a dataset.
Recording Option Parameter Tags
Recording_Options
Defines recording request actions.
The following parameter is a Recording_Options sub-parameter. If you supply this tag, be sure to place it between the opening and closing Recording_Options tags.
Reuse_Capture_File
This parameter applies only to segmented capture files. It causes Global Recording to continue capturing activity after the capture file segments are full. After the last segment fills, Global Recording begins writing to the first segment again, replacing the oldest captured activity.
To enable this option, supply this tag with a value of 'YES'. If you omit this tag or supply it with a value of 'NO', recording terminates after the last segment is full.
Data To Keep Tags
Data_To_Keep
Defines the amount, in bytes, of client and server data to capture. These options support application debugging and reduce the demand on system resources. For example, if you need to inspect the first 200 bytes of message data for debugging purposes, specify 200 on both sub-parameters. If you are testing transaction speed
6-18 Hiperstation for Mainframe Servers User Guide
and want to avoid storing and processing unnecessary data, limit capture of server messages.
If your testing requires comparing actual and expected values during playback, specify 'ALL', or omit these parameters altogether.
The following parameters are Data_to_Keep sub-parameters. Supply the applicable parameters between the opening and closing Data_to_Keep tags.
Data_From_Client
The number of bytes to capture from each datastream coming from the client. This is an optional parameter. If you omit this tag, Global Recording captures all message data.
Data_From_Server
The number of bytes to capture from each datastream coming from the server. This is an optional parameter. If you omit this tag, Global Recording captures all message data.
TCP Capture Filter Tags
Filter Record="x"
Defines a capture filter. Supply the tag with a filter number enclosed in double quotation marks. For example, <Filter Record="1">. To create multiple filters, copy this block of tags and increment the value of x for each filter.
The following parameters are Filter Record="x" sub-parameters. Nest the applicable sub-parameters between an opening <Filter Record="x"> tag and a closing </Filter> tag.
All of the sub-parameters are optional. However, the batch interface requires at least one filter and each filter must contain at least one of the following sub-parameter. To record all activity on the system, create a filter containing any of the sub-parameters with a wildcard value. For example:
<Filter Record="1"> <Client_IP_Address> '*' </Client_IP_Address> </Filter>
Client_IP_Address
The client IP addresses subject to capture. Specify:
• A specific IP address.
• A range of addresses by supplying a wildcard character (*) for any or all nodes of the address. For example, 172.22.*.* indicates that the activity on all addresses beginning with 172.22 is subject to capture, or 172.*.173.165 indicates all addresses beginning with 172 and ending with 173.165 are subject to capture.
• All IP address by supplying a single asterisk or omitting the tag altogether.
Client_Port
The client ports subject for capture. Specify a port or enter an asterisk (*) to capture all ports associated with the specified client IP addresses.
Server_IP_Address
The server IP addresses subject to capture. Specify:
• A specific IP address.
TCP/IP Global Recording 6-19
• A range of addresses by supplying a wildcard (*) for any or all nodes of the address. 10.10.*.* indicates all addresses beginning with 10.10 are subject to capture, or 10.*.0.200 indicates all addresses beginning with 10 and ending with 0.200 are subject to capture.
• All IP address by supplying a single asterisk or omitting the tag altogether.
Server_Port
The server ports subject for capture. Specify a port or enter an asterisk (*) to capture all ports associated with the specified server IP addresses.
Check the Status of Existing Requests
Use the KEYS function to:
• Check the status of a specific Global Recording request.
• Generate status information for all of your existing Global Recording requests that you created. You can also use this feature to locate a forgotten request ID.
Each request has an associated request key that consists of the following information:
• Protocol — the protocol of the activity that the request is to record.
• Status — the status of the request (Stopped, Active, or Disabled).
• Request ID — the six byte ID assigned to the request.
• Capture File — the name of the capture file (also known as the Repository Dataset).
This is the same information that the batch interface returns when you create a request. In fact, if you are checking the status of a specific request, use the returned request key as the input for the KEYS function.
Use SQQFSAMP member DCIJCL (Figure 6-11 on page 6-11) to execute the KEYS function.
1. Insert job statement information at the top of the sample.
2. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
3. Keys are written to the location defined by the FEEDBACK DD statement. To save the keys in your personal library, specify a sequential dataset, PDS(E) and member, or a generation data group (GDG).
Note: Allocate the GDG with a fixed block record format and an 80 byte record length.
4. On the SYSTSIN DD statement, specify KEYS on the PARM keyword.
5. KEYS function parameters are also defined in XML. The parameters required differ depending on the information you need to produce.
– To check the status of a specific request, the KEYS function requires the protocol, request ID, and capture file associated with the request. On the SYSIN DD, either supply the name of the dataset containing the request key or enter the parameters in-line. For example:
// SYSIN DD * <APPC> <Request_ID> C'QA_REQ’ </Request_ID> <Capture_File> <Dataset> ‘USR2503.TCP.QA.REC??’ </Dataset> </Capture_File> </APPC>
6-20 Hiperstation for Mainframe Servers User Guide
If the ADD request FEEDBACK went to SYSOUT, copy and paste the request key from the JES job log.
– To generate status information for all of the existing TCP/IP requests that you created, the KEYS function requires the protocol parameter. For example:
// SYSIN DD * <TCP> </TCP>
6. Submit the job.
Manage Existing Requests
Use the batch interface request management functions to:
• Stop recording.• Delete or update a request.• Restart an inactive request.• Disable a request to prevent it from automatically restarting.• Switch the capture file segment to review captured activity without interrupting
recording.
All of these functions require information found in the request key that the batch interface returns when you create a request. If you do not have the request key but you know the request ID and capture file name, write the parameters directly into the job. If you do not know this information, use the KEYS function to produce a list of existing requests. See “Check the Status of Existing Requests” on page 6-19.
Use SQQFSAMP member DCIJCL (Figure 6-11 on page 6-11) to execute request management functions.
Note: DCIJCL contains the FEEDBACK DD statement that supports request creation. Request management functions do not write output to this DD. To see request modification messages, review the PRGLOG DD in the JES job log.
1. Insert job statement information at the top of the sample.
2. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
3. On the SYSTSIN DD statement, specify one of the following request management functions on the PARM keyword:
– CANCEL cancels and deletes the request. All buffered information is also deleted, which may result in partially recorded business transactions. To avoid losing important data, STOP the request and wait until the request terminates before issuing the CANCEL command. Use ISPF file management tools to delete any repository or repository segments created by the request.
– FORCE terminates recording immediately and deactivates the request. This option may result in partially recorded business transactions. To terminate capture of new sessions, but allow capture to finish for in-flight sessions, use STOP instead.
– STOP stops capture of new sessions and deactivates the request. Global Recording continues to capture all sessions that are in-flight at the time the STOP is issued.
– RESTART restarts the request. The request becomes active as soon as the time frame specified within the request is met. Use this option to activate an inactive request.
– DISABLE disables the request. When the Global Recording started task is brought up, all requests, except disabled requests, are restarted. STOP or FORCE the request prior to disabling it.
TCP/IP Global Recording 6-21
– SWITCH closes the capture file segment that is currently being written and opens the next segment. This option is only available if the capture file dataset name contains a wildcard character (* or ?).
4. The request management functions require the protocol, request ID, and capture file associated with the request. On the SYSIN DD, either supply the name of the dataset containing the request key or enter the parameters in-line. For example:
// SYSIN DD * <TCP> <Request_ID> C'QA_REQ’ </Request_ID> <Capture_File> <Dataset> ‘USR2503.TCP.QA.REC??’ </Dataset> </Capture_File> </TCP>
5. Submit the job.
Note: The batch interface does not supply an update function. Use a combination of other functions to modify a request.
1. Use the VIEW function to retrieve the parameters from the request. See “Retrieve the Parameters of an Existing Request” on page 6-21.
2. Modify the parameters. See “Global Recording Request Parameters” on page 6-13 for parameter definitions.
3. Use the STOP, FORCE, or CANCEL functions to stop recording.
4. If you use STOP or FORCE to stop recording, wait for recording to terminate and use CANCEL to delete the request.
5. Use the ADD function to create a new request using the modified parameters.
Execute steps 3-5 as separate jobs or separate steps within a single job.
Retrieve the Parameters of an Existing Request
The VIEW function writes the parameters from a specified request to a location you define. Use it to:
• Review or validate a request’s parameters.
• Save time when adding a new request. Rather than writing Global Recording request parameters from scratch, retrieve the parameters from a similar request and modify them to meet your needs.
• Update a request. Retrieve the parameters from the request you need to update. Modify the parameters. STOP the request. CANCEL the request. ADD a new request using the modified parameters.
Note: If there are no existing requests, you do not specify a request ID, or the specified request ID does not exist, the VIEW function produces a request parameters skeleton, which is a complete set of parameters with default values.
Use SQQFSAMP member DCIJCL (Figure 6-11 on page 6-11) to execute the VIEW function.
1. Insert job statement information at the top of the sample.
2. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
6-22 Hiperstation for Mainframe Servers User Guide
3. The batch interface writes VIEW function output to the location specified on the FEEDBACK DD. To save the VIEW output in your personal library, specify a sequential dataset, PDS(E) and member, or a generation data group (GDG).
Note: Allocate the GDG with a fixed block record format and an 80 byte record length.
4. On the SYSTSIN DD statement, specify VIEW on the PARM keyword.
5. When retrieving parameters from a specific request, the VIEW function requires the protocol, request ID, and capture file associated with the request. On the SYSIN DD, either supply the name of the dataset containing the request key or enter the parameters in-line. For example:
// SYSIN DD * <TCP> <Request_ID> C'QA_REQ’ </Request_ID> <Capture_File> <Dataset> ‘USR2503.TCP.QA.REC??’ </Dataset> </Capture_File> </TCP>
6. Submit the job.
Generate a Request Parameters Skeleton
If there are no existing requests, you do not specify a request ID, or the specified request ID is not found, the VIEW function produces a request parameters skeleton. A request parameters skeleton is a complete set of Global Recording parameters with default values. Generate a skeleton to:
• Save time when creating a new request. • See all of the available parameters.• Reference the syntax of a particular tag.
Use SQQFSAMP member DCIJCL (Figure 6-11 on page 6-11) to execute the VIEW function.
1. Insert job statement information at the top of the sample.
2. Make sure the UPROCS statement points to the procedures library that contains DCIPROC.
3. The batch interface writes VIEW function output to the location specified on the FEEDBACK DD. To save the VIEW output in your personal library, specify a sequential dataset, PDS(E) and member, or a generation data group (GDG).
Note: Allocate the GDG with a fixed block record format and an 80 byte record length.
4. On the SYSTSIN DD statement, specify VIEW on the PARM keyword.
5. On the SYSIN DD, supply the opening and closing protocol tags for the type of request you need to create. For example:
// SYSIN DD * <TCP> </TCP>
TCP/IP Global Recording 6-23
Troubleshoot Failed Jobs
An ISPF background task initiates and terminates the Global Recording batch interface. ISPF issues a return code for the background task. Do not confuse this return code with the Global Recording batch interface’s return code. The batch interface writes its return code to the PRGLOG DD. If your installer accepted the default, PRGLOG resides in the JES job log.
The Global Recording batch interface adds and modifies recording requests based on the parameters you supply. The Global Recording started task executes the requests. The batch interface reports messages pertaining to request creation or modification, while the started task reports messages pertaining to recording. Locate:
• Batch interface status and error messages in the PRGLOG in the JES job log.
• Global Recording started task error and status message in the JES job log and SYSTEM log.
Merging TCP/IP Capture RepositoriesHiperstation for Mainframe Servers provides an MVS batch utility that combines the information in two or more specified repositories. It orders the activity by time stamp. If you need to generate scripts from multiple repositories, you can save time by merging the repositories first. For example, rather than generating scripts four times from repositories captured on four different systems (LPARs), merge the repositories and generate scripts once.
To merge two or more repositories:
1. Copy member SYSPLEX from the samples library, typically SQQFSAMP, to your personal JCL library.
2. Open SYSPLEX (Figure 6-13) with a standard editing tool such as ISPF Edit.
3. Place job statement information at the top of the sample.
4. Make sure the STEPLIB DD points to the Hiperstation load library and the C and C++ LE datasets at your installation.
5. On the REPIN DD statement, specify the repositories to be merged. Place each fully qualified repository dataset name on a separate line. If the repository is segmented, supply the repository name with the appropriate wildcard characters followed by a space, a ‘first’ value, a space, and a ‘last’ value. ‘First’ and ‘last’ are numeric values between 1 and 9999999. ‘First’ must be lower than ‘last’. These values are used to resolve the repository segment dataset names.
6. On the SYSIN DD statement, supply the job parameters, as shown in the sample, or the name of the dataset containing the job parameters. Whether the parameters are defined inline or in an external dataset, place each parameter on a separate line. For the parameters that require a value, follow the parameter name with a space, an equals sign (=), another space, and the value.
Parameter definitions follow Figure 6-13.
7. Submit or schedule the job. To submit the job immediately, type SUB on the Command line and press Enter.
6-24 Hiperstation for Mainframe Servers User Guide
Figure 6-13. Sample Repository Merging JCL: SYSPLEX
********************************* Top of Data ********************************** //*....... JOB ...PLACE YOUR INSTALLATION'S JOBCARD HERE... //********************************************************************* //********************************************************************* //SYSPLEX EXEC PGM=SYSPLEXM,REGION=0M,PARM='0' //STEPLIB DD DSN=COMPWARE.QQF800.SQQFLOAD,DISP=SHR // DD DISP=SHR,DSN=CEE.SCEECPP // DD DISP=SHR,DSN=CEE.SCEERUN //SYSPRINT DD SYSOUT=* //CEEDUMP DD SYSOUT=* //********************************************************************* //* REPIN IS WHERE THE REPOSITORY SETS TO BE MERGED ARE ENTERED. //* EACH SET IS ENTERED ON A NEW LINE WITH THE FORMAT: //* <DATASET_SPECIFICATION> <FIRST_INTEGER> <LAST_INTEGER> <IGNORED> //********************************************************************* //REPIN DD * COMPWARE.SYS1.REPOS1* 1 10 COMPWARE.SYS2.REPOS2* 1 10 COMPWARE.SYS3.REPOS3* 1 10 COMPWARE.SYS4.REPOS4* 1 10 /* //********************************************************************* //* REQUIRED: //* REP_MERGE = FULLY QUALIFIED REPOSITORY SET SPECIFICATION, USING //* * (ASTERISK) AND ? (QUESTION MARK) AS APPROPRIATE. //* EXAMPLE: USR2503.HTTP1*.REPOS //* OPTIONAL: //* FIRST = REPOSITORY SET SPECIFICATION FIRST NUMBER. DEFAULT 0. //* LAST = REPOSITORY SET SPECIFICATION LAST NUMBER. DEFAULT 0. //* REP_SPACE = CAPTURE FILE SPACE UNIT. MUST BE TRK(DEFAULT) OR CYL. //* REP_UNIT = CAPTURE FILE UNIT NAME. DEFAULT IS SYSDA. //* REP_PRI = CAPTURE FILE PRIMARY SPACE, IN CAP_SPACE UNITS. //* REP_SEC = CAPTURE FILE SECONDARY SPACE, IN CAP_SPACE UNITS. //* REP_STORCLAS = CAPTURE FILE SMS STORAGE CLASS - SYSTEM DEFAULT. //* REP_DATACLAS = CAPTURE FILE SMS DATA CLASS - SYSTEM DEFAULT. //* REP_MGMTCLAS = CAPTURE FILE SMS MANAGEMENT CLASS - SYSTEM DEFAULT. //* MAX_MSG_SIZE = MAXIMUM SIZE UNSEGMENTED REPOSITORY MESSAGE HANDLED //* BY CONVERTER. UNITS ARE 1K, DEFAULT IS 32 (32,768). //* TCP = ALLOWS TCP REPOSITORIES TO BE USED. APPC AND MQ //* ARE ALSO VALID VALUES. DEFAULT MQ. //********************************************************************* //SYSIN DD * REP_MERGE = COMPWARE.MERGED.NEWREP* /* ******************************** Bottom of Data ********************************
SYSPLEX Job Input Parameters
REP_MERGE
The dataset to contain the merged repositories. This parameter is required. Specify a fully qualified repository dataset name. The utility dynamically allocates this dataset, so be sure to supply a dataset name that does not exist. To segment the new repository, specify the dataset name with the appropriate wildcard characters and supply a FIRST and LAST parameter (discussed next). For information regarding repository name wildcard characters, see step 6 on page 6-5.
FIRST and LAST
The first and last values to use for resolving the wildcard characters specified in the repository name. For each field, supply a value between 1 and 999999999. The default value is 0. If the specified repository name does not contain a wildcard character (* or ?), do not supply these parameters.
REP_SPACE
The type of units used to store the data. Valid values are: TRK (Tracks) or CYL (Cylinders). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.
TCP/IP Global Recording 6-25
REP_UNIT
The type of device that the dataset will be stored on. This value can be up to eight characters long. The default value, if the parameter is not specified, is SYSDA.
REP_PRI
The number of space units (tracks or cylinders) to allocate initially. Specify a value between 1 and 99999. If not specified, the default value of 1 is used. After the utility fills the primary quantity, it allocates the secondary quantity (REP_SEC).
REP_SEC
The number of space units to allocate after the primary quantity is full. Specify a value between 1 and 99999. If not specified, the default value of 1 is used.
REP_STORCLAS
The storage class to apply to the output dataset as defined by the storage administrator at your site. This optional parameter has no default value.
REP_DATACLAS
The data class to apply to the output dataset as defined by the storage administrator at your site. Your storage administrator provides default values for dataset definition parameters such as SPACE, RECFM, and LRECL. This optional parameter has no default value.
REP_MGMTCLAS
The management class to apply to the output dataset as defined by the storage administrator at your site. Your storage administrator controls attributes of SMS managed datasets such as migration, back up, compression, retention period, and space reclamation. This optional parameter has no default value.
MAX_MSG_SIZE
The maximum size of an application message handled by this utility. Specify the size, in kilobytes, of the largest message expected. Valid values are 1 to 99999. For example, MAX_MSG_SIZE 64 indicates that the first 65,536 bytes of each message will be processed. This is an optional parameter. If not specified, the utility uses 32K as the default.
TCP/APPC/MQ
The record-type selection parameter. This utility supports Hiperstation for Mainframe Servers and Hiperstation for WebSphere MQ, so you must specify the type of record to select from the input repository. If you are merging capture repositories containing TCP, HTTP, HTTPS, ECI, CTG, DB2C, or IMSC activity, specify TCP. Otherwise, the utility uses the default value of MQ.
6-26 Hiperstation for Mainframe Servers User Guide
7-1
Chapter 7.
7TCP/IP Scripts and Subset Repositories Chap 7Creating Scripts and Subset RepositoriesCapture repositories contain recorded activity in a compressed format. Scripts contain formatted, human-readable data generated from a capture repository. Play back scripts to test TCP/IP applications or browse them to review TCP/IP data flows.
After you have recorded activity (see Chapter 6, “TCP/IP Global Recording”), use the Create TCP/IP Scripts option to:
• Build testing scripts from the capture repository.
• Generate subset repositories containing specified activity.
• Generate a Connection Log that lists the all of the scripts created. Use the Connection Log as the SYSIN for an unattended playback job.
Hiperstation for Mainframe Servers processes the entire repository during script creation. The larger the repository, the longer it takes to create scripts. Additionally, scripts require more storage than raw data. Minimize script creation time and storage overhead by generating subset repositories containing only the desired activity. Store the data as a repository until you need to create testing scripts.
When you are ready to create scripts, you can save time and spare system resources by identifying the repository segments of interest. Script only the segments you need, as opposed to the entire capture repository. The Capture Segment Summary, discussed on page 2-50, indicates when recording began and ended for each segment of the specified repositories. Review the report with a file browsing tool such as ISPF Browse or import it into a spreadsheet or database for easy manipulation.
Create TCP/IP Scripts and Establish Filtering Criteria
The capture repository may contain more activity than is required to perform a given test. You can supply filtering criteria to create only the scripts or subset repositories containing the activity you need. Activity that matches any of the filters is written into the scripts or subset repositories.
You can filter by one or more of the following criteria: Time Frame, Client IP Address, Client Port, Server IP Address. and Server Port.
Additional protocol-specific filtering options are also available:
• “DB2 Connect Filters” on page 7-4. • “IMS Connect Filters” on page 7-5. • “CTG Filters” on page 7-7. • “ECI Filters” on page 7-8.
Hiperstation for Mainframe Servers requires at least one filter to create scripts or subset repositories. Each line in the lower portion of the screen represents a separate filter for creating scripts or subset repositories.
7-2 Hiperstation for Mainframe Servers User Guide
Filtering Line Commands
The “TCP/IP Create Scripts - Filtering Screen” (Figure 7-2) as well as the DB2, IMS, CTG, and ECI filter screens all use the following line commands to view additional filter details and to add or remove filters:
• (S)elect displays a protocol-specific filtering screen when additional filtering is available.
• (R)epeat repeats the selected filter.• (D)elete deletes the selected filter as long as it is not currently in use by an active
Global Recording request.• (I)nsert inserts a blank filter after the selected filter.• (A)ddress displays the TCP/IP Create Scripts - Filtering IP Addresses screen. This
allows you to specify whether you want to use IPv6 or IPv4 as your IP address format.
From the Hiperstation for Mainframe Servers Main Menu (Figure 7-1), type 7 on the Option line to select Create TCP/IP Scripts and press Enter.
Figure 7-1. Hiperstation for Mainframe Servers Main Menu
--------------- Hiperstation for Mainframe Servers - Main Menu --------------- Option ===> Product Release: 08.00.01 SNA (3270, LU0, APPC) 1 Monitor Requests Add/Review your Global Record requests 2 Review Repository Create scripts from a repository 3 Global Record Manager Manage Include/Exclude filter lists 4 Unattended Processing Setup Unattended Playback and Compare JCL TCP/IP 5 Archive Requests Add, Review or Terminate archive requests 6 Monitor TCP/IP Requests Add/Review your Global Record requests 7 Create TCP/IP Scripts Create scripts from a repository 8 Playback TCP/IP Scripts Execute playbacks of TCP/IP scripts 9 TCP/IP Playback Reporting Report on database created from playback 10 Archive Web Reporting Manage TCP/IP archive web reports
The “TCP/IP Create Scripts - Filtering Screen” appears (Figure 7-2).
Figure 7-2. TCP/IP Create Scripts - Filtering Screen
Hiperstation -------- TCP/IP Create Scripts - Filtering ------ Row 1 to 2 of 8 Command ===> Scroll ===> PAGE Make changes to the filtering criteria below (use * for wildcards) and press ENTER or select a filter to edit protocol-specific fields. Use OK command when complete. Use DEFAULT to see a sample list of possible filters or use RESET to restore the list to the basic HTTP filter only. Only use data that is within certain times (optional): HH : MM : SS MM / DD / YYYY Start Time . . 00 : 00 : 00 Start Date . . 00 / 00 / 0000 End Time . . . 00 : 00 : 00 End Date . . . 00 / 00 / 0000 Line commands are: (A)ddress, (S)elect, (R)epeat, (D)elete, or (I)nsert S Ftr F IP Address Port ***** * ********** ***** 001 Client: *.*.*.*_______________________________________ *____ Protocol: HTTP__ Server: *.*.*.*_______________________________________ 80___ 002 Client: *.*.*.*_______________________________________ *____ Protocol: HTTPS_ Server: *.*.*.*_______________________________________ 443__
TCP/IP Scripts and Subset Repositories 7-3
This screen is the starting point for creating Hiperstation TCP/IP scripts. The scripts that you create with these panels can then be used for performing playbacks or simply for browsing TCP/IP data flows (for example, to help with application debugging).
Before creating scripts, you must have a repository that contains the raw TCP/IP data captured with the Hiperstation Global Recording component. A repository is an MVS sequential dataset that was named on a Global Recording request to contain captured TCP/IP data.
Use this Filtering panel to limit the data used to create scripts. You can also name the protocols associated with particular TCP port numbers. This is important if your system uses nonstandard port numbers for the HTTP or HTTPS servers.
Hiperstation can play back HTTP, HTTPS, DB2, IMS, ECI and CTG scripts, but you can capture (for browsing, not for playback) any TCP data streams, regardless of application protocol. Currently, UDP data streams cannot be captured or played back.
1. Supply start and end times and dates to generate scripts that contain only data from a specific period. Note that the start and end times form a single range, not multiple ranges across several dates. For example, START TIME = 08:00:00, END TIME = 10:00:00, START DATE = 5/20/2010, END DATE = 5/21/2010 is a total of 26 hours, not 2 hours.
Valid date ranges are from January 1, 1900 through December 31, 2041. Hiperstation for Mainframe Servers populates these fields with the last specified values. Leave all values zeros if you do not want to filter activity based on time and date.
Note: The Ftr column contains an arbitrary value assigned as a unique ID for each filter. This field cannot be modified.
2. Supply IP addresses and port numbers to limit scripts to the specified values. The wildcard character, an asterisk (*), can be supplied to indicate that any value is a match. In addition, any or all of the four segments of an IP address can be wild-carded. In a field or an IP address segment, a wildcard must appear by itself, not mixed with other values.
3. Valid line commands are ‘D’elete, ‘I’nsert, ‘R’epeat, ‘S’elect and ‘A’ddress. Selecting a row moves to a protocol-specific CONTENT filtering panel (not available for HTTP, HTTPS, or TCP). Addressing a row formats the Client and Server IP addresses into structured fields, depending on format (IPv6, IPv4 or mixed) for easy modification. Use one of the line commands to perform an action on the designated filter. See “Filtering Line Commands” on page 7-2 for more information.
4. Enter a Protocol Name to apply to the activity that matches the given filter. Valid values are HTTP, HTTPS, TCP, ECI, CTG, DB2C, and IMSC. Hiperstation for Mainframe Servers uses the protocol names assigned to the activity in the scripts to initiate the appropriate message handlers during playback.
5. Enter the Client IP Address associated with the activity you wish to include in the scripts or subset repositories. Enter an asterisk (*) wildcard for any IP address segment to include all possible values for the given segment. A wildcard character can be used on any or all segments. You can enter an IPv6 or IPv4 address.
6. Specify the Client Port. Enter an asterisk (*) wildcard to indicate all ports. If you enter an asterisk, all activity on all ports for the specified IP address is labeled with the protocol specified in the Protocol Name field.
7. Specify the Server IP Address. Enter an asterisk (*) wildcard for any IP address segment to include all possible values for the given segment. A wildcard character can be used on any or all segments. You can enter an IPv6 or IPv4 address.
8. Specify the Server Port. Enter an asterisk (*) wildcard to indicate all ports. If youenter an asterisk, all activity on all ports for the specified IP address is labeled with the protocol specified in the Protocol Name field.
7-4 Hiperstation for Mainframe Servers User Guide
9. Type OK on the command line and press Enter to validate the information you have entered and move to the next Create Scripts panel. Use Exit to return to the previous panel.
Note: As a guide to the available protocols, type DEFAULT to propagate the filters list with a default filter for every supported protocol. When doing this, you must type a Server Port number for those ports that are set to asterisk (*) in the default samples because duplicates (including duplicate asterisks) are not allowed. To reset the filters list (losing all changes), type RESET to restore the filters list to to the initial HTTP filter.
The screen that appears next depends on what you select on this panel. If you typed OK, see “Define Activity Grouping” on page 7-11 to continue. If you selected one of the protocols (other than HTTP, HTTPS, or TCP, which do not accept filters), you will navigate to the filter screen for that protocol. A description of these filters follows. If you used the ‘A’ddress line command, you will proceed to the “TCP/IP Create Scripts - Filtering IP Addresses Screen” screen (Figure 7-11 on page 7-11).
DB2 Connect Filters1. On the “TCP/IP Create Scripts - Filtering Screen”(Figure 7-2 on page 7-2), select a DB2
Connect filter from the list of filters. The “TCP/IP Create Scripts - DB2 Connect Filters” appears (Figure 7-3).
Figure 7-3. TCP/IP Create Scripts - DB2 Connect Filters
Hiperstation ------- TCP/IP Create Scripts - DB2 Connect Filte Row 1 to 8 of 8 Command ===> Scroll ===> PAGE Make changes to the DB2 Connect filtering criteria below or select a filter to edit the expanded fields. Use END when complete. Client IP Address: *.*.*.* Client Port: * Server IP Address: *.*.*.* Server Port: 3115 Line commands are: (S)elect, (R)epeat, (D)elete, or (I)nsert SQL SQL S Ftr Act SQL Statement RDB Name UserId Code State ***** **** ************************** ****************** ******** ****** ***** _ 001 ____ __________________________ __________________ ________ ______ _____ _ 002 ____ __________________________ __________________ ________ ______ _____ _ 003 ____ __________________________ __________________ ________ ______ _____ _ 004 ____ __________________________ __________________ ________ ______ _____ _ 005 ____ __________________________ __________________ ________ ______ _____ _ 006 ____ __________________________ __________________ ________ ______ _____ _ 007 ____ __________________________ __________________ ________ ______ _____ _ 008 ____ __________________________ __________________ ________ ______ _____ ******************************* Bottom of data ********************************
Note: The Ftr column contains an arbitrary value assigned as a unique ID for each filter. This field cannot be modified.
You can use one of the line commands, (S)elect, (R)epeat, (D)elete, or (I)nsert, to perform an action on the designated filter. See “Filtering Line Commands” on page 7-2 for more information.
2. Specify the filter action (Act) to be performed. Valid values are INCL (include) or EXCL (exclude). Data from the repository must match at least one Include filter and none of the Exclude filters to be included in the output.
3. Enter an SQL statement to be monitored (alphanumeric). Enter an asterisk (*) wildcard to specify all SQL statements.
4. Enter an RDB Name (alphanumeric Relational Database Name). Enter an asterisk (*) wildcard to specify all databases.
TCP/IP Scripts and Subset Repositories 7-5
5. Enter the UserId to filter connections on. Enter an asterisk (*) wildcard to indicate all user IDs.
6. Enter a five-digit SQL code. Valid values include numbers from -30106 to 30100.
7. Enter a five-digit, alphanumeric SQL state, xxyyy, where xx represents the class code and yyy the subclass code.
8. Issue the S (select) line command to view detail data for the desired filter. The “TCP/IP Create Scripts - DB2 Connect Filter Detail Screen” appears (Figure 7-4).
The SQL Statement, RDB Name, UserId, SQLcode, and SQLstate fields are prefilled from the previous screen but can be changed.
Figure 7-4. TCP/IP Create Scripts - DB2 Connect Filter Detail Screen
Hiperstation - TCP/IP Create Scripts - DB2 Connect Filter Detail ------------ Command ===> Review and/or Edit this filter. Use END when complete. Filter number 001 of 008 Filter action Include (Include or Exclude) Field Name RO Filtering Criteria ************** ** ************************************************************ SQL Statement __ ____________________________________________________________ SQL Answer Set __ ____________________________________________________________ RDB Name __ __________________ UserId __ ________ SQLCode __ ____ SQLstate __ _____
9. Enter an SQL Answer Set and its relational operator. This alphanumeric field specifies data returned in response to an SQL statement. Enter an asterisk (*) wildcard to indicate all responses.
The relational operators (RO) for each field with filtering criteria are prefilled from the previous screen but can be changed. This column specifies how the filtering criteria are compared to the actual content data. Valid values can be entered as either alphabetic- or character-based codes as shown below.
Alphabetic Character Description Code Code Equal EQ == or = Not Equal NE ^= or != Less Than LT < Greater Than GT > Less Than or Equal To LE <= Greater Than or Equal To GE >= Contains CO (no equivalent) Not Contains NC (no equivalent)
IMS Connect Filters1. On the “TCP/IP Create Scripts - Filtering Screen”(Figure 7-2 on page 7-2), select an
IMS Connect filter. The “TCP/IP Create Scripts - IMS Connect Filters Screen” appears (Figure 7-5).
7-6 Hiperstation for Mainframe Servers User Guide
Figure 7-5. TCP/IP Create Scripts - IMS Connect Filters Screen
Hiperstation -------- TCP/IP Create Scripts - IMS Connect Filt Row 1 to 8 of 8 Command ===> Scroll ===> PAGE Make changes to the IMS Connect filtering criteria below or select a filter to edit the expanded fields. Use END when complete. Client IP Address: *.*.*.* Client Port: * Server IP Address: *.*.*.* Server Port: 3150 Line commands are: (S)elect, (R)epeat, (D)elete, or (I)nsert S Ftr Act Transcode Datastore User Id Client Id Client USERDATA ***** **** ********* ********* ******** ********* ************************** _ 001 ____ ________ ________ ________ ________ __________________________ _ 002 ____ ________ ________ ________ ________ __________________________ _ 003 ____ ________ ________ ________ ________ __________________________ _ 004 ____ ________ ________ ________ ________ __________________________ _ 005 ____ ________ ________ ________ ________ __________________________ _ 006 ____ ________ ________ ________ ________ __________________________ _ 007 ____ ________ ________ ________ ________ __________________________ _ 008 ____ ________ ________ ________ ________ __________________________ ******************************* Bottom of data *****************************
Note: The Ftr column contains an arbitrary value assigned as a unique ID for each filter. This field cannot be modified.
You can use one of the line commands, (S)elect, (R)epeat, (D)elete, or (I)nsert, to perform an action on the designated filter. See “Filtering Line Commands” on page 7-2 for more information.
2. Specify the filter action (Act) to be performed. Valid values are INCL (include) or EXCL (exclude). Data from the repository must match at least one Include filter and none of the Exclude filters to be included in the output.
3. Specify the alphanumeric Transcode to filter connections by IMS transaction code (the target application program). Enter an asterisk (*) wildcard to indicate all transaction codes.
4. Enter an alphanumeric Datastore to filter connections by IMS datastore (as defined in the IMS Connect configuration file on the server). Enter an asterisk (*) wildcard to indicate all datastores.
5. Enter an alphanumeric User ID to filter connections based on the RACF userID associated with them. Enter an asterisk (*) wildcard to indicate all user IDs.
6. Enter an alphanumeric Client ID to filter connections based on the unique client identifier associated with them. Enter an asterisk (*) wildcard to indicate all client IDs.
7. Enter alphanumeric Client USERDATA to filter client data not found in IMS Connect headers. Enter an asterisk (*) wildcard to indicate all client data.
8. Enter the S (select) line command. The “TCP/IP Create Scripts - IMS Connect Filter Detail Screen” appears (Figure 7-6).
The Transcode, Datastore, User Id, Client Id, and Client USERDATA fields and their relational operators are prefilled from the previous screen but can be changed.
TCP/IP Scripts and Subset Repositories 7-7
Figure 7-6. TCP/IP Create Scripts - IMS Connect Filter Detail Screen
Hiperstation ---- TCP/IP Create Scripts - IMS Connect Filter Detail --------- Command ===> Review and/or Edit this filter. Use END when complete. Filter number 001 of 008 Filter action Include (Included or Exclude) Field Name RO Filtering Criteria **************** ** ********************************************************** Transcode __ ________ Datastore __ ________ User Id __ ________ Client Id __ ________ Client USERDATA __ __________________________________________________________ Server USERDATA __ __________________________________________________________
9. Enter alphanumeric Server USERDATA to filter server data not found in IMS Connect headers. Enter an asterisk (*) wildcard to indicate all server data.
The relational operator (RO) column specifies how the filtering criteria are compared to the actual content data. Valid values can be entered as either alphabetic- or character-based codes as shown on page 7-5.
CTG Filters1. On the “TCP/IP Create Scripts - Filtering Screen”(Figure 7-2 on page 7-2), select a
CTG filter. The TCP/IP Create Scripts - CTG Filters screen appears (Figure 7-7).
Figure 7-7. TCP/IP Create Scripts - CTG Filters
Hiperstation ----------- TCP/IP Create Scripts - CTG Filters - Row 1 to 8 of 8 Command ===> Scroll ===> PAGE Make changes to the CTG filtering criteria below or select a filter to edit the expanded fields. Use END when complete. Client IP Address: *.*.*.* Client Port: * Server IP Address: *.*.*.* Server Port: 2006 Line commands are: (S)elect, (R)epeat, (D)elete, or (I)nsert S Ftr Act Program Applid Client COMMAREA ***** **** ******** ******** ************************************************** _ 001 ____ ________ ________ __________________________________________________ _ 002 ____ ________ ________ __________________________________________________ _ 003 ____ ________ ________ __________________________________________________ _ 004 ____ ________ ________ __________________________________________________ _ 005 ____ ________ ________ __________________________________________________ _ 006 ____ ________ ________ __________________________________________________ _ 007 ____ ________ ________ __________________________________________________ _ 008 ____ ________ ________ __________________________________________________ ******************************* Bottom of data ********************************
Note: The Ftr column contains an arbitrary value assigned as a unique ID for each filter. This field cannot be modified.
2. Use one of the line commands, (S)elect, (R)epeat, (D)elete, or (I)nsert, to perform an action on the designated filter. See “Filtering Line Commands” on page 7-2 for more information.
3. Specify the Filter Action (Act) to be performed. Valid values are INCL (include) or EXCL (exclude). Data from the repository must match at least one Include filter and none of the Exclude filters to be included in the output.
7-8 Hiperstation for Mainframe Servers User Guide
4. Enter an alphanumeric Program Name to filter connections by program name. Enter an asterisk (*) wildcard to indicate all program names.
5. Enter an alphanumeric Applid to filter connections by VTAM application ID. Enter an asterisk (*) wildcard to indicate all connections.
6. Enter an alphanumeric Client COMMAREA to filter the user data portion passed by the client to the CICS application.
7. Enter the S (select) line command. The TCP/IP Create Scripts - CTG Connect Filter Detail screen appears (Figure 7-8).
Figure 7-8. TCP/IP Create Scripts - CTG Filter Detail
Hiperstation -------- TCP/IP Create Scripts - CTG Filter Detail ------------- Command ===> Review and/or Edit this filter. Use END when complete. Filter number 001 of 008 Filter action Include (Include or Exclude) Field Name RO Filtering Criteria **************** ** ********************************************************** Program Name __ ________ Applid __ ________ Client COMMAREA __ __________________________________________________________
8. The Program Name, Applid, and Client COMMAREA fields are prefilled from the previous screen
The relational operator (RO) column specifies how the filtering criteria are compared to the actual content data. Valid values can be entered as either alphabetic- or character-based codes as shown on page 7-5.
ECI Filters1. On the “TCP/IP Create Scripts - Filtering Screen”(Figure 7-2 on page 7-2), select an
ECI filter. The TCP/IP Create Scripts - ECI Filters screen appears (Figure 7-9).
Figure 7-9. TCP/IP Create Scripts - ECI Filters
Hiperstation ----------- TCP/IP Create Scripts - ECI Filters - Row 1 to 8 of 8 Command ===> Scroll ===> PAGE Make changes to the ECI filtering criteria below or select a filter to edit the expanded fields. Use END when complete. Client IP Address: *.*.*.* Client Port: * Server IP Address: *.*.*.* Server Port: 1435 Line commands are: (S)elect, (R)epeat, (D)elete, or (I)nsert S Ftr Act Program Userid Client COMMAREA ***** **** ******** ******** ************************************************** _ 001 ____ ________ ________ __________________________________________________ _ 002 ____ ________ ________ __________________________________________________ _ 003 ____ ________ ________ __________________________________________________ _ 004 ____ ________ ________ __________________________________________________ _ 005 ____ ________ ________ __________________________________________________ _ 006 ____ ________ ________ __________________________________________________ _ 007 ____ ________ ________ __________________________________________________ _ 008 ____ ________ ________ __________________________________________________ ******************************* Bottom of data ********************************
TCP/IP Scripts and Subset Repositories 7-9
Note: The Ftr column contains an arbitrary value assigned as a unique ID for each filter. This field cannot be modified.
2. Use one of the line commands, (S)elect, (R)epeat, (D)elete, or (I)nsert, to perform an action on the designated filter. See “Filtering Line Commands” on page 7-2 for more information.
3. Enter the filter action (Act) to be performed. Valid values are INCL (include) or EXCL (exclude). Data from the repository must match at least one Include filter and none of the Exclude filters to be included in the output.
4. Enter an alphanumeric Program Name to filter connections by program ID being invoked by CICS. Enter an asterisk (*) wildcard to indicate all program names.
5. Enter an alphanumeric Userid to filter connections by the user ID associated with them. Enter an asterisk (*) wildcard to indicate all user IDs.
6. Enter an alphanumeric Client COMMAREA to filter the user data portion of COMMAREA being passed into CICS.
7. Enter the S (select) line command. The TCP/IP Create Scripts - ECI Connect Filter Detail screen appears (Figure 7-10).
The Program Name, Userid, and Client COMMAREA fields are prefilled from the previous screen but can be changed.
Figure 7-10. TCP/IP Create Scripts - ECI Filter Detail
Hiperstation -------- TCP/IP Create Scripts - ECI Filter Detail ------------- Command ===> Review and/or Edit this filter. Use END when complete. Filter number 001 of 008 Filter action Include (Include or Exclude) Field Name RO Filtering Criteria **************** ** ********************************************************** Program Name __ ________ Userid __ ________ Client COMMAREA __ __________________________________________________________
The relational operator (RO) column specifies how the filtering criteria are compared to the actual content data. Valid values can be entered as either alphabetic- or character-based codes as shown on page 7-5.
Filtering IP Addresses
The “TCP/IP Create Scripts - Filtering Screen” (Figure 7-2 on page 7-2) is a starting point for creating IP address and port filters for TCP/IP Script Create. With the introduction of IPv6 support, there are now three formats in which IP addresses can be expressed in Hiperstation. The “TCP/IP Create Scripts - Filtering IP Addresses Screen” (Figure 7-11 on page 7-11) provides an illustrative structure for entering these formats for users who are new to IPv6.
You can access the “TCP/IP Create Scripts - Filtering IP Addresses Screen” by using the “A” line command for any of the filters on the “TCP/IP Create Scripts - Filtering Screen”.
IP address values in the selected filter list entry are expanded into the Client or Server IP address fields on this screen, as appropriate. The format chosen is determined by the format of the entered IP addresses. IP addresses on this screen are validated for correctness when you press Enter. Addresses where all segments are zeroed out are ignored.
7-10 Hiperstation for Mainframe Servers User Guide
When you exit the “TCP/IP Create Scripts - Filtering IP Addresses Screen”, the IP address segments are recombined into a single text string and used to update the Client and Server fields of the originally selected filter list entry. Which exit format is selected is determined by the validity of the IP addresses. If all formats contain valid IP addresses the precedence order is IPv6, followed by IPv4, and then mixed IPv6 and IPv4. Client IP addresses are evaluated first, then the corresponding Server IP address selected format is validated.
IPv6 IP Address Filters
The first format on the screen is IPv6. An IPv6 IP address is 16 bytes long and, in textual form, consists of eight two-byte segments. Each two-byte segment is defined as a four-digit hexadecimal XXXX (0..9,A..F) value and segments are separated by colons. Therefore, as shown in Figure 7-11, an IPv6 IP address contains seven colons.
Given that many of these segments could have a zero value, IPv6 defines a shorthand representation to prevent the repetitive entering of :0. Use double colon (::), to represent one or more consecutive zero segments. Thus, an Ipv6 address of FE80:0:0:0:0:0:0:A0A could be written as FE80::A0A. The double colon notation can be entered in the IP address free-form area on the previous panel. Such a double colon IP address is expanded into its full form on the “TCP/IP Create Scripts - Filtering IP Addresses Screen”. ::XXXX and XXXX:: are supported for 0:0:0:0:0:0:0:XXXX and XXXX:0:0:0:0:0:0:0 respectively.
Other valid IPv6 IP address formats include:
The IP address filter (::10.10.27.200) captures IPv6 compatible addresses. Since this format is valid but depricated, it is allowed with a pop-up warning. It only captures IPv6 address 0000:0000:0000:0000:0000:0000:0A0A:1BCA. It will not capture a mapped IPv4 address.
The IP address filter (FE80::C0C:10.10.200.0) is valid and will only capture FE80:0000:0000:0000:0000:C0C:A0A:CA00.
The IP address filter (FE80::C0C:675) specifies that nodes 1, 7, and 8 must be as specified. Nodes 206 are zeros.
The IP address filter (::1) specifies all zeros ending with an eighth node of 1.
IPv4 IP Address Filters
The second format on the screen is IPv4. IPv4 IP addresses are four bytes long and are usually expressed as four decimal numbers in the form “ddd.ddd.ddd.ddd” where “ddd” is a decimal number in the range 0-255. An example might look like: 10.10.27.200, which will only capture native IPv4 address 10.10.27.200 or 0000:0000:0000:0000:0000:FFFF:0A0A:1BCA.
Other valid IPv4 IP address formats include:
The IP address filter (10.*.27.*) is similar to the previous example except that the second and fourth nodes can be anything.This example will only capture native IPv5 address 10.nn.27.nn or 0000:0000:0000:0000:0000:FFFF:0Ann:1Bnn where nn can be anything.
The IP address filter (::FFFF:10.*.27.*) or (0:0:0:0:0:FFFF:10.*.27.*) captures native IPv4 addresses or mapped IPv4 addresses only.
Mixed IPv6 and IPv4 Address Filters
The third format on the screen is a mixed IPv6 and IPv4 notation, designed for mapping existing IPv4 addresses into the IPv6 environment. As an IPv6 address, mixed IP addresses are 16 bytes long. They are defined as six two-byte IPv6 segments plus a four-byte IPv4 address (i.e., XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:ddd.ddd.ddd.ddd). Note that an extra colon is added to the end of the IPv6 portion to connect the IPv6 and IPv4 components together.
TCP/IP Scripts and Subset Repositories 7-11
It is likely that many users will want to format groups of TCP/IP sessions. This can be achieved by using the wildcard asterisk (*) character. Any IP address segment, IPv6 or IPv4, can be replaced with a wildcard.
To wildcard the entire address, there are three possibilities: a single asterisk (*) entered in the filter list entry on the previous panel, a full IPv4 wildcarded address (*.*.*.*), and a full IPv6 wildcarded address (*:*:*:*:*:*:*:*), which will also capture IPv4 addresses. A single asterisk (*) is expanded to a full IPv6 wildcarded address on the “TCP/IP Create Scripts - Filtering IP Addresses Screen”. Except when using a single asterisk (*) or valid IPv6 shorthand notations (FE80::FA49), all filter nodes must be specified.
No line commands are available on the “TCP/IP Create Scripts - Filtering IP Addresses Screen”. Press Enter to validate input. Use EXIT to return to the previous screen.
Warning Message
A warning, specified as a “W” will appear if you omit the FFFF and enter an IP address in the format:
::10.10.0.32
Type an S over the W to select that IP address and you will navigate to the “TCP/IP Collect Data Filters Screen” where you will get a message stating “Deprecated IPV4 mapped IPV6 will capture only IPV6 address. On this screen, you can modify your IP address if desired.
Invalid IP Address Filter Examples
Following are examples of invalid IP address filters:
The IP address filter (10.**.58) is not valid for either IPv6 or IPv4.
The IP address filter (::C0C::A0A) is invalid because you cannot use more than one set of colons (::) in a single IP address filter.
The IP address filter (*:A0A:*:B00:*) is invalid because not enough nodes are specified.
Figure 7-11. TCP/IP Create Scripts - Filtering IP Addresses Screen
+-------------- Create IP Address Filters for Client and Server --------------+ | Hiperstation --------- TCP/IP Create Scripts - Filtering IP Addresses ----- | | Command ===> Scroll ===> PAGE | | | | Using the most appropriate of the three provided IP address formats, enter | | client and server IP address filters (use * for wildcards). Press ENTER to | | validate the addresses. Press PF3/END to validate the addresses and return. | | | | IPv6 | | ************************************************************* | | Client 0000 : 0000 : 0000 : 0000 : 0000 : 0000 : 0000 : 0000 | | Server 0000 : 0000 : 0000 : 0000 : 0000 : 0000 : 0000 : 0000 | | | | IPv4 | | ***************************** | | Client *__ . *__ . *__ . *__ | | Server *__ . *__ . *__ . *__ | | | | Mixed IPv4 IPv6 | | *********************************************************************** | | Client 0000 : 0000 : 0000 : 0000 : 0000 : 0000 : ___ . ___ . ___ . ___ | | Server 0000 : 0000 : 0000 : 0000 : 0000 : 0000 : ___ . ___ . ___ . ___ | | | +-----------------------------------------------------------------------------+
Define Activity Grouping
To define activity grouping, you will need to generate one of the following:
7-12 Hiperstation for Mainframe Servers User Guide
• One script containing filtered activity ordered as it was captured.
• Separate scripts containing filtered activity grouped by connection.
• Separate scripts containing filtered activity grouped by client IP address, client port, server IP address, server port, and/or protocol. Selecting more than one grouping criteria results in a separate script for each combination.
Determine your grouping selection based on the nature of your application and the types of testing you need to perform. For example:
• To replicate an issue that a specific user encountered, and each user has a unique IP address, group by client IP address to create a separate script containing each user’s activity.
• To test a specific application within the system, group by server IP address and port to create a separate script containing each application’s activity.
• To test Secure Socket connections, group by protocol to isolate HTTPS activity.
• To test the application’s responses to user action, group by connection to create a separate script for each transfer of information from client to server.
• To test client activity, group by connection to create a separate script containing each client’s activity.
Although you can use activity grouping for several purposes, it is primarily used to create scripts for stress, load, and concurrency testing. Later in this process, you can generate a log to use as the SYSIN for a playback job. The log contains one SOCKETS and one SCRIPT statement for each script created. All SOCKETS play back simultaneously. Be mindful of transaction interdependence. For example, while recording, you request a record and then update the record. If your grouping selection places the inquiry transaction in one script and the update in another, the inquiry transaction may play back after the update resulting in a “miscompare”. Depending on the focus of your testing, this may or may not be an issue.
1. On the “TCP/IP Create Scripts - Filtering Screen” (Figure 7-2 on page 7-2), specify the desired filter criteria and enter OK on the command line. The “TCP/IP Create Scripts - Grouping Screen” appears (Figure 7-12).
Note: Selections on this screen do not impact subset repositories.
Figure 7-12. TCP/IP Create Scripts - Grouping Screen
Hiperstation --------- TCP/IP Create Scripts - Grouping ---------------------- Command ===> Choose how to group data among scripts, then press Enter to continue. Create a new script for each: _ 1. One script for everything 2. Connection 3. New combination of (one or more) _ Client IP address _ Client port _ Server IP address _ Server port _ Protocol Select item 1 if you want to play back all TCP/IP activity in the exact sequence that it was originally created. Synthesized Connection Special Processing: Reverse Synthesized Connections: _ Server Port DSN:________________________________________________
TCP/IP Scripts and Subset Repositories 7-13
2. On the line next to option 1, enter the number of the desired grouping selection. Choices include:
– 1 (One script for everything) — Puts all activity in one script in the exact order that it was recorded (optimum for playback)
– 2 (Connection) — Creates a separate script for each connection captured. Connection is the desired setting if testing client activity (for example, PLAY(SERVER)).
– 3 (New combination of one or more) — Creates separate scripts for each unique combination of selected grouping criteria. Type a slash (/) next to the desired grouping criteria. Combinations include:
• Client IP address• Client port• Server IP address• Server port• Protocol
3. (Reverse Synthesized Connections:) This optional selection applies to Synthesized Connections only. To create a TCP/IP Connection in a Script when one was not recorded, Script Create uses a heuristic algorithm to determine the Client and Server Assignments from the existing data. If the determination made by Script Create is incorrect, select this field to reverse the determination made using the algorithm.
4. (Server Port DSN:) Specify a fully qualified dataset name, without quotes, in the Server Port DSN field if you wish to supply a list of Ports that will always be considered the Server side by Script Create in a Client-Server pair. This option applies to Synthesized Connections only and is optional. This option takes precedence over Reverse Synthesized Connections option, but they are not mutually exclusive.
5. Press Enter to continue.
Specify the Source Repository
After you select a grouping option from the previous section, the “TCP/IP Create Scripts - Input Screen” appears (Figure 7-13).
Figure 7-13. TCP/IP Create Scripts - Input Screen
Hiperstation ---------- TCP/IP Create Scripts - Input ------------------------- Command ===> Choose the repository to use as input, then press Enter to continue. Repository dataset: Dataset name . . . . . ______________________________________________ First and last number . _______ _______ (Needed if wildcard in dataset name) Amount of data to use: Data from client . . . ALL_____ (ALL or number of bytes) Data from server . . . ALL_____ (ALL or number of bytes)
1. Specify the capture repository or repository segments to use for generating the scripts or subset repositories.
You can save time and system resources by scripting the repository segments of interest as opposed to the entire repository. To identify the information contained in each segment of the repository, generate a Capture Segment Summary, described on page 2-50. It indicates when recording began and ended for each repository segment.
2. Enter the repository Dataset name to use for generating your scripts/subset repositories. To select a range of source repositories, use either of the following
7-14 Hiperstation for Mainframe Servers User Guide
wildcard characters in the dataset name designation and define a range with the First to last number fields:
– Asterisk (*): Insert the asterisk in place of the dataset name qualifier characters that should be substituted with incremental values during repository selection. This wildcard pads to eight characters. For example, enter USER.REP*.DATABASE with first=1 and last=3 to create scripts/subset repositories from source repositories:
USER.REP00001.DATABASE USER.REP00002.DATABASE USER.REP00003.DATABASE
– Question mark (?): Insert a question mark for each dataset name qualifier character that should be substituted with incremental values during repository selection. For example, enter USER. REP??.DATABASE with first=9 and last=11 to create scripts/subset repositories from source repositories:
USER.REP09.DATABASE USER.REP10.DATABASE USER.REP11.DATABASE
3. Specify the Amount of data to use to minimize the size of your scripts by truncating the client and/or server transmission data detail, that is, data tagged <CONTENT> in TCP/IP scripts. This option supports tasks such as debugging and stress testing.
For example, if you are manually inspecting scripts for debugging purposes and only need to see the first 200 bytes, truncate to 200. If you are stress testing and are only interested in the transaction speed, rather than data comparison, truncate client data to reduce the size of your scripts and demand on DASD storage. Enter ALL to include all transaction data or indicate the number of bytes, between 0-9999999, to include.
If you intend to play back and compare actual with expected values, select ALL. If you truncate client data, your scripts may not play back properly. If you truncate server data, your scripts may play back, but comparing actual to expected values may not be possible.
4. Press Enter to continue.
Define Detail Data Storage and Output Requirements
After selecting a source repository or set of repositories from the previous section, the “TCP/IP Create Scripts - Create Options Screen” appears (Figure 7-14). Use this screen to specify how to store transmission data, what to create, and whether the new items should replace existing items with the same names.
TCP/IP Scripts and Subset Repositories 7-15
Figure 7-14. TCP/IP Create Scripts - Create Options Screen
Hiperstation ------ TCP/IP Create Scripts - Create Options ------------------- Command ===> Press Enter to continue. Where should Details be stored: _ 1. Merged into the script 2. Separate from the script, client and server together 3. Separate from the script, client and server split What should be created: Enter "/" to select options / Log / Script / Details _ Subset Repository _ Replace existing log members _ Replace existing script members _ Replace existing detail members
1. On the line next to option 1, specify where details should be stored. Detail data is the information actually sent by TCP socket applications. This data is either written to one or more detail files, or is written within the script on <CONTENT> tags. In both cases, the data is prefixed with a twelve-byte header carrying information about the detail data.
Detail data can be mapped into File-AID/MVS to view or edit in a formatted context. You can map all detail data at once if it is stored in an external file. If it is merged into the script, each message must be mapped independently. See “Editing TCP/IP Detail Data with File-AID/MVS” on page 7-38, for more information.
Choices include:
– Merged into the script — Merges the detail data into the script where it can be found on <CONTENT> tags.
– Separate from the script, client and server together — Stores the script and detail data in separate PDSE members. The script contains links to the detail data and the activity reflects the data flow at the time of capture.
– Separate from the script, client and server split — Stores the script, client activity, and server activity in separate PDSE members. The script contains links to the detail data, and the activity is separated by client and server. Therefore, all client activity is written into one member and the server activity into another.
2. Type a slash next to the items to be generated. To overwrite existing files for any of the selected items, type a slash next to the corresponding replace option.
– Log — Generates a Connection Log that lists every script Hiperstation for Mainframe Servers created. Each entry consists of a SOCKETS and SCRIPT statement. The log not only reports the results of script creation, but may also be used as the SYSIN for an Unattended Playback job. Depending on your testing requirements, you may need to modify it before playing back your scripts. For more playback information, see Chapter 9, “TCP/IP Unattended Playback”.
– Script — Generates scripts that consist of header information and data for one or more TCP connections. For more information on the contents of script tags, see “Browsing and Editing Scripts” on page 7-20.
– Details — Generates detail data, which is the information actually sent by TCP socket applications. This data is either written to one or more detail files, or is written within the script on <CONTENT> tags, depending on your previous selections. In both cases, the data is prefixed with a twelve-byte header carrying information about the detail data.
7-16 Hiperstation for Mainframe Servers User Guide
To generate scripts you intend to play back, be sure to select this option. Otherwise, the scripts will contain unresolved <DETAIL> tags, <DETAIL COMBINED ???>. Either regenerate the scripts, or generate the details and replace the question marks with the DD names associated with the Detail Datasets.
– Subset Repository — Generate one or more subset repositories depending on your selections on the previous and remaining screens.
– Replace existing log members — Replaces any log member that has the same name as the log being generated.
– Replace existing script members — Replaces any script members that have the same name as the scripts being generated.
– Replace existing detail members — Replaces any detail members that have the same name as the detail members being generated.
3. Press Enter to go to the next screen.
Specify Output Datasets
If you selected Log, Script, or Details on the “TCP/IP Create Scripts - Create Options Screen” (Figure 7-14), the “TCP/IP Create Scripts - Output Screen” appears (Figure 7-15). Otherwise, the “TCP/IP Create Scripts - Subset Output Screen” appears (Figure 7-17 on page 7-19). Go to “Specify Subset Repository Output Datasets” on page 7-18 to continue.
Figure 7-15. TCP/IP Create Scripts - Output Screen
Hiperstation ---------- TCP/IP Create Scripts - Output ------------------------ Command ===> Enter the output dataset names, member name prefixes, member name suffixes, and DDnames. Rows marked with * are required. Script Datasets: Log: . . . . . . ______________________________________________ * Prefix ______ Suffix: 0000000 Script: . . . . ______________________________________________ * Prefix ______ Suffix: 0000000 Combined detail: ______________________________________________ Prefix ______ Suffix: 0000000 DDname: ________ Client detail: . ______________________________________________ Prefix ______ Suffix: 0000000 DDname: ________ Server detail: . ______________________________________________ Prefix ______ Suffix: 0000000 DDname: ________
1. Complete the fields that are marked with an asterisk (*)
– Dataset Name — Supply a PDSE name, without a member name, for each row marked with an asterisk (*). If you do not enclose the PDSE name in single quotes, Hiperstation for Mainframe Servers prefixes it with your TSO prefix, typically your user ID, at processing time.
– Prefix — Enter a one- to six-character member name prefix for each row marked with an asterisk (*). Provide a prefix that makes it easy to identify the type of data stored in the members of the given dataset. Hiperstation for Mainframe Servers uses the prefix and suffix to create complete member names. For example, prefix payroll system testing scripts with PRTEST and set the suffix to 01 to generate members PRTEST01, PRTEST02, and so on.
Note: Make sure the combined number of characters for prefix and suffix does not exceed eight.
– Suffix — Enter a one- to seven-numeral member name suffix for each row marked with an asterisk (*). Hiperstation for Mainframe Servers uses the prefix
TCP/IP Scripts and Subset Repositories 7-17
and suffix to create complete member names for the information stored in the given dataset. If it creates more than one member for the dataset, it increments the suffix to create unique member names. For example, your grouping selection produces three scripts. If the prefix is set to PRTEST and suffix is set to 01, Hiperstation for Mainframe Servers generates members PRTEST01, PRTEST02, PRTEST03.
– DDname — Enter a one- to eight-character DD name for detail datasets marked with an asterisk (*). Hiperstation for Mainframe Servers creates a <DETAIL> tag in the script that points to the DD names you specify. It uses this information to locate the detail data during playback.
Note: The playback JCL contained in the log will include the DD names you enter here. If you compose your own playback JCL, instead of using the JCL from the log, be sure to include the same DD names.
2. After filling in all of the desired dataset names, press Enter to continue.
3. If you enter a dataset name that does not exist, the Allocate Dataset screen appears. The fields on the allocation screen default to the last specified values. Set the record length (LRECL) for:
– Log datasets to 76 or higher.
– Script datasets to 76 or higher. To minimize CPU utilization and the amount of time it takes to generate the scripts, set this value to 256 or higher.
– Detail datasets equal to or greater than the maximum TCP message length.
Note: Messages longer than the detail dataset LRECL will span multiple lines. If the dataset contains messages that span multiple lines, the MAPD command, discussed on page 7-38, will not allow you to map the entire detail dataset into File-AID/MVS for editing, only individual messages.
– Block size must be minimally the record length plus four — 32760 is the maximum allowable value. Leave this field empty to have the system calculate block size for you.
4. After filling in the fields, press Enter to allocate the dataset or press End to exit the screen without allocating the dataset.
Note: If more datasets require allocation, the allocation screen for the next dataset appears. Otherwise, continue with the next section “Select Script Options”.
Select Script Options
After you specify Log, Script, or Detail Output datasets, the “TCP/IP Create Scripts - Options Screen” appears (Figure 7-16). If you are generating a subset repository only, you will not see the Options screen. Go to “TCP/IP Create Scripts - Subset Output Screen” on page 7-19.
Use the “TCP/IP Create Scripts - Options Screen” to select script formatting options.
7-18 Hiperstation for Mainframe Servers User Guide
Figure 7-16. TCP/IP Create Scripts - Options Screen
Hiperstation --------- TCP/IP Create Scripts - Options ----------------------- Command ===> Press Enter to continue. Options: Enter "/" to select options _ Suppress time stamps in script _ Translate detail data from ASCII to EBCDIC _ Translate sample data from ASCII to EBCDIC _ Split lines at linefeed characters (for readability) _ Suppress CONTENT data formatting (DB2C, IMSC, CTG, or ECI) Description . . . _______________________________________________________
1. Enter a slash to select any or all of the following options:
– Suppress time stamps in script — This option omits time stamps, making the script easier to browse for auditing purposes. However, Hiperstation uses time stamps to synchronize playback when think option 2, THOPT(2), is specified on the playback CONTROL statement. Do not use this option if you intend to play back your scripts at the same pace as they were recorded.
– Translate detail data from ASCII to EBCDIC — Converts detail data, normally written in ASCII, to EBCDIC. This makes it easier to display and edit detail data in ISPF. Hiperstation adds the TRANSLATE=A2E keyword to the script tag to indicate that translation has occurred. During playback, Hiperstation translates the data back to ASCII.
– Translate sample data from ASCII to EBCDIC — When you store script and detail data separately, Hiperstation includes a single line, or sample, of the detail data in the script for reference purposes. This option converts ASCII sample data to EBCDIC. Select this option if you plan to view your scripts in ISPF.
– Split lines at linefeed characters (for readability) — Select Split lines at linefeed characters to show the detail data in a more readable format. Much of the data transferred between Web browsers and servers consists of readable lines that end with the ASCII linefeed character (x'0A'). Splitting detail data lines at each linefeed character can help you understand script contents. Playback is not affected by this option.
– Suppress CONTENT data formatting (DB2C, IMSC, CTG, or ECI) — Select this option to indicate that key protocol fields (DB2C, IMSC, CTG, or ECI) should not be separated from the CONTENT data and formatted into a readable format within the script.
2. Enter up to 53 characters that describe the scripts or subset repositories you are creating. This description appears at the top of the Log and at the top of each script.
3. Press Enter to continue.
Specify Subset Repository Output Datasets
If you are creating a subset repository, the “TCP/IP Create Scripts - Subset Output Screen” appears (Figure 7-17). Otherwise, the “TCP/IP Create Scripts - Process Screen” appears (Figure 7-18 on page 7-20). See “Select a Processing Option” on page 7-19.
TCP/IP Scripts and Subset Repositories 7-19
Figure 7-17. TCP/IP Create Scripts - Subset Output Screen
Hiperstation ----------- TCP/IP Create Scripts - Subset Output --------------- Command ===> Specify the subset repository to create, then press ENTER to continue. Subset repository dataset: Dataset name . . . . ._____________________________________________________ First and last number ._______ _______ (Needed if wildcard in dataset name)
Specify a single dataset to contain the entire subset repository or a range of datasets to segment the repository. Hiperstation writes the new repository data to the first specified dataset. If the dataset contains data, it adds the new data to the end of existing data until it completes repository creation or the dataset is full. If there is more data to write, it continues writing to the next specified dataset. Hiperstation reports progress with messages indicating the opening and closing of datasets.
Note: To overwrite an existing repository dataset, first delete the dataset.
1. In the Dataset name field, enter the name of the sequential dataset to contain the new subset repository. To create a segmented repository, use either of the following wildcards and specify a wildcard range with the First and last number fields:
– Asterisk (*): Insert the asterisk in place of the dataset name qualifier characters to substitute with incremental values during repository creation. This wildcard pads to eight characters. For example, enter USER.REP*.DATABASE with first=1 and last=3 to create the following subset repositories:
USER.REP00001.DATABASE USER.REP00002.DATABASE USER.REP00003.DATABASE
– Question mark (?): Insert a question mark for each dataset name qualifier character to substitute with incremental values during repository creation. For example, enter USER. REP??.DATABASE with first=9 and last=11 to create the following subset repositories:
USER.REP09.DATABASE USER.REP10.DATABASE USER.REP11.DATABASE
2. Press Enter to continue.
If the first specified dataset does not exist, the Allocate Dataset screen appears. It populates the Space units, Primary quantity, and Secondary quantity fields with allocation values from the originating (input) repository and Block size with the default value of 9004.
3. Make changes, if necessary, and press Enter to continue or press End to exit the screen without allocating the file.
Note: For segmented repositories, Hiperstation automatically allocates subsequent datasets, if they do not exist, with the allocation parameters of the first dataset.
Select a Processing Option
After selecting all of your script/subset repository creation options, the “TCP/IP Create Scripts - Process Screen” appears (Figure 7-18).
7-20 Hiperstation for Mainframe Servers User Guide
Figure 7-18. TCP/IP Create Scripts - Process Screen
Hiperstation --------- TCP/IP Create Scripts - Process ----------------------- Command ===> Select an option: _ 1. Submit batch job 2. Edit batch job 3. Process in foreground X. Exit Job statement information for batch job: ===> //JOBNAME JOB (ACCOUNT),'NAME' ===> //* ===> //* ===> //*
Enter the desired processing option on the line next to the list and press Enter to begin processing. Press End to exit the screen without processing the job.
Note: By default, the maximum message size that Script Create processes is 32K. Increase this value by adding a parameter to the JCL prior to submitting the job. Select option 2 and insert the TCPCSMSG 'value' into the list of SYSIN parameters.
Submit batch job
Processes the script/subset repository creation job in batch mode. Refresh your screen to see job submit and confirm messages. When the job is complete, Hiperstation for Mainframe Servers returns to the TCP/IP Create Scripts - Process screen (Figure 7-18).
Edit batch job
Opens up the batch job for editing before processing. If you edit the job, type SUB or SUBMIT on the Command line and press Enter to submit the job. To exit the edit session without submitting the job, type EXIT on the Command line and press Enter.
Process in foreground
Processes the script/subset repository creation job in TSO foreground. Your TSO terminal session is not available for other work until the script/subset repository creation process is complete. All status messages are displayed on your TSO terminal.
Exit
Use this option to exit this screen without submitting the job.
Job statement information for batch job
Enter batch JOB card information into this area. If you use option 2, you can edit this information again before job submission.
Browsing and Editing ScriptsScripts are formatted to make browsing and editing activity easy. Scripts contain tagged data that adheres to a set of syntax rules. Browsing a script requires understanding the purpose and information provided by each script tag. Editing a script requires understanding script tags, syntax rules, and the relationship between the information in the script and the statements that run playback.
TCP/IP Scripts and Subset Repositories 7-21
Browse a Script
Browse scripted activity for tasks such as debugging an application, validating new functionality, and verifying database changes. Use a standard text browsing tool such as ISPF Browse to review the contents of a script.
This section defines all of the available TCP/IP script tags. Each definition includes a syntax diagram that shows all of the parameters for the given script tag.
<VERSION> Tag
The <VERSION> tag identifies the version of the Hiperstation for Mainframe Servers script creation program that created the script and appears only once in a script.
The value after the <VERSION> tag is in the form VV.RR.MM, for version, release, and modification level, respectively. For example:
<VERSION> 07.01.00
Note: The version number is not the same as the product release number, and should not be modified. Modifying it can cause unpredictable results during playback.
<DETAIL> Tag
The <DETAIL> tag specifies the location of the detail data (the bytes that flow between clients and servers). For example, this could be an HTTP request and response. The <DETAIL> tag appears after the <VERSION> tag at the beginning of the script.
COMBINED
Specifies that client and server data are stored together in a single PDSE member, either within the script or in an external file. If the details are contained in the script, the value of this parameter is an asterisk (*). If they are stored externally, the value is the DD name of the external file, along with the PDSE member name, which is supplied during script creation. If COMBINED is present, neither CLIENT nor SERVER appear on this tag and cannot be added.
CLIENT
Identifies where client data is located. The value is the DD name provided during script creation.
SERVER
Identifies where server data is located. The value is the DD name provided during script creation.
Note: If, on the “TCP/IP Create Scripts - Create Options Screen” described on page 7-15, you do not select the Details option, a <DETAIL> tag appears in the script, but the member name appears as three question marks (???). Edit the script to provide the correct location or regenerate the script.
7-22 Hiperstation for Mainframe Servers User Guide
<TIME> Tag
The <TIME> tag specifies the date and time an event was seen during data capture, for the immediately following tag. The <TIME> tag is used during some types of playback to provide script synchronization and “timed release” of data flows. The <TIME> tag appears immediately before each <CONNECT>, <CLIENT>, and <SERVER> tag.
The time value is relative to the system the scripts were created on; it is not GMT (not Coordinated Universal Time, UTC). The content of this tag is a time stamp with the format: YYYY/MM/DD_HH:MM:SS.XXXXXX. For example:
<TIME>2006/07/28_13:02:42.246413
<CONNECT> Tag
The <CONNECT> tag shows the start of a TCP connection. The keywords and values on the <CONNECT> tag indicate the identities of the two partners (the client and server) and the application protocol used by the connection. At playback time, the <CONNECT> tag starts a TCP connection between Hiperstation for Mainframe Servers and a partner application.
ID
Identifies all of the data flows for a single TCP connection. The value of the ID attribute changes for each different TCP connection in a single script. The same ID value is present on all data flows for a single TCP connection. The value of ID is a decimal number, starting at 1 for the first connection in the script.
TCP/IP Scripts and Subset Repositories 7-23
PROTOCOL
Lists the application protocol used by the TCP connection. This is the protocol that you assigned to the activity during script creation. Supported protocols include: HTTP, HTTPS, TCP, ECI, CTG, IMSC, and DB2C.
Note: This value must be accurate for successful playback. Hiperstation uses this value to initiate the appropriate message handlers.
CLIENT_ADDRESS
The IP address of the partner that started the TCP connection (the partner that issued the TCP connection request). At playback time, Hiperstation usually overrides this IP address with the IP address of the local machine (the OS/390 system) that the playback is running on. The value of CLIENT_ADDRESS can be specified in IPv6 or IPv4 format. See “Filtering IP Addresses” on page 7-9 for more information on how to specify IPv6 or IPv4 addresses.
CLIENT_PORT
The port number of the partner that started the TCP connection (the partner that issued the TCP connection request). At playback time, Hiperstation usually overrides this port number with a temporary port number, which is dynamically assigned by the local host machine that the playback is running on. The value of CLIENT_PORT is a decimal number from 0 through 65535.
SERVER_ADDRESS
The IP address of the partner that accepted the TCP connection (the partner that issued a LISTEN and ACCEPT). At playback time, Hiperstation usually uses this IP address with no modification. The value of SERVER_ADDRESS can be specified in IPv6 or IPv4 format. See “Filtering IP Addresses” on page 7-9 for more information on how to specify IPv6 or IPv4 addresses.
SERVER_PORT
The port number of the partner that accepted the TCP connection. At playback time, Hiperstation usually uses this port number with no modification. The value of SERVER_PORT is a decimal number from 0 through 65535. Port number 80 is often used by the HTTP protocol (Web browsing) and port number 443 is often used by the HTTPS protocol (secure Web browsing).
STIME
Indicates the local date and time when the TCP connection started. The STIME value is relative to the system that the scripts were created on; it is not GMT (i.e., not Coordinated Universal Time, UTC). The value is a time stamp with the format: YYYY/MM/DD_HH:MM:SS.XXXXXX. For example:
<TIME>2007/01/31_13:02:42.246413
TRANSLATE
Lists the character translation that was applied to the TCP data flows at script creation time for this connection. In this release, the only value allowed is A2E, which is short for ASCII-to-EBCDIC. A value of A2E indicates that all detail data for this connection, whether in the script or in an external file, has been translated from ASCII to EBCDIC.
This translation does not use a specific IBM or ISO character set and code page. Instead, Hiperstation does a product-specific translation that changes a minimum number of characters when going from ASCII to EBCDIC. An attempt is made to translate only the typical “human readable” characters, (a-z, A-Z, 0-9, and punctuation), while leaving control characters in their original ASCII format. In this way, you can read the translated characters and still see the ASCII control codes that were transmitted (for example, carriage return (CR) and linefeed (LF)).
7-24 Hiperstation for Mainframe Servers User Guide
Here is the translation table used by Hiperstation during script creation and script playback:
ASCII to EBCDIC 0 .1 .2 .3 .4 .5 .6 .7 .8 .9 .A .B .C .D .E .F Changed chars? -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- ---------------- 0. 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ................ 1. 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ................ 2. 40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61 yyyyyyyyyyyyyyyy 3. F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F yyyyyyyyyyyyyyyy 4. 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 yyyyyyyyyyyyyyyy 5. D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D yyyyyyyyyyyyyyyy 6. 79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96 yyyyyyyyyyyyyyyy 7. 97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 4F D0 A1 20 yyyyyyyyyyyyyyyy 8. 80 21 22 23 24 25 26 27 28 29 8A 8B 8C 8D 8E 8F .yyyyyyyyy...... 9. 90 2A 2B 2C 2D 2E 2F 30 31 32 9A 9B 9C 9D 9E 9F .yyyyyyyyy...... A. A0 33 34 35 36 37 38 39 3A 3B AA AB AC 3C AE AF .yyyyyyyyy...y.. B. B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC 3D BE BF .............y.. C. 3E 3F 41 42 43 44 45 46 47 48 CA CB CC CD CE CF yyyyyyyyyy...... D. 49 4A 51 52 53 54 55 56 57 58 DA DB DC DD DE DF yyyyyyyyyy...... E. 59 E1 62 63 64 65 66 67 68 69 EA EB EC ED EE EF y.yyyyyyyy...... F. 6A 70 71 72 73 74 75 76 77 78 FA FB FC FD FE FF yyyyyyyyyy
Note: If a connection event was never seen for a particular TCP connection at capture time, a <CONNECT> tag is “synthesized” for that connection and written to the script. (A connection event may not have been seen at capture time because the Hiperstation recording request was activated after the connection was already “in-flight”.) These synthesized <CONNECT> tags are preceded by a comment line like this:
* SYNTHESIZED CONNECT TAG
The appearance of a synthesized <CONNECT> tag may lead to incorrect playback results since some of the data that originally flowed on the TCP connection may be missing from the script. Be careful when interpreting the playback results from a script that contains a synthesized <CONNECT> tag.
<DISCONNECT> Tag
The <DISCONNECT> tag specifies the end of a TCP connection. It immediately follows either a <CLIENT> tag or a <SERVER> tag, depending on which partner ended the connection.
Note: If a disconnection event was never seen for a particular TCP connection at capture time, a <DISCONNECT> tag is synthesized for that connection and written at the end of the script. These synthesized <DISCONNECT> tags are always placed under a <CLIENT> tag and are preceded by a comment line like this:
* SYNTHESIZED DISCONNECT TAG
The appearance of a synthesized <DISCONNECT> tag may lead to incorrect playback results since some of the data that originally flowed on the TCP connection may be missing from the script. Be careful when interpreting the playback results from a script that contains a synthesized <DISCONNECT> tag.
TCP/IP Scripts and Subset Repositories 7-25
<CLIENT> Tag
The <CLIENT> tag specifies that either data or a disconnect event flowed from the client to the server. The value after the <CLIENT> tag is a decimal number indicating how many events (CONNECT, CLIENT data, or SERVER data) have been seen so far in this script.
ID
Identifies all of the data flows for a single TCP connection. The value of the ID attribute changes for each different TCP connection in a single script. The same ID value will be present on all data flows for a single TCP connection. The value of ID is a decimal number, starting at 1 for the first connection in the script.
CRNTLEN
Indicates the number of bytes of detail data recorded for this client data flow event. This is the number of bytes actually written into the script or an external file, which may be different than the number of bytes sent by the client at capture time. The CRNTLEN value may be less than the TRUELEN value if data truncation was requested by the user either at data capture time or at script creation time.
TRUELEN
Indicates the number of bytes of detail data actually sent by the client, as seen during data capture. This may not be the same as the number of bytes actually written into the script or an external file. The TRUELEN value may be greater than the CRNTLEN value (see above) if data truncation was requested by the user either at data capture time or at script creation time.
<SERVER> Tag
The <SERVER> tag specifies that either data or a disconnect event flowed from the server to the client. The value after the <SERVER> tag is a decimal number indicating how many events (CONNECT, SERVER data, or CLIENT data) have been seen so far in this script.
ID
Identifies all of the data flows for a single TCP connection. The value of the ID attribute changes for each different TCP connection in a single script. The same ID value will be present on all data flows for a single TCP connection. The value of ID is a decimal number, starting at 1 for the first connection in the script.
CRNTLEN
Specifies the number of bytes of detail data recorded for this server data flow event. This is the number of bytes actually written into the script or an external file, which may be different than the number of bytes sent by the server at capture time. The CRNTLEN value may be less than the TRUELEN value if data truncation was requested by the user either at data capture time or at script creation time.
TRUELEN
Specifies the number of bytes of detail data actually sent by the server, as seen during data capture. This may not be the same as the number of bytes actually written into the script or an external file. The TRUELEN value may be greater than the CRNTLEN
7-26 Hiperstation for Mainframe Servers User Guide
value (see above) if data truncation was requested by the user either at data capture time or at script creation time.
<CTG> Tag
<CTG> tags present information that may appear in a script for formatted CTG content.
Note: When using the <REPLACE> tag in conjunction with the <CTG> tag, be aware that either tag will replace the information specified by the other tag depending on which tag is set last.
APPLID
The VTAM application ID associated with the session.
PROGID
The CICS program associated with the session.
<DB2> Tag
<DB2> tags present information that may appear in a script for formatted DB2 Connect content.
Note: When using the <REPLACE> tag in conjunction with the <DB2> tag, be aware that either tag will replace the information specified by the other tag depending on which tag is set last.
SQLSTMT
The SQL statement in editable form.
USERID
The userID associated with the session.
PASS
The password for the session.
NPASS
The password for the session in an encrypted format.
RDBNAM
The server name for DB2 Connect (the name of the relational database).
SQLCODE
A non-editable field returned by the server.
TCP/IP Scripts and Subset Repositories 7-27
SQLSTATE
A non-editable field returned by the server.
<ECI> Tag
<ECI> tags present information that may appear in a script for formatted ECI content.
Note: When using the <REPLACE> tag in conjunction with the <ECI> tag, be aware that either tag will replace the information specified by the other tag depending on which tag is set last.
USERID
The user ID associated with the session.
PASS
The password for the session.
NPASS
The password for the session in an encrypted format, which is ‘xx...xx’X where xx...xx indicates 2 to 16 hexadecimal characters.
PROGID
The CICS program associated with the session.
<IMS> Tag
<IMS> tags present information that may appear in a script for formatted IMS Connect content.
Note: When using the <REPLACE> tag in conjunction with the <IMS> tag, be aware that either tag will replace the information specified by the other tag depending on which tag is set last.
USERID
The userID associated with the session.
PASS
The password for the session.
NPASS
The password for the session in an encrypted format, which is ‘xx...xx’X where xx...xx indicates 2 to 16 hexadecimal characters.
7-28 Hiperstation for Mainframe Servers User Guide
CLIENT
The unique client identifier for the session.
DSTORE
The target IMS Datastore for the session.
TRANS
The transaction code (application program) the message belongs to.
<CONTENT> Tag for Inline Data
<CONTENT> tags present the data that flowed between the client and the server. One or more <CONTENT> tags appear immediately after a <CLIENT> or <SERVER> tag. If the length of the client or server data is greater than the logical record length (LRECL) of the script dataset, the detail data is presented on a series of consecutive <CONTENT> tags.
When detail data is merged into the script, known as inline data, the <CONTENT> tag has no attributes and is immediately followed, on the same line, by a 12-byte header and then the application's data bytes, known as detail data. In the following example, “....00000007” is the <CONTENT> tag header and the detail data begins immediately after “7”.
<CONTENT>....00000007.......XPPJOBM400...wæìÎUR÷...ö«.\.m÷G 4444CDDECDE60310FFFFFFFF0002000EDDDDCDFFF000A957EDE000C83E49EC 000C3653553E0241000000070A0210A77716244002076C86491308CA00B417
Note: On the Command line in ISPF Edit, type HEX ON and press Enter to see the HEX values for all of the bytes in the <CONTENT> tag.
The 12-byte header describes the <CONTENT> tag:
• The first two bytes indicate the length of the data following the <CONTENT> tag. This value includes the 12-byte header and has a maximum value of X'7FF8' (32760).
Note: If you are editing the script, make sure this number accurately reflects the actual number of bytes in the dataset record plus twelve for the header. If the data record is longer than this value, playback ignores the extra bytes. If the data record is shorter than this value, playback pads it with EBCDIC blanks (X'40').
• The third byte indicates the format of the <CONTENT> tag data. Its value is a combination of all applicable formats from the following list.
– X'10' indicates TCP/IP data– X'08' indicates the beginning of the CONTENT chain– X'04' indicates the end of the CONTENT chain– X'02' indicates truncated data– X'01' indicates SERVER data
For example, if the TCP/IP message is comprised of three <CONTENT> tags, this byte’s value on the:
– First tag is X'18', which indicates TCP/IP data and beginning of CONTENT chain.– Second tag is X'10', which indicates TCP/IP data– Third tag is X'14', which indicates TCP/IP data and end of CONTENT chain.
If the <CONTENT> tag follows a <SERVER> tag, this byte’s values on each <CONTENT> tag is: X'19', X'11', and X'15'.
TCP/IP Scripts and Subset Repositories 7-29
• The fourth byte indicates the protocol of the detail data.
– X'01' indicates generic TCP/IP– X'03' indicates HTTP– X'04' indicates HTTPS– X'05' indicates DB2 Connect– X'06' indicates ECI – X'07' indicates CTG– X'08' indicates IMS Connect
• The fifth through the twelfth bytes indicate the record number, beginning with 0000001 (X'F0F0F0F0F0F0F0F1'). This value increases by one for each subsequent <CONTENT> tag.
Note: If you use the <REPLACE> tag (page 7-32) to replace application data during playback, be mindful of this 12-byte header when calculating the offset.
Header: L L F P N N N N N N N N Offset: 0 1 2 3 4 5 6 7 8 9 A B
Avoid manually calculating the data-replacement offset value by using the offset determination macros that Hiperstation for Mainframe Servers provides (page 7-33).
<CONTENT> Tag for External Data
Identifies the detail data records that are associated with the preceding <CLIENT> or <SERVER> tag. The <CONTENT> tag only includes the FROM and TO parameters when the detail data is stored in an external file.
FROM
A decimal number indicating the first label in the external file containing detail data for this data flow.
TO
A decimal number indicating the last label in the external file containing detail data for this data flow.
The value after the <CONTENT> tag is called 'sample data'. It is the first few bytes of detail data and is provided to support script browsing when the detail data is stored separately. The sample bytes are translated from ASCII to EBCDIC if you requested that option at script creation time.
Whether the detail data is contained within the script or in an external file it is prefixed by a 12-byte header that describes the affiliated <CONTENT> tag. See the description of the 12-byte header provided in the “<CONTENT> Tag for Inline Data” discussion on page 7-28.
Edit a Script
You may want to edit scripted activity to:
• Manipulate the way the scripts play back. For example, to stress test a function, edit the script to isolate a single transaction and then play back several concurrent instances repeatedly.
7-30 Hiperstation for Mainframe Servers User Guide
• Ensure successful playback. For example, if recording begins after a connection is already in progress, the script may contain a partially recorded business transaction that results in an application or playback error. Delete the unwanted activity from the script.
• Alter information within the TCP/IP data streams. For example, you have modified your application to accept a longer product code. To test the application using a script recorded before the modifications, edit the product code portion of the <CLIENT> and <SERVER> tag content.
Use ISPF Edit to edit your scripts. To perform dynamic data replacement during playback, insert the <REPLACE> tag. For example, the script contains a series of transactions performed against a specific account. If the account number resides in the same location in the TCP/IP data streams, you can replace that account number in all of the transactions by inserting one <REPLACE> tag in the appropriate location. You can replace data in a single client or server data stream or in a specified range of data streams.
You can add REXX logic to the script to:
• Create dynamic scripts that facilitate data-driven testing or create smart scripts that modify application flow based on message content.
• Define custom MVS job step return codes for more definitive playback results.
Hiperstation for Mainframe Servers provides customized REXX variables that return playback information. You can incorporate these variables into your REXX routines. For example, use the REXX variables that return the current playback count and repeat values to control record substitution for data-driven testing.
This section of the manual describes the elements necessary for basic script editing and a short description of the Hiperstation REXX variables:
• “Script Syntax Rules” on page 7-30 • “<REPLACE> Tag” on page 7-32 • “Offset and Length Determination Macros” on page 7-33• “Hiperstation for Mainframe Servers REXX Variables” on page 7-35
For more advanced scripting concepts or a better understanding of REXX applications, refer to the Hiperstation Scripting Reference. Additionally, consider reviewing “APPC Data-Driven Testing Example Using REXX” on page 4-44. Although it applies to APPC testing, it provides a comprehensive example that includes the use of Hiperstation REXX variables and the <REPLACE> tag. The concepts and mechanics are the same regardless of the type of application you are testing.
Notes:
1. Hiperstation for Mainframe Servers supports editing application data in the script or detail file with File-AID/MVS. For more information, see “Editing TCP/IP Detail Data with File-AID/MVS” on page 7-38.
2. Understanding the relationship between the information in the scripts and the statements used to run playback can impact your editing decisions. For example, scripts contain connection information that indicates the server address accessed by each connection. Edit the script if you need to modify the server address on a connection-by-connection basis. However, if you need to modify the server address for all of the connections in the script, supply the SERVER_ADDRESS keyword on the SCRIPT playback statement instead. Prior to editing your scripts, review the information in Chapter 9, “TCP/IP Unattended Playback”.
Script Syntax Rules
Editing a script requires an understanding of script tags and syntax rules. If you are unfamiliar with TCP/IP script tags, see “Browse a Script” on page 7-21.
TCP/IP Scripts and Subset Repositories 7-31
TCP/IP Script Syntax Rules:
Note: The examples below that show an IP address are shown in IPv4 format. IPv6 format is also valid.
• A script tag must be enclosed in angle brackets ‘<>’ and the tag name must be adjacent to the opening angle bracket ‘<‘. For example:
<TIME>
• Script tag parameters follow the tag name inside the angle brackets. The format of a script tag parameter is parameter=value.
<CLIENT ID=6>
• A tag can have multiple parameters. Parameters on the same line must be separated by one or more spaces. For example:
<CONNECT ID=6 PROTOCOL=TCP...
Parameters can appear on separate lines for easy reading. Each line must end with a comma, which is the standard ISPF record continuation character. For example:
<CONNECT, ID=6, PROTOCL=TCP,
• Script tag parameter values must be enclosed in single quotation marks if they need to be interpreted as constants or if they contain characters other than: underscore (_), uppercase A through Z, or 0 through 9. For example, the CLIENT_ADDRESS parameter value contains periods so it is enclosed in single quotation marks. IPv6 and IPv4 IP address formats are both valid CLIENT_ADDRESS values.
<CONNECT, ID=2, PROTOCOL=TCP, CLIENT_ADDRESS='10.10.0.200',
• The script tag’s value follows the tag’s closing bracket ‘>’. For example, 4 is this <CONNECT> tag’s value.
<CONNECT, ID=2, PROTOCOL=TCP, CLIENT_ADDRESS='10.10.0.200', CLIENT_PORT=3621, SERVER_ADDRESS='10.10.0.200', SERVER_PORT=2241, STIME='2007/01/23_13:31:02.411122'>4
• The script tag’s entire value must be on the same line as the closing bracket ‘>’.
• Comment lines, used to provide details or enhance formatting, must begin with an asterisk and can appear anywhere in the script. For example, the following comment lines provide spacing between blocks of connection information and a description of the next connection in the script
<CONTENT>....00000073.d * * CONNECTION NUMBER(6) * * WARNING: MISSING DATA, SYNTHESIZED CONNECT TAG <TIME>2007/01/23_13:31:08.946828 <CONNECT>
• REXX clauses added to the script must precede the activity the logic applies to. They can be inserted between scripts tags, but not within a tag or its value.
7-32 Hiperstation for Mainframe Servers User Guide
do id# 1 to 100 say ‘Starting connection # ‘id# <CONNECT ID=id# SERVER_PORT=80>123 <CLIENT ID=id#>124 <CONTENT>....00000001GET / HTTP/1.0.... <CLIENT ID=id#>125 <DISCONNECT> end
• A single REXX variable can be supplied as the value of a script tag parameter. For example:
port#=80; ipaddress , ‘24.25.190.224’ <CONNECT ID-1, SERVER_ADDRESS=ipaddress = , SERVER_PORT=port#>123,
However, REXX variables cannot be supplied within the script tag’s value. Therefore, they cannot be the value or within the value following the tag’s closing angle bracket ‘>’.
<REPLACE> Tag
The <REPLACE> tag replaces the information within the TCP/IP data streams during playback. Use the <REPLACE> tag to supply new data, such as account numbers, user names, etc. For advanced scripting concepts, such as data-driven testing, incorporate the <REPLACE> tag into REXX logic that reads the replacement data from an external file, as described in “Edit a Script” on page 7-29.
The <REPLACE> tag can be applied to the CONTENT of a single <CLIENT> or <SERVER> tag or to a range of tags. If applied to a range, the <REPLACE> tag acts on the CONTENT of both <CLIENT> and <SERVER> tags within the range.
Insert the <REPLACE> tag before the <CLIENT> or <SERVER> tag or group of tags it applies to. To establish a range, specify ALL on the TYPE parameter of the <REPLACE> tag and insert another <REPLACE> tag at the end of the range. Specify DELETE on the TYPE parameter of the closing <REPLACE> tag to terminate the action of the previous <REPLACE> tag.
Note: When using the <REPLACE> tag in conjunction with the <CTG> tag, be aware that either tag will replace the information specified by the other tag depending on which tag is set last. This is also true for the <DB2>, <ECI>, and <IMS> tags.
FIELD
Identifies where to begin replacing data within the subsequent CONTENT records (offset) and what value to insert. Data replacement occurs during playback processing. The original value in the script or detail file is preserved.
The offset value is zero-based and should not include the 12-byte header at the beginning of each <CONTENT> tag. For example,
<REPLACE FIELD=(0,'GET') LENGTH=3>
replaces ‘XXP’ with ‘GET’ in the following <CONTENT> record.
TCP/IP Scripts and Subset Repositories 7-33
<CONTENT>....00000007XPPJOBM400...wæìÎUR÷...ö«.\.m÷G....... 4444CDDECDE60310FFFFFFFF0002000EDDDDCDFFF000A957EDE000C83E49EC 000C3653553E0241000000070A0210A77716244002076C86491308CA00B417
Specify one or more FIELD attributes on a given <REPLACE> tag. For example:
<REPLACE FIELD=(0,’CAT’) FIELD=(20,’DOG’)>
Note: Hiperstation provides macros for easily determining offset values. See the next section “Offset and Length Determination Macros” for details.
TYPE
Indicates how to apply data replacement.
– TYPE=ONE applies data replacement to the next CLIENT or SERVER message. This is the default.
– TYPE=ALL applies data replacement to all subsequent CLIENT and SERVER messages. This is a global data replacement.
– TYPE=DELETE disables global data replacement established by a previous <REPLACE> tag with the TYPE=ALL parameter.
LENGTH
Sets the length for the entire message content to be used during playback, LENGTH=n, where n indicates the number of bytes. If part of a message is replaced and it changes the data length from the original, then the LENGTH parameter would be needed. This applies whether the length change shortens or lengthens the data.
For example, if the original message was 50 bytes in length and a replaced piece of data was being substituted that changed the length to 60 bytes, the Replace tag would read <REPLACE FIELD(offset,value) LENGTH=60>. Conversely, if a replaced piece of data was being substituted that changed the length to 30 bytes, the Replace tag would read <REPLACE FIELD(offset,value) LENGTH=30>.
Note: Hiperstation for Mainframe Servers provides macros for easily determining length values. See the next section “Offset and Length Determination Macros”.
Offset and Length Determination Macros
The <REPLACE> tag requires an offset value that indicates where to begin data replacement. The offset value is zero-based and applies to the actual data stream. If a data stream is longer than the LRECL of the script dataset, the data stream is broken into multiple content records each beginning with the <CONTENT> tag and a 12-byte header. For example:
000484 <CLIENT ID=9>39 000485 <CONTENT> 00000295GET /BonusPak2/db2/telco.htmls HTTP/1.1 Accept 000486 <CONTENT> 00000296image/gif, image/x-xbitmap,image/jpeg, image/p 000487 <CONTENT> 00000297jpeg, application/vnd.ms-excel,application/vnd. 000488 <CONTENT> 00000298ms-powerpoint,application/msword, application/x 000489 <CONTENT> 00000299-%hockwave-flash, */* Referer: http://cw01.comp 000490 <CONTENT> 00000300uware.com/bp2atoc.html Accept-Language: en-us
The <CONTENT> tag and header should not be considered in the offset value. This can make determining the offset somewhat difficult especially in multi-record <CONTENT> tags. For example, the ‘G’ in ‘GET’ on line 485 is the first byte of application data and would require an offset of 0 if replaced, while the ‘i’ in ‘image’ on line 486 is the 49th byte and would require an offset of 48. Further, the <REPLACE> tag offers an optional length parameter that indicates the number of bytes that the replacement data should occupy. It is typically used when the replacement data is longer or shorter than the original data.
7-34 Hiperstation for Mainframe Servers User Guide
To ease offset and length determination, Hiperstation provides the following macros:
• LOCPOS — displays the offset value based on the cursor’s position within a <CONTENT> tag.
• BRULE — displays a byte ruler for the selected <CONTENT> record.
• BRULES — displays a byte ruler for all records in the selected <CONTENT> tag.
Note: Each time you execute a macro, you have to type the macro name on the Command line, position the cursor, and press Enter. You can avoid repeatedly typing the macro name, by assigning a PF key. To assign a PF key, type KEYS on the Command line of an ISPF Edit or View session. The ISPF Keylist Utility screen appears. In the definition area next to the desired key, enter a macro name. Refer to the ISPF Keylist Utility Help to learn more about key mapping.
To use the offset and length determination macros:
1. Open the script or detail dataset with ISPF Edit.
2. Scroll through the script or detail data until the appropriate <CONTENT> record is in view.
3. On the Command line, type the macro name. If you assigned a PF key, skip this step.
4. If using the LOCPOS macro, place the cursor on the first character of the data to be replaced. If using either of the byte ruler macros, place the cursor anywhere in the applicable <CONTENT> record.
5. Press Enter or the assigned PF key. The LOCPOS macro displays the offset of the selected character in a pop-up window near the bottom of the screen (Figure 7-19).
Figure 7-19. LOCPOS Results
File Edit Edit_Settings Menu Utilities Compilers Test Help ------------------------------------------------------------------------------- EDIT USER2312.TCPIP.SCRIPTS.NEW(SCRPT001) - 00.01 Columns 00001 00072 Command ===> Scroll ===> PAGE 000476 PROTOCOL=HTTP, 000477 CLIENT_ADDRESS='10.15.80.190', 000478 CLIENT_PORT=1477, 000479 SERVER_ADDRESS='10.10.0.200', 000480 SERVER_PORT=80, 000481 STIME='2007/01/24_14:31:13.674379', 000482 TRANSLATE=A2E>38 000483 <TIME>2007/01/24_14:31:13.674478 000484 <CLIENT ID=9>39 000485 <CONTENT> 00000295GET /BonusPak2/db2/telco.htmls HTTP/1.1 Accept: 000486 <CONTENT> 00000296 image/gif, image/x-xbitmap, image/jpeg, image/p 000487 <CONTENT> 00000297jpeg, application/vnd.ms-excel, application/vnd. 000488 <CONTENT> 00000298ms-powerpoint, application/msword, application/x 000489 <CONTENT> 00000299-%hockwave-flash, */* Referer: http://cw01.comp 000490 <CONTENT> 00000300uware.com/bp2atoc.html Accept-Language: en-us 000491 <CONTENT> 00000301Accept-Encoding: gzip, deflate If-Modified-Sinc 000492 <CONTENT> 000003 +--------------+ 997 05:07:23 GMT User-Agent: Mo 000493 <CONTENT> 000003 | OFFSET = 264 | tible; MSIE 6.0; Windows NT 5.1; 000494 <CONTENT> 000003 +--------------+ 01.compuware.com Connection: Ke 000495 <CONTENT> 00000305ep-Alive
The BRULE macro displays a byte ruler above the selected <CONTENT> record (Figure 7-20). In the illustration, the offset of ‘m’ is 144, ‘s’ is 145, ‘-’ is 146, etc. Every fifth and tenth byte is indicated with a number on the ruler. When the offset value is greater than 10, the number on the rules occupies two positions. In these cases, the offset values apply to the character under the 0. For example, 50 appears over the ‘we’ in the word ‘powerpoint’. The offset value of ‘w’ is 149 and ‘e’ is 150.
TCP/IP Scripts and Subset Repositories 7-35
Figure 7-20. BRULE Results
File Edit Edit_Settings Menu Utilities Compilers Test Help ------------------------------------------------------------------------------- EDIT USER2312.TCPIP.SCRIPTS.NEW(SCRPT001) - 00.01 Columns 00001 00072 Command ===> Scroll ===> PAGE 00483 <TIME>2007/01/26_14:31:13.674478 000484 <CLIENT ID=9>39 000485 <CONTENT> 00000295GET /BonusPak2/db2/telco.htmls HTTP/1.1 Accept: 000486 <CONTENT> 00000296 image/gif, image/x-xbitmap, image/jpeg, image/p 000487 <CONTENT> 00000297jpeg, application/vnd.ms-excel, application/vnd. ====== DATA BELOW 144==>-5---50----5---60----5---70----5---80----5---90- 000488 <CONTENT> 00000298ms-powerpoint, application/msword, application/x 000489 <CONTENT> 00000299-%hockwave-flash, */* Referer: http://cw01.comp 000490 <CONTENT> 00000300uware.com/bp2atoc.html Accept-Language: en-us 000491 <CONTENT> 00000301Accept-Encoding: gzip, deflate If-Modified-Sinc 000492 <CONTENT> 00000302e: Fri, 23 Feb 2007 05:07:23 GMT User-Agent: Mo 000493 <CONTENT> 00000303zilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; 000494 <CONTENT> 00000304 CPWR) Host: cw01.compuware.com Connection: Ke
The BRULES macro displays a byte ruler above each record (line) of the selected <CONTENT> tag (Figure 7-21).
Figure 7-21. BRULES Results
File Edit Edit_Settings Menu Utilities Compilers Test Help ------------------------------------------------------------------------------- EDIT USER2312.TCPIP.SCRIPTS.NEW(SCRPT001) - 00.01 Columns 00001 00072 Command ===> Scroll ===> PAGE 000481 STIME='2007/01/26_14:31:13.674379', 000482 TRANSLATE=A2E>38 000483 <TIME>2007/01/26_14:31:13.674478 000484 <CLIENT ID=9>39 ====== DATA BELOW 0==>0----5---10----5---20----5---30----5---40----5-- 000485 <CONTENT> 00000295GET /BonusPak2/db2/telco.htmls HTTP/1.1 Accept: ====== DATA BELOW 48==>-50----5---60----5---70----5---80----5---90----5 000486 <CONTENT> 00000296 image/gif, image/x-xbitmap, image/jpeg, image/p ====== DATA BELOW 96==>--100----5---10----5---20----5---30----5---40--- 000487 <CONTENT> 00000297jpeg, application/vnd.ms-excel, application/vnd. ====== DATA BELOW 144==>-5---50----5---60----5---70----5---80----5---90- 000488 <CONTENT> 00000298ms-powerpoint, application/msword, application/x ====== DATA BELOW 192==>---5--200----5---10----5---20----5---30----5---4 000489 <CONTENT> 00000299-%hockwave-flash, */* Referer: http://cw01.comp
Hiperstation for Mainframe Servers REXX Variables
Add REXX logic to your TCP/IP scripts to control the way scripts play back. For example, dynamically replace script data with unique data from an external file on each iteration of playback. Incorporate the following Hiperstation predefined REXX variables. They return playback information used to drive data-replacement logic. Refer to the Hiperstation Scripting Reference for more information.
Note: Understanding playback, especially the SOCKETS and SCRIPT statements is integral to determining how to apply these variables. Additionally, do not forget to set the SET_REXX_STREAM_VARIABLES playback control parameter to YES to enable the use of these variables during playback. See “CONTROL Statement” on page 9-3.
TCPIP_ACTUAL
Returns the content of the most recent message processed by Hiperstation. This variable’s value is similar to the RequestBody or ResponseBody reporting fields, depending on whether the data came from the client or server.
7-36 Hiperstation for Mainframe Servers User Guide
TCPIP_EXPECTED
Returns the content of an inbound message that Hiperstation expects to receive. This is the server content from your script. This variable is similar to the ExpResponseBody reporting field.
TCPIP_ACTUAL_LENGTH
Returns the length of the most recent message processed by Hiperstation.
TCPIP_EXPECTED_LENGTH
Returns the length of an inbound message that Hiperstation expects to receive.
CONNECTION_NBR
Returns the current ID of the connection that is playing back. This variable’s value may be the same across multiple sockets, as it is pulled from the script.
REPLAY_ID
Returns a sequential value for each instance of a SOCKETS replay. For example, a SOCKETS statement with COUNT(2) REPEAT(3), replays two instances of a script simultaneously, repeated three times, for a total of six unique replay IDs. Use REPLAY_ID in volume testing to provide a unique message for each connection to your application.
For example, to test 1000 simultaneous customer requests accessing your application, each with a different customer number and name:
1. Create an external file containing customer numbers and names with one customer per line.
2. Add data replacement logic to your script, for example:
/* Access external file and parse customer info */ "EXECIO * DISKR CUSTFILE (STEM cust.FINIS" parse var cust.REPLAY_ID 1 cust_nbr 11 cust_name /* Replace content in script with info from file */ <REPLACE FIELD(0,cust_nbr) FIELD(10,cust_name)> /* Send the message */ <CLIENT...
3. Set the count value in the SOCKETS statement to 1000:
SOCKETS COUNT(1000)
This generates 1000 unique customer requests by starting 1000 simultaneous sessions, all with unique REPLAY_IDs that correspond to the customer information from your external file.
SOCKETS_COUNT_NBR
Returns the COUNT value of the current SOCKETS replay. For example, if the SOCKETS statement specifies COUNT(3), the first instance returns COUNT = 1; the second, COUNT = 2; the third, COUNT = 3. This value is set when the SOCKETS replay begins.
Use this variable and SOCKETS_REPEAT_NBR to extend testing capability.
SOCKETS_REPEAT_NBR
Returns the REPEAT value of the given SOCKETS. This value is set when a socket begins execution. Use SOCKETS_COUNT_NBR and SOCKETS_REPEAT_NBR to replace script data
TCP/IP Scripts and Subset Repositories 7-37
on specific COUNTS and REPEATS. For example, to test three products (A, B, C) with two accounts (1, 2).
All COUNTS execute simultaneously
COUNT 1 COUNT 2 COUNT 3
Repeat 1 Product A, Account 1 Product B, Account 1 Product C, Account 1
Repeat 2 (begins after Repeat 1 finishes)
Product A, Account 2 Product B, Account 2 Product C, Account 2
1. Create an external file for each parameter you want to replace. Each file should contain one parameter value per line.
2. Add data replacement logic to your script, for example:
/* Access external files */ "EXECIO * DISKR PRODFILE (STEM product.FINIS" "EXECIO * DISKR ACCTFILE (STEM account.FINIS" product_nbr product.MQGROUP_COUNT_NBR account_nbr account.MQGROUP_REPEAT_NBR /* Replace content in script with info from file */ <REPLACE FIELD(5,account_nbr) FIELD(32,product_nbr)> /* Send the message */ <CLIENT...
3. Set the count and repeat values in the SOCKETS statement as follows:
SOCKETS COUNT(3),REPEAT(2)
This generates six unique customer requests, each with a unique combination of product and account parameter values.
SCRIPT_REPEAT_NBR
Returns the REPEAT value of the current script playback. This value is set to one when the script begins execution, and increments with every repeat.
ACTUAL_DB2_USERID
Returns the ID of the user associated with the DB2 transaction being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_DB2_RDBNAM
Returns the name of the relational database associated with the DB2 transaction being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_DB2_SQLSTMT
Returns the SQL Statement associated with the DB2 transaction being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_DB2_SQLSTATE
Returns the value of the last SQL State returned by the application during playback. This is a live value that is received by playback from the server being tested.
ACTUAL_DB2_SQLCODE
Returns the value of the last SQL code returned by the application during playback. This is a live value that is received by playback from the server being tested.
7-38 Hiperstation for Mainframe Servers User Guide
ACTUAL_DB2_ANSWER_SET
Returns the server’s response to an SQL Query/Statement being played back. This is a live value that is received by playback from the server being tested.
ACTUAL_IMS_CLIENT
Returns the unique client identifier associated with the IMS transaction being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_IMS_TRANS
Returns the IMS transaction code (target application) associated with the IMS transaction being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_IMS_DSTORE
Returns the IMS Datastore associated with the IMS transaction being played back. This value comes from the script and is sent to the server by playback
ACTUAL_IMS_USERID
Returns the ID of the user associated with the IMS transaction being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_CTG_APPLID
Returns the APPLID of the VTAM application being accessed by the CTG transaction being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_CTG_PROGID
Returns the name of the program being accessed by the CTG transaction being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_ECI_USERID
Returns the ID of the user associated with the ECI call being played back. This value comes from the script and is sent to the server by playback.
ACTUAL_ECI_PROGID
Returns the name of the program invoked in CICS by the ECI call being played back. This value comes from the script and is sent to the server by playback.
Editing TCP/IP Detail Data with File-AID/MVSReview and edit TCP/IP detail data (transmission or message data) with:
• ISPF Edit or View.• File-AID/MVS version 08.00 (if you are licensed).
Invoke File-AID/MVS from an ISPF Edit or View session to review and edit TCP/IP message data in a formatted context. For example, if the message data contains a numeric string representing a customer ID and account number, identifying the account number portion of the string may be difficult in ISPF Edit and therefore editing may be more error prone.
Use the MAPD command to invoke File-AID/MVS Edit and apply a record layout that presents the information with labels you define, such as Customer ID and Account Number. Edit information as necessary and exit File-AID/MVS to carry changes over to
TCP/IP Scripts and Subset Repositories 7-39
the ISPF session. End the session to apply changes to the script/detail dataset. This process is referred to as mapping message data into application data structures.
Note: This feature supports a maximum record length of 32K.
If TCP/IP message data is stored in the script, map one message at a time. If it is stored in a separate dataset, map an individual message or all messages in the dataset at once. Refer to page 7-15.
Assign a PF Key to MAPD
Simplify editing individual messages by assigning a PF key to execute the MAPD command. Access the ISPF Keylist Utility by typing KEYS on the Command line of an ISPF Edit or View session. In the definition area next to the desired key, enter an exclamation point (!) followed by MAPD (!MAPD). Refer to the ISPF Keylist Utility Help to learn more about key mapping.
Note: The command prefix character may be different depending on the code page used by your terminal. The command prefix is the character that maps to hexadecimal value X‘5A’. In the United States, the exclamation point is typically the correct character. To determine the appropriate character, either refer to the code page relevant to your terminal or use the HEX editing features of an ISPF Edit session. Open an edit session, invoke HEX editing, type 5A in the edit area, and disable HEX editing.
Map an Individual Message
Make sure the Maintain PDS Statistics option in File-AID/MVS is set to ADD before you begin mapping. Refer to your File-AID/MVS manual or your system programmer for help.
To map individual messages:
1. Open the script or detail dataset in ISPF Edit or View. ISPF View prompts for confirmation prior to writing changes back to the script or detail data file.
2. Use standard ISPF commands to locate the message you wish to map.
Note: To view only the message data in a script file, type X ALL on the Command line and press Enter; then type F <CONTENT> ALL and press Enter.
3. If you have not assigned a PF key for the MAPD command, place the cursor on the Command line and enter an exclamation point (!) following by MAPD.
Note: The command prefix (!) is only required for the first mapping in the session. It is an ISPF standard for invoking a macro. Also, the command prefix may be different depending on the code page used by your terminal. In the United States, the exclamation point is typically the correct character. See the note in the “Assign a PF Key to MAPD” on page 7-39 discussion for more information.
4. Position the cursor anywhere right of the line command area on the record you wish to map and press the assigned PF key. If you did not assign a PF key, be sure MAPD is on the Command line and the cursor is correctly positioned, then press Enter.
5. MAPD invokes File-AID/MVS. Refer to your File-AID/MVS documentation for help with the screens that appear. With File-AID/MVS, you can apply a record layout, generate XML from mapped data, XREF information, and filter information to see only the activity you need to review or edit.
Note: MAPD creates a temporary dataset, with a 4-node naming convention (USERID.MAPDTEMP.DATE.TIME), to pass mapped messages to
7-40 Hiperstation for Mainframe Servers User Guide
File-AID/MVS. File-AID/MVS writes changes to the temporary dataset. When you leave File-AID/MVS, it passes your changes back to ISPF and deletes the temporary dataset. Upon exiting ISPF, MAPD updates the script/detail dataset.
If for some reason, the File-AID/MVS session is lost during edit, delete the temporary dataset manually.
Additionally, you can use the temporary dataset as input to an XML generation job. After you submit the job, exit the File-AID screen that appears to ensure the temporary dataset is available for use. Do not exit File-AID until the job is complete.
Edit message content as necessary. Make sure Caps Lock is off when you enter File-AID/MVS. If you edit a line and Caps Lock is on, File-AID coverts the entire line to uppercase. Press Cancel to cancel your work return to ISPF or End to exit File-AID/MVS and transfer your changes to ISPF.
6. To exit the ISPF session without saving changes, press Cancel. To save your work in:
– An Edit session, press End.
– A View session, use the Create or Replace commands. Then press End to terminate the session.
Map an Entire Data File
Make sure the Maintain PDS Statistics option in File-AID/MVS is set to ADD before you begin mapping. Refer to your File-AID/MVS manual or your system programmer for help.
To map an entire data file:
1. Open the detail dataset in ISPF Edit or View.
Note: ISPF View prompts for confirmation prior to writing changes back to the script or detail data file.
2. Place your cursor on the Command line and press the PF key assigned to the MAPD command. If you have not assigned a PF Key for the MAPD command, type exclamation point (!) MAPD on the Command line and press Enter.
Note: The command prefix (!) is only required for the first mapping in the session. It is an ISPF standard for invoking a macro. Also, the command prefix may be different depending on the code page used by your terminal. In the United States, the exclamation point is typically the correct character. See the note in the “Assign a PF Key to MAPD” on page 7-39 discussion for more information.
3. MAPD invokes File-AID/MVS. Refer to your File-AID/MVS documentation for help with the screens that appear. With File-AID/MVS, you can apply a record layout, generate XML from mapped data, XREF information, and filter information to see only the activity you need to review or edit.
Note: MAPD creates a temporary dataset, with a four-node naming convention (USERID.MAPDTEMP.DATE.TIME), to pass mapped messages to File-AID/MVS. File-AID/MVS writes changes to the temporary dataset. When you leave File-AID/MVS, it passes your changes back to ISPF and deletes the temporary dataset. Upon exiting ISPF, MAPD updates the script/detail dataset.
If for some reason, the File-AID/MVS session is lost during edit, delete the temporary dataset manually.
TCP/IP Scripts and Subset Repositories 7-41
Additionally, you can use the temporary dataset as input to an XML generation job. After you submit the job, exit the File-AID screen to ensure that the temporary dataset is available for use. Do not exit File-AID until the job is complete.
Edit message content as necessary. Make sure Caps Lock is off when you enter File-AID/MVS. If you edit a line and Caps Lock is on, File-AID coverts the entire line to uppercase. Press Cancel to cancel your work and return to ISPF or End to exit File-AID/MVS and transfer your changes to ISPF.
CAUTION:Deleting and inserting messages may cause unsynchronized playback.
The script contains a link to each message in the detail file that supports playing back the script. If the detail file contains more or fewer messages than the script calls, playback will become unsynchronized. When you exit File-AID/MVS, Hiperstation for Mainframe Servers warns you if the message count has been altered.
If you replace messages by deleting and inserting, be sure the replacement messages contain the same type of data as the original messages.
4. To exit the ISPF session without saving changes, press Cancel. To save your work in:
– An Edit session, press End.
– A View session, use the Create or Replace commands. Then press End to terminate the session.
Access MAPD Help Panels
To access MAPD help panels, type MAPD space HELP or MAPD space question mark (?) on the Command line in the ISPF Edit or View session. Then press Enter.
Troubleshoot Message Mapping
MAPD presents information, error, and warning messages in the ISPF session. Depending on your ISPF settings, message content either appears on the first line of the display or in a pop-up window. Most messages are fairly intuitive. However, some may be more difficult to troubleshoot. This section explains each message and provides the appropriate action to take, if any.
Script Dataset Messages
'CURSOR NOT ON <CONTENT> - SEE USER’S GUIDE'
Explanation: The dataset containing the message you are mapping is not a script dataset.
User Response: Press Enter to clear the message and Cancel to exit the ISPF session. Locate the appropriate dataset and try again.
'DATA CHANGES DETECTED - EXTRA RECORD(S) IGNORED'
Explanation: You added one or more records while editing in File-AID/MVS. MAPD sent a single message, so it expects to receive a single record.
System Action: MAPD ignores the additional records when transferring changes back to ISPF. However, ISPF will reflect changes, if any, made to the originally mapped message.
'INVALID CONTENT LENGTH - SEE USER'S GUIDE'
Explanation: While editing a script dataset, the message length attribute byte was modified.
System Action: MAPD will not transfer data to File-AID/MVS if the message length does not match the value of the length attribute byte.
7-42 Hiperstation for Mainframe Servers User Guide
User Response: Press Enter to clear the message. If editing occurred in the current ISPF session, use Cancel to exit the session without saving changes and retry.
'SCRIPT & DETAIL MUST BE COMBINED - SEE USER’S GUIDE'
Explanation: You are attempting to map from a script dataset that is stored separately from the detail dataset (message data). It contains links to the message data and the first part of each message for identification purposes. Refer to “Define Detail Data Storage and Output Requirements” on page 7-14.
User Response: Press Cancel to exit the ISPF session. Locate the corresponding detail dataset and map messages from there.
Detail Dataset Messages
'CURSOR NOT ON DETAIL RECORD - SEE USER’S GUIDE'
Explanation: You are either attempting to map from a dataset that is not a detail dataset or you inadvertently altered a detail data sequence number.
User Response: Press Enter to clear the message. Then make sure you are in a detail file. If you are in a detail file and you inadvertently altered a sequence number in the current ISPF session, cancel without saving your work and start over. If the sequence number was altered in another ISPF session and saved, regenerate the script and detail.
'LINE(S) DELETED - DETAIL OUT OF SYNC'
Explanation: While editing a detail dataset in File-AID/MVS, you deleted a record, which will cause an unsynchronized playback.
User Response: Press Cancel to exit the ISPF session without saving changes to the detail dataset.
'LINE(S) INSERTED - DETAIL OUT OF SYNC'
Explanation: While editing a detail dataset in File-AID/MVS, you inserted a record, which will cause an unsynchronized playback
User Response: Press Cancel to exit the ISPF session without saving changes to the detail dataset.
'MESSAGE DATA SPANS MULTIPLE LINES - SEE USER'S GUIDE'
Explanation: When the script was created, if the length of the TCP/IP message data is longer that the detail dataset’s logical record length (LRECL), the message will span more than one line. This message appears when you try to map an entire file containing messages that span more than one line.
User Response: Press Enter to clear the message. The cursor will position to the first offending message. Map messages individually or regenerate the script and detail with an LRECL equal to or greater than the maximum message length.
General Information and Error Messages
'32K MAXIMUM LRECL EXCEEDED'
Explanation: You are attempting to map a file containing messages larger than 32K. 32K is the maximum record length supported by MAPD.
'COMMAND NOT FOUND'
Explanation: The ISPF Edit Macro invocation character is missing or incorrect. ISPF requires the invocation character for the first use of the macro in a given session.
User Response: Prefix the MAPD command with the appropriate macro invocation character. This is the character that maps to hexadecimal value X‘5A’. For devices using the EBCDIC Code Page 037, the prefix character is an exclamation point (!).
'DATA CHANGES DETECTED'
Explanation: This message informs you that data has been changed.
TCP/IP Scripts and Subset Repositories 7-43
User Response: If you did not intend to change data, press Enter to clear the message and Cancel to exit the ISPF session without saving the changes.
'INVALID PARAMETER'
Explanation: On the Command line, MAPD is followed by text that is not recognized as a valid parameter.
User Response: Press Enter to clear the message. Remove characters following the MAPD command and press Enter to resume work. Note: HELP or ‘?’ are the only valid MAPD parameters.
'NO CHANGES DETECTED'
Explanation: This message informs you that data has not been changed.
User Response: Press Enter to clear the message and return to ISPF.
'NO DATA RETURNED FROM FILE-AID'
Explanation: You deleted the message in File-AID/MVS; therefore, File-AID/MVS had no data to return.
System Action: No changes are made to the TCP/IP message data.
User Response: Press Enter to clear the message and return to ISPF.
7-44 Hiperstation for Mainframe Servers User Guide
8-1
Chapter 8.
8TCP/IP Interactive Playback Chap 8Introducing TCP/IP Interactive PlaybackUse interactive playback to:
• Play back scripts — execute the commands found in the script.
• Analyze scripts — process the script without executing the commands to report information on the script’s contents.
In order to play back a Hiperstation for Mainframe Servers script, you must have created a script using the Create Scripts panels, (See Chapter 7, “TCP/IP Scripts and Subset Repositories” for information on how to create a script.) The concept behind playback is to recreate the traffic you captured to your script using the Global Record tool. Entering information on these playback screens will generate batch JCL that can either be saved or submitted for execution.
1. On the Hiperstation for Mainframe Servers Main Menu, select option 8 Playback TCP/IP Scripts. The “TCP/IP Playback - Selection Screen” appears (Figure 8-1).
Figure 8-1. TCP/IP Playback - Selection Screen
------------------------ TCP/IP Playback - Selection ----------------------- Command ===> Primary commands: C)reate Playback, G)enerate Playback from Script Log Playback DSN : Line commands...: S)elect, P)lay or D)elete S Name Playback Description Date - -------- ------------------------------------------------------ ---------- USER2312 test playback 05/07/2010
2. Select what you want to do:
– Create a new Playback by filling in the relevant information on the screens that follow (see “Creating a New Interactive Playback” on page 8-2).
– Generate a Playback from a log dataset that was created in the script create job (see “Generating a Playback from a Script Log” on page 8-4). The script dataset and names will be extracted from the log allowing a playback to be instantly created for a particular log.
– Play back a previously saved script (see “Submitting Your Playback for Execution” on page 8-12).
– Delete a a previously saved Playback (see “Deleting a Playback” on page 8-14).
– Select a previously saved Playback to review (see “Selecting a Previously Saved Playback to Review” on page 8-14).
8-2 Hiperstation for Mainframe Servers User Guide
CAUTION:When you perform a Global Recording capture of DB2 Connect and make a script, you must use the same version of DB2 connect when you play back the script. If you use different versions of DB2 Connect for capture and playback, an error will occur.
Creating a New Interactive Playback1. On the “TCP/IP Playback - Selection Screen”, type C (create) on the command line
and press Enter. The “TCP/IP Playback - Datasets Screen” appears (Figure 8-2).
Figure 8-2. TCP/IP Playback - Datasets Screen
------------------------- TCP/IP Playback - Datasets ------------------------ Command ===> __________________________________________________________________ Script Dataset: Project . . . USER2312 Group . . . . TCPIP Type . . . . SCRIPT Other Partitioned Dataset: Dataset Name. . . . _______________________________________________________ Define more than one Script Dataset(/) Specify locations of playback outputs Reporting Database(optional) Generate Reporting Job ==> Dataset Name. . . . ________________________________________________________ Playback Error Log(if not SYSOUT=*): Dataset Name. . . . ________________________________________________________ Press ENTER to continue, END to cancel setup.
2. Enter the Script Dataset name of the script you want to play back. If your dataset name does not conform to ISPF naming standards, enter the dataset name, in single quotes, in the Other Partitioned Dataset field. Either Script Dataset or Other Partitioned Dataset is required.
a. To play back multiple script datasets, type a slash in the Define More than one Script Dataset field and press Enter. The “TCP/IP Script Dataset List Screen” will appear (Figure 8-3).
Figure 8-3. TCP/IP Script Dataset List Screen
-------------------------- TCP/IP Script Dataset List ------------------------- Command ===> Please supply the dataset(s) containing the scripts to be used in this playback. Additional Script Dataset Names: __________________________________________________________ __________________________________________________________ __________________________________________________________ __________________________________________________________ __________________________________________________________ __________________________________________________________ Enter End to return to the previous menu.
You can enter up to six script dataset names. If the first character is a single quote (‘), a fully qualified dataset name is expected. If the first character is not a single quote, then the user ID is attached as a prefix or high-level qualifier. After you
TCP/IP Interactive Playback 8-3
enter all of the desired dataset names, press Enter to return to the “TCP/IP Playback - Datasets Screen”. Continue with step 3.
b. If you will be playing back a single script, continue with step 3.
3. To report on the playback, enter a name for the Reporting Database. Data from the playback will be collected to this database and used in a future reporting job. This field is required only if you selected the Generate Reporting Job field. Selecting Generate Reporting Job provides reporting panels after the playback panels are completed.
4. The playback error log is a report that describes any errors that occurred during playback. If you leave this field blank, the report will go to SYSOUT=*. You can enter a dataset name or an hfs path to specify an alternate location.
5. Press Enter to continue. The “TCP/IP Playback - Script Member List Screen” will appear (Figure 8-4).
Figure 8-4. TCP/IP Playback - Script Member List Screen
MEMBER LIST -- USER2312.TCPIP.SCRIPT ---------------------- ROW 00001 OF 00002 COMMAND ===> SCROLL ===> PAGE END End and process selection CANcel End without processing Line Cmds: S Select member B Browse member Name Prompt Size Created Changed ID LOG00000 23 2007/07/27 2007/07/27 16:10:00 USER2312 SCR00000 1508 2007/07/27 2007/07/27 16:10:00 USER2312 **End**
6. Select a member from the list and use END to process your selection. The “TCP/IP Playback - Setup Screen” appears (Figure 8-5).
Figure 8-5. TCP/IP Playback - Setup Screen
------------------- TCP/IP Playback - Setup ---------------- Row 1 to 1 of 1 Command ===> Scroll ===> PAGE Enter script, and modify desired options using /. Type OK and press ENTER when ready. Note: Use multiple Sockets to test parallel connections to your application. Scripts under each Socket will run sequentially. Environment Options(apply to all Sockets except when overridden) Socket and script line commands are: (D)elete,(R)epeat,(A)dd,(/)Options S Socket S Script ** ******* ** ******** 1 SCR00000
7. The name of the member you selected on the previous screen is prefilled in the Script field. To add another script to play back, use the Add line command, and select another member from the list. All scripts for this playback must be contained within the dataset that you named on the “TCP/IP Playback - Datasets Screen”.
8. If you do not need to change any options, type OK on the Command line. The “TCP/IP Playback - Submit Screen” appears. See “Submitting Your Playback for Execution” on page 8-12 to submit your playback for processing.
If you need to change Environment, Socket, and/or Script options, see “Changing Playback Options” on page 8-5 for complete information. Then continue with
8-4 Hiperstation for Mainframe Servers User Guide
“Submitting Your Playback for Execution” on page 8-12 to submit your playback for processing.
Notes:
1. To explain the relationship between Sockets and Scripts, a Socket represents a single connection to your application. When there are multiple sockets in a playback, they run in parallel to each other, unless the socket start time is modified in the environment options. Within a socket, there are one or more scripts that run sequentially in the order they appear.
2. Lines commands can be applied to either the Socket or the Script. The Add, Repeat, and Delete line commands will add, repeat, or delete a socket. When applied to a script, they will add, repeat, or delete a script from that socket. When deleting, keep in mind that at least one script and socket are required for a playback.
Generating a Playback from a Script LogThe Generate command allows you to create a playback from a log dataset that was created in a script create job. The script dataset and names will be extracted from the log allowing a playback to be instantly created for a particular log.
1. On the “TCP/IP Playback - Selection Screen”, type G (generate) on the command line and press Enter. The “TCP/IP Playback - Log File Screen” appears (Figure 8-6).
Figure 8-6. TCP/IP Playback - Log File Screen
---------------------Generate TCP/IP Playback - Log File --------------------- Command ===> Enter log file member to generate playback: Log Dataset: Project . . . ________ Group . . . . ________ Type . . . . ________ Member . . . ________ (Blank or pattern for member selection list) Other Partitioned Dataset: Dataset Name. . . . ____________________________________________________ Press ENTER to continue, END to cancel setup.
2. Specify the log file you wish to use for playback. If you did not enter a member name when you specified the log dataset, a list of members will appear allowing you to select the desired member.
3. Type S next to the desired member and press Enter. The “TCP/IP Playback - Datasets Screen” appears. If your dataset name does not conform to ISPF naming standards, the name including the member name must be entered in the Other Partitioned Dataset Name field.
The remainder of the steps are the same as those you performed in “Creating a New Interactive Playback” on page 8-2. Continue with step 2 on page 8-2.
TCP/IP Interactive Playback 8-5
Changing Playback Options
Environment Options
Environment options are applied to the entire playback with the exception of certain parameters that can be overridden on the SOCKET or SCRIPT level. The current settings for the options are displayed next to each option category.
1. You can access the “Environment Options Screen” (Figure 8-7), by typing a slash next to the Environment Options field on the “TCP/IP Playback - Setup Screen” (Figure 8-5 on page 8-3).
Figure 8-7. Environment Options Screen
----------------------------- Environment Options ----------------------------- Command ===> Select the type of options to view/modify using / . _ Processing Options: Rexx Disabled, No live transactions executed Internal Hiperstation REXX variables OFF _ Timing Options: Play at Full Speed,Groups start simultaneously, Wait 15 seconds for I/O to complete _ Connection Options: Use Protocol From Script Use Server Port From Script Use Server Address From Script _ Data Replacement Options: Use Userid From Script Enter END command to return to the previous panel
This screen allows you to view or modify processing, timing, connection, and data replacement options.
2. Type a slash (/) next to the Processing Options field and press Enter. The “Environment - Processing Options Screen” appears (Figure 8-8).
Figure 8-8. Environment - Processing Options Screen
----------------------- Environment - Processing Options ---------------------- Command ===> Review current option settings and modify if required: Enable REXX to be used in TCP scripts? ==> _ Use internal Rexx Stream Variables? ==> _ Rexx Log Dataset name TCP Playback play as: Client ==> / Server ==> _ Do live I/O during playback? ==> _ Error Handling: Suppress Error Messages? ==> _ When error occurs: Continue playback ==> _ Stop connection ==> _ Stop script ==> _ Stop socket ==> _ Stop playback ==> _ Press ENTER to continue, END to exit
8-6 Hiperstation for Mainframe Servers User Guide
The options on this panel correspond to keywords that are placed in control cards for the playback JCL.
– Enable REXX to be used in TCP scripts? enables REXX to be used in scripts. The keyword is REXXON.
– Use Internal REXX stream variables? enables the use of the Enterprise Servers’ predefined REXX variables during playback. The variables return information about the playback and incorporate them into REXX logic that you add to your scripts to control the way the scripts play back. The keyword is SET REXX STREAM VARIABLES.
– Rexx Log Dataset name specifies the dataset name to be used for your log file.
– TCP Playback play as Client or Server tells the playback program to function as a client or server. The default is to function as a client, testing the server application.
– Do Live I/O during playback? permits Hiperstation to play back scripts without performing any I/O allowing you to generate reports for analyzing script content. The keyword is OFFLINE.
– Suppress Error Messages? suppresses warning and socket I/O error messages.
– When error occurs stops the playback at the level specified when an error occurs. The default is Continue playback. Choices include:
• Continue playback• Stop connection• Stop script• Stop Socket• Stop playback
After making your changes, enter END to return to the previous screen.
3. Type a slash (/) next to the Timing Options field and press Enter. The “Environment - Timing Options Screen” appears (Figure 8-9).
Figure 8-9. Environment - Timing Options Screen
------------------------- Environment - Timing Options ------------------------ Command ===> Review current option settings and modify if required: Use start times to control dispatching of each Socket? ==> _ Number of seconds to wait for I/O to complete before timing out ==> 15 Number of seconds to listen for connection attempt(server only) ==> __ Select an option for playback think time: 1 1 Play at full speed 2 Play at think time recorded on script 3 Play at user specified think time If you have selected options 2 or 3, you may alter the rate of the playback by altering the Think Time (For option 3 only) or the percentage. User Think Time (HH:MM:SS) . . ________ Percentage . . . . . . . . . . 100 Press ENTER to continue, END to exit
4. Use start times to control dispatching of each Socket? controls the playback initiation time for each socket statement supplied in the job. If USESTIME is specified, Hiperstation initiates playback of each socket relative to the start time values supplied in the socket statement. When this option is selected, Start Time for
TCP/IP Interactive Playback 8-7
each socket is displayed on the main setup panel. Enter a slash (/) to select this option.
5. Enter a Number of seconds to wait for I/O completion before timing out.
6. Enter a Number of seconds to listen for connection attempt (server only).
7. Select an option for playback think time:
– 1 Play at full speed — no think time.
– 2 Play at think time recorded in the script.
– 3 Play at user-specified think time.
8. If you selected option 2 or 3, you can change the User Think Time and/or Percentage if desired. User think time sets the amount of time to wait after receiving a server message before sending the next client message. Seconds is the only required value. Percentage is the percentage of think time to use for playback. With Option 2, it is the think time recorded in the script. With Option 3, it is the user-specified think time.
9. Press Enter to continue and return to the “Environment Options Screen”.
10. Type a slash (/) next to the Connection Options field and press Enter. The “Environment - Connection Options Screen” appears (Figure 8-10).
Figure 8-10. Environment - Connection Options Screen
----------------------- Environment - Connection Options ---------------------- Command ===> Review current option settings and modify if required: Protocol ==> _____ Server Port ==> ____ Server Address ==> _______________ Number of Connection Attempts before error ==> __ Pipelining - Send multiple client messages before receiving response ==> _ Press ENTER to continue, END to exit
11. Protocol — enter the desired protocol in this field.
12. Change the Server Port and Server Address if desired. These fields override the default server port and address for the playback.
13. Enter the number of times you want playback to try to connect to a server before giving an error message.
14. Select Pipelining if you want playback to send multiple client messages to the server before waiting for a response.
15. Press Enter to continue and return to the “Environment Options Screen”.
16. Type a slash (/) next to the Data Replacement Options field and press Enter. The “Environment - Data Replacement Options Screen” appears (Figure 8-11).
8-8 Hiperstation for Mainframe Servers User Guide
Figure 8-11. Environment - Data Replacement Options Screen
-------------------- Environment - Data Replacement Options ------------------- Command ===> Values entered on this screen will replace corresponding content data in the script. To encrypt password type it in the "password" field and press Enter. DB2C Userid ==> ________ Password ==> Confirm Password: IMSC Userid ==> ________ Password ==> Confirm Password: ECI Userid ==> __________ Password ==> Confirm Password: Press ENTER to continue, END to exit
On this screen you can replace data in the script during playback for the DB2C, IMSC, and ECI protocols.
17. Enter information you want to override the User ID and password in the DB2 Connect CONTENT. You must enter the password a second time for confirmation.
18. Enter information you want to override the User ID and password in the IMS Connect CONTENT. You must enter the password a second time for confirmation.
19. Enter information you want to override the User ID and password in the ECI Connect CONTENT. You must enter the password a second time for confirmation.
20. Press Enter to continue and return to the “Environment Options Screen”.
Socket Options1. Type a slash (/) next to the desired Socket on the “TCP/IP Playback - Setup Screen”
and press Enter. The “Socket Options Screen” appears (Figure 8-12).
Figure 8-12. Socket Options Screen
------------------------------ Socket 1 Options ----------------------------- Command ===> Select the type of options to view/modify using / . To copy options to all Sockets in playback, type save all from any Socket options panel . _ Processing Options: Repeat(1),Count(1) _ Timing Options: No start delay _ Connection Options: Use Protocol From Script Use Server Port From Script Use Server Address From Script _ Data Replacement Options: Use Userid From Script Enter END command to return to the previous panel
From this screen, you can choose to change Processing, Timing, Connection, and Data Replacement options for the selected socket.
2. Type a slash (/) next to the Processing Options field and press Enter. The “Socket - Processing Options Screen” appears (Figure 8-13).
TCP/IP Interactive Playback 8-9
Figure 8-13. Socket - Processing Options Screen
----------------------- Socket 1 - Processing Options ----------------------- Command ===> Review current option settings and modify if required: Number of Repeats ==> 1__ Number of instances of this Socket ==> 1__ Error Handling: Suppress Error Messages ==> _ When error occurs: Continue playback ==> _ Stop connection ==> _ Stop script ==> _ Stop socket ==> _ Stop playback ==> _ Press ENTER to continue, END to exit
3. Enter the number of times to repeat playback of scripts in the Socket and the number of instances of this Socket to play back concurrently.
4. Suppress Error Messages suppresses warning and socket I/O error messages.
5. When error occurs stops the playback at the level specified when an error occurs. The default is Continue playback. Choices include:
• Continue playback• Stop connection• Stop script• Stop Socket• Stop playback
6. After making your changes, enter END to return to the “Socket Options Screen”.
7. Type a slash (/) next to the Timing Options field and press Enter. The “Socket Timing Options Screen” appears (Figure 8-14).
Figure 8-14. Socket Timing Options Screen
------------------------- Socket 001 - Timing Options ------------------------- Command ===> Review current option settings and modify if required: Number of seconds to delay start of this Socket ==> 0__ Press ENTER to continue, END to exit
8. Enter a number of seconds to delay the start of this Socket. This tells playback how long to wait between the start of a socket and commencement of playback.
9. Type a slash (/) next to the Connection Options field and press Enter. The “Socket - Connection Options Screen” appears (Figure 8-15).
8-10 Hiperstation for Mainframe Servers User Guide
Figure 8-15. Socket - Connection Options Screen
TCPGRPC --------------- Socket 1 - Connection Options ----------------------- Command ===> _____________________________________________ Review current option settings and modify if required: Protocol ==> _____ New Server Port ==> _____ New Server Address ==> Number of Connection Attempts before error ==> __ Send multiple client messages(pipelining) ==> _ Press ENTER to continue, END to exit
10. Protocol — enter the desired protocol in this field.
11. Change the Server Port and Server Address if desired. These fields override the default server port and address for the playback.
12. Enter the number of times you want playback to try to connect to a server before giving an error message.
13. Select Pipelining if you want playback to send multiple client messages to the server before waiting for a response.
14. Press Enter to continue and return to the “Socket Options Screen”.
15. Type a slash (/) next to the Data Replacement Options field and press Enter. The “Socket - Data Replacement Options Screen” appears (Figure 8-16).
Figure 8-16. Socket - Data Replacement Options Screen
-------------------- Socket 1 - Data Replacement Options -------------------- Command ===> _____________________________________________ Values entered on this screen will replace corresponding content data in the script. To encrypt password type it in the "password" field and press Enter. DB2C Userid ==> ________ Password ==> Confirm Password: Rdbname ==> ________________ IMSC Userid ==> ________ Password ==> Confirm Password: Datastore ==> ________ TranCode ==> __________ ECI Userid ==> __________ Password ==> Confirm Password: CTG Applid ==> __________ Progid ==> __________ Press ENTER to continue, END to exit
16. Enter information you want to override the User ID, password, and Rdbname in the DB2 Connect CONTENT.
17. Enter information you want to override the User ID, password, Datastore, and TranCode in the IMS Connect CONTENT.
TCP/IP Interactive Playback 8-11
18. Enter information you want to override the User ID and password in the ECI Connect CONTENT.
19. Enter information you want to override the application ID and program ID in the CTG CONTENT.
20. Press Enter to continue and return to the “Socket Options Screen”.
Script Options1. Type a slash (/) next to the desired Script on the “TCP/IP Playback - Setup Screen”
and press Enter. The “Script Socket Options Screen” appears (Figure 8-17).
Figure 8-17. Script Socket Options Screen
-------------------- Script SCR00000 Socket 1 Options ------------------- Command ===> Select the type of options to view/modify using / . To copy options to all scripts in playback, type save all from any Script options panel. _ Processing Options: Repeat(1) _ Connection Options: Use Protocol From Script Use Server Port From Script Use Server Address From Script Enter END command to return to the previous panel
On this screen, you can choose to modify Processing and Connection options for the selected script.
2. Type a slash (/) next to the Processing Options field and press Enter. The “Script Processing Options Screen” appears (Figure 8-18).
Figure 8-18. Script Processing Options Screen
--------------------- Script SCR00000 Processing Options -------------------- Command ===> Review current option settings and modify if required: Number of Repeats ==> 1___ Press ENTER to continue, END to exit
3. Specify the number of times to repeat playback of the selected scrip.
4. Press Enter to continue and return to the “Script Socket Options Screen”.
5. Type a slash (/) next to the Connection Options field and press Enter. The “Script Connection Options Screen” appears (Figure 8-19).
8-12 Hiperstation for Mainframe Servers User Guide
Figure 8-19. Script Connection Options Screen
TCPSCRC ------------- Script Connection Options --------------------- Command ===> Review current option settings and modify if required: Protocol ==> _____ New Server Port ==> ____ New Server Address ==> _______________ Press ENTER to continue, END to exit
6. To override the protocol, server port and/or address, enter your changes in the appropriate field.
7. Press Enter to continue and return to the “Script Socket Options Screen”.
8. After you have completed your modifications to the options, enter END to return to the “TCP/IP Playback - Setup Screen”.
9. Type OK on the command line and press Enter. The “TCP/IP Playback - Submit Screen” appears. Continue with the next section, “Submitting Your Playback for Execution”.
Submitting Your Playback for ExecutionAfter creating your playback script, the “TCP/IP Playback - Submit Screen” appears (Figure 8-20).
Figure 8-20. TCP/IP Playback - Submit Screen
--------------------- TCP/IP Playback - Submit -------------------------------- Command ===> Select a processing option, or type SAVE on the command line to save playback JCL to a dataset. Select an option: _ 1. Submit batch job 2. Edit batch job 3. Save playback X. Exit Job statement information for batch job: ===> //JOBNAME JOB (ACCOUNT),'NAME' ===> //* ===> //* ===> //*
On this screen, you can submit, edit, or save a batch job, save your playback, and exit playback submission.
1. To save your playback JCL to a dataset, type SAVE on the command line. The “TCP/IP Playback - Save JCL File Screen” appears (Figure 8-21).
TCP/IP Interactive Playback 8-13
Figure 8-21. TCP/IP Playback - Save JCL File Screen
Hiperstation ---------- TCP/IP Playback - Save JCL File ---------------------- Command ===> Enter the name of the dataset where JCL will be saved, then press ENTER to continue. Playback JCL dataset: Project . . . ________ Group . . . . ________ Type . . . . ________ Member . . . ________ Other Data Set Name: _______________________________________________________ Data Set Name . . . Save JCL Options: (Enter "/" to select) _ Replace existing members
This will save all of the parameters you have selected on the previous screens to your Hiperstation profile.
2. Enter a JCL dataset name. If your name does not conform to ISPF naming standards, enter the name in the Other Data Set Name field. The JCL file must be a partitioned dataset (PDS) or sequential file with variable blocked (VB) or fixed blocked (FB) record format. The record length must be at least 72.
3. Press Enter to save your JCL file and return to the “TCP/IP Playback - Submit Screen”. If your dataset does not already exist, an “Allocate JCL File Screen” will appear. Press Enter to allocate the dataset.
4. Select an option:
– Option X exits the “TCP/IP Playback - Submit Screen” without submitting the playback.
– Option 1 submits a batch job that creates your scripts.
– Option 2 puts you in an ISPF edit session for the JCL that can be submitted to create your scripts. To create scripts, you must enter the “SUBMIT” primary command from within the edit session. After finishing your edits, enter the END command to return to the “TCP/IP Playback - Submit Screen”.
Note: If you select option 1 or 2, you need to enter job card information into the Job statement information for batch job.
– Option 3 allows you to save your playback. The “TCP/IP Playback - Save Screen” appears (Figure 8-22).
8-14 Hiperstation for Mainframe Servers User Guide
Figure 8-22. TCP/IP Playback - Save Screen
-------------------------- TCP/IP Playback - Save --------------------------- Command ===> __________________________________________________________________ Playback Name . PBTCPIP_ Description . . TCP/IP playback___________________________________________ Save Playback Dataset: Dataset Name. . USER2312.TCPIP.PLAYBACK’_____________________________________ Press ENTER to continue, END to cancel save.
5. Enter a name and optional description for the Playback and a playback dataset name. Then press Enter to save your Playback and press END to return to the “TCP/IP Playback - Submit Screen”.
6. Press Enter to execute the option you selected on the “TCP/IP Playback - Submit Screen”. A message appears stating that your job was submitted.
Selecting a Previously Saved Playback to Review1. On the “TCP/IP Playback - Selection Screen”, type S (select) next to the playback you
want to select and press Enter. The “TCP/IP Playback - Datasets Screen” appears.
This will load a previously created playback. You can make changes and resave it using the same or another name.
2. Continue pressing Enter to view the next screen.
3. When finished, you can run your playback or press END to return to the Hiperstation for Mainframe Servers main menu.
Deleting a Playback1. On the “TCP/IP Playback - Selection Screen”, type D (delete) next to the playback
you want to delete from the list and press Enter. The “Delete Confirmation Screen” appears
2. Accept the default Y and press enter to delete your playback. Change the default to N to keep the playback.
Generating Playback Reports1. On the Hiperstation for Mainframe Servers Main Menu, select option 9 TCP/IP
Playback Reporting. The “TCP/IP Playback - Selection Screen” appears (Figure 8-23).
TCP/IP Interactive Playback 8-15
Figure 8-23. TCP/IP Reporting - Selection Screen
----------------------- TCP/IP Reporting - Selection ----------------------- Command ===> __________________________________________________________________ Enter a database name , or select a database from the playback list below. Dataset Name. . . . ‘USER2312.PLAYBACK.REPORT_________________________________ Playback DSN : ‘USER2312.TCPIP.PLAYBACK’ Line commands...: S)elect or D)elete S Name Database Name - -------- ------------------------------------------------------ TEST1 USER2312.REPORT.DATABASE
2. On this screen, select the desired report from the list, or type a dataset name within single quotes in the Dataset Name field and press Enter. The “TCP/IP Reporting Screen” appears (Figure 8-24).
Figure 8-24. TCP/IP Reporting Screen
------------------------------- TCP/IP Reporting ------------------------------ Command ===> Select the type of report you wish to generate using / . _ Basic Reports: Fixed format reports include HTML Exception, Script Timing and Response Time Summary _ Custom Reports: Select member below that contains reporting process Project . . . ________ Group . . . . ________ Type . . . . ________ Member . . . ________ Other Partitioned Dataset: Dataset Name. . . . _____________________________________________________ Type END command to return to the previous panel, ENTER to continue
3. Specify whether to generate basic or custom reports and press Enter.
– Basic reports include the response time summary, exception, and script timing reports.
– Custom Reports are reports that your site has created that contain REPORT statements to be used in the report job. When you make this selection, you must enter a dataset name in the Other Partitioned Dataset field. Use a member from a dataset that contains report statements to be used in the report job.
4. Continue with the next section, “TCP/IP - Basic Reports” or “TCP/IP - Custom Reports” on page 8-16.
TCP/IP - Basic Reports1. You will have accessed this screen by typing a slash (/) next to the Basic Reports field
on the “TCP/IP Reporting Screen” (Figure 8-24) and pressing Enter. The “TCP/IP - Basic Reports Screen” appears (Figure 8-25).
8-16 Hiperstation for Mainframe Servers User Guide
Figure 8-25. TCP/IP - Basic Reports Screen
---------------------------- TCP/IP - Basic Reports --------------------------- Command ===> _______________________________________________________________ Select a report(s) to generate using / and enter location. _ HTML Exception Report (hfs path required): __________________________________________________________________________ __________________________________________________________________________ Optional Parameters: Number of mismatches to display before stopping ==> ___ Masking DSN __________________________________________________________ Compare to baseline database ==> _ Baseline DSN __________________________________________________________ _ Script Timing Summary (hfs path, DSN, or leave blank for SYSOUT=*): __________________________________________________________________________ __________________________________________________________________________ _ Response Time Summary (hfs path, DSN, or leave blank for SYSOUT=*): __________________________________________________________________________ __________________________________________________________________________ Enter END command to return to the previous panel
On this screen, you can specify the locations of the basic reports that you want to generate. If you specify a location for a type of report, that type of report will be generated. You can generate multiple report types in the same reporting job. The types of reports available include:
– HTML Exception Report: A standard exception report that compares actual response messages to expected response messages from a single data collection. You must specify an hfs path. (Example: u/compware/user/excp.htm.)
• If desired, specify the number of mismatches to display before ending report generation.
• You can use data masking to prevent comparison of specific data. Store your masking statements in a sequential dataset or PDS member.
• To perform a baseline comparison, type a slash (/) in the Compare to baseline database field and enter the name of the baseline dataset you wish to compare.
– Script Timing Summary: A standard report that reports the time it took for each script to play back. It also provides additional timing statistics for the play back job. (Example: u/compware/user/scrp.htm.)
– Response Time Summary: A standard report that reports the amount of time it took each group of related messages to occur. For example, this includes the time that elapsed from the first byte of the request to the last byte of the response. (Example: u/compware/user/resp.htm.)
TCP/IP - Custom Reports
Custom reports allow you to use a member from a dataset that contains REPORT statements that will be used in the report job.
1. On the “TCP/IP Reporting Screen” (Figure 8-24 on page 8-15), type a slash (/) next to the Custom Reports field, enter a dataset name and member and press Enter. The “Custom Report Parameters Screen” appears (Figure 8-26).
TCP/IP Interactive Playback 8-17
Figure 8-26. Custom Report Parameters Screen
--------------------------- Custom Report Parameters -------------------------- Command ===> _____________________________________________ Report Layout: Table(columns) ==> _ Form(rows) ==> _ Type: Text ==> _ Html ==> _ CSV ==> _ Number of lines to print in a field before truncating data ==> ____ Maximum Number of Lines to print on a page(30-9999) ==> ____ Break(only applicable to form reports) _ EJECT begin each record on a new page _ NEXT continue reporting on next line Type END command to return to the previous panel, ENTER to continue
2. Report Layout
3. Select the desired Report Layout. Table is the default.
– Select Table to produce a row/column-oriented report. Figure 8-27 shows a Table report layout.
Figure 8-27. Table Report Layout
Hiperstation for Mainframe Servers - Message Report Date: 07/28/06 07:48 Page: 1 --------------------------------------------------------------------------------------- MessageID SocketsNumber MessageStartTime MessageFinishTime --------------------------------------------------------------------------------------- 4 1 2006/07/21_15:10:37.290 2006/07/21_15:10:38.052 6 1 2006/07/21_15:10:39.409 2006/07/21_15:10:39.938 9 1 2006/07/21_15:10:40.913 2006/07/21_15:10:42.170 ******************************** BOTTOM OF DATA ***************************************
– Select Form to produce a line-based report. Figure 8-28 shows a Form report layout.
8-18 Hiperstation for Mainframe Servers User Guide
Figure 8-28. Form Report Layout
Hiperstation for Mainframe Servers - Message Report Date: 07/28/06 07:48 Page: 1 --------------------------------------------------------------------------------------- MessageID 4 --------------------------------------------------------------------------------------- SocketsNumber 1 --------------------------------------------------------------------------------------- MessageStartTime 2010/07/21_15:10:37.290 --------------------------------------------------------------------------------------- MessageFinishTime 2010/07/21_15:10:38.052 --------------------------------------------------------------------------------------- Hiperstation for Mainframe Servers - Message Report Date: 07/28/06 07:48 Page: 2 --------------------------------------------------------------------------------------- MessageID 6 --------------------------------------------------------------------------------------- SocketsNumber 1 --------------------------------------------------------------------------------------- MessageStartTime 2010/07/21_15:10:39.409 --------------------------------------------------------------------------------------- MessageFinishTime 2010/07/21_15:10:39.938 --------------------------------------------------------------------------------------- Hiperstation for Mainframe Servers - Message Report Date: 07/28/06 07:48 Page: 3 --------------------------------------------------------------------------------------- MessageID 9 --------------------------------------------------------------------------------------- SocketsNumber 1 --------------------------------------------------------------------------------------- MessageStartTime 2010/07/21_15:10:40.913 --------------------------------------------------------------------------------------- MessageFinishTime 2010/07/21_15:10:42.170 ---------------------------------------------------------------------------------------
4. Select the type of report you want to produce. Choices include: Text (default), HTML, and CSV.
5. Enter a number of lines to print in a field before truncating data. This applies only to Text and CSV reports and allows you to truncate the printing of large fields that may contain up to two gigabytes of data.
6. Enter the maximum number of lines to print on a page. Enter between 30 and 9999. This applies only to Text reports. The default is 60.
7. If you are using form reports in a Text or HTML format, select EJECT to begin each record on a new page or NEXT to continue the report on the next line. EJECT is the default.
8. Press Enter to continue. The “Custom Report Locations Screen” appears (Figure 8-29).
Figure 8-29. Custom Report Locations Screen
--------------------------- Custom Report Locations --------------------------- Command ===> Enter a location for the table(s) you are reporting on, if different than SYSOUT=*. The tables used by each report correspond to the INTO parameter. Playback _______________________________________________________________ _______________________________________________________________ Sockets _______________________________________________________________ _______________________________________________________________ Script _______________________________________________________________ _______________________________________________________________ Connection _______________________________________________________________ _______________________________________________________________ Message _______________________________________________________________ _______________________________________________________________ Type END command to return to the previous panel, ENTER to continue
TCP/IP Interactive Playback 8-19
9. If the tables you are reporting on are not located in SYSOUT=*, then specify the table locations.
Note: Use unique report locations. If you specify the same dataset location for more than one report, the last report will be the only one shown because the previous ones will be overwritten.
10. Press Enter to continue. “TCP/IP Playback - Submit Screen” appears (Figure 8-20 on page 8-12).
Note: You submit your playback report for execution in the same way you submitted your playback for execution. See “Submitting Your Playback for Execution” on page 8-12 for information on submitting and saving your playback report.
8-20 Hiperstation for Mainframe Servers User Guide
9-1
Chapter 9.
9TCP/IP Unattended Playback Chap 9Play back your scripts to test your TCP/IP applications. During playback, Hiperstation for Mainframe Servers executes the activity that is identified as CLIENT in the script. If you collect the appropriate playback information, you can generate reports that compare the server activity resulting from playback (actual) to the server activity recorded in the script (expected).
Unattended Playback is a batch-driven function that requires control statements. Write the statements from scratch, or save time by editing the Connection Log that is optionally generated during script creation. After the statements are prepared, customize the provided JCL sample and submit the job. Unattended Playback automatically generates a text-based Error Summary report to help you troubleshoot playback issues. You can also generate an interactive HTML version of the report if your installer enabled web reporting.
Creating Playback Control StatementsEach playback control statement you write can be used for client testing or server testing. TCP/IP Unattended Playback control statements include:
• CONTROL — Provides playback control information for all scripts in the job.
• SOCKETS — Provides playback control information for a group of scripts.
• SCRIPT — Provides playback control information for a specific script.
• COLLECT — Defines the playback information to collect for reporting for server testing only.
Playback requires one SCRIPT statement for each script and at least one SOCKETS statement. By default, all SOCKETS play back simultaneously and the SCRIPTS listed under a SOCKETS statement play back consecutively. This supports playing back groups of related scripts in parallel. For example, to simulate two users performing different activity at the same time, construct the statements as follows:
CONTROL SOCKETS SCRIPT(SCRPT1) SCRIPT(SCRPT2) SOCKETS SCRIPT(SCRPT4) COLLECT (*) FROM (PLAYBACK) COLLECT (*) FROM (MESSAGE)
Be mindful of transaction interdependence when building multiple SOCKETS statements. For example, two scripts contain transactions that access the same customer record. If each script appears under a different SOCKETS statement, one of the transactions may fail during playback because the customer record is in use by the other transaction.
Playback control statements provide parameters for controlling all aspects of playback including overriding the connection information in the scripts. Specify a server IP address or port on one of the playback control statements to play back scripts in an environment other than the one they were captured in. For example, regression testing may require playing back activity in a test environment that was captured in a production environment. If you do not specify connection parameters on any of the
9-2 Hiperstation for Mainframe Servers User Guide
playback statements, Hiperstation uses the information found on the <CONNECT> tag in the script.
Consider statement hierarchy when defining your playback control statements. The CONTROL, SOCKETS, and SCRIPT statements offer many of the same parameters. If a parameter is defined on more than one statement, the parameter on the lowest-level statement takes precedence. For example, the following statements result in SCRPT1 and SCRPT2 using server address 10.10.0.200, while SCRPT3 uses 0.0.0.0.
CONTROL SOCKETS SERVER_ADDRESS(10.10.0.200) SCRIPT(SCRPT1) SCRIPT(SCRPT2) SCRIPT(SCRPT3) SERVER_ADDRESS (0.0.0.0)
Although you can write Unattended Playback statements from scratch, it is typically faster and easier to modify the Connection Log (Figure 9-1) that is optionally generated during script creation. The log contains one SOCKETS and one SCRIPT statement for each script created. Each SOCKETS statement always includes an:
• ID parameter that provides a value for correlating entries on performance and comparison reports with the associated SOCKETS statements.
• STIME parameter that states the start time and date of the first connection in the script.
The rest of the SOCKETS statement parameters vary depending on the contents of the script. If a connection attribute is the same for all connections in the script, the attribute is written into the SOCKETS statement as a parameter. For example, if all connections use the same protocol, the SOCKETS statement includes the PROTOCOL parameter. The parameters are written into the statements as comments so you can review and easily override their values. Remove the comment indicator — the asterisk (*) at the beginning of the line — for all modified parameters that you require for playback.
Figure 9-1. Sample TCP/IP Connection Log
************************************************************************ * * * HIPERSTATION TCP/IP LOG STARTED ON 2008/01/15 AT 20:16:57 * * * * DESC: * * GROUP: (2) Connection * * * * FILTERS: PROTOCOL CLIENT ADDRESS PORT SERVER ADDRESS PORT * * -------- --------------- ----- --------------- ----- * * HTTP *.*.*.* * *.*.*.* 80 * * HTTPS *.*.*.* * *.*.*.* 443 * * TCP *.*.*.* * *.*.*.* * * * * * REPOSITORY NAME: VP.AT.TCPSC.S70156B.INPUT.REPOS.P??? * * REPOSITORY NUMS: 1:8 * * LOG . . . . . : VP.AT.TCPSC.S72036E.OUTPUT.LOG * * SCRIPT . . . . : VP.AT.TCPSC.S72036E.OUTPUT.SCRIPT * * CLIENT DETAIL : VP.AT.TCPSC.S72036E.OUTPUT.DETAIL * * SERVER DETAIL : VP.AT.TCPSC.S72036E.OUTPUT.DETAIL * * * ************************************************************************ * * SCRIPT NUMBER(1) * SOCKETS- ID(1)- * PROTOCOL(HTTP)- * CLIENT_ADDRESS('10.15.16.120')- * CLIENT_PORT(4791)- * SERVER_ADDRESS('10.10.0.200')- * SERVER_PORT(80)- STIME('2006/07/10_16:05:34.541335') SCRIPT(SCR00000) *
TCP/IP Unattended Playback 9-3
Note: The Create TCP/IP Script option allows you to generate a log independent of script creation. However, the script names appear as question marks (???). Replace the question marks with the correct script member names.
• Add a CONTROL statement before the first SOCKETS statement to define job-level attributes. For example, insert a CONTROL statement with the REXXON attribute to enable the use of REXX in all of the scripts in the job.
• Add or remove SOCKETS statements to achieve the script grouping required for your testing needs.
• Add, remove, or modify the parameters on the generated statements to meet your testing needs.
• Add COLLECT statements to define the reporting information to collect during playback for server testing.
Define Statements for Server Testing
This section provides a syntax diagram for each playback control statement written for server testing. If you are unfamiliar with syntax diagrams, see “Reading Syntax Diagrams” on page xxi. Parameter definitions follow the diagrams.
CONTROL Statement
You can use the CONTROL statement to provide job-level playback parameters and connection attribute overrides. If you include a CONTROL statement, place it before the first SOCKETS statement.
The following syntax diagram shows all of the available CONTROL statement parameters.
9-4 Hiperstation for Mainframe Servers User Guide
CACHE|CACHEOFF
CACHE instructs Hiperstation to store scripts in memory during playback to improve performance. CACHEOFF disables script caching and is the default.
Note: Script caching is required if you specify REPEAT on the SOCKETS or SCRIPT statements. If you specify CACHEOFF and provide a REPEAT value, Hiperstation produces an error and terminates playback with return code 8.
CONNECTION_ATTEMPTS(1|count)
The number of times Hiperstation tries to connect to a partner. If the connection is not made after the specified number of attempts, Hiperstation will perform the action specified on the ERROR_ACTION parameter.
TCP/IP Unattended Playback 9-5
DB2_USERID(‘user_ID’)
Overrides the user ID in the DB2 Connect CONTENT. The quotes are required.
DB2_PASS(‘password’)|DB2_NPASS(‘encrypted_password’)
Overrides the password in the DB2 Connect CONTENT. The password must be a plain text password or a password using Hiperstation encryption. The quotes are required.
ECI_USERID(‘user_ID’)
Overrides the user ID in the ECI CONTENT. The quotes are required.
ECI_PASS(‘password’)|ECI_NPASS(‘encrypted_password’)
Overrides the password in the ECI CONTENT. The password must be a plain text password or a password using Hiperstation encryption. The quotes are required.
ERROR_ACTION(MESSAGE|NOMESSAGE,STOP_CONNECTION|STOP_SCRIPT| STOP_SOCKETS|STOP_PLAYBACK|RETRY)
Specifies which messages Hiperstation produces and the action it takes when a socket I/O error occurs (including connection failures, lost connections, and read/write failures). Options are:
MESSAGE
Print warning and socket I/O error messages.
NOMESSAGE
Suppress warning and socket I/O error messages.
STOP_CONNECTION
Stop the playback on the connection that the error occurred on. Continue the playback on the other connections in the script.
STOP_SCRIPT
Stop the playback of the script.
STOP_SOCKETS
Stop the playback under the SOCKETS statement. When COUNT(x) is included on the SOCKETS statement, all x of the playbacks are stopped when a socket I/O occurs.
STOP_PLAYBACK
Stop the playback.
RETRY
Retry playing back the script.
IMS_USERID(‘user_ID’)
Overrides the user ID in the IMS Connect CONTENT. The quotes are required.
IMS_PASS(‘password’)|IMS_NPASS(‘encrypted_password’)
Overrides the password in the IMS Connect CONTENT. The password must be a plain text password or a password using VTAM Dark Field encryption. The quotes are required.
OFFLINE
Plays back scripts without connecting to the partner or performing any I/O. This allows you to generate reports for analyzing script content. Be sure to include COLLECT statements in the JCL.
9-6 Hiperstation for Mainframe Servers User Guide
OWNERNAME(owner_name)
Provides reporting information. The OWNERNAME (OWNA) field on the playback reports displays the information specified on this keyword. Enter up to 256 characters.
PLAY(CLIENT)
Tells the playback program to function as a client.
PLAYBACKNAME(playback_name)
Provides reporting information. The PLAYBACKNAME (PLNA) field on the playback reports displays the information specified on this keyword. Enter up to 256 characters.
PROTOCOL(CTG|DB2C|ECI|HTTP|HTTPS|IMSC|TCP)
Identifies the protocol used to play back the scripts in the given job. Use this parameter to override the protocol identified on the <CONNECT> tag in the script. Valid values are CTG, DB2C, ECI, HTTP, HTTPS, IMSC, and TCP.
Note: Protocol overrides are typically unnecessary. This value initiates the appropriate message handler. If it is inaccurate, playback may fail.
REXXOFF|REXXON
Enables or disables support for REXX logic in the scripts. If your scripts contain REXX logic, specify REXXON.
RLOG(*|destination)
Specifies where to write the output from REXX SAY statements added to your scripts. Supply a single-character sysout class, a PDSE and member, or a sequential dataset.
Generate a separate dataset or PDSE member for each thread of replay by including wildcard characters in the dataset or member name. Valid wildcard characters include:
– Asterisk (*) — Playback replaces the asterisk with a four-digit value representing the current replay value padded with leading zeros. For example, RLOG(MRRLOG.RPLY*) generates MYRLOG.RPLY0001, MYRLOG.RPLY0002, etc. Playback allows one asterisk per dataset name qualifier or member name, in any position except the first character.
– Question mark (?) — Playback replaces a string of one or more question marks with the current replay value. For example, RLOG(MYRLOG.RPLY??) generates MYRLOG.RPLY01, MYRLOG.RPLY02, etc. Include at least one question mark for each digit of the maximum replay value. For example, if the replay value will reach 20, insert at least two consecutive question marks. Playback truncates the replay value or pads it with leading zeros if there are more or fewer question marks than the number of digits in the replay value. Playback allows up to seven consecutive question marks per dataset name qualifier or member name, in any position except the first character.
Note: Replay values are based on the number of SOCKETS statements and their COUNT values. For example, two SOCKETS statements, each bearing a COUNT(3), results in six replay values.
If you specify a dataset or PDSE member that does not exist, Hiperstation allocates it with default values. To override default allocation values, add an RLOG DD statement to the playback JCL. For example:
//RLOGDD DD DUMMY,SPACE=(TRK,(15,15,15)),DSNTYPE=LIBRARY, // DCB=(LRECL=121,BLKSIZE=12100,RECFM=FB)
TCP/IP Unattended Playback 9-7
SET_REXX_STREAM_VARIABLES(NO|YES)
Enables the use of the Hiperstation predefined REXX variables during playback. The variables return information about the playback. Incorporate them into REXX logic that you add to your scripts to control the way the scripts play back. For example, use them to dynamically replace data in the script during playback. See “Hiperstation for Mainframe Servers REXX Variables” on page 7-35. Since this is not necessary for replay, the default value for this parameter is NO.
STDWAIT(15|hh:mm:ss.nnn)
The longest time that Hiperstation waits for I/O completion. If no I/O finishes in the STDWAIT interval, all outstanding I/O is canceled for that specific script. Hiperstation retries the connections up to the number of attempts set in the CONNECTION_ATTEMPTS parameter and retries any other I/O twice. If still unsuccessful after all attempts are made to complete the I/O, Hiperstation takes the action set on the ERROR_ACTION parameter.
If you do not include the STDWAIT parameter, Hiperstation uses the default value of 15 seconds.
THINK(0|hh:mm:ss.nnn)
Sets the amount of think time to wait after receiving a server message before sending the next client message. This keyword accepts hours, minutes, and seconds separated by colons (:) — HH:MM:SS. However, seconds is the only required value and you can specify fractions of a second by providing a decimal value. For example, THINK(1) is one second of think time. THINK(10:14.5) is ten minutes, fourteen and a half seconds of think time.
This keyword is only available if THOPT3 is specified. If you do not supply this keyword when using think option three, playback does not wait.
THOPT(1|2|3)
Specifies which option to use for simulating think time. Specify a value of:
– 1 to play back at full speed.
– 2 to play back using the think time recorded in the script. Think time is simulated based on the differences between the values of the <TIME> tags in the script. Include the THPCT keyword to stipulate a percentage of recorded think time. For example, THOPT(2) THPCT(50) causes playback to use half of the difference between the <TIME> tags in the script.
– 3 to play back using an arbitrary value that is specified with the THINK and THPCT keywords. For example, THOPT(3) THINK(5) causes playback to wait five seconds after receiving a server response before sending the next client message.
THPCT(100|percent)
Specifies the percentage of think time to use for playback. This parameter applies to think time options THOPT(2) and THOPT(3). It works differently depending on the selected option. If you specify:
– THOPT(2), THPCT is the percentage of the think time recorded in the script.
– THOPT(3), THPCT is the percentage of the value specified on the THINK keyword. For example, THOPT(3) THINK(10:3) THPCT(50) results in five minutes, one and a half seconds of think time.
If you do not supply the THPCT keyword, playback uses the default value of 100%.
TRACE(sysout_class|dataset)
Produces diagnostic information regarding Hiperstation internal behavior. Contact Compuware Customer Support prior to using this option.
Use TRACE to specify the location for the output. Supply a single-character sysout class, a PDSE and member, or a sequential dataset.
9-8 Hiperstation for Mainframe Servers User Guide
Generate a separate dataset or PDSE member for each thread of replay by including wildcard characters in the dataset or member name. Valid wildcard characters include:
– Asterisk (*) — Playback replaces the asterisk with a four-digit value representing the current replay value padded with leading zeros. For example, TRACE(MYTRACE.RPLY*) generates MYTRACE.RPLY0001, MYTRACE.RPLY0002, etc. Playback allows one asterisk per dataset name qualifier or member name in any position except the first character.
– Question mark (?) — Playback replaces a string of one or more question marks with the current replay value. For example, TRACE(MYTRACE.RPLY??) generates MYTRACE.RPLY01, MYTRACE.RPLY02, etc. Include at least one question mark for each digit of the maximum replay value. For example, if the replay value will reach 20, insert at least two consecutive question marks. Playback truncates the replay value or pads it with leading zeros if there are more or fewer question marks than the number of digits in the replay value. Playback allows up to seven consecutive question marks per dataset name qualifier or member name, in any position except the first character.
Note: Replay values are based on the number of SOCKETS statements and their COUNT values. For example, two SOCKETS statements, each bearing a COUNT(3), results in six replay values.
If you specify a dataset or PDSE member that does not exist, Hiperstation allocates it with default values. To override default allocation values, add a TRACE DD statement to the playback JCL. For example:
//TRACEDD DD DUMMY,SPACE=(TRK,(15,15,15)),DSNTYPE=LIBRARY, // DCB=(LRECL=121,BLKSIZE=12100,RECFM=FB)
USE_PIPELINING(NO|YES)
Enables support of message pipelining for playback of DB2C, ECI, and IMSC scripts. USE_PIPELINING(YES) causes playback to send multiple messages to the server before receiving responses. NO is the default value.
USE_HTTP_PIPELINING(NO|YES)
Enables support of message pipelining for playback of HTTP and HTTPS scripts. USE_HTTP_PIPELINING(YES) causes playback to send multiple messages to the server before receiving responses. NO is the default value.
USESTIME
Provides control of playback initiation time for each SOCKETS statement supplied in the job. If USESTIME is specified, Hiperstation initiates playback of each SOCKETS relative to the STIME values supplied on the SOCKETS statements. For example, the following STIME values result in the second SOCKETS playing back five minutes after the first.
SOCKETS STIME (‘2006/07/10=10:10:10.000000’) SOCKETS STIME (‘2006/07/10=10:15:10.000000’)
Note: If the STIME keyword is not defined on the SOCKETS statement, playback uses the first STIME in the script.
If USESTIME is not specified, Hiperstation initiates playback of all SOCKETS simultaneously.
SOCKETS Statement
You can use the SOCKETS statement to define a group of scripts to play back and to provide playback parameters for that group. Place the applicable SCRIPT statements under each SOCKETS statement in the order that they should be played back. Place the
TCP/IP Unattended Playback 9-9
SOCKETS statements after the CONTROL statement. For more information regarding statement hierarchy, see “Creating Playback Control Statements” on page 9-1.
The following syntax diagram shows all of the available SOCKETS statement parameters. Parameter definitions follow the diagram.
9-10 Hiperstation for Mainframe Servers User Guide
COUNT(1|n)
Specifies the number instances to play back concurrently. For example, COUNT(5) plays the SOCKETS back five time concurrently. If COUNT is not specified, Hiperstation plays back one instance of the SOCKETS.
Use COUNT and REPEAT together to create the volume of traffic necessary for your testing. For example, to simulate two users executing the same activity at the same time, repeated five times in a row, specify COUNT(2) REPEAT(5).
CONNECTION_ATTEMPTS(1|count)
The number of time Hiperstation tries to connect to a partner. If the connection is not made after the specified number of attempts, Hiperstation will perform the action specified on the ERROR_ACTION parameter.
CTG_APPLID(application_ID)
Overrides the application ID in the CTG CONTENT.
CTG_PROGID(program_ID)
Overrides the program ID in the CTG CONTENT.
DB2_RDBNAM(‘database_name’)
Overrides the relational database name in the DB2 Connect CONTENT.
DB2_USERID(‘user_ID’)
Overrides the user ID in the DB2 Connect CONTENT. The quotes are required.
TCP/IP Unattended Playback 9-11
DB2_PASS(‘password’)|DB2_NPASS(‘encrypted_password’)
Overrides the password in the DB2 Connect CONTENT. The password must be a plain text password or a password using Hiperstation encryption. The quotes are required.
ECI_PROGID(program_ID)
Overrides the program ID in the ECI CONTENT.
ECI_USERID(‘user_ID’)
Overrides the user ID in the ECI CONTENT. The quotes are required.
ECI_PASS(‘password’)|ECI_NPASS(‘encrypted_password’)
Overrides the password in the ECI CONTENT. The password must be a plain text password or a password using Hiperstation encryption. The quotes are required.
ERROR_ACTION(MESSAGE|NOMESSAGE,STOP_CONNECTION|STOP_SCRIPT| STOP_SOCKETS|STOP_PLAYBACK|RETRY)
This parameter specifies the message that Hiperstation produces and the action it takes when a socket I/O error occurs (including connection failures, lost connections, and read/write failures). Options are:
MESSAGE
Print warning and socket I/O error messages.
NOMESSAGE
Suppress warning and socket I/O error messages.
STOP_CONNECTION
Stop the playback on the connection where the error occurred. Continue the playback on the other connections in the script.
STOP_SCRIPT
Stop the playback of the script.
STOP_SOCKETS
Stop the playback under the SOCKETS statement. When COUNT(x) is included on the SOCKETS statement, all x of the playbacks are stopped when a socket I/O occurs.
STOP_PLAYBACK
Stop the playback.
RETRY
Retry playing back the script.
ID(id_number)
The ID value provides a way to correlate entries on performance and comparison reports with the associated SOCKETS statement. This value can be added, deleted, or changed by the user. If this parameter is not specified on the SOCKETS statement, the field does not appear on the report.
PROTOCOL(CTG|DB2C|ECI|HTTP|HTTPS|IMSC|TCP)
Identifies the protocol used to play back the scripts in the given SOCKETS. This keyword overrides a PROTOCOL defined on the CONTROL statement, if specified. Otherwise, it overrides the value on the <CONNECT> tags in the script. Valid values are CTG, DB2C, ECI, HTTP, HTTPS, IMSC, and TCP.
Note: Protocol overrides are typically unnecessary. This value initiates the appropriate message handler. If it is incorrect, playback may fail.
9-12 Hiperstation for Mainframe Servers User Guide
IMS_DSTORE(datastore)
Overrides the datastore in the IMS Connect CONTENT.
IMS_TRANS(transaction_code)
Overrides the transaction code in the IMS Connect CONTENT.
IMS_USERID(‘user_ID’)
Overrides the user ID in the IMS Connect CONTENT. The quotes are required.
IMS_PASS(‘password’)|IMS_NPASS(‘encrypted_password’)
Overrides the password in the IMS Connect CONTENT. The password must be a plain text password or a password using VTAM Dark Field encryption. The quotes are required.
REPEAT(1|n)
Defines the number of times to repeat playback of the given SOCKETS. For example, REPEAT(6) causes the SOCKETS to play back six times in a row. If you do not specify REPEAT, Hiperstation plays back the SOCKETS one time.
Use COUNT and REPEAT to create the volume of traffic necessary for your testing. For example, to simulate two users executing the same activity at the same time, repeated five times in a row, specify COUNT(2) REPEAT(5).
Note: REPEAT requires script caching. If you supply a REPEAT value, make sure the CONTROL statement does not include the CACHEOFF keyword. Otherwise, Hiperstation produces an error and terminates playback with return code 8.
RLOG(*|destination)
Specifies where to write the output from REXX SAY statements added to your scripts. Supply a single-character sysout class, a PDSE and member, or a sequential dataset.
Generate a separate dataset or PDSE member for each thread of replay by including wildcard characters in the dataset or member name. Valid wildcard characters are:
– Asterisk (*) — Playback replaces the asterisk with a four-digit value representing the current replay value padded with leading zeros. For example, RLOG(MRRLOG.RPLY*) generates MYRLOG.RPLY0001, MYRLOG.RPLY0002, etc. Playback allows one asterisk per dataset name qualifier or member name, in any position except the first character.
– Question mark (?) — Playback replaces a string of one or more question marks with the current replay value. For example, RLOG(MYRLOG.RPLY??) generates MYRLOG.RPLY01, MYRLOG.RPLY02, etc. Include at least one question mark for each digit of the maximum replay value. For example, if the replay value will reach 20, insert at least two consecutive question marks. Playback truncates the replay value or pads it with leading zeros if there are more or fewer question marks than the number of digits in the replay value. Playback allows up to seven consecutive question marks per dataset name qualifier or member name, in any position except the first character.
Note: Replay values are based on the number of SOCKETS statements and their COUNT values. For example, two SOCKETS statements, each bearing a COUNT(3), results in six replay values.
If you specify a dataset or PDSE member that does not exist, Hiperstation allocates it with default values. To override default allocation values, add an RLOG DD statement to the playback JCL. For example:
//RLOGDD DD DUMMY,SPACE=(TRK,(15,15,15)),DSNTYPE=LIBRARY, // DCB=(LRECL=121,BLKSIZE=12100,RECFM=FB)
TCP/IP Unattended Playback 9-13
SERVER_ADDRESS(ASIS|IP Address)
Specifies a server address for all of the scripts within the SOCKETS to access. Supply an IPv6 or IPv4 IP address. This keyword overrides the server addresses shown on the <CONNECT> tags in the scripts.
SERVER_PORT(ASIS|Port Number)
Specifies a server port for all of the scripts within the SOCKETS to access. Supply a port number value between 0 and 65535. This keyword overrides the server ports shown on the <CONNECT> tags in the scripts.
SET_REXX_STREAM_VARIABLES(NO|YES)
Specifies whether the TCPIP_ACTUAL, TCPIP_EXPECTED, TCPIP_ACTUAL_LENGTH, TCPIP_EXPECTED_LENGTH and CONNECTION_NBR should be set during the playback. Hiperstation sets REXX variables when the reporting data is gathered for message completion. Copying data to these variables is unnecessary if you never reference these variables within a script. The default value is NO.
STARTDLY(0|hh:mm:ss.nnn)
Tells Hiperstation how long to wait between the start of SOCKETS and the commencement of playback. You can use STARTDLY to stagger the start of playbacks using multiple SOCKETS statements. For example, to wait five seconds, enter STARTDLY(5).
STDWAIT(15|hh:mm:ss.nnn)
The longest time that Hiperstation waits for I/O completion. If no I/O finishes in the STDWAIT interval, all outstanding I/O is canceled for that specific script. Hiperstation retries the connections up to the number of attempts set in the CONNECTION_ATTEMPTS parameter. Hiperstation retries any other I/O twice. After all attempts are made to complete the I/O, and if still unsuccessful, Hiperstation takes the action set on the ERROR_ACTION parameter.
If you do not include the STDWAIT parameter, Hiperstation uses the default value of 15 seconds.
STIME(time_stamp)
Defines a value that Hiperstation uses to determine when to start playing back the SOCKETS relative to the other SOCKETS in the job. If the USESTIME keyword is specified on the CONTROL statement, Hiperstation staggers playback initiation of each SOCKETS based on the difference in the STIME values.
Supply a date-time stamp inside single quotation marks in the following format: YYYY/MM/DD_HH:MM:SS.NNNNNN. To ensure proper formatting, copy and paste an STIME value from the script and modify it as necessary.
This is an optional keyword. If USESTIME is specified on the CONTROL statement, but the STIME keyword is not defined on the SOCKETS statement, playback uses the first STIME in the script.
If USESTIME is not specified on the CONTROL statement, Hiperstation ignores this keyword.
THINK(0|hh:mm:ss.nnn)
Sets the amount of think time (for example, the amount of time to wait after receiving a server message before sending the next client message). This keywords accepts hours, minutes, and seconds separated by colons (:) — HH:MM:SS. However, seconds is the only required value and you can specify fractions of a second by providing a decimal value. For example, THINK(1) is one second of think time. THINK(10:14.5) is ten minutes, fourteen and a half seconds of think time.
This keyword is only available if THOPT3 is specified. If you do not supply this keyword when using think option three, playback does not wait.
9-14 Hiperstation for Mainframe Servers User Guide
THOPT(1|2|3)
Specifies which option to use for simulating think time. Enter a value of:
– 1 to play back at full speed.
– 2 to play back using the think time recorded in the script. Think time is simulated based on the differences between the values of the <TIME> tags in the script. Include the THPCT keyword to stipulate a percentage of recorded think time. For example, THOPT(2) THPCT(50) causes playback to use half of the difference between the <TIME> tags in the script.
– 3 to play back using an arbitrary value that is specified with the THINK and THPCT keywords. For example, THOPT(3) THINK(5) causes playback to wait five seconds after receiving a server response before sending the next client message.
THPCT(100|percent)
Specifies the percentage of think time to use for playback. This parameter applies to think time options: THOPT(2) and THOPT(3). It works differently depending on the selected option. If you specify:
– THOPT(2), THPCT is the percentage of the think time recorded in the script.
– THOPT(3), THPCT is the percentage of the value specified on the THINK keyword. For example, THOPT(3) THINK(10:3) THPCT(50) results in five minutes, one and a half seconds of think time.
If you do not supply the THPCT keyword, playback uses the default value of 100%.
TRACE(sysout_class|dataset)
Produces diagnostic information regarding Hiperstation internal behavior. Contact Compuware Customer Support prior to using this option.
Indicate the location for the output. Specify a single-character sysout class, a PDSE and member, or a sequential dataset.
Generate a separate dataset or PDSE member for each thread of replay by including wildcard characters in the dataset or member name. Valid wildcard characters include:
– Asterisk (*) — Playback replaces the asterisk with a four-digit value representing the current replay value padded with leading zeros. For example, TRACE(MYTRACE.RPLY*) generates MYTRACE.RPLY0001, MYTRACE.RPLY0002, etc. Playback allows one asterisk per dataset name qualifier or member name, in any position except the first character.
– Question mark (?) — Playback replaces a string of one or more question marks with the current replay value. For example, TRACE(MYTRACE.RPLY??) generates MYTRACE.RPLY01, MYTRACE.RPLY02, etc. Include at least one question mark for each digit of the maximum replay value. For example, if the replay value will reach 20, insert at least two consecutive question marks. Playback truncates the replay value or pads it with leading zeros if there are more or fewer question marks than the number of digits in the replay value. Playback allows up to seven consecutive question marks per dataset name qualifier or member name, in any position except the first character.
Note: Replay values are based on the number of SOCKETS statements and their COUNT values. For example, two SOCKETS statements, each bearing a COUNT(3), results in six replay values.
If you specify a dataset or PDSE member that does not exist, Hiperstation allocates it with default values. To override default allocation values, add a TRACE DD statement to the playback JCL. For example:
//TRACEDD DD DUMMY,SPACE=(TRK,(15,15,15)),DSNTYPE=LIBRARY, // DCB=(LRECL=121,BLKSIZE=12100,RECFM=FB)
TCP/IP Unattended Playback 9-15
USE_PIPELINING(NO|YES)
Enables support of message pipelining for playback of DB2C, ECI, and IMSC scripts. USE_PIPELINING(YES) causes playback to send multiple messages to the server before receiving responses. NO is the default value.
USE_HTTP_PIPELINING(NO|YES)
Enables support of message pipelining for playback of HTTP and HTTPS scripts. USE_PIPELINING(YES) causes playback to send multiple messages to the server before receiving responses. NO is the default value.
SCRIPT Statement
You can use SCRIPT statements to specify which scripts to play back and to provide playback parameters for each script. Place SCRIPT statements, in the order that they should be played back, under a SOCKETS statement. For information on statement hierarchy and to learn how to group SCRIPT statements, see “Creating Playback Control Statements” on page 9-1.
The following syntax diagram shows all of the available SCRIPT statement parameters. Parameter definitions follow the diagram.
scriptname
Identifies the SCRIPT (member name of the script in the script dataset) to be played back.
PROTOCOL(CTG|DB2C|ECI|HTTP|HTTPS|IMSC|TCP)
Identifies the protocol used to play back the script. This keyword overrides a PROTOCOL defined on the SOCKETS and CONTROL statements, if specified. Otherwise, it overrides the value on the <CONNECT> tags in the script. Valid values are CTG, DB2C, ECI, HTTP, HTTPS, IMSC, and TCP.
Note: Protocol overrides are typically unnecessary. This value initiates the appropriate message handler. If it is incorrect, playback may fail.
9-16 Hiperstation for Mainframe Servers User Guide
REPEAT(1|n)
Defines the number of times to repeat playback of the given SCRIPT. For example, REPEAT(6) causes the SCRIPT to play back six times in a row. REPEAT can be specified on both SOCKETS and SCRIPT statements. For example, the following statements result in script2 playing back six times, twice within each repeat of the SOCKETS.
SOCKETS REPEAT(3) SCRIPT(script1) SCRIPT(script2) REPEAT(2) SCRIPT(script3)
If you do not specify REPEAT on the SOCKETS or SCRIPT statements, Hiperstation plays back the SCRIPT one time.
Note: REPEAT requires script caching. If you supply a REPEAT value, make sure the CONTROL statement does not include the CACHEOFF keyword. Otherwise, Hiperstation produces an error and terminates playback with return code 8.
SERVER_ADDRESS(ASIS|IP Address)
Specifies a server address to access for the given script. Supply an IPv6 or IPv4 address. This keyword overrides the SERVER_ADDRESS defined on the SOCKETS statement, if specified. Otherwise, it overrides the server addresses shown on the <CONNECT> tags in the scripts.
SERVER_PORT(ASIS|Port Number)
Specifies a server port to access for the given script. Supply a port number value between 0 and 65535. This keyword overrides the SERVER_PORT defined on the SOCKETS statement, if specified. Otherwise, it overrides the server ports shown on the <CONNECT> tags in the scripts.
COLLECT Statement
You can specify the information to collect during the playback job and generate reports from the collected information by including one or more COLLECT statements in the playback job.
Note: Collect all fields from all tables to ensure the necessary data is available to run any type of report. Reporting is not supported for client testing.
TCP/IP Unattended Playback 9-17
FIELDS
Follow this keyword with:
– An asterisk to collect all fields from the collection and reporting table you specify on the FROM keyword. Collecting all field ensures the optimum reporting flexibility.
9-18 Hiperstation for Mainframe Servers User Guide
– A comma-separated list of fields, in long or short format, from the collection and reporting table you specify on the FROM keyword. This option minimizes storage overhead and processing time. Incorporate the SUBSTR keyword to collect a specified number of bytes from a specific field. The following example collects the first 20 bytes of the Expected Response Header field (EXHS) and all of the Message ID field (MSID).
COLLECT FIELDS(SUBSTR(EXHS,20),MSID) FROM(MESSAGE)
Refer to Appendix A, “TCP/IP Data Collection and Reporting Tables”, to determine which tables and fields to collect or to locate short field names.
Note: Depending on use, not every field is always available. For example, message header fields cannot be sent by an application during a particular transmission, and therefore would not be available for reporting.
FROM
Follow the FROM keyword with the name of the collection and reporting table that owns the fields specified on the FIELDS keyword. For a list of available tables, see Appendix A, “TCP/IP Data Collection and Reporting Tables”.
WHERE
Use the WHERE clause to provide criteria for collecting only required data. For example, to collect all fields from the SOCKETS table for the second of five sockets in the playback job, construct the COLLECT statement as follows:
COLLECT FIELDS (*) FROM (SOCKETS) WHERE (SOCKETSNUMBER 2)
Define Statements for Client Testing
This section provides a syntax diagram for each playback control statement for client testing. If you are unfamiliar with syntax diagrams, see “Reading Syntax Diagrams” on page xxi. Parameter definitions follow the diagrams.
CONTROL Statement
Use the CONTROL statement to provide job-level playback parameters and connection attribute overrides. If you include a CONTROL statement, place it before the first SOCKETS statement.
The following syntax diagram shows all of the available parameters for the CONTROL statement. Parameter definitions follow the diagram.
TCP/IP Unattended Playback 9-19
CACHE|CACHEOFF
CACHE instructs Hiperstation to store scripts in memory during playback to improve performance. CACHE is the default. To disable script caching, specify CACHEOFF.
Note: Script caching is required if you specify REPEAT on the SOCKETS or SCRIPT statements. If you specify CACHEOFF and provide a REPEAT value, Hiperstation produces an error and terminates playback with return code 8.
ERROR_ACTION(MESSAGE|NOMESSAGE,STOP_CONNECTION|STOP_SCRIPT| STOP_SOCKETS|STOP_PLAYBACK|RETRY)
ERROR_ACTION specifies which messages Hiperstation produces and the action it takes when a socket I/O error occurs (including connection failures, lost connections, and read/write failures). MESSAGE prints and NOMESSAGE suppresses warning and socket I/O error messages. STOP_CONNECTION stops playback on the connection where the error occurred but continues playback on the other connections in the script. STOP_SCRIPT stops script playback. STOP_SOCKETS stops playback under the SOCKETS statement. When COUNT(x) is included on the SOCKETS statement, all x playbacks are stopped when a socket I/O occurs. STOP_PLAYBACK stops playback. RETRY retries playing back the script.
PLAY(SERVER|SERVER_IPV6)
PLAY(SERVER) tells the playback program to function as an IPv4 server. PLAY(SERVER_IPV6) tells the playback program to function as an IPv6 server.
PROTOCOL(TCP|EB2C)
PROTOCOL identifies the protocol used to play back the scripts in the given job. Valid values are TCP (default) and DB2C.
9-20 Hiperstation for Mainframe Servers User Guide
Note: Protocol overrides are required.
REXXOFF|REXXON
REXXOFF disables and REXXON enables support for REXX logic in scripts. If your scripts contain REXX logic, specify REXXON.
RLOG(*|destination)
RLOG specifies where to write the output from REXX SAY statements added to your scripts. Supply a single-character sysout class, a PDSE and member, or a sequential dataset.
Generate a separate dataset or PDSE member for each thread of replay by including wildcard characters in the dataset or member name. Valid wildcard characters include:
– Asterisk (*) — Playback replaces the asterisk with a four-digit value representing the current replay value padded with leading zeros. For example, RLOG(MRRLOG.RPLY*) generates MYRLOG.RPLY0001, MYRLOG.RPLY0002, etc. Playback allows one asterisk per dataset name qualifier or member name, in any position except the first character.
– Question mark (?) — Playback replaces a string of one or more question marks with the current replay value. For example, RLOG(MYRLOG.RPLY??) generates MYRLOG.RPLY01, MYRLOG.RPLY02, etc. Include at least one question mark for each digit of the maximum replay value. For example, if the replay value will reach 20, insert at least two consecutive question marks. Playback truncates the replay value or pads it with leading zeros if there are more or fewer question marks than the number of digits in the replay value. Playback allows up to seven consecutive question marks per dataset name qualifier or member name, in any position except the first character.
Note: Replay values are based on the number of SOCKETS statements and their COUNT values. For example, two SOCKETS statements, each bearing a COUNT(3), results in six replay values.
If you specify a dataset or PDSE member name that does not exist, Hiperstation allocates it with default values. To override default allocation values, add an RLOG DD statement to the playback JCL. For example:
//RLOGDD DD DUMMY,SPACE=(TRK,(15,15,15)),DSNTYPE=LIBRARY, // DCB=(LRECL=121,BLKSIZE=12100,RECFM=FB)
SERVER_PORT(n)
SERVER_PORT specifies which port the playback server will be listening on.
LISTENWAIT(120|hh:mm:ss:nnn)
LISTENWAIT specifies in seconds or in hh:mm:ss:nnn format, the longest that the listener will wait for connects sent by clients. The default value is 120 seconds. When you enter hours, minutes, or fractions along with seconds (separated by a colon), the individual numbers cannot be longer than two digits each (excluding fractions).
SET_REXX_STREAM_VARIABLES(NO|YES)
SET_REXX_STREAM_VARIABLES enables the use of Hiperstation predefined REXX variables during playback. The variables return information about the playback. You can incorporate them into REXX logic that you add to your scripts to control the way the scripts play back. For example, you can use them to dynamically replace data in the script during playback (see “Hiperstation for Mainframe Servers REXX Variables” on page 7-35). Since this is not required for replay, the default value for this parameter is NO.
TCP/IP Unattended Playback 9-21
STDWAIT(15|hh:mm:ss.nnn)
STDWAIT is the longest time that Hiperstation waits for I/O completion. If no I/O finishes in the STDWAIT interval, all outstanding I/O is canceled for that specific script. Hiperstation retries the connections up to the number of attempts set in the CONNECTION_ATTEMPTS parameter. Hiperstation retries any other I/O twice. After all attempts are made to complete the I/O, and if still unsuccessful, Hiperstation takes the action set on the ERROR_ACTION parameter.
If you do not include the STDWAIT parameter, Hiperstation uses the default value of 15 seconds.
TRACE(sysout_class|dataset)
TRACE produces diagnostic information regarding Hiperstation’s internal behavior. Contact Compuware Customer Support prior to using this option.
Specify the location for the output as a single-character sysout class, a PDSE and member, or a sequential dataset.
Generate a separate dataset or PDSE member for each thread of replay by including wildcard characters in the dataset or member name. Valid wildcard characters include:
– Asterisk (*) — Playback replaces the asterisk with a four-digit value representing the current replay value padded with leading zeros. For example, TRACE(MYTRACE.RPLY*) generates MYTRACE.RPLY0001, MYTRACE.RPLY0002, etc. Playback allows one asterisk per dataset name qualifier or member name, in any position except the first character.
– Question mark (?) — Playback replaces a string of one or more question marks with the current replay value. For example, TRACE(MYTRACE.RPLY??) generates MYTRACE.RPLY01, MYTRACE.RPLY02, etc. Include at least one question mark for each digit of the maximum replay value. For example, if the replay value will reach 20, insert at least two consecutive question marks. Playback truncates the replay value or pads it with leading zeros if there are more or fewer question marks than the number of digits in the replay value. Playback allows up to seven consecutive question marks per dataset name qualifier or member name, in any position except the first character.
Note: Replay values are based on the number of SOCKETS statements and their COUNT values. For example, two SOCKETS statements, each bearing a COUNT(3), results in six replay values.
If you specify a dataset or PDSE member that does not exist, Hiperstation allocates it with default values. To override default allocation values, add a TRACE DD statement to the playback JCL. For example:
//TRACEDD DD DUMMY,SPACE=(TRK,(15,15,15)),DSNTYPE=LIBRARY, // DCB=(LRECL=121,BLKSIZE=12100,RECFM=FB)
USE_PIPELINING(NO|YES)
USE_PIPELINING enables support of message pipelining for playback of DB2C scripts. USE_PIPELINING(YES) causes playback to send multiple messages to the client before receiving responses. NO is the default value.
USESTIME
USESTIME provides control of playback initiation time for each SOCKETS statement supplied in the job. If USESTIME is specified, Hiperstation initiates SOCKETS playback relative to the STIME values supplied on each SOCKETS statement. For example, the following STIME values result in the second SOCKETS playing back five minutes after the first.
SOCKETS STIME (‘2006/07/10=10:10:10.000000’) SOCKETS STIME (‘2006/07/10=10:15:10.000000’)
9-22 Hiperstation for Mainframe Servers User Guide
Note: STIME is used only to determine the order that SOCKETS statements are served.
SOCKETS Statement
You can use the SOCKETS statement to define the script to play back and to provide playback parameters for that script. Place the applicable SCRIPT statements under each SOCKETS statement, in the order that they should be played back. Place SOCKETS statements after the CONTROL statement. For more information regarding statement hierarchy, see “Creating Playback Control Statements” on page 9-1.
The following syntax diagram shows all of the available SOCKETS statement parameters. Parameter definitions follow the diagram.
CLIENT_ADDRESS(n.n.n.n|n:n:n:n:n:n:n:n)
This parameter specifies the IP address that this SOCKET will accept connections from. IPv6 or IPv4 IP address formats are both valid.
COUNT(1|n)
Specifies the number of instances to serve. For example, COUNT(5) will serve five client requests. If COUNT is not specified, Hiperstation serves one instance of the SOCKETS.
ERROR_ACTION(MESSAGE|NOMESSAGE,STOP_CONNECTION|STOP_SCRIPT| STOP_SOCKETS|STOP_PLAYBACK|RETRY)
ERROR_ACTION specifies which messages Hiperstation produces and the action it takes when a socket I/O error occurs (including connection failures, lost connections, and read/write failures). MESSAGE prints and NOMESSAGE suppresses warning and socket I/O error messages. STOP_CONNECTION stops playback on the connection where the error occurred but continues playback on the other connections in the script. STOP_SCRIPT stops script playback. STOP_SOCKETS stops playback under the SOCKETS statement. When COUNT(x) is included on the SOCKETS statement, all
TCP/IP Unattended Playback 9-23
x playbacks are stopped when a socket I/O occurs. STOP_PLAYBACK stops playback. RETRY retries playing back the script.
ID(id_number)
The ID value provides a way to specify which connection in a script should be used based on the ID parameter of the <CONNECT> tag in the script. Otherwise, the first connection found in the script will be used.
RLOG(*|destination)
RLOG specifies where to write the output from REXX SAY statements added to your scripts. Supply a single-character sysout class, a PDSE and member, or a sequential dataset.
Generate a separate dataset or PDSE member for each thread of replay by including wildcard characters in the dataset or member name. Valid wildcard characters include:
– Asterisk (*) — Playback replaces the asterisk with a four-digit value representing the current replay value padded with leading zeros. For example, RLOG(MRRLOG.RPLY*) generates MYRLOG.RPLY0001, MYRLOG.RPLY0002, etc. Playback allows one asterisk per dataset name qualifier or member name, in any position except the first character.
– Question mark (?) — Playback replaces a string of one or more question marks with the current replay value. For example, RLOG(MYRLOG.RPLY??) generates MYRLOG.RPLY01, MYRLOG.RPLY02, etc. Include at least one question mark for each digit of the maximum replay value. For example, if the replay value will reach 20, insert at least two consecutive question marks. Playback truncates the replay value or pads it with leading zeros if there are more or fewer question marks than the number of digits in the replay value. Playback allows up to seven consecutive question marks per dataset name qualifier or member name, in any position except the first character.
Note: Replay values are based on the number of SOCKETS statements and their COUNT values. For example, two SOCKETS statements, each bearing a COUNT(3), results in six replay values.
If you specify a dataset or PDSE member that does not exist, Hiperstation allocates it with default values. To override default allocation values, add an RLOG DD statement to the playback JCL. For example:
//RLOGDD DD DUMMY,SPACE=(TRK,(15,15,15)),DSNTYPE=LIBRARY, // DCB=(LRECL=121,BLKSIZE=12100,RECFM=FB)
SET_REXX_STREAM_VARIABLES(NO|YES)
SET_REXX_STREAM_VARIABLES specifies whether TCPIP_ACTUAL, TCPIP_EXPECTED, TCPIP_ACTUAL_LENGTH, TCPIP_EXPECTED_LENGTH, and CONNECTION_NBR should be set during playback. Hiperstation sets REXX variables when the reporting data is gathered for message completion. Copying data to these variables is unnecessary if these variables are never referenced within a script. The default value is NO.
STDWAIT(15|hh:mm:ss.nnn)
STDWAIT is the longest time that Hiperstation waits for I/O completion. If no I/O finishes in the STDWAIT interval, all outstanding I/O is canceled for that specific script. Hiperstation retries the connections up to the number of attempts set in the CONNECTION_ATTEMPTS parameter. Hiperstation retries any other I/O twice. After all attempts are made to complete the I/O, and if still unsuccessful, Hiperstation takes the action set on the ERROR_ACTION parameter.
If you do not include the STDWAIT parameter, Hiperstation uses the default value of 15 seconds.
9-24 Hiperstation for Mainframe Servers User Guide
STIME(time_stamp)
STIME defines a value that Hiperstation uses to determine the order that SOCKETS statements are served. If the USESTIME keyword is specified on the CONTROL statement, Hiperstation staggers connection of each SOCKETS based on the order of the STIME values.
Supply a date-timestamp inside single quotation marks in the following format: YYYY/MM/DD_HH:MM:SS.NNNNNN. To ensure proper formatting, copy and paste an STIME value from the script and modify it as necessary.
STIME is an optional keyword. If USESTIME is specified on the CONTROL statement, but the STIME keyword is not defined on the SOCKETS statement, playback uses the first STIME in the script.
If USESTIME is not specified on the CONTROL statement, Hiperstation ignores this keyword.
Note: Specifying CLIENT_ADDRESS may cause out of STIME order connections if a connection coming from a client address matches a SOCKETS statement with CLIENT_ADDRESS specified that is not the next SOCKETS statement to be server-based in STIME order.
TRACE(sysout_class|dataset)
TRACE produces diagnostic information regarding Hiperstation internal behavior. Contact Compuware Customer Support prior to using this option.
Specify the location for the output as a single-character sysout class, a PDSE and member, or a sequential dataset.
Generate a separate dataset or PDSE member for each thread of replay by including wildcard characters in the dataset or member name. Valid wildcard characters include:
– Asterisk (*) — Playback replaces the asterisk with a four-digit value representing the current replay value padded with leading zeros. For example, TRACE(MYTRACE.RPLY*) generates MYTRACE.RPLY0001, MYTRACE.RPLY0002, etc. Playback allows one asterisk per dataset name qualifier or member name, in any position except the first character.
– Question mark (?) — Playback replaces a string of one or more question marks with the current replay value. For example, TRACE(MYTRACE.RPLY??) generates MYTRACE.RPLY01, MYTRACE.RPLY02, etc. Include at least one question mark for each digit of the maximum replay value. For example, if the replay value will reach 20, insert at least two consecutive question marks. Playback truncates the replay value or pads it with leading zeros if there are more or fewer question marks than the number of digits in the replay value. Playback allows up to seven consecutive question marks per dataset name qualifier or member name, in any position except the first character.
Note: Replay values are based on the number of SOCKETS statements and their COUNT values. For example, two SOCKETS statements, each bearing a COUNT(3), results in six replay values.
If you specify a dataset or PDSE member that does not exist, Hiperstation allocates it with default values. To override default allocation values, add a TRACE DD statement to the playback JCL. For example:
//TRACEDD DD DUMMY,SPACE=(TRK,(15,15,15)),DSNTYPE=LIBRARY, // DCB=(LRECL=121,BLKSIZE=12100,RECFM=FB)
TCP/IP Unattended Playback 9-25
USE_PIPELINING(NO|YES)
UE_PIPELINING enables support of message pipelining for playback of DB2C scripts. USE_PIPELINING(YES) causes playback to send multiple messages to the client before receiving responses. NO is the default value.
USE_HTTP_PIPELINING(NO|YES)
USE_HTTP_PIPELINING enables support of message pipelining for playback of HTTP and HTTPS scripts. USE_HTTP_PIPELINING(YES) causes playback to send multiple messages to the server before receiving responses. NO is the default value.
SCRIPT Statement
You can use SCRIPT statements to specify which scripts to play back and to provide playback parameters for each script. Place SCRIPT statements under a SOCKETS statement in the order that they should be played back. For information on statement hierarchy and to learn how to group SCRIPT statements, see “Creating Playback Control Statements” on page 9-1.
For client testing, there is only one SCRIPT statement under a SOCKETS statement.
scriptname
Identifies the SCRIPT (member name of the script in the script dataset) to be played back.
Preparing the Playback JobHiperstation provides sample JCL to:
• Execute an unattended playback job (SQQFSAMP member TCPRUN).
• Sort the information collected during playback. Sorting collected information is required for reporting (SQQFSAMP member TCPPBSRT).
Separate samples are provided for flexibility. You can sort and save the collected information as soon as playback finishes or later when you are ready to generate reports.
To prepare a playback and sorting job:
1. Copy SQQFSAMP members TCPRUN (Figure 9-2) and TCPPBSRT (Figure 9-3 on page 9-27) into your personal JCL libraries.
2. Open TCPRUN in a file editing tool such as ISPF Edit.
9-26 Hiperstation for Mainframe Servers User Guide
Figure 9-2. TCPRUN-Sample TCP/IP Playback JCL
********************************* Top of Data ********************************** //* JOB CARD INFORMATION GOES HERE //* HOWEVER BE SURE TO RUN WITH REGION=0M //UPROCS JCLLIB ORDER=('COMPWARE.QQF800.SQQFSAMP') //******************************************************************** //* TCPPLAY PROC IS SHIPPED WITH THE SAMPLES //******************************************************************** //GO EXEC PROC=TCPPLAY,MEM=TCPPBMN,GPARM='POSIX(ON)/' //* //* INPUT STATEMENTS, INCLUDING THE RECORDED LOG //* //GO.SYSIN DD DSN=HPER.TEST.SCRIPTS(LOG00001),DISP=SHR //* //* INPUT SCRIPTS, RECORDED INTO HPER.TEST.SCRIPTS. //* //GO.SYSLIB DD DSN=HPER.TEST.SCRIPTS,DISP=SHR //* //* IF INPUT DETAIL IS SPLIT, THEN UPDATE THE SERVER, //* CLIENT AND COMBINED DD STATEMENTS APPROPRIATELY. //* //GO.SERVER DD DSN=HPER.TEST.SCRIPTS,DISP=SHR //GO.CLIENT DD DSN=HPER.TEST.SCRIPTS,DISP=SHR //GO.COMBINED DD DSN=HPER.TEST.SCRIPTS,DISP=SHR //* //* USED FOR REPORTING DATA COLLECTION. //* ONLY REQUIRED IF 'COLLECT' STATEMENTS ARE IN SYSIN. //* DDNAME MAY BE ALTERED BY 'CONTROL DATABASE' STATEMENT. //* //GO.DATABASE DD DISP=(,CATLG), //* DSN=VP.USER1.TCP.UNSORTED.DATA, //* UNIT=SYSDA,SPACE=(CYL,(5,1)), //* DCB=(RECFM=VB,BLKSIZE=9004,LRECL=9000) //* //GO.HTMLLOG DD PATHOPTS=(ORDWR,OCREAT), // PATHMODE=(SIRWXU,SIRWXG,SIRWXO), // PATH='/u/p9/compuware/summary.htm' //GO.SYSABEND DD SYSOUT=*
3. Insert job statement information at the top of the sample.
4. Ensure UPROCS points to the procedures library that contains the TCPPLAY procedure. See your Systems Administrator for this information.
5. Modify the following DD statements:
– On the SYSIN DD statement, either supply the dataset name containing the customized Connection Log or replace the dataset name statement with inline playback control statements.
– On the SYSLIB DD statement, supply the dataset name containing the script members.
– If the scripts contain the server and client detail data, insert an asterisk (*) before GO on the SERVER, CLIENT, and COMBINED DD statements to turn the lines into script comments.
If the server and client detail data is stored externally, in the same dataset, modify the COMBINED DD statement and comment the SERVER and CLIENT DD statements.
If the server and client detail data is stored in separate datasets, modify the respective DD statements and comment the COMBINED DD statement.
Note: On the COMBINED, or CLIENT and SERVER DD statements, supply the PSDE name only. Do not specify a member name. The member name is provided on the <DETAIL> tag within the scripts.
– If the SYSIN DD statement does not include COLLECT statements, insert an asterisk before GO on the DATABASE DD statement. Otherwise, supply a dataset name to store the information collected during playback and remove the asterisk
TCP/IP Unattended Playback 9-27
comment indicator at the beginning of the line. If the dataset name does not exist, remove the asterisks from allocation parameter lines and modify as necessary.
– To generate an interactive HTML version of the Playback Error Summary report (page 9-30), supply an HFS path on the HTMLLOG DD statement. Otherwise, insert an asterisk at the beginning of each line of the statement.
6. The job is ready to execute playback. If you do not want to sort the collected data, submit the job. See “Submitting the Job” on page 9-27. Otherwise, complete the remaining instructions.
7. Copy TCPPBSRT (Figure 9-3) and insert it at the end of the playback JCL.
Figure 9-3. TCPPBSRT-Sample JCL to Sort Data Collected During Playback
********************************* Top of Data ********************************** //*PLACE YOUR JOBCARD BEFORE THIS STATEMENT //* //* //* HIPERSTATION TCPIP PLAYBACK REPORT DATA SORT //* //* //JOBLIB DD DISP=SHR,DSN=COMPWARE.QQF800.SQQFLOAD //TCPSORT EXEC PGM=TCPPBSRT,REGION=4M //* //SYSOUT DD DUMMY //* //UNSORTED DD DISP=SHR, // DSN=VP.USER1.TCP.UNSORTED.DATA //* //SORTED DD DISP=(,CATLG), // UNIT=SYSDA,SPACE=(CYL,(5,1)), // DSN=VP.USER1.TCP.SORTED.DATA //* //WORK DD UNIT=VIO,SPACE=(CYL,(5,1)) //* //SORTWK01 DD UNIT=VIO,SPACE=(CYL,(5,1)) //SORTWK02 DD UNIT=VIO,SPACE=(CYL,(5,1)) //SORTWK03 DD UNIT=VIO,SPACE=(CYL,(5,1)) //*
8. The sample is set up to run as a separate job. To make it a step in the playback job, change JOBLIB to STEPLIB, cut the line and insert it below the TCPSORT line, and point it to the Hiperstation load library at your installation. See your Systems Administrator for this information.
9. On the SORTED DD statement, supply the name of the dataset for storing the sorted data.
10. Submit the job. See the next section, “Submitting the Job”, for submission options and job step return code information.
Submitting the JobAfter the job is prepared, you can submit it in one of the following ways:
• Submit the job from the ISPF Edit session to execute it immediately. Type SUB on the Command line and press Enter.
• Schedule the job to run at a specific time. Refer to your job scheduler’s documentation for help.
After the job has completed, review the return codes to see if playback completed successfully or to determine the cause of failure.
9-28 Hiperstation for Mainframe Servers User Guide
Review Playback Return Codes
Hiperstation reports an MVS return code for each step of a playback job. The return code is a numeric value specifying whether the job step completed successfully and to what degree. See the next section, “Playback Return Code Descriptions”, for a complete list of TCP/IP return codes.
Note: For more definitive playback results, you can add REXX logic to a script to return a specific value based on criteria you supply. This is called a ‘custom’ return code. Refer to the Hiperstation Scripting Reference to learn how to define custom return codes.
The location of your return codes depends on your system configuration. On some systems, with the correct job statement parameter, return codes display in the user’s TSO session. On others, they are written to a job log. For help locating your return codes, see your systems administrator.
Hiperstation also writes the following informational messages to the SYSPRINT upon job completion.
TCPSRPL-0051I Play complete for Replay=1 - Return Code=xxxx. TCPPBMN-0007I Maximum return code=xxxx
Message TCPSRPL-0051I reports the return code from the specified playback session (Replay). Hiperstation produces one of these messages for each playback session in the job step. For example, the following playback statements result in six playback sessions (Table 9-1) and therefore, six TCPSRPL-0051I messages:
SOCKETS COUNT(2) REPEAT(3) SCRIPT(TEST)
Table 9-1. Playback Sessions for a SOCKETS statement with COUNT(2) REPEAT(3)
Repeat Count 1 Count 2
1 Replay=1 Replay=2
2 Replay=3 Replay=4
3 Replay=5 Replay=6
Message TCPPBMN-0007I reports the maximum return code from all of the playback sessions in the job step. This is the value that Hiperstation returns as the job step completion code.
Note: The job step completion code can be tested with the COND parameter on a JCL EXEC or JOB statement.
If the SOCKETS statement contains multiple scripts, Hiperstation returns the value set by the last script processed. Incidentally, playback terminates SOCKETS processing if it encounters a non-zero return code. For example, Hiperstation reports the return code from the LOGOFF script in the following SOCKETS, unless LOGON or TEST produce a non-zero return code.
SOCKETS SCRIPT(LOGON) SCRIPT(TEST) SCRIPT(LOGOFF)
Playback Return Code Descriptions
Hiperstation writes the following information to SYSPRINT:
• A return code message for each playback session in the job step.
TCP/IP Unattended Playback 9-29
• A message indicating the maximum return code for the job step.
• Playback status, warning, and error messages.
Note: It also writes a Playback Error Summary report to the location specified on the ERRORLOG DD statement in the playback JCL. See “Troubleshooting with the Playback Error Summary” for detailed information.
If you receive a non-zero return code, review the return code description provided in Table 9-2. Then review the warning and error messages to determine the cause of the problem. Refer to Hiperstation Messages and Codes for help with error resolution.
Table 9-2. Hiperstation for Mainframe Servers Internal Return Codes
Code Description
0 All scripts ran successfully without errors.
4 Playback ended due to one of the following:
• An invalid script record was encountered. Review the playback errors to determine which record caused the issue, then edit the script record.
• An invalid CONNECTION_ID was encountered. Edit the script to repair the incorrect connection ID.
• A REXX initialization error was encountered. Refer to your REXX documentation for help with initialization errors.
8 Playback ended due to one of the following:
• A file allocation error occurred. Review the allocation parameters in the playback job. If they are correct, contact your systems administrator.
• A file could not be opened. Make sure you have authority to access all of the files specified in the job and that the files are not in use.
• A file could not be read. Make sure you have authority to read all of the files specified in the job.
• A file could not be written. Make sure you have authority to write to all of the files specified in the job.
• A script file was not found. Make sure the member names specified on the SCRIPT statements are accurate and exist and that the dataset name provided on the SYSLIB DD parameter is accurate.
• Hiperstation for Mainframe Servers was unable to access or read the internal cache. This could happen for a variety of reasons (for example, if memory was corrupted). Contact your systems administrator. Note: Removing the CACHON parameter from the CONTROL statement may resolve the error, but it will not correct any systems issues.
• Hiperstation for Mainframe Servers was unable to write to the internal cache. This could happen for a variety of reasons (for example, the cache is full). Contact your systems administrator. Note: Reducing the size of the job may resolve the issue, but it will not correct any systems issues.
• An invalid control card was encountered. Correct the job SYSIN.
• An invalid IP Address was encountered. Review the playback errors to determine which address is invalid. Either edit the address in the script or supply an override on the SOCKETS or SCRIPT statement.
9-30 Hiperstation for Mainframe Servers User Guide
Note: You can add REXX logic to a script to return a specific value based on criteria you supply. For example, add logic to evaluate application message content and return a specific value if the content is incorrect. Refer to the Hiperstation Scripting Reference to learn how to define custom return codes.
Troubleshooting with the Playback Error SummaryHiperstation’s playback function automatically generates an Error Summary Report, in text format, for all playback jobs. Use this report to troubleshoot playback errors. View it with a spool display facility such as IBM SDSF.
The summary contains all of the error messages and significant warning messages that occurred during the playback. Use the time stamps from the messages in the summary as search criteria for locating the area of the playback log where the event occurred. This feature requires an ERRORLOG DD statement in the playback JCL. Position the ERRORLOG DD statement ahead of the Playback Log SYSOUT DD to ensure that the summary appears at the top of the report.
Note: The ERRORLOG DD statement is required for successful playback. If you do not include it, playback halts and the job returns an error code of 100. If you use the sample playback JCL, TCPRUN, you do not have to add this statement. TCPRUN calls a procedure that supplies it.
Generate an interactive HTML version of the report by including an HTMLLOG DD statement that specifies an HFS path in the playback JCL.
Note: The sample playback JCL, TCPRUN, supplies this DD statement. However, you may need to override the default path. Note that HFS paths are case sensitive, so ensure that Caps Lock is not turned on when you edit the JCL. Additionally, optimum screen resolution for viewing this report is 800 x 600 pixels or higher.
You can view the report with a supported Web browser.
12 Playback terminated due to a system failure. Some causes for this return code include:
• You are not licensed to use Hiperstation for Mainframe Servers.
• Errors occurred during socket dispatch.
• Signal errors occurred while replaying.
• Major system failure such as TCP is not running.
• No OMVS segment is available.
Contact your systems administrator.
100 Playback terminated because the playback job does not include an ERRORLOG DD statement. Insert an ERRORLOG DD statement before the SYSOUT DD in the playback JCL.
Table 9-2. Hiperstation for Mainframe Servers Internal Return Codes
Code Description
TCP/IP Unattended Playback 9-31
Figure 9-4. Playback Error Summary Report (HTML Format)
The error summary appears at the top of the browser window and the message log at the bottom. The time stamps on the messages in the summary are hyperlinked to the message in the playback log. Click an error or warning message’s time stamp to position the log accordingly. The target error/warning message is highlighted for easy recognition. Scroll up or down to see messages generated before and after the error.
9-32 Hiperstation for Mainframe Servers User Guide
10-1
Chapter 10.
10TCP/IP Reporting Chap 10With Hiperstation for Mainframe Servers, you can generate basic, predefined reports and build custom reports that contain information you specify.
Both custom and basic report generation require the same steps. However, assets necessary to generate basic reports are much easier to build. In fact, Hiperstation provides sample reporting assets for each basic report. This chapter describes how to generate both types of report.
Reporting OverviewGenerating reports requires collecting data from an unattended playback job, sorting the collected data, and submitting a report generation job. After you have a sorted data collection, you can generate as many reports as needed at any time. You can even generate reports that compare data from different playback jobs. See Chapter 9, “TCP/IP Unattended Playback” to learn about collecting, sorting, and saving unattended playback data.
A reporting job is controlled by the following input statements:
• CONTROL statements (optional), which provide general processing information for a group of reports.
• REPORT statements, which define the information to report and potentially the layout of the report.
Store these statements in members of the system-level reporting library or your personal reporting library. Plug the library and member names into any of the sample reporting jobs that Hiperstation provides, modify or insert necessary DD statements, and submit the job. The rest of this section provides general instructions for creating reports. Each step includes a cross-reference to the section detailing the given task.
To set up and run a reporting job using any of the sample reporting jobs:
1. Verify that the assets in the system-level reporting control library suit your needs. If necessary, build additional assets and store them in either the system-level or your personal library. See “Creating and Managing Reporting Control Assets” on page 10-2.
2. Select the appropriate sample reporting job and customize as necessary. See “Preparing the Reporting Job” on page 10-13.
– Add a job card.
– Edit the values of the SET statements at the top.
– Supply a DD statement for each REPORT statement in the REPORT member that is to be written to a dataset or HFS file.
Note: Do not add a DD statement for reports written to SYSOUT. The ESREPT1 reporting procedure supplies a SYSOUT DD statement.
– To run a baseline report (a report that compares two databases), supply a DD statement for the baseline database.
10-2 Hiperstation for Mainframe Servers User Guide
– To mask information for an HTML Exception Report, supply a DD statement for each masking statement dataset to be used during the reporting job.
Note: Each sample reporting job provides DD statements corresponding to the parameters on the REPORT statements in the specified report member. Modify if necessary.
3. Submit the Job. See “Submitting the Job” on page 10-16.
Creating and Managing Reporting Control AssetsHiperstation provides a system-level report control library complete with several types of reporting assets:
• Sample JCL to generate basic reports• REPORT statements• CONTROL statements
Table 10-1 lists the contents of the system-level reporting library.
Table 10-1. Contents of System-Level Reporting Library
Samples Description
ESREPT1 JCL Procedure to Run Sample TCP/IP Reports
ESRJCL1 JCL to Produce TCP/IP Exception Report
ESRJCL2 JCL to Produce TCP/IP Exception Report with Baseline
ESRJCL3 JCL to Produce TCP/IP Exception Report with Masking
ESRJCL4 JCL to Produce TCP/IP Response Time Report
ESRJCL5 JCL to Produce TCP/IP Script Time Report
ESRCTH CONTROL Statement to Produce TCP/IP Basic Reports in HTML Format
ESRREXCB REPORT STATEMENT for TCP/IP Exception Report w/Baseline
ESRREXCM REPORT STATEMENT for TCP/IP Exception Report w/Masking
ESRREXCP REPORT Statement for TCP/IP Exception Report
ESRRRESP REPORT Statement for TCP/IP Response Time Report
ESRRSCRT REPORT Statement for TCP/IP Script Time Report
NONE Report CONTROL member to Specify No CONTROL Statement
Each sample reporting job (ESRJCL*) contains a series of SET statements that identify the assets to use for the job. Use these sample jobs to generate basic reports with the parameters defined in the specified sample assets or to modify the SET statements to use the assets you create. For example, use ESRJCL1 to generate a standard HTML exception report or modify the SET statements to generate any report you need.
Organize your personal report control library as follows.
• One member for each report or set of reports to generate in a given job. • One member for each report CONTROL statement.
Note: You can also store CONTROL statements directly in the reporting members, if necessary. See the “CONTROL Statement” discussion for details.
Reporting CONTROL statements apply to both basic and custom reports. Basic REPORT statements require parameters specific to the basic report you are generating while custom REPORT statements offer a variety of parameters that apply to all custom reports.
TCP/IP Reporting 10-3
This section provides syntax diagrams accompanied by parameter descriptions for each reporting control statement.
CONTROL Statement
Reporting CONTROL statements are optional. They provide processing information for a group of REPORT statements. For example, to run several reports of the same type, set the report type on the CONTROL statement so you do not have to specify it on each REPORT statement.
Most of the parameters available on CONTROL statements are also available on REPORT statements. If the same parameter is defined on both the CONTROL and REPORT statements, the REPORT statements take precedence. For example, if CONTROL specifies table and REPORT specifies form, then form is used instead of table.
Store each CONTROL statement in a separate member to apply the statement to an entire reporting job. When you use one of the sample jobs to generate your reports, Hiperstation assembles the statements from specified CONTROL and REPORT members in the appropriate order. For example, if your REPORT member contains two REPORT statements, Hiperstation assembles the input statements as:
CONTROL REPORT REPORT
However, if you are generating several reports in a given job, you may need multiple CONTROL statements — one for each group of reports. In this case, store the CONTROL statements in the reporting member itself. Be sure to position the CONTROL statement before the applicable REPORT statements.
For example, to run three reports with one set of processing options and two with another, you can:
• Create two REPORT members, A and B, each containing the applicable REPORT statements. Create two CONTROL members, Table and Form, each containing a single CONTROL statement. Then run two reporting jobs.
Job1 Processes: Job2 Processes:
CONTROL (from member Table) REPORT (from member A) REPORT (from member A) REPORT (from member A)
CONTROL (from member Form) REPORT (from member B) REPORT (from member B)
Although this may be more work initially, the CONTROL and REPORT members are independent assets that are easily reusable.
• Create one REPORT member containing both CONTROL statements, each followed by the applicable REPORT statements, and run a single reporting job.
Job1
CONTROL REPORT REPORT REPORT CONTROL REPORT REPORT
This may be less work initially, however, you cannot use the CONTROL statements and REPORT member as independent assets for future reporting jobs.
10-4 Hiperstation for Mainframe Servers User Guide
• Create one REPORT member containing REPORT statements that provide all of the necessary processing parameters and run a single job.
Note: The CONTROL statement provides additional processing options that are not available on the REPORT statements. This method only works if you do not require any of those options.
If you specify a CONTROL member and a REPORT member containing CONTROL statements, Hiperstation uses the statements in the REPORT member.
Note: If two or more consecutive CONTROL statements precede the REPORT statements, Hiperstation uses the last statement listed.
The following syntax diagram shows all of the parameters available on the CONTROL statement. Each is optional. LAYOUT and TYPE are also available on REPORT statements.
DATABASE(DATABASE|ddname)
Follow the DATABASE parameter with the DD name for the collected, sorted data to use for report generation. DATABASE is the default value. The ESREPT1 procedure, used by the sample jobs, supplies a DD statement that defines the SET SORTED dataset as “DATABASE”. Thus, the default should suffice if you did not alter the DD statement in the procedure.
Note: If you are running reports that compare two data collections, specify the additional databases with REPORT statement parameters. See “HTML Exception REPORT Statement” on page 10-6 or “REPORT Statement for Custom Reports” on page 10-9.
LAYOUT(TABLE|FORM)
LAYOUT specifies whether the report type will be TABLE or FORM.
TABLE produces a row, column oriented report (Figure 10-1). If you do not specify a layout, TABLE is used.
Note: TEXT reports with a table layout will print a maximum of six fields. HTML reports with a table layout will print a maximum of 32 fields.
FORM produces a line based report (Figure 10-2).
Figure 10-1. Sample Message Report in Table Layout
Hiperstation for Mainframe Servers - Message Report Date: 07/28/06 07:48 Page: 1 --------------------------------------------------------------------------------------- MessageID SocketsNumber MessageStartTime MessageFinishTime --------------------------------------------------------------------------------------- 4 1 2006/07/21_15:10:37.290 2006/07/21_15:10:38.052 6 1 2006/07/21_15:10:39.409 2006/07/21_15:10:39.938 9 1 2006/07/21_15:10:40.913 2006/07/21_15:10:42.170 ******************************** BOTTOM OF DATA ***************************************
TCP/IP Reporting 10-5
Figure 10-2. Sample Message Report in Form Layout
Hiperstation for Mainframe Servers - Message Report Date: 07/28/06 07:48 Page: 1 --------------------------------------------------------------------------------------- MessageID 4 --------------------------------------------------------------------------------------- SocketsNumber 1 --------------------------------------------------------------------------------------- MessageStartTime 2006/07/21_15:10:37.290 --------------------------------------------------------------------------------------- MessageFinishTime 2006/07/21_15:10:38.052 --------------------------------------------------------------------------------------- Hiperstation for Mainframe Servers - Message Report Date: 07/28/06 07:48 Page: 2 --------------------------------------------------------------------------------------- MessageID 6 --------------------------------------------------------------------------------------- SocketsNumber 1 --------------------------------------------------------------------------------------- MessageStartTime 2006/07/21_15:10:39.409 --------------------------------------------------------------------------------------- MessageFinishTime 2006/07/21_15:10:39.938 --------------------------------------------------------------------------------------- Hiperstation for Mainframe Servers - Message Report Date: 07/28/06 07:48 Page: 3 --------------------------------------------------------------------------------------- MessageID 9 --------------------------------------------------------------------------------------- SocketsNumber 1 --------------------------------------------------------------------------------------- MessageStartTime 2006/07/21_15:10:40.913 --------------------------------------------------------------------------------------- MessageFinishTime 2006/07/21_15:10:42.170 ---------------------------------------------------------------------------------------
TYPE(TEXT|CSV|HTML)
Follow TYPE with either TEXT, HTML, or CSV (comma separated value). You can generate custom reports in any of these formats. Some basic reports support only HTML, others support TEXT and HTML. Basic reports do not support CSV format. Refer to the REPORT statement for the desired basic report. If you do not specify a type, TEXT is used.
Note: For TEXT and CSV reports, make sure the LRECL of the dataset you allocate for the report is equal to or larger than the longest message reported. Hiperstation truncates or wraps messages exceeding the dataset’s LRECL.
BREAK(EJECT|NEXT)
BREAK only applies to TEXT and HTML reports with a FORM layout. For:
– TEXT reports, follow the parameter with EJECT to begin each record on a new page, or NEXT to continue reporting on the next line.
– HTML, follow the parameter with EJECT to begin each record in a new HTML table or NEXT to continue reporting on the next line of the same HTML table.
Note: HTML FORM reports are displayed in HTML tables.
If you do not specify breaking conditions, EJECT is used.
MAXLINES(60|n)
MAXLINES only applies to TEXT reports. Follow MAXLINES with the maximum number of lines to print on each page. The value must be between 30 and 9999. If you do not specify MAXLINES, 60 is used.
10-6 Hiperstation for Mainframe Servers User Guide
FIELDDEPTH(99|n)
FIELDDEPTH only applies to TEXT and CSV reports. Use it to truncate the printing of large fields, some of which may contain up to two gigabytes of data. Follow FIELDDEPTH with the number of lines of message data to print. For example, FIELDDEPTH(1) results in one line of data per message.
REPORT Statements for Basic Reports
Hiperstation offers the following basic reports:
• HTML Exception Report: Compares the response messages and reports differences.
– A standard exception report compares “actual” response messages to “expected” response messages from a single data collection.
– A baseline exception report compares “actual” response messages from two data collections. The baseline “actuals” are used as “expected” values for comparison.
• Response Time Summary: Reports the amount of time it took each group of related messages to occur (for example, the time that elapsed from the first byte of the request to the last byte of the response).
• Script Time Summary: Reports the time it took for each script to play back and provides additional timing statistics for the playback job.
HTML Exception REPORT Statement
The following syntax diagram shows all of the parameters available on the REPORT statement for the HTML Exception Report. See “HTML Exception Report” on page 10-17 for a report sample and detailed information including field definitions. Also, refer to your system-level reporting control library, members: ESRREXCP (standard exception report statement sample), ESRREXCB (baseline exception report statement sample), ESRREXCM (exception report with masking sample).
COMPARE
The COMPARE parameter is required to generate an HTML Exception Report.
BASELINE(ddname)
Use the optional BASELINE parameter to identify the DD name of the baseline database to use for comparison. If you do not specify a baseline, the report compares the “actual” responses to “expected” responses from the data collection specified on the SET SORTED statement in the reporting job. That is, it reports the differences between the responses resulting from playback to the responses recorded in the script.
Note: Sample job ESRJCL2 provides a corresponding DD statement that you complete with the dataset name of the baseline database.
MASK(ddname)
Use the optional MASK parameter to identify the DD name of the masking statement or the sequential dataset or PDS member containing the masking statements. Masking statements prevent specified information from being compared. See “Masking Statements” on page 10-7.
TCP/IP Reporting 10-7
Note: Sample job ESRJCL3 generates five reports, each with different masking. It provides DD statements corresponding to the MASK(ddname) parameters specified on the REPORT statements. Each DD statement is followed by an in-line masking statement. If you store your masking statements in a dataset, modify the first DD statement to point to that dataset and optionally delete the additional DD statements.
STOPON(n)
Use the optional STOPON parameter to automatically end report generation after the specified number of mismatches have occurred. For example, if you specify STOPON(5), Hiperstation stops reporting after the fifth mismatch. Valid values are 1 to 9999.
TITLE(‘title’)
Use the optional TITLE parameter to specify a title to appear at the top of the report and in the title bar of the browser window. If you do not specify a title, the report is titled “Hiperstation for Mainframe Servers - Exception Report”.
INTO(ddname)
Use the INTO parameter to specify the DD name of the HFS file to write the HTML report to. This parameter is required.
Note: Each of the sample jobs supplies DD statements corresponding to the INTO(ddname) parameters specified on the REPORT statements. Customize these statements with your pathnames.
Masking Statements
Use data masking to prevent comparison of specified TCP/IP message data. For example, mask date and time fields to prevent generating mismatches for data that you expect to be different. Data masks are statements that specify qualification criteria and stipulate the positions to mask if the criteria is met. Each statement consists of a WHEN and a MASK clause.
Store all of the masking statements for a given report in a sequential dataset or PDS member. Specify a DD name on the MASK parameter of the REPORT statement. In the reporting job, supply a corresponding DD statement that points to the dataset.
Note: If you only need to apply a single masking statement to the report, you can write it directly into the reporting job as shown in sample job ESRJCL3. However, storing it in a dataset allows you to reuse it for subsequent reporting jobs.
If a given dataset contains multiple statements, Hiperstation applies the masking specification from the first true statement. The statement must be true for both the “actual” and “expected” messages in order for the mask to apply.
Note: In a baseline report, Hiperstation uses the “actuals” from the baseline as the “expected” values for the comparison.
Only one masking statement is applied to a given set of “actual” and “expected” messages. After a statement is applied, Hiperstation processes the next “actual” and “expected” message in the collected data.
The syntax of a masking statement is as follows:
WHEN(POSITION1, RO, VALUE) MASK(POSITION2:LENGTH2, ...)
POSITION1
Specify the starting position of the data to evaluate for masking qualification.
10-8 Hiperstation for Mainframe Servers User Guide
RO
Specify the relational operator (RO) to use for qualifying data for masking. You may use either the RO code or symbol. Valid operators for:
– Character, Hexadecimal, or Packed Decimal data are:
Conditional RO Codes RO Symbol Description RO
EQ = Equal To
NE \= Not Equal
LT < Less Than
GT > Greater Than
LE <= Less Than or Equal To
GE >= Greater Than or Equal To
– Binary data are:
BIT RO Codes RO Symbol Bit RO
EQ = Specified bits are all ones
NE \= Specified bits are all zeros
NO not applicable Specified bits are not all ones
NZ not applicable Specified bits are not all zeros
MX not applicable Specified bits are mixed ones and zeros
VALUE
Specify the data value that completes the comparison argument. If the argument is true, Hiperstation masks the data specified by the MASK clause. Place the value in single quotations and precede it with one of the following data type indicators:
– C (character), for example, C'Smith' Character mask values are case-sensitive. For example, messages containing Smith match the mask value above, while message containing SMITH do not.
– X (hexadecimal), for example, X'0CDF' Hexadecimal masking values must consist of an even number of hexadecimal digits (0-9, A-F).
– P (packed decimal), for example, P'0001' Packed decimal mask values must consist of decimal digits and may be preceded by an optional sign (+-). Additionally, they must be fewer than 32 bytes.
– M (binary masks), for example, M'11000000' Binary mask values must consist of eight binary digits that identify the bits within the specified byte (POSITION1 in WHEN clause) to consider for masking. In the example above, Hiperstation will examine the first two bits of the specified byte.
POSITION2:LENGTH2
Specify the starting position and length of the data to mask. Specify multiple positions and lengths by inserting a comma between each POSITION:LENGTH parameter. For example, the following masking statement masks columns 4 through 11, 45 and 46 when columns 5 and 6 contain 03.
WHEN(5, EQ, C'03') MASK(4:8, 45:2)
Set length to 0 (zero) to mask the remainder of the message.
TCP/IP Reporting 10-9
Response Time and Script Timing REPORT Statements
The REPORT statements for the Response Time and Script Timing Reports are virtually the same except for the basic REPORT keyword.
The following syntax diagram shows all of the parameters available on the basic REPORT statement.
For basic reports, follow REPORT with RESPONSETIME to generate a Response Time Summary report or SCRIPTTIME to generate a Script Timing Summary report. See “Script Timing Summary” on page 10-20 and “Response Time Summary” on page 10-22 for a sample of each report and detailed information including field definitions. Also, refer to your system-level reporting control library, members: ESRRRESP (response time report statement sample) and ESRRSCRT (script time report statement sample).
TYPE(TEXT|HTML)
Use the optional TYPE parameter to specify the format (TEXT or HTML) of the report file. If you do not specify a type, Hiperstation uses the type specified on the CONTROL statement if it is either HTML or TEXT. If CSV is specified on the CONTROL or REPORT statement, you will receive an error. If you do not specify a type on the CONTROL or REPORT statement, or you are not using a CONTROL statement, TEXT is used.
Note: If you generate a Text version of the report, be sure the logical record length (LRECL) of the reporting dataset is at least 133.
TITLE(‘title’)
Use the optional TITLE parameter to specify a title that will appear at the top of the report. The title will appear in the title bar of the browser window if you are generating an HTML report. If you do not specify a title, the report will be called “Hiperstation for Mainframe Servers - Response Time Summary” or “Hiperstation for Mainframe Servers - Script Timing Summary” depending on the basic report keyword you select.
INTO(ddname)
Use the INTO parameter to specify the DD name for the dataset or HFS file that the report will be written to. This parameter is required.
Be sure there is a corresponding DD statement in the reporting job. If your destination is SYSOUT, do not add a DD statement. The reporting procedure supplies a DD statement for SYSOUT.
REPORT Statement for Custom Reports
Just as there are five collection and reporting tables, there are five types of custom reports:
• PLAYBACK reports• SOCKETS reports• SCRIPT reports• CONNECTION reports• MESSAGE reports
10-10 Hiperstation for Mainframe Servers User Guide
Your report can contain any combination of the fields from a given collection and reporting table if you collected and saved the fields during unattended playback. For example, report all fields from the PLAYBACK table to produce a Playback Summary. See Appendix A, “TCP/IP Data Collection and Reporting Tables” for a list of the fields available for each report type.
Although you cannot include fields from multiple tables on a single report, you can generate multiple reports from the same data collection in the same reporting run. For instance, you cannot include a PLAYBACK field on a SOCKETS report, but you can generate a PLAYBACK report and a SOCKETS report from the same data collection at the same time. Create a REPORT statement for each report and save them in the same reporting member. Then use one of the sample reporting jobs to generate the reports.
You can build custom comparison reports by including the same reporting fields from multiple unattended playback data collections. Qualify comparison fields with the DD names of the applicable data collection. For example, to compare the message counts from three playback data collections with DD names PLAY1, PLAY2, and PLAY3, create a report member containing the following statement and store it in your reporting control library:
REPORT FIELDS(- MESSAGESETCOUNT,- PLAY1.MESSAGESETCOUNT,- PLAY2.MESSAGESETCOUNT- )- FROM(CONNECTION) INTO(SYSOUT)
Use this reporting member in a reporting job that uses the third data collection. That is, the SET SORTED statement at the top of the job is set to PLAY3. See “Preparing the Reporting Job” on page 10-13.
The following syntax diagram shows all fields available on the custom REPORT statement.
Note: TEXT reports in table layout print a maximum of six fields. HTML reports in table layout print a maximum of 32 fields. Consider breaking large reports into several smaller reports to support printing or viewing them with standard paper or terminal size.
TCP/IP Reporting 10-11
10-12 Hiperstation for Mainframe Servers User Guide
LAYOUT(value from CONTROL LAYOUT|TABLE|FORM)
LAYOUT specifies whether the report will be in table (row, column) or form (one line per record) format. Figure 10-1 and Figure 10-2 on page 10-5 show the same report in both TABLE and FORM layout.
TYPE(value from CONTROL TYPE|TEXT|HTML|CSV)
TYPE specifies the format of the report — either Text, HTML, or CSV. Text reports are written in EBCDIC and the LINK function is not valid. HTML reports support the LINK function, which tells Hiperstation to write that field’s value to a separate file. A reference to that separate file appears in the HTML report as a link.
TITLE(‘title’)
Use the optional TITLE parameter to specify a title for the report. If you do not specify a title, then the report is titled “Hiperstation for Mainframe Servers - Table Report”, where Table is the collection and reporting table specified on the FROM clause.
FIELDS
See Appendix A, “TCP/IP Data Collection and Reporting Tables” to select the fields you wish to report. In order to report a field, you must have collected it during unattended playback. Even if you collected all possible fields, every field is not always available for reporting. For example, message header fields cannot be sent by an application during a particular transmission, and therefore would not be available to put in a report.
Use long or short field names to specify the fields to include in the report. The field labels in the report appear as specified on the statement. For example, if the statement includes short field names, the report will contain short field names. Additionally, the fields appear in the report in the same order as specified on the REPORT statement.
To report on every available field for a given table, use an asterisk (*) on the FIELDS parameter - FIELDS(*).
Built-in function fields (AVG, MIN, MAX, SUM, etc.) are not automatically included by using FIELDS(*). These fields must be explicitly requested in the format FIELDS(*,AVG(xxxx)).
TCP/IP Reporting 10-13
Any field names not fully qualified with a database name use the database name supplied on the FROM keyword. If no database name is available on the FROM keyword, the value supplied, or defaulted, by CONTROL DATABASE is used.
FROM
FROM specifies the type of report to produce. The table name specified in the FROM keyword is used to resolve field names specified by FIELDS(*) and to validate the field names specified in the FIELDS keyword. The optional database qualifier can be used as explained in the FIELDS description.
WHERE
Use the WHERE clause to provide criteria for reporting only the data you need. For example, to report all fields from the MQGROUP table for the second of five groups in the reporting job, construct the REPORT statement as:
REPORT FIELDS(*) FROM(SOCKETS) WHERE(SocketNumber 2)
SUBSTR
Produces a substring of the first argument. The second argument is the starting position of the substring, and may have a minimum value of one (1). The third argument is optional and is the length of the substring. If it is absent, the remainder of the string is the new substring. The behavior of the SUBSTR function matches the behavior of the REXX SUBSTR function.
The SUBSTR function is only valid on character fields. Other usage causes an error at statement parsing time and ends the reporting jobstep.
SUBSTRX
The SUBSTRX keyword works the same way as the SUBSTR keyword, but displays the value of the argument in hexadecimal characters.
DIFFERENCE
(DIFF) produces a number indicating the first byte position in a string that is different from another string. The two arguments are the byte strings to be compared. The strings may contain any values, including non-printable characters. Two strings that are identical result in a value of zero (0). The SUBSTR and DIFFERENCE functions may be nested as “DIFFERENCE(SUBSTR(...))”.
LINK
Indicates that a field’s value should be shown as an HTML link in a report rather than shown directly in the report. There is an exception for a non-HTTP protocol report. The LINK field with message headers and bodies (RQHS-RequestHeaders, RSHS-ResponseHeaders, EXHS-ExpResponseHeaders, RQBD-RequestBody, RSBD-ResponseBody and EXBD-ExpResponseBody) for non-HTTP protocol will be displayed in four-line hexadecimal format. If LAYOUT(FORM) is specified, it will be displayed with IFORM so that it will be shown in the message report itself. The SUBSTR and LINK functions may be nested as “LINK(SUBSTR(...))”.
Note: Use of LINK in the WHERE clause is invalid. It is only valid as described.
Preparing the Reporting JobHiperstation provides the following sample reporting jobs:
• ESRJCL1 — Generates a standard HTML Exception Report.
• ESRJCL2 — Generates a baseline HTML Exception Report.
• ESRJCL3 — Generates a standard HTML Exception Report with masking.
• ESRJCL4 — Generates a Response Time Summary Report.
10-14 Hiperstation for Mainframe Servers User Guide
• ESRJCL5 — Generates a Script Timing Summary Report.
Each of these samples contains a series of SET statements that identify the reporting assets to use for the job. They also supply DD statements corresponding to the applicable REPORT statement parameters. Although these samples support generating specific basic reports, you can use any sample to generate any type of report. This section explains how to prepare a reporting job.
To prepare a reporting job:
1. Open one of the sample reporting jobs in an ISPF Edit session. Figure 10-3 on page 10-15 shows sample job ESRJCL4.
2. Insert a job card at the top of the sample.
3. Edit the values of the SET statements. See the SET statement definitions following the reporting job sample illustration.
4. Each sample job provides DD statements that correspond to the applicable parameters on the REPORT statement from the specified reporting member. Modify these statements to point to your datasets or HTML files.
If you plug your own reporting assets into the SET statements, insert DD statements for each:
– REPORT statement in the specified REPORT member that is to be written to a dataset for HFS file. Do not add DD statements for reports written to SYSOUT. The reporting procedure ESREPT1 provides a DD statement for SYSOUT.
– Baseline database that is to be used for comparison reports.
– Masking statement dataset that is to be used for an HTML Exception Report.
Refer to the “flower box” showing a sample DD statement defining an HFS path and a sample statement defining a dataset.
5. When finished preparing the JCL, submit the job. See “Submitting the Job” on page 10-16.
TCP/IP Reporting 10-15
Figure 10-3. Sample Reporting Job ESRJCL4
********************************* Top of Data ********************************** //* INSERT JOB CARD HERE.................... //* //UPROCS JCLLIB ORDER=('COMPWARE.QQF800.SQQFSAMP') //* //********************************************************************** //* * //* JCL TO CREATE A TCP/IP RESPONSE TIME REPORT TO A HFS FILE. * //* THIS WILL ALLOW USERS TO VIEW THE REPORT WITH A WEB BROWSER * //* * //* TCP/IP RESPONSE TIME REPORT PRODUCED FROM THE DATABASE DATASET * //* IDENTIFIED BY THE SET STATEMENT //SET SORTED= * //* * //********************************************************************** //* //********************************************************************** //* //* INSTRUCTIONS: //* //* 1) ADD JOBCARD //* 2) UPDATE THE UPROCS STATEMENT TO THE DATASET CONTAINING ESREPT1 //* 3) PROVIDE DSN FOR REPTDS - REPORT CONTROL CARD DATASET //* 4) PROVIDE DSN FOR SORTED - SORTED DATABASE PRODUCED BY PLAYBACK //* 5) REVIEW REPORT.OUTHTML DDCARD - SUPPLY HFS PATH NAME //* 6) SUBMIT JOB //* //* NOTE: SET STATEMENTS REQUIRE UPPER CASE //* //********************************************************************** //* EXEC PROC TO PROCESS LOG/SORT/REPORT * //********************************************************************** //* // SET EXEC=ESREPT1 // SET REPTDS=COMPWARE.QQF800.ES.REPORT // SET SORTED=customer.sorted.database // SET REPTCNTL=ESRCTH // SET REPTMEM=ESRRRESP //* //ANALYZE EXEC PROC=&EXEC //* //********************************************************************** //* * //* TO ADD ADDITIONAL REPORT OUTPUT DATASETS, USE THE FOLLOWING * //* HFS OR MVS DATASET MODEL CHANGING THE ddname TO THE NAME * //* SPECIFIED ON THE REPORT INTO() STATEMENT * //* * //* //REPORT.ddname DD PATHMODE=(SIRWXU,SIRGRP,SIROTH), * //* // PATHOPTS=(ORDWR,OCREAT), * //* // PATH='/hfs/path/reptname.htm' * //* * //* or * //* * //* //REPORT.ddname DD DISP=SHR,DSN=sysout.dataset.name * //* * //********************************************************************** //* //********************************************************************** //* * //* REPORT DD'S FOLLOW. REPORT DDNAMES ARE SPECIFIED IN REPORT * //* CONTROL MEMBER ESRRRESP SPECIFIED ON THE REPTMEM SET STATEMENT * //* * //********************************************************************** //* //REPORT.OUTHTML DD PATHMODE=(SIRWXU,SIRGRP,SIROTH), // PATHOPTS=(ORDWR,OCREAT), // PATH='/hfs/path/resptime.htm'
SET Statement Definitions
SET EXEC
Identifies the JCL procedure to use for the reporting job. All samples specify ESREPT1. If necessary, override with your own procedures.
10-16 Hiperstation for Mainframe Servers User Guide
SET REPTDS
Identifies the report control library containing the assets you are using for the job. This statement must point to the library where the REPORT and report CONTROL members specified on the SET REPTCNTL and SET REPTMEM statements reside.
SET SORTED
Identifies the database to use for reporting. Complete this statement with the name of the dataset that was collected and sorted during an unattended playback job. The ESREPT1 procedure assigns DD name DATABASE to the dataset you plug in here.
Note: “DATABASE” is the default DD name on the DATABASE parameter of the reporting CONTROL statement.
SET REPTCNTL
Identifies the report CONTROL member to use for the job. Each sample job specifies sample member ESRCTH, which produces an HTML report in table format. Override it with:
– Any report CONTROL member stored in the library specified on the SET REPTDS statement.
– NONE if a reporting CONTROL member is not required. If the specified REPORT member provides all of the necessary control information, a report CONTROL member is not necessary.
SET REPTMEM
Identifies the REPORT member to use for the job. Each sample job supplies a sample member from the system-level reporting library. “Creating and Managing Reporting Control Assets” on page 10-2, provides a list and description of each sample asset. Plug in the name of the desired reporting member from the library specified on SET REPTDS.
Submitting the JobTo submit the reporting job, open the log file in an ISPF Browse or Edit session, type SUBMIT on the Command line, and press Enter.
In the message report for the protocol ECI and TCP, the contents of RQBD, RSBD, and EXBD can contain either EBCDIC or ASCII data. By providing a PARM '-O1', the message report can be generated with the opposite encoding.
When the executed JCL is still available in SDSF after submit, edit the JCL and add PARM '-O1' as follows:
change
//REPORT EXEC PGM=TCPPBRPT,REGION=4M
to
//REPORT EXEC PGM=TCPPBRPT,REGION=4M,PARM='-O1'.
This JCL line is located in the ESREPT1 member.
For an ECI message report, LINK(RQBD), LINK(RSBD) and LINK(EXBD) retain their original codepage if the content is ASCII, and as a result, the HTML report on the Web will display with the Windows codepage. The link file is defined with an .eci extension. By setting the file type for .eci to notepad in folder options, the link will automatically open notepad with .eci files.
TCP/IP Reporting 10-17
Reading and Navigating Basic ReportsThis section provides report samples and detailed information including field definitions for each of the basic reports.
HTML Exception Report
A standard HTML Exception Report compares the TCP/IP response messages that occurred during playback (“actual”) to the response messages recorded in the script (“expected”).
A baseline HTML Exception Report compares “actual” response messages from two unattended playback data collections. The “actuals” from the baseline database are used as “expected” values for comparison.
Note: In an offline playback, the response messages in the script are the “actuals”. In an online playback job, the response messages that resulted from the playback are the “actuals”.
An HTML Exception Report provides a summary of mismatches at the top of the report followed by the “actual” and “expected” messages with highlighted differences. The messages in the summary are hyperlinked to the messages in the detail. Depending on the content of the script or the structure of the application you are testing, the report may also include the request message related to the reported response messages.
Note: The report requires collecting several fields from several reporting and collection tables. Collect all fields from all tables to ensure the necessary data is available for this or any other report. See Chapter 9, “TCP/IP Unattended Playback”.
View the report with a supported Web browser. Scroll up and down to view the entire report or click a message number in the summary to see the mismatch detail for that message.
Figure 10-4 shows a mismatch summary and Figure 10-5 on page 10-19 shows the corresponding mismatch detail.
Figure 10-4. HTML Exception Report Mismatch Summary (Top of Report)
Field Definitions
The title specified on the REPORT statement or the default report title (Hiperstation for Mainframe Servers - Exception Report) appears across the top of the window and in the title bar. The following fields provide information about the playback job. In a baseline report, they come from the database entered on the SET SORTED statement in the log file.
10-18 Hiperstation for Mainframe Servers User Guide
Run Date
The date and time that the unattended playback job was executed.
SYSID
The LPAR where the playback job was executed.
Jobname
The playback job name.
Jobnumber
The playback job number.
Socket Number
The number of the socket the message was played back in. Sockets are numbered sequentially.
Script Number
The number of the script containing the reported message. Scripts are numbered sequentially within the SOCKET.
Script Name
The name of the script containing the reported message.
Connection ID
The connection number where the reported message occurred. Connection IDs are numbered sequentially in the script.
Message Number
The reported message’s number. Messages are numbered sequentially within a Connection ID.
Server IP Address and Port
Server address and port where the reported message was played back. For offline playback jobs, this is the address and port where the reported message occurred during recording. IPv6 and IPv4 IP address formats are both valid.
Client IP Address and Port
Client address and port where the reported message was played back. For offline playback jobs, this is the address and port where the reported message occurred during recording. IPv6 and IPv4 IP address formats are both valid.
Bypassed Fields Message
If any messages were not compared, an error message appears after the summary with a bypassed message count. Hiperstation bypasses a message if no corresponding message to compare it against exists. For example:
– If a connection fails during playback, there is no “actual” response to collect. Since there is no “actual” response, the message is bypassed.
– If one data collection, in a baseline report, contains more messages than the other, the additional messages are bypassed.
TCP/IP Reporting 10-19
Figure 10-5. HTML Exception Report Mismatch Detail
Field Definitions
Each group of “expected” and “actual” messages is preceded by the associated Sockets Number, Script Number, Script Name, Connection ID, Message Number, Server IP Address and Port, and Client IP Address and Port. These are the same fields presented in the summary at the top of the report. See “Field Definitions” on page 10-17. Additionally, all fields displayed under the “expected” message also display under the “actual” message. Although the values they present may be different, the field definitions are the same.
Expected Response Message
The “expected” TCP/IP response message. In a standard exception report, this comes from the script. In a baseline report, this comes from the baseline data collection. If the baseline was generated from an:
– Online playback, this is the response message that resulted from the playback.– Offline playback, this is the response message from the script.
Mismatches are highlighted. Masked information displays in green text.
Response Body Byte Count
The number of bytes in the “expected” response message.
Response Status Code
The “expected” message’s TCP/IP Status Code.
Response Reason Phrase
The “expected” message’s TCP/IP Reason Phrase.
Response Headers
The “expected” message’s HTTP response header information.
10-20 Hiperstation for Mainframe Servers User Guide
Actual Response Message
The “actual” TCP/IP response message. In a standard exception report, this is the response message that resulted from the playback. In a baseline report, this comes from the baseline data collection. If the baseline was generated from an:
– Online playback, this is the response message that resulted from the playback.– Offline playback, this is the response message from the script.
Mismatches are highlighted. Masked information displays in green text.
Message Start Time
The date and time the reported message was received.
Actual Request Message
The TCP/IP request message related to the preceding response messages. This section only appears if there is a correlating request message.
Note: Figure 10-5 on page 10-19 does not show an “Actual Request Message”.
Script Timing Summary
A Script Timing Summary Report shows the amount of time it took for each script to play back and provides additional timing statistics for the playback job.
Generate an HTML or TEXT version of the report. View the HTML version with a supported Web browser.
Figure 10-6 shows an HTML Script Timing Summary followed by field definitions.
Figure 10-6. HTML Script Timing Summary Report
Field Definitions
The title you specified on the REPORT statement or the default report title, Hiperstation for Mainframe Servers - Script Timing Summary Report, displays across the top of the report. In an HTML version, the report title also appears in the title bar of the browser window.
Run Date
The date and time that the playback job was executed. This field only appears on the HTML version of the report.
Note: The Text version of the report includes the date and time the report was generated.
TCP/IP Reporting 10-21
SYSID
The LPAR where the playback job was executed. This field only appears on the HTML version of the report.
Jobname
The playback job name. This field only appears on the HTML version of the report.
Jobnumber
The playback job number. This field only appears on the HTML version of the report.
Socket Number
The number of the SOCKET that the reported script was played back in. Sockets are numbered sequentially.
Script Name
The name of the script.
Number
The number of the script being reported. Scripts are numbered sequentially within SOCKETS.
Start Time
The date and time playback began for the given script.
Finish Time
The date and time playback completed for the given script.
Duration
The amount of time it took for the given script to play back.
Socket Total
A row of statistics for each SOCKET played back.
Number
The total number of scripts within the SOCKET.
Minimum Duration
The shortest playback duration in the SOCKET.
Maximum Duration
The longest playback duration in the SOCKET.
Average Duration
The average of all playback durations in the SOCKET.
Report Total
A row of statistics for the entire playback job.
Number
The total number of scripts played back.
Minimum Duration
The shortest playback duration in the job.
Maximum Duration
The longest playback duration in the job.
Average Duration
The average of all playback durations in the job.
10-22 Hiperstation for Mainframe Servers User Guide
Response Time Summary
A Response Time Summary Report shows the amount of time it took each group of related messages to occur. For example, the amount of time it took to receive the response from the time the correlating request was sent.
You can generate an HTML or TEXT version of the report. View the HTML version with a supported Web browser.
Figure 10-7 shows an HTML Response Time Summary. Field definitions follow the illustration.
Figure 10-7. HTML Response Time Summary Report
Field Definitions
The title you specified on the REPORT statement or the default report title (Hiperstation for Mainframe Servers - Response Time Summary Report) appears across the top of the report. In an HTML version, the report title also appears in the title bar of the browser window.
Run Date
The date and time that the playback job was executed. This field only appears on the HTML version of the report.
Note: The TEXT version of the report includes the date and time the report was generated.
SYSID
The LPAR where the playback job was executed. This field only appears on the HTML version of the report.
Jobname
The playback job name. This field only appears on the HTML version of the report.
Jobnumber
The playback job number. This field only appears on the HTML version of the report.
TCP/IP Reporting 10-23
Socket Number
The number of the SOCKET that the reported script was played back in. Sockets are numbered sequentially.
Script Name
The name of the script.
Connection ID
The number of the connection that the reported message was played back on. Connections are numbered sequentially within the script.
Number
The number of the message being reported. Messages are numbered sequentially within the script.
Start Time
The date and time the reported message began playing back.
Finish Time
The date and time the reply to the message completed.
Duration
The amount of time it took for the given message set to play back.
Total
A row of statistics for the given script.
Number
The total number of messages within the script.
Minimum Duration
The shortest response duration within the script.
Maximum Duration
The longest response duration within the script.
Average Duration
The average of all response durations for the given script.
Socket Total
A row of statistics for each SOCKET played back.
Number
The total number of request/response message sets within the SOCKET.
Minimum Duration
The shortest response duration in the SOCKET.
Maximum Duration
The longest response duration in the SOCKET.
Average Duration
The average of all response durations in the SOCKET.
Report Total
A row of statistics for the entire playback job.
Number
The total number of request/response message sets played back.
10-24 Hiperstation for Mainframe Servers User Guide
Minimum Duration
The shortest response duration in the job.
Maximum Duration
The longest response duration in the job.
Average Duration
The average of all response durations in the job.
11-1
Chapter 11.
11Archive Functions Chap 11Introducing the Archive FunctionHiperstation is a zSeries automated testing solution that enables systems and applications programmers and quality assurance personnel to streamline the testing process and improve the quality of their applications. In addition to automated testing, Hiperstation can address other business issues as well, specifically, security monitoring.
Using Hiperstation as a Security Monitoring Tool
Today's mainframe application organizations use two standard facilities for managing security. First, security systems prevent unauthorized users from logging on and then controlling access privileges of authorized users. Second, monitoring facilities, such as System Management Facilities (SMF), log a variety of activities performed by the user, including opening datasets and logging off. Most organizations have programs that post-process their SMF records to produce audit reports.
Hiperstation can provide what these facilities lack, which is an in-depth record of the detail on each screen the user accessed on their terminal. Hiperstation's Auditing Archive Recording feature allows you to record all users of a given application that you want to monitor, select users across all of the applications that they use, and for VTAM, document each keystroke and screen that the user sees. Hiperstation can be likened to an electronic security camera installed directly behind the user. The user is not aware that the recording is taking place unless the security team chooses to disclose this information.
Hiperstation is the watchdog for users who are able to gain access to the mainframe and are able to navigate throughout the system. Rather than relying only on security violations and SMF records, the Hiperstation script is a true picture of what the user saw and did.
Implementing Hiperstation as a Security Monitoring Tool
Implementing Hiperstation for Mainframe Servers as a security-monitoring tool requires analysis and agreement between management and the system implementation team. You need to decide:
• Whether to monitor all mainframe users or just a selected group of users
• Whether to record groups or users in separate recordings or all together in one
• Whether to record continuously
• Who will be responsible for administering the recording
• Where to store the recorded data and scripts in secured files
• Who will be accountable for the web reports
• How long to store the recorded data
• How to analyze the web reports
11-2 Hiperstation for Mainframe Servers User Guide
After you decide what to do about these issues, an implementation plan can be developed. Although the details will vary slightly, the general task list includes the following items:
• Set up and start Global Recording. Compuware recommends that you integrate the Global Recording Started Task into the IPL process. This allows data capture to begin immediately with any IPL.
• Implement your Archive Audit Request scheme (for example, how many requests record which users, terminals or applications). Use the Name and Description fields to help convey the probable contents of each Archive Audit Request to the users.
• Train your Search users to use the tool effectively (for example, restricting date/time of searches to save processing time and DASD space consumption).
• Ensure that users who plan to execute the Search Tool against the Archive Audit Requests understand the Archive Audit Request schemes.
• Ensure RACF controls are in place to provide proper access protection to the Archive Audit Repositories.
• Encourage Search users to build a repository of shared search criteria wherever possible.
• Set goals for report management (for example, cleanup and final disposition of Web Reports) by the Search users.
Summary
Hiperstation can provide an organization with a comprehensive audit trail of online user activity. Unlike other auditing processes that require looking at security logs and SMF records, Hiperstation provides a complete audit trail of what the user executed on their terminal with the application in question. The Archive Search Web Report capability gives the auditor the ability to step through each screen the user viewed. The auditor will see all traffic for that user from logon to logoff.
The benefit of using Hiperstation for security monitoring can be summed up in two words: maximum accountability. By combining the analysis potential of Hiperstation scripts with existing security tools, the security auditor is able to analyze and quantify the impact of all security breaches.
Figure 11-1. Hiperstation Archive Recording Setup Screen
Hiperstation ------------- 3270 - Archive Criteria ------------------------ Command ===> Press ENTER to continue, or PF1 for help, or CANCEL to exit. Name . . . . . . . . CICSPROD Description. . . . . Capture All Data for Region CICSPROD Repository Registry Dataset. . . ‘CICSPROD.ALLDATA’ Terminal . . . . . . . . . . . * Use an asterisk for wildcarding Application. . . . . . . . . . CICSPROD the Terminal, Application or Userid Userid . . . . . . . . . . . . * fields. OR Global Record Manager List . . Second filter GRM List . . MM / DD / YYYY HH : MM : SS Start Date . . . 00 / 00 / 0000 Start Time . . . 00 : 00 : 00 (Optional) End Date . . . . 00 / 00 / 0000 End Time . . . . 00 : 00 : 00 (Optional)
Archive Functions 11-3
Figure 11-1 shows the Archive Criteria setup screen. In this example, we are capturing all of the activity for our CICSPROD region, regardless of terminal ID or user ID. Notice that there is no specified start or end date or time. Therefore, our recording will continue 24x7 as long as the Global Recording Started Task is running.
We have specified a meaningful NAME and DESCRIPTION for the request. We have also specified a Repository Registry Dataset of CICSPROD.ALLDATA. This name will be used to generate the Registry Dataset (VSAM file containing date/time indexes to the created repository segments). The Repository Registry Dataset name will also be used to generate the dataset names of the repository segments by adding a sequence number to it (for example, #0000001, #0000002, etc.).
Searches can be performed automatically against any repository segment that has filled up and switched, or has been switched manually, with an e-mail notification being sent to the owner of the request.
Note: E-mail notification is set up using Hiperstation profiles. See the Hiperstation Installation Guide for details.
Using the Archive FunctionFor complete details on how to use the Archive Function, see the Hiperstation Auditor User Guide.
11-4 Hiperstation for Mainframe Servers User Guide
12-1
Chapter 12.
12Hiperstation for Mainframe Servers Profile Defaults Chap 12APPC Profile DefaultsThe APPC Record and Script Create Defaults settings allow you to specify only the APPC conversations you want to record by supplying field values that identify those conversations. Only the APPC conversations that match all of your field values will be recorded. The fields are logically linked together using 'AND'.
1. Select option 2 APPC from the Hiperstation Profile screen (Figure 12-1).
Figure 12-1. Hiperstation Profile Screen
Hiperstation -------------- Hiperstation Profile ---------------------------- OPTION ===> More: + Primary commands: menu-number, ALL, CANCEL Line commands: S or / to select options. Active Profile: Dataset ===> 'USER2312.HIPER.PROFILE' Member ===> HIPER Description ===> changed description _ 1 Domain Traveler Recording and Playback defaults _ 2 APPC Global Record and Script Create settings _ 3 3270/LU0 Global Record and Script Create settings _ 4 WebSphere MQ Global Record and Script Create settings _ 5 TCP/IP Global Record and Script Create settings _ 6 Auditing 3270 Auditing defaults for 3270 _ 7 Auditing MQ Auditing defaults for WebSphere MQ _ 8 Auditing TCP/IP Auditing defaults for TCP/IP _ 9 Playback MQ MQ Playback parameter defaults _ 10 Playback TCP TCP Playback parameter defaults _ 11 ATV Manager Test Vehicle defaults Should changes made elsewhere to Profile values be saved? Profile Autosave ===> Y (Y = YES, N = NO OR A = ASK) Should changes made elsewhere to dataset names be saved? DSN Autosave ===> Y (Y = YES, N = NO) Email address: _______________________________________________________________ Codepage: ISO8859-1 Job statement information for batch jobs: ===> //XXXXXXXA JOB ('ACCOUNT',5M-0000),'HIPERSTN', ===> // CLASS=Q,MSGCLASS=R,NOTIFY=&SYSUID ===> //*
> //*
The APPC Record and Script Create Defaults screen appears (Figure 12-2).
Note: For easier display, the initial Profile screens have been combined. Figure 12-1 shows the profile selection screen. The APPC screens in this section have been combined. Figure 12-2 on page 12-2 shows the Record settings and Figure 12-3 on page 12-4 shows the Script Create settings. On your actual screen, press FORWARD (PF8) or BACKWARD (PF7) to view all of the fields.
12-2 Hiperstation for Mainframe Servers User Guide
Figure 12-2. APPC Record and Script Create Defaults - Record Settings
Hiperstation ----- APPC Record and Script Create Defaults ------------------- Profile: HIPER Profile Dataset: 'USER2312.HIPER.PROFILE' OPTION ===> More: + --------------------------------Record settings-------------------------------- Capture Criteria: Side A LU ===> *_______ (Logical unit name or *) Side A Netid ===> ________ Side B LU ===> *_______ (Logical unit name or *) Side B Netid ===> ________ Logmode ===> *_______ (VTAM logmode name or *) User ID ===> *_______ (userid or *) TP Name ===> ____________________________________________________ Start and End times: Date and Time HH : MM : SS MM / DD / YY Start Time ===> 00 : 00 : 00 Start Date 01 / 01 / 07 End Time ===> 00 : 00 : 00 End Date 12 / 31 / 07 Repository Dataset: Dataset Name ===> 'USER2312.HIPER.REPOSIT' First Number ===> ________ (if wildcard in dataset) Last Number ===> ________ (if wildcard in dataset) Recording options: (Enter "/" to select) / Suspend Script Creation / FORCE Request at 'End Time' / Normal Event Notification / Error Event Notification
2. Fill in or change the Record Settings fields. The fields in this group are all optional.
– Side A LU and Side B LU (optional) contain the VTAM LU name for one of the partners that make up the APPC conversation you want to capture. Wild cards are allowed. If you leave both of these fields blank, you will capture all APPC activity on this MVS system. If you enter a value in either the Side A LU or Side B LU field and leave the other blank, then conversations involving the particular LU name will be captured.
– Side A Netid and Side B Netid (optional) contain the VTAM Network ID for the Side A and Side B LU partner. Only supply values for these fields if you want to restrict data capture to APPC conversations between logical units on specific VTAM networks. One of those networks must be the one on which the VTAM on this MVS system is running.
– Logmode (optional) contains the VTAM logon mode name and specifies some of the characteristics of the session.
– User ID (optional) contains the user ID passed between APPC partners when a conversation begins. The user ID is used by one partner to validate the other partner. Since not all APPC conversations pass a user ID, if you enter a user ID value, only those APPC conversations that pass the value will be recorded.
– TP Name (optional) contains the transaction program name. It identifies the program located at the partner's logical unit that is to be run. TP names can be from 1 to 64 characters and can contain non-printable values. If the TP name contains only printable values and no blanks, you can supply the TP name with no quotation marks. If the TP name contains blanks, enclose the TP name in single quotation marks. Letters will not be converted to uppercase since TP names may contain lowercase letters. If the TP name contains non- printable values, type the TP name in hexadecimal, enclose it in single quotation marks and either prefix the first quote or suffix the last quote with the letter X. For example, the CNOS transaction is entered as X'06F1' or '06F1'X.
3. Start and End Date and Time are optional fields that specify the date and time of day that you want the capture request to be started or stopped. If you enter a Start Time you must enter a Start Date. If you enter an End Time you must enter an End Date.
Hiperstation for Mainframe Servers Profile Defaults 12-3
4. Specify your Repository Dataset options.
– Dataset Name is required and specifies where captured data will be stored on DASD. You can enter a fully qualified dataset name up to 44 characters to allocate a fixed repository. You can also enter a dataset name with a wildcard of “*” or “?” to allocate a repository set. This set is defined by a range of numbers specified in the First Number and Last Number fields. Entering an “*” in the dataset name expands the qualifier to eight characters and fills with zeros (for example, xyz* would result in XYZ00001). Entering one or more “?”s in the dataset name replaces those character positions with numbers (for example, XYZ??ABC would result in XYZ01ABC).
– First Number and Last Number define the range of datasets for your repository set. You can enter any range from 0 to 9999999. When one dataset fills up, it is closed and data continues to be written to the next dataset in sequence. These fields are required if you enter a wildcard in the Repository Dataset name field.
5. Specify your Recording options.
Recording options defines the way your capture request will generate scripts, process the repository, stop your requests, and send normal and/or error messages.
Enter a slash (/) to select the following options:
– Suspend Script Creation controls automatic script creation. Enter a slash (/) to defer script creation when your capture request stops. It also defers the entry of script creation criteria to a later time. If you leave this field blank, you will be guided through the script creation criteria screens prior to your capture request being activated, and your scripts will be created automatically when your capture request is stopped.
– FORCE Request at 'End Time' controls whether your capture request is forced rather then stopped when it reaches the End Time specified in your request. A forced request is stopped immediately regardless of whether the sessions you are capturing have ended. A stopped request is deactivated so no new sessions will be captured. In-flight sessions continue to be captured until a session logoff occurs. If you leave this field blank, your capture request will be stopped rather then forced when it reaches the End Time in your request. This field can only be selected if you entered an End Time in your request.
– Normal Event Notification and Error Event Notification control whether normal and error event messages are generated and sent to your TSO session. Enter a slash (/) to receive these messages at your terminal, or leave blank for no messages to be sent.
– Error Event Notification controls whether error event messages are generated and sent to your TSO session. If you enter a slash (/) in this field, you will receive these messages at your terminal. If you leave it blank then no messages will be sent.
12-4 Hiperstation for Mainframe Servers User Guide
Figure 12-3. APPC Record and Script Create Defaults - Script Create Settings
Hiperstation ----- APPC Record and Script Create Defaults ------------------- Profile: HIPER Profile Dataset: 'USER2312.HIPER.PROFILE' OPTION ===> More: - + -----------------------------Script Create Settings---------------------------- Script Dataset Dataset Name ===> ____________________________________________________ Prefix ===> ______ (1 - 6 character prefix) Suffix ===> _______ (2 - 7 numeric suffix) Replace? ===> Y (Y = Yes, N = No) Script Content: Where Should Details be Stored: (Enter number to select) _ 1. Merged into the script 2. Separate from the script, input and output together 3. Separate from the script, input and output split What Should be Recorded: (Enter "/" to select) _ Conversation Log _ Script _ Details Script Create Options: (Enter "/" to select) _ Suppress time stamps in script _ Write script tags in short CPIC format _ Write all PIU traffic as script comments _ Include SNA service transactions (logmodes: SNASVCMG, CPSVCMG, CPSVRMGR) Script Create Execution Options: Select processing option: (Enter number to select) _ 1. Submit batch job 2. TSO Other Datasets: Conversation Log Dataset Name ===> ____________________________________________________ Prefix ===> ______ (1 - 6 character prefix) Suffix ===> _______ (2 - 7 numeric suffix) Replace? ===> _ (Y = Yes, N = No) Combined Detail ===> ____________________________________________________ Prefix ===> ______ (1 - 6 character prefix) Suffix ===> _______ (2 - 7 numeric suffix) DDname ===> ________ Outbound Detail ===> ____________________________________________________ Prefix ===> ______ (1 - 6 character prefix) Suffix ===> _______ (2 - 7 numeric suffix) DDname ===> ________ Replace? ===> _ (Y = Yes, N = No) Inbound Detail ===> ____________________________________________________ Prefix ===> ______ (1 - 6 character prefix) Suffix ===> _______ (2 - 7 numeric suffix) DDname ===> ________
6. Specify the Script Create Settings.
– Script Dataset, Dataset Name, Prefix, and Suffix specify the fully qualified dataset and member names where you want to store your scripts.
– Replace? specifies whether the script dataset will replace a dataset of the same name. Enter Y or N.
7. Specify your Script Content options.
Script Content fields specify where to store the detail data for your scripts, what to record, and how to process your script datasets.
– Where should detail be stored is a required field that specifies where on DASD to store the APPC message details in relationship to your scripts. You must choose one of the following options. Enter a number to make your selection.
Hiperstation for Mainframe Servers Profile Defaults 12-5
1. Merged into the script places the detail data into the same PDS member as the script. APPC verbs contained in the script will be merged with the data sent by the verbs. This option allows you to view all data for a conversation in a single PDS member.
2. Separate from the script, inbound and outbound together places the detail data into a PDS member that is separate from the script PDS member. This option keeps the script member uncluttered with (possibly) non-printable data. In addition, a file-formatting tool can be used to display the detail data since it is now separate from the APPC verbs.
3. Separate from the script, inbound and outbound split places the detail data into two PDS members, both of which are separate from the script member. One member contains outbound data; the other member contains inbound data. Outbound refers to all data sent by the logical unit that started the APPC conversation (issued the ALLOCATE verb). Inbound refers to all data sent by the other logical unit.
8. Specify What should be recorded options.
These options define what you will create from your captured data when requesting script creation processing. Enter a slash (/) to make your selection. You can select one or more of the following options:
– Conversation log creates a single conversation log for each of your capture requests. The log contains a list of every APPC conversation (ALLOCATE statement) that has been captured by your request. After each ALLOCATE statement is a SCRIPT statement naming the PDS member containing the entire APPC conversation. The conversation log is written when you issue the Stop or Force line command from the Global Record Monitor Requests screen. The conversation log, after some modifications, is typically used as the SYSIN dataset for your play backs.
– Script creates a new script for every APPC conversation that was captured by your request. Each script is placed in a different member of a PDS. The name of each member is also entered in the conversation log on the SCRIPT statement. In this way, the conversation log points to every script that was created. A script contains all of the APPC verbs (ALLOCATE, SEND, RECEIVE, etc.) issued by the two partners in the APPC conversation.
– Details writes the details for every APPC conversation that was captured by your request. 'Details' is the term used for the data sent by the APPC partners to each other. It might be human readable data, or it might consist of only binary data.
9. Fill in or change the Script create options.
– Suppress time stamps in script omits time stamps making the script easier to browse. If you are reviewing the scripts for debugging purposes, select this option to make the scripts easier to read. Hiperstation uses time stamps to synchronize playback. If you intend to play back scripts at the same pace as they were recorded, do not select this option.
– Write script tags in short CPIC format writes APPC verbs in Common Programming Interface for Communications (CPIC) format, rather than Hiperstation proprietary format. For example, a send verb appears in the script as CMSEND rather than SEND_DATA. This option is for readability and has no impact on playback.
– Write all PIU traffic as script comments writes VTAM Path Information Units (PIUs) into the script (the 26-byte Transmission Headers (TH), the 3-byte Request Headers (RH), and the variable length Request Units (RU) that are sent between VTAM logical units). In the scripts, this information appears in CONTENT tags under a PIU tag. Although the information does not appear with the traditional comment indicator (*) in column one, playback ignores the PIU block of tags. This option supports debugging VTAM applications.
12-6 Hiperstation for Mainframe Servers User Guide
– Include SNA service transactions writes special APPC conversations used by subsystems such as VTAM and CICS into the scripts. For example, the Change Number of Session (CNOS) and Exchange Log Name (XLN) transactions appear in the script if you select this option. These conversations use the following logmodes: SNASVCMG, CPSVCMG, or CPSVRMGR. This option supports application debugging and does not impact playback.
10. Script Create Execution Options specifies whether you want background (batch) or foreground processing to be your default. Select 1 (background) or 2 (foreground). Sample JCL is provided for a batch job, which you can change if desired.
11. Several Other Datasets will be created. You can change the dataset name, prefix, suffix, DDname, etc. if desired.
– The Conversation log dataset specifies where you want the conversation log to reside on DASD. If you allocate this dataset as a PDS or PDSE, you must enter a member name prefix value and a numeric suffix value unless you want the default value of zero.
– The Combined detail dataset specifies where you want the combined inbound and outbound message data to reside on DASD. This dataset must be allocated as a PDS or PDSE, and you must enter a member name prefix value, a numeric suffix value unless you want the default value of zero, and a unique 8-character DDname value. The DDname you supply is written into the script member along with the APPC verbs. This enables Hiperstation to find your detail data when you play back the script. You must place the same DDname in the JCL used to play back your scripts.
– The Outbound detail dataset specifies where you want the outbound detail message data to reside on DASD. This dataset must be allocated as a PDS or PDSE, and you must enter a member name prefix value in the PREFIX column, a numeric suffix value in the SUFFIX column unless you want the default value of zero, and a unique 8-character DDname value. The DDname you supply is written into the script member along with the APPC verbs. This enables Hiperstation to find your detail data when you play back the script. You must place the same DDname in the JCL used to play back your scripts.
– The Inbound detail dataset specifies where you want the inbound detail message to reside on DASD. This dataset must be allocated as a PDS or PDSE, and you must enter a member name prefix value in the PREFIX column, a numeric suffix value in the SUFFIX column unless you want the default value of zero, and a unique 8-character DDname value. The DDname you supply is written into the script member along with the APPC verbs. This enables Hiperstation to find your detail data when you play back the script. You must place the same DDname in the JCL used to play back your scripts.
TCP/IP Profile DefaultsThis section specifies the TCP/IP Global Recording and Script Create defaults.
1. Select option 5 TCP/IP from the Hiperstation Profile screen (Figure 12-4).
Note: For easier display, the initial Profile screens have been combined. Figure 12-4 shows the profile selection screen. The TCP/IP screens in this section have been combined into logical groups. Figure 12-5 shows the Record Settings, Figure 12-6 on page 12-9 shows the Script Create Settings, and Figure 12-7 on page 12-12 shows the Dataset Settings. On your actual screen, press FORWARD (PF8) or BACKWARD (PF7) to view all of the fields.
Hiperstation for Mainframe Servers Profile Defaults 12-7
Figure 12-4. Hiperstation Profile Screen
Hiperstation -------------- Hiperstation Profile ---------------------------- OPTION ===> More: + Primary commands: menu-number, ALL, CANCEL Line commands: S or / to select options. Active Profile: Dataset ===> 'USER2312.HIPER.PROFILE' Member ===> HIPER Description ===> changed description _ 1 Domain Traveler Recording and Playback defaults _ 2 APPC Global Record and Script Create settings _ 3 3270/LU0 Global Record and Script Create settings _ 4 WebSphere MQ Global Record and Script Create settings _ 5 TCP/IP Global Record and Script Create settings _ 6 Auditing 3270 Auditing defaults for 3270 _ 7 Auditing MQ Auditing defaults for WebSphere MQ _ 8 Auditing TCP/IP Auditing defaults for TCP/IP _ 9 Playback MQ MQ Playback parameter defaults _ 10 Playback TCP TCP Playback parameter defaults _ 11 ATV Manager Test Vehicle defaults Should changes made elsewhere to Profile values be saved? Profile Autosave ===> Y (Y = YES, N = NO OR A = ASK) Should changes made elsewhere to dataset names be saved? DSN Autosave ===> Y (Y = YES, N = NO) Email address: _______________________________________________________________ Codepage: ISO8859-1 Job statement information for batch jobs: ===> //XXXXXXXA JOB ('ACCOUNT',5M-0000),'HIPERSTN', ===> // CLASS=Q,MSGCLASS=R,NOTIFY=&SYSUID ===> //*
> //*
The TCP/IP Global Record/Script Create Defaults screen appears.
Figure 12-5. TCP/IP Global Record/Script Create Defaults - Record Settings
Hiperstation ---- TCP/IP Global Record/Script Create Defaults ----------------- Profile: HIPER Profile Dataset: 'USER2312.HIPER.PROFILE' OPTION ===> ________________________________________________ More: + --------------------------------Record Settings-------------------------------- _ Create Recording Filters (/ for Filter Create panel) Repository Dataset: Dataset Name ===> ______________________________________________ First Number ===> _______ (if wildcard in dataset) Last Number ===> _______ (if wildcard in dataset) Reuse Repository Options: (Enter "/" to select) _ Delete existing data _ Append to existing data _ Overwrite existing data when all segments are full Amount of Data to Record: Data from client ===> ________ (ALL/number) Data from server ===> ________ (ALL/number)
2. In the Create Recording Filters field, enter a slash (/) to display the TCP/IP Data Collect screen where you can create recording filters. See the Hiperstation for Mainframe Servers User Guide or the online help for information about creating filters.
3. Specify your Repository Dataset options.
12-8 Hiperstation for Mainframe Servers User Guide
– Dataset Name is required and specifies where captured data will be stored on DASD. You can enter a fully qualified dataset name up to 44 characters to allocate a fixed repository. You can also enter a dataset name with a wildcard of “*” or “?” to allocate a repository set. This set is defined by a range of numbers entered in the First Number and Last Number fields. Entering an “*” in the dataset name expands the qualifier to eight characters and fills with zeros (for example, xyz* would result in XYZ00001). Entering one or more “?”s in the dataset name replaces those character positions with numbers (for example, XYZ??ABC would result in XYZ01ABC).
– First Number and Last Number define the range of datasets for your repository set. You can enter any range from 0 to 9999999. When one dataset is full, it is closed and data continues to be written to the next dataset in sequence. These fields are required if you entered a wildcard in the Repository Dataset Name field.
4. Reuse repository options specifies the way your capture request will process the repository. Enter a slash (/) to select.
– Delete existing data allows capture to start writing data to the beginning of the repository or the first segment of a repository set. Any data that exists will be overwritten. This selection is mutually exclusive with Append to existing data.
– Append to existing data allows capture to add data to the repository (or the last segment of a repository set) that was capturing data. Any data that exists will be preserved. This selection is mutually exclusive with Delete existing data.
– Overwrite existing data when all segments are full continues writing captured data to the first segment of a repository set when the last segment is full. This option is valid only when using a repository set.
5. Amount of data to record can record any TCP/IP data that passes through this MVS system and matches your filtering criteria. To record all of that data, enter ALL in Data from client and Data from server. Otherwise, any non-zero numeric value will limit the amount of data recorded from a single message to a number of bytes.
Hiperstation for Mainframe Servers Profile Defaults 12-9
Figure 12-6. TCP/IP Global Record/Script Create Defaults - Script Create Settings
Hiperstation ---- TCP/IP Global Record/Script Create Defaults ----------------- Profile: HIPER Profile Dataset: 'USER2312.HIPER.PROFILE' OPTION ===> ________________________________________________ More: + -----------------------------Script Create Settings---------------------------- _ Create Script Filters (/ for Filter Create panel) Amount of Data to Use: Data from Client ===> ________ (ALL/number) Data from Server ===> ________ (ALL/number) Script Content: Where Should Details be Stored: (Enter number to select) _ 1. Merged into the script 2. Separate from the script, input and output together 3. Separate from the script, input and output split What Should be Created: _ Create Log entries _ Create Script entries _ Create Detail entries _ Create Subset repository Grouping: Create a New Script for Each: _ 1. One script for everything 2. Connection 3. New combination of (one or more) _ Client IP address _ Client port _ Server IP address _ Server port _ Protocol Script Options: (Enter "/" to select) _ Suppress timestamps _ Translate detail data from ASCII to EBCDIC _ Translate sample data from ASCII to EBCDIC _ Split lines at linefeed characters (for readability) _ Suppress CONTENT data formatting (DB2C, IMSC, CTG, or ECI) Script Create Execution Options: Select Processing Option: (Enter number to select) _ 1. Submit batch job 2. TSO
6. Enter a slash (/) to select Create Script Filters and display the TCP/IP Script Create screen. See the Hiperstation for Mainframe Servers User Guide or the online help for information about creating filters.
7. Specify the Amount of Data to Use. Hiperstation can record any TCP/IP data that passes through and matches your filtering criteria. To record all data, enter ALL in both the Data from Client and Data from Server fields. Otherwise, a non-zero numeric value will limit the amount of data used for Script Creation.
8. Specify your Script Content options. Script Content fields specify where to store the detail data for your scripts, what to record, and how to process your script datasets.
– Where Should Details be Stored is a required field that specifies where on DASD to store the message details in relationship to your scripts.
You must choose one of the options. Enter a number to make your selection.
1. Merged into the script places the detail data into the same PDSE member as the script. TCP/IP verbs contained in the script will be merged with the data sent by the verbs. This option allows you to view all data for a connection in a single PDSE member.
2. Separate from the script, input and output together places the detail data into a PDSE member that is separate from the script PDSE member. This option keeps the script member uncluttered with (possibly) non-printable
12-10 Hiperstation for Mainframe Servers User Guide
data. In addition, a file-formatting tool can be used to display the detail data since it is now separate from the TCP/IP verbs.
3. Separate from the script, input and output split places the detail data into two PDSE members, both of which are separate from the script member. One member contains client data; the other member contains server data. Client refers to all data sent by the partner that started the TCP/IP connection. Server refers to all data sent by the other partner.
9. Specify the What Should be Created options. These options specify what to create from your captured data when requesting script creation processing.
Enter a slash (/) to select one or more options.
– Create Log entries generates a Connection Log that lists every script Hiperstation for Mainframe Servers created. Each entry consists of a SOCKETS and SCRIPT statement. The SCRIPT statement names the PDSE member containing the TCP/IP connections. The log is written when you issue the Stop or Force line command from the Global Recording Monitor TCP/IP Requests screen. The log, after some modifications, is typically used as the SYSIN dataset for your TCP/IP playbacks.
– Create Script entries generates a new script for each TCP/IP connection or for a group of connections. Each script is placed into a different member of a PDSE. The name of each member is also entered into the TCP/IP log on the SCRIPT statement. In this way, the log points to every script that was recorded. A script contains all the TCP/IP verbs (CONNECT, CLIENT, SERVER, etc.) issued by the two partners in each TCP/IP connection.
– Create Detail entries. Details is the term used for the data sent by TCP/IP partners to each other. It might be human readable or might consist only of binary data. You have a choice of where to store the details:
• Option 1 Recorded with the script member places the details into the same PDSE member as the script; TCP/IP verbs contained in the script will be merged with the data sent by the verbs. This option allows all of the data for a connection to be viewed in a single location: one PDSE member.
• Option 2 Recorded in a separate member places the detail data into a PDSE member that is separate from the script PDSE member. This option keeps the script member uncluttered with (possibly) non-printable data. Also a file formatting tool can be used to display the detail data since it is now separate from the TCP/IP verbs.
• Option 3 Split and recorded in separate members places the detail data into two PDSE members, both of which are different from the script member. One member contains the client data, the other member contains the server data. Client refers to all data sent by the partner that started the TCP/IP connection. Server refers to all data sent by the other partner.
– Create Subset repository generates one or more subset repositories depending on the other selections you make. A subset repository is a filtered copy of the input repository (for example, it contains raw TCP/IP data captured via Global Recording). The filtering is the selection criteria applied by the TCP/IP script creation process.
10. Accept or change the Grouping fields. Grouping fields control which TCP/IP connections are included in any one script. Your choice of grouping options depends on how you intend to play back the scripts.
– To reproduce, at playback time, the timing and sequence of all the TCP/IP connections and messages as seen at capture time, you could choose Option 1 (One script for everything). A script created with this option contains multiple TCP/IP connections, and they are played back in the order recorded in the script.
Hiperstation for Mainframe Servers Profile Defaults 12-11
– To have all of your TCP/IP connections played back at once, you could choose Option 2 (Connection). A script created with this option contains a single TCP/IP connection, which can be played back independently of other scripts and connections.
– The other options enable you to create scripts that contain just the subset of TCP/IP connections that you need. Select Option 3 (New combination of (one or more)) and select one or more of the following:
• Client IP address• Client port• Server IP address• Server port• Protocol
Note: IPv6 and IPv4 IP address formats are valid for both the Client IP address or Server IP address.
11. Enter a slash (/) to select one or more of the desired Script Options:
– Select Suppress timestamps only if you have no plans to play back the scripts. Time stamps appear with every TCP/IP verb in a script and are used during playback to keep scripts synchronized. If you are using scripts as debugging tools rather than for playback, you might want to suppress time stamps to make the scripts more readable.
– Select Translate detail data from ASCII to EBCDIC to make the data within the script more readable. Almost all data flowing between Web browsers and servers is in ASCII; translating it to EBCDIC makes most of the data readable on the mainframe. The data is translated back into ASCII (internally) during playback.
– Select Translate sample data from ASCII to EBCDIC to make the data within the script more readable when you have chosen to store detail data in external files (not within the script). Sample data refers to the single line of detail data written on the CLIENT and SERVER tags within the script. This sample data is not used during playback. It is only present to help you understand what is contained in a script.
– Select Split lines at linefeed characters to show the detail data in a more readable format. Much of the data transferred between Web browsers and servers consists of readable lines that end with the ASCII linefeed character (x'0A'). Splitting detail data lines at each linefeed character can help you understand what is contained in the script. Playback is not affected by this option.
– Select Suppress CONTENT data formatting if you do not require tags for specific CONTENT data (associated with DB2C, IMSC, CTG, or ECI) to be created in the script. Suppressing these tags may increase the speed of Playback and will decrease the size of the scripts. These tags allow for substitution of CONTENT data during Playback and aid in readability but are not required.
12. Script Create Execution Options specify whether you want background (batch) or foreground processing to be your default. Select 1 (background) or 2 (foreground).
– 1. Submit batch job submits a job for background execution.
– 2. TSO executes script creation as a foreground task under your TSO session. Your session will remain locked until script creation processing completes.
12-12 Hiperstation for Mainframe Servers User Guide
Figure 12-7. TCP/IP Global Record/Script Create Defaults - Dataset Settings
Hiperstation ---- TCP/IP Global Record/Script Create Defaults ----------------- Profile: HIPER Profile Dataset: 'USER2312.HIPER.PROFILE' OPTION ===> More: - + Output Datasets: Log: Dataset Name ===> 'USER2312.HIPER.CONVLOG' Member Prefix ===> ______ (1 - 6 character prefix) Member Suffix ===> _______ (2 - 7 numeric suffix) Replace? ===> _ (Y = Yes, N = No) Script: Dataset Name ===> 'USER2312.HIPER.SCRIPT' Member Prefix ===> ______ (1 - 6 character prefix) Member Suffix ===> _______ (2 - 7 numeric suffix) Replace? ===> _ (Y = Yes, N = No) Combined Detail: Dataset Name ===> 'USER2312.HIPER.COMBINED' Member Prefix ===> ______ (1 - 6 character prefix) Member Suffix ===> _______ (2 - 7 numeric suffix) DDname ===> ________ Replace? ===> _ (Y = Yes, N = No) Client Detail: Dataset Name ===> 'USER2312.CLIENT.DETAIL' Member Prefix ===> ______ (1 - 6 character prefix) Member Suffix ===> _______ (2 - 7 numeric suffix) DDname ===> ________ Server Detail: Dataset Name ===> 'USER2312.SERVER.DETAIL’ Member Prefix ===> ______ (1 - 6 character prefix) Member Suffix ===> _______ (2 - 7 numeric suffix) DDname ===> ________
13. Several Output Datasets will be created. You can add or change the dataset name, member prefix, member suffix, or DDname, if desired.
– Dataset Name: Supply a dataset name (without a member name) for each row. The dataset names can be fully qualified (enclosed in single quotes) or partially qualified (not in quotes). Partially qualified dataset names will be prefixed with your TSO prefix (normally your user ID) at processing time. All datasets must be partitioned datasets extended (PDSE). A regular PDS is not supported. For an HTML event summary, supply the HFS path of where the report is to be written (not in quotes).
– Member Prefix: Supply a member name prefix (one to six characters) for each row marked with an *. This prefix is used (in combination with the suffix) to create complete member names to be stored in your datasets. You should select member name prefixes that make it easy for you to identify the type of data stored in each member. You can supply any prefix that is valid as the start of a PDSE member name. For an HTML event summary, the prefix is used with the suffix to create an .htm file and subdirectory.
– Member Suffix: Supply a member name suffix (one to seven numerals) for each row marked with an *. This suffix is used (in combination with the prefix) to create complete member names to be stored in your datasets. As Hiperstation creates new members for each new script, the suffix number is incremented to produce a unique member names.
– DDname: Supply a data definition name (DDname) for each row marked with an * that is also for detail data. The DDname can be from one to eight characters in length. The DDname you supply is written into the script member along with the WebSphere MQ verbs. The DDname enables to find your detail data when you play back the script. You must place the same DDname in the Job Control Language (JCL) used to play back your Hiperstation scripts.
Hiperstation for Mainframe Servers Profile Defaults 12-13
– Replace?: Specifies whether the script dataset will replace a dataset of the same name.
Auditing TCP/IP Profile DefaultsThis section specifies the TCP/IP auditing defaults.
1. Select option 8 Auditing TCP/IP from the Hiperstation Profile screen.
Note: For easier display, the initial Profile screens have been combined. Figure 12-8 shows the profile selection screen. On your actual screen, press FORWARD (PF8) or BACKWARD (PF7) to view all of the fields.
Figure 12-8. Hiperstation Profile Screen
Hiperstation -------------- Hiperstation Profile ---------------------------- OPTION ===> More: + Primary commands: menu-number, ALL, CANCEL Line commands: S or / to select options. Active Profile: Dataset ===> 'USER2312.HIPER.PROFILE' Member ===> HIPER Description ===> changed description _ 1 Domain Traveler Recording and Playback defaults _ 2 APPC Global Record and Script Create settings _ 3 3270/LU0 Global Record and Script Create settings _ 4 WebSphere MQ Global Record and Script Create settings _ 5 TCP/IP Global Record and Script Create settings _ 6 Auditing 3270 Auditing defaults for 3270 _ 7 Auditing MQ Auditing defaults for WebSphere MQ _ 8 Auditing TCP/IP Auditing defaults for TCP/IP _ 9 Playback MQ MQ Playback parameter defaults _ 10 Playback TCP TCP Playback parameter defaults _ 11 ATV Manager Test Vehicle defaults Should changes made elsewhere to Profile values be saved? Profile Autosave ===> Y (Y = YES, N = NO OR A = ASK) Should changes made elsewhere to dataset names be saved? DSN Autosave ===> Y (Y = YES, N = NO) Email address: _______________________________________________________________ Codepage: ISO8859-1 Job statement information for batch jobs: ===> //XXXXXXXA JOB ('ACCOUNT',5M-0000),'HIPERSTN', ===> // CLASS=Q,MSGCLASS=R,NOTIFY=&SYSUID ===> //*
> //*
The “Auditing Defaults for TCP/IP Screen” appears (Figure 12-9).
12-14 Hiperstation for Mainframe Servers User Guide
Figure 12-9. Auditing Defaults for TCP/IP Screen
Hiperstation ---------- Auditing Defaults for TCP/IP ------------------------ Profile: HIPER Profile Dataset: 'USER2312.HIPER.PROFILE' OPTION ===> _________________________________________________ _ Create Recording Filters (/ for Filter Create panel) Datasets: Registry DSN ===> _____________________________________________ Description ===> __________________________________________ Replace Existing Repositories? ===> _ 1 = Yes, 2 = Terminate Archive Request Criteria: Recording Date and Time HH : MM : SS (Optional) MM / DD / YYYY Start Time ===> 00 : 00 : 00 Start Date 00 / 00 / 0000 End Time ===> 00 : 00 : 00 End Date 00 / 00 / 0000
2. Enter a slash (/) to select Create Recording Filters and display the “TCP/IP Collect Data - Filtering Screen”. This screen specifies the IP addresses and ports for filtering traffic.
3. Specify your Datasets information.
– Registry DSN specifies the name of the dataset that contains the index to this archive recording request. You can enter a fully qualified dataset name up to 35 characters in length to allocate the repository registry. Repositories created by this archive record request will be based on the repository registry dataset name (for example, a repository registry dataset of A.B.C would result in repositories being created from A.B.C.#0000001 to A.B.C.#9999999).
– Description is an optional field that describes the archive record request. This description will be provided to the user when the user specifies an archive record request in the Create Search Reports function.
– Replace Existing Repositories? specifies what should occur when archive record attempts to switch to a new repository segment and a dataset already exists that matches that repository segment dataset name. Select 1 or 2.
1 (Yes) deletes the existing dataset and creates a new dataset with the same name that is allocated and with the same options as the initial repository dataset segment. Specify this option if it is imperative that the archive record request remain active.
2 (Terminate) terminates the archive record request. The archive record request will not start if any datasets exist that match the repository dataset specification.
4. Archive Request Criteria specifies whether to exclude SYSTEM traffic. Enter a slash (/) to exclude SYSTEM traffic.
5. Specify a Recording Start and End Date and Time if desired. These fields are optional. For a user profile, leaving the date and time blank is most useful. When a user specifies a time-frame for the request, it becomes active at the designated start time. If no time-frame is specified, it becomes active immediately. Capture begins when all of the criteria for an active request are met. If you enter a Start Time you must enter a Start Date. If you enter an End Time you must enter an End Date. Times are entered in a 24-hour clock. The range of acceptable year values is 2000 to 2040, and the end date and time must be later than the start date and time.
Playback TCP/IP Profile DefaultsThis section specifies the TCP playback profile defaults.
Hiperstation for Mainframe Servers Profile Defaults 12-15
1. Select option 10 Playback TCP from the Hiperstation Profile screen (Figure 12-10).
Note: For easier display, the initial Profile screens have been combined. Figure 12-10 shows the profile selection screen. The Playback TCP screens in this section have been combined. Figure 12-11 shows all of the Playback TCP profile settings. On your actual screen, press FORWARD (PF8) or BACKWARD (PF7) to view all of the fields.
Figure 12-10. Hiperstation Profile Screen
Hiperstation -------------- Hiperstation Profile ---------------------------- OPTION ===> More: + Primary commands: menu-number, ALL, CANCEL Line commands: S or / to select options. Active Profile: Dataset ===> 'USER2312.HIPER.PROFILE' Member ===> HIPER Description ===> changed description _ 1 Domain Traveler Recording and Playback defaults _ 2 APPC Global Record and Script Create settings _ 3 3270/LU0 Global Record and Script Create settings _ 4 WebSphere MQ Global Record and Script Create settings _ 5 TCP/IP Global Record and Script Create settings _ 6 Auditing 3270 Auditing defaults for 3270 _ 7 Auditing MQ Auditing defaults for WebSphere MQ _ 8 Auditing TCP/IP Auditing defaults for TCP/IP _ 9 Playback MQ MQ Playback parameter defaults _ 10 Playback TCP TCP Playback parameter defaults _ 11 ATV Manager Test Vehicle defaults Should changes made elsewhere to Profile values be saved? Profile Autosave ===> Y (Y = YES, N = NO OR A = ASK) Should changes made elsewhere to dataset names be saved? DSN Autosave ===> Y (Y = YES, N = NO) Email address: _______________________________________________________________ Codepage: ISO8859-1 Job statement information for batch jobs: ===> //XXXXXXXA JOB ('ACCOUNT',5M-0000),'HIPERSTN', ===> // CLASS=Q,MSGCLASS=R,NOTIFY=&SYSUID ===> //*
> //*
The “TCP Interactive Playback Defaults Screen” appears.
12-16 Hiperstation for Mainframe Servers User Guide
Figure 12-11. TCP Interactive Playback Defaults Screen
Hiperstation --------- TCP Interactive Playback Defaults ---------------------- Profile: HIPER Profile Dataset: 'USER2312.HIPER.PROFILE' OPTION ===> _________________________________________________ More: + Playback Information _ Live (/ for live I/O, blank for off-line) _ Use REXX _ Set REXX Stream Variables Stop On ===> ____ (End compare report generation after the speci- fied number of mismatches have been reached.) Standard Wait Time ===> ___ Think Time Option _ 1. Play at full speed 2. Think time recorded on script 3. User-specified think time (HH:MM:SS) ===> ________ Percent ===> ___ Reporting Options: Field Depth ===> ____ (Maximum lines to print in field) Max Lines per Page ===> ____ (30-9999) Break ===> _ (E)ject, (N)ext Datasets: Conversation log: Dataset Name ===> ______________________________________________ Script Dataset: Dataset Name ===> ______________________________________________ Database: Dataset Name ===> ______________________________________________ REXX log: Dataset Name ===> ______________________________________________ Error log: Dataset Name ===> ______________________________________________
2. Specify your TCP Playback Information.
– In the Live field, enter a slash (/) for interactive playback or leave blank for unattended playback.
– Use REXX sets REXXON or REXXOFF on the Hiperstation for Mainframe Servers CONTROL statement. This allows you to use REXX clauses outside of script tags to perform tasks such as replacing recorded application data during playback. For Hiperstation for VTAM you can use REXX conditional logic to replace recorded inputs with variable names to dynamically replace input data with unique values during playback. Enter a slash (/) to set REXXON or leave blank to set REXXOFF.
– Set REXX Stream Variables on is specified in the Hiperstation for Mainframe Servers and the Hiperstation for WebSphere MQ CONTROL statements. This parameter enables the use of the Hiperstation for Mainframe Servers predefined REXX variables during playback. The variables return information about the playback. Incorporate them into REXX logic that you add to your scripts to control the way the scripts play back. For example, use them to dynamically replace data in the script during playback. Since this is not necessary for replay, the default value for this parameter is usually set to NO. A slash (/) sets the value to YES.
– In the Stop On field, enter a number to end compare report generation after the specified number of mismatches have been reached.
3. Specify a Standard Wait Time or enter the number of the Think Time Option you want to select.
– Standard Wait Time is the Think Time for each transaction.
Hiperstation for Mainframe Servers Profile Defaults 12-17
– Select one of the following Think Time Options:
1. Play at full speed. Transactions are played back as fast as the system can execute them.
2. Think time recorded on script. Think time is simulated using the time recorded on the script.
3. User-specified think time. Enter the think time in the desired number of minutes and seconds. Or you can enter a percent. One hundred percent specifies the original think time. Fifty percent specifies one-half the original think time. Seconds is the only required value.
4. Select the desired Reporting Options.
– Field Depth specifies the number of lines to print in a field before truncating data. This applies only to Text and CSV reports and allows you to truncate the printing of large fields that may contain up to two gigabytes of data.
– Max lines per Page specifies the maximum number of lines to print on a page. Enter a number between 30 and 9999. This applies only to Text reports. The default is 60.
– Break specifies whether to begin each record on a new page or continue the report on the next line. This is valid if you are using form reports in a Text or HTML format. Select EJECT to begin each record on a new page or NEXT to continue the report on the next line. EJECT is the default.
5. Name your Datasets.
– Conversation Log Dataset Name — The dataset name where you want the conversation log to reside on DASD.
– Script Dataset Name — The location of the scripts you will play back. This is a required field and must refer to an existing dataset.
– Database Dataset Name — To report on the playback, enter a name for the reporting database. Data from the playback is collected to this database and used in a future reporting job. This field is only required if “Generate Reporting Job” is selected.
– REXX Log Dataset Name — Specifies that the output generated by REXX statements in a script is directed to a SYSOUT or DASD dataset, rather than to SYSPRINT. If the specified value is a single character, the REXX log is allocated to a SYSOUT class. The SYSOUT goes to the class specified by the single character. If the value is more than one character, the REXX Log is allocated to a permanent file with the name dataset.Pnnnn, where nnnn is the port number assigned to the terminal. Wild cards (* or ?) can be used to identify where the port number (nnnn) is inserted. A member can also be supplied. By default, REXX output is directed to the SYSPRINT dataset.
– Error Log Dataset Name — The playback error log is a report that describes any errors that occurred during playback. If this field is left blank, the report will go to SYSOUT=*. Enter a dataset name or an hfs path to specify an alternate location.
12-18 Hiperstation for Mainframe Servers User Guide
A-1
Appendix A.
ATCP/IP Data Collection and Reporting Tables App AThis appendix provides information to help you define the parameters of your COLLECT and custom REPORT statements. See “COLLECT Statement” on page 9-16 and “REPORT Statement for Custom Reports” on page 10-9 for information.
Hiperstation for Mainframe Servers provides the following tables of data collection and reporting criteria:
• “PLAYBACK Table” on page A-1
• “SOCKETS Table” on page A-3
• “SCRIPT Table” on page A-5
• “CONNECTION Table” on page A-7
• “MESSAGE Table” on page A-9
Most report tables are broken into two sections:
• Report fields: Collect any or all of these fields during playback. Then build custom reports containing the fields you need. For example:
COLLECT FIELDS(*) FROM(PLAYBACK)
collects all report fields from the PLAYBACK table.
REPORT FIELDS(OWNA, JBNA, PLNA) FROM(PLAYBACK)
reports the OwnerName, JobName, and PlaybackName fields from the PLAYBACK table.
• Statistic fields: These fields report counts, minimum and maximum values, averages, and sums of specified report fields. You do not collect statistic fields, but do collect the field the statistic is based on. For example, collect SocketsDuration from the SOCKETS table to report the SUM of SocketsDuration on a PLAYBACK report.
While sorting the collected data, Hiperstation for Mainframe Servers calculates statistics for that data. Report the statistic by specifying any or all of the statistics fields on your REPORT statements.
Additionally, statistics are relative to the table from which they are reported. For example:
REPORT FIELDS(MAX(ConnectionDuration)) FROM(PLAYBACK)
reports the longest connection duration that occurred during the playback.
REPORT FIELDS(MAX(ConnectionDuration)) FROM(SOCKETS)
reports the longest connection duration from each sockets played back.
The tables include the long and short name for each report field. Use either on the FIELDS declarations of your COLLECT and REPORT statements.
PLAYBACK TableThe PLAYBACK table includes both report and statistic fields.
A-2 Hiperstation for Mainframe Servers User Guide
PLAYBACK Report Fields
COLLECT any or all of the following fields and REPORT them on customized PLAYBACK reports.
Long Field Names Short Field Names
JobName JBNA
JobNumber JBNU
OwnerName OWNA
PlaybackDuration PLDR
PlaybackFinishTime PLFT
PlaybackName PLNA
PlaybackNumber PLNU
PlaybackReturnCode PLRC
PlaybackStartTime PLST
SocketsStatementCount SOSC
SystemName SYNA
Note: Hiperstation for Mainframe Servers and Hiperstation for WebSphere MQ share the same PLAYBACK report fields table. As such, a report containing all of the fields from the table includes the MQGroupStatementCount field.
PLAYBACK Statistic Fields
REPORT any of the following statistics on customized PLAYBACK reports.
Note: Use the Collect from Table column to determine the parameters for the collection statement required to report the given statistic. For example, to report MAXIMUM ConnectionCount from the PLAYBACK table, you need to collect the ConnectionCount field from the SCRIPT table. Collect all fields from all tables to simplify collection and to ensure a complete reporting database.
Statistics For Field (long names) Field Short Names Collect from Table
MIN or MAX SocketsReturnCode SORC SOCKETS
MIN or MAX ScriptReturnCode SCRC SCRIPT
AVG, MIN, MAX, or SUM SocketsDuration SODR SOCKETS
AVG, MIN, MAX, or SUM ScriptDuration SCDR SCRIPT
AVG, MIN, MAX, or SUM ConnectionDuration CNDR CONNECTION
AVG, MIN, MAX, or SUM MessageDuration MSDR MESSAGE
AVG, MIN, MAX, or SUM InitialResponseTime RTIN MESSAGE
AVG, MIN, MAX, or SUM FinalResponseTime RTFN MESSAGE
AVG, MIN, or MAX BytesSentRate BYSR MESSAGE
AVG, MIN, or MAX BytesReceivedRate BYRR MESSAGE
SUM ScriptStatementCount SCSC SOCKETS
AVG, MIN, MAX, or SUM ConnectionCount CNCT SCRIPT
AVG, MIN, MAX, or SUM MessageCount MSCT CONNECTION
AVG, MIN, MAX, or SUM ConnectionsAttempted CNAT CONNECTION
TCP/IP Data Collection and Reporting Tables A-3
SOCKETS TableThe SOCKETS table includes both report and statistic fields.
AVG, MIN, MAX, or SUM ConnectionsRefused CNRF CONNECTION
AVG, MIN, MAX, or SUM ConnectionsTimedOut CNTO CONNECTION
AVG, MIN, MAX, or SUM TimeToConnect TMTC CONNECTION
AVG, MIN, MAX, or SUM TimeForConnectionRefusal TMCR CONNECTION
AVG, MIN, MAX, or SUM TimeForConnectionTimedOut TMCT CONNECTION
MIN or MAX ConnectionStatus CNSC CONNECTION
AVG, MIN, or MAX ConnectionRate CNRT SCRIPT
AVG, MIN, or MAX MessageRate MSRT CONNECTION
AVG, MIN, MAX, or SUM RequestByteCount RQCT MESSAGE
MIN or MAX RequestVersionNumber RQVN MESSAGE
AVG, MIN, MAX, or SUM RequestHeaderCount RQHC MESSAGE
CNT RequestHeadersnnnn1 RQHDnnnn MESSAGE
AVG, MIN, MAX, or SUM RequestBodyLineCount RQBL MESSAGE
AVG, MIN, MAX, or SUM RequestBodyByteCount RQBB MESSAGE
AVG, MIN, MAX, or SUM ResponseByteCount RSCT MESSAGE
MIN or MAX ResponseVersionNumber RSVN MESSAGE
MIN or MAX ResponseStatusCode RSSC MESSAGE
AVG, MIN, MAX, or SUM ResponseHeaderCount RSHC MESSAGE
CNT ResponseHeadernnnn1 RSHDnnnn MESSAGE
AVG, MIN, MAX, or SUM ResponseBodyByteCount RSBB MESSAGE
AVG, MIN, MAX, or SUM ResponseBodyLineCount RSBL MESSAGE
AVG, MIN, MAX, or SUM ExpResponseByteCount EXCT MESSAGE
MIN or MAX ExpResponseVersionNumber EXVN MESSAGE
MIN or MAX ExpResponseStatusCode EXSC MESSAGE
AVG, MIN, MAX, or SUM ExpResponseHeaderCount EXHC MESSAGE
CNT ExpResponseHeadernnnn1 EXHDnnnn MESSAGE
AVG, MIN, MAX, or SUM ExpResponseBodyByteCount EXBB MESSAGE
AVG, MIN, MAX, or SUM ExpResponseBodyLineCount EXBL MESSAGE
1. Where nnnn is the Header Field Identifier. See Table B-2 on page B-5, for a list of identifiers.
Statistics For Field (long names) Field Short Names Collect from Table
A-4 Hiperstation for Mainframe Servers User Guide
SOCKETS Report Fields
COLLECT any or all of the following fields and REPORT them on customized SOCKETS reports.
Long Field Names Short Field Names
PlaybackNumber PLNU
ScriptStatementCount SCSC
SocketsDuration SODR
SocketsFinishTime SOFT
SocketsID SOID
SocketsNumber SONU
SocketsReturnCode SORC
SocketsStartTime SOST
SOCKETS Statistic Fields
REPORT any of the following statistics on customized SOCKETS reports.
Note: Use the Collect from Table column to determine the parameters for the collection statement required to report the given statistic. For example, to report MAXIMUM ScriptDuration from the SOCKETS table, you need to collect the ScriptDuration field from the SCRIPT table. Collect all fields from all tables to simplify collection and to ensure a complete reporting database.
Statistics For Field (long names) Field Short Names Collect from Table
MIN or MAX ScriptReturnCode SCRC SCRIPT
AVG, MIN, MAX, or SUM ScriptDuration SCDR SCRIPT
AVG, MIN, MAX, or SUM ConnectionDuration CNDR CONNECTION
AVG, MIN, MAX, or SUM MessageDuration MSDR MESSAGE
AVG, MIN, MAX, or SUM InitialResponseTime RTIN MESSAGE
AVG, MIN, MAX, or SUM FinalResponseTime RTFN MESSAGE
AVG, MIN, or MAX BytesSentRate BYSR MESSAGE
AVG, MIN, or MAX BytesReceivedRate BYRR MESSAGE
AVG, MIN, MAX, or SUM ConnectionCount CNCT SCRIPT
AVG, MIN, MAX, or SUM MessageCount MSCT CONNECTION
AVG, MIN, MAX, or SUM ConnectionsAttempted CNAT CONNECTION
AVG, MIN, MAX, or SUM ConnectionsRefused CNRF CONNECTION
AVG, MIN, MAX, or SUM ConnectionsTimedOut CNTO CONNECTION
AVG, MIN, MAX, or SUM TimeToConnect TMTC CONNECTION
AVG, MIN, MAX, or SUM TimeForConnectionRefusal TMCR CONNECTION
AVG, MIN, MAX, or SUM TimeForConnectionTimedOut TMCT CONNECTION
MIN or MAX ConnectionStatus CNSC CONNECTION
AVG, MIN, or MAX ConnectionRate CNRT SCRIPT
AVG, MIN, or MAX MessageRate MSRT CONNECTION
TCP/IP Data Collection and Reporting Tables A-5
SCRIPT TableThe SCRIPT table includes both report and statistic fields.
SCRIPT Report Fields
COLLECT any or all of the following fields and REPORT them on customized SCRIPT reports.
AVG, MIN, MAX, or SUM RequestByteCount RQCT MESSAGE
MIN or MAX RequestVersionNumber RQVN MESSAGE
AVG, MIN, MAX, or SUM RequestHeaderCount RQHC MESSAGE
CNT RequestHeadersnnnn1 RQHDnnnn MESSAGE
AVG, MIN, MAX, or SUM RequestBodyLineCount RQBL MESSAGE
AVG, MIN, MAX, or SUM RequestBodyByteCount RQBB MESSAGE
AVG, MIN, MAX, or SUM ResponseByteCount RSCT MESSAGE
MIN or MAX ResponseVersionNumber RSVN MESSAGE
MIN or MAX ResponseStatusCode RSSC MESSAGE
AVG, MIN, MAX, or SUM ResponseHeaderCount RSHC MESSAGE
CNT ResponseHeadernnnn1 RSHDnnnn MESSAGE
AVG, MIN, MAX, or SUM ResponseBodyByteCount RSBB MESSAGE
AVG, MIN, MAX, or SUM ResponseBodyLineCount RSBL MESSAGE
AVG, MIN, MAX, or SUM ExpResponseByteCount EXCT MESSAGE
MIN or MAX ExpResponseVersionNumber EXVN MESSAGE
MIN or MAX ExpResponseStatusCode EXSC MESSAGE
AVG, MIN, MAX, or SUM ExpResponseHeaderCount EXHC MESSAGE
CNT ExpResponseHeadernnnn1 EXHDnnnn MESSAGE
AVG, MIN, MAX, or SUM ExpResponseBodyByteCount EXBB MESSAGE
AVG, MIN, MAX, or SUM ExpResponseBodyLineCount EXBL MESSAGE
1. Where nnnn is the Header Field Identifier. See Table B-2 on page B-5, for a list of identifiers.
Statistics For Field (long names) Field Short Names Collect from Table
Long Field Names Short Field Names
ConnectionCount CNCT
ConnectionRate CNRT
PlaybackNumber PLNU
ScriptDuration SCDR
ScriptFinishTime SCFT
ScriptName SCNA
A-6 Hiperstation for Mainframe Servers User Guide
SCRIPT Statistic Fields
REPORT any of the following statistics on customized SCRIPT reports.
Note: Use the Collect from Table column to determine the parameters for the collection statement required to report the given statistic. For example, to report MAXIMUM MessageRate from the SCRIPT table, you need to collect the MessageRate field from the CONNECTION table. Collect all fields from all tables to simplify collection and ensure a complete reporting database.
ScriptNumber SCNU
ScriptReturnCode SCRC
ScriptStartTime SCST
SocketsNumber SONU
Long Field Names Short Field Names
Statistics For Field (long names) Field Short Names Collect from Table
AVG, MIN, MAX, or SUM ConnectionDuration CNDR CONNECTION
AVG, MIN, MAX, or SUM MessageDuration MSDR MESSAGE
AVG, MIN, MAX, or SUM InitialResponseTime RTIN MESSAGE
AVG, MIN, MAX, or SUM FinalResponseTime RTFN MESSAGE
AVG, MIN, or MAX BytesSentRate BYSR MESSAGE
AVG, MIN, or MAX BytesReceivedRate BYRR MESSAGE
AVG, MIN, MAX, or SUM MessageCount MSCT CONNECTION
AVG, MIN, MAX, or SUM ConnectionsAttempted CNAT CONNECTION
AVG, MIN, MAX, or SUM ConnectionsRefused CNRF CONNECTION
AVG, MIN, MAX, or SUM ConnectionsTimedOut CNTO CONNECTION
AVG, MIN, MAX, or SUM TimeToConnect TMTC CONNECTION
AVG, MIN, MAX, or SUM TimeForConnectionRefusal TMCR CONNECTION
AVG, MIN, MAX, or SUM TimeForConnectionTimedOut TMCT CONNECTION
MIN or MAX ConnectionStatus CNSC CONNECTION
AVG, MIN, or MAX MessageRate MSRT CONNECTION
AVG, MIN, MAX, or SUM RequestByteCount RQCT MESSAGE
MIN or MAX RequestVersionNumber RQVN MESSAGE
AVG, MIN, MAX, or SUM RequestHeaderCount RQHC MESSAGE
CNT RequestHeadersnnnn1 RQHDnnnn MESSAGE
AVG, MIN, MAX, or SUM RequestBodyLineCount RQBL MESSAGE
AVG, MIN, MAX, or SUM RequestBodyByteCount RQBB MESSAGE
AVG, MIN, MAX, or SUM ResponseByteCount RSCT MESSAGE
MIN or MAX ResponseVersionNumber RSVN MESSAGE
MIN or MAX ResponseStatusCode RSSC MESSAGE
AVG, MIN, MAX, or SUM ResponseHeaderCount RSHC MESSAGE
CNT ResponseHeadernnnn1 RSHDnnnn MESSAGE
AVG, MIN, MAX, or SUM ResponseBodyByteCount RSBB MESSAGE
TCP/IP Data Collection and Reporting Tables A-7
CONNECTION TableThe CONNECTION table includes both report and statistic fields.
CONNECTION Report Fields
COLLECT any or all of the following fields and REPORT them on customized CONNECTION reports.
AVG, MIN, MAX, or SUM ResponseBodyLineCount RSBL MESSAGE
AVG, MIN, MAX, or SUM ExpResponseByteCount EXCT MESSAGE
MIN or MAX ExpResponseVersionNumber EXVN MESSAGE
MIN or MAX ExpResponseStatusCode EXSC MESSAGE
AVG, MIN, MAX, or SUM ExpResponseHeaderCount EXHC MESSAGE
CNT ExpResponseHeadernnnn1 EXHDnnnn MESSAGE
AVG, MIN, MAX, or SUM ExpResponseBodyByteCount EXBB MESSAGE
AVG, MIN, MAX, or SUM ExpResponseBodyLineCount EXBL MESSAGE
1. Where nnnn is the Header Field Identifier. See Table B-2 on page B-5, for a list of identifiers.
Statistics For Field (long names) Field Short Names Collect from Table
Long Field Names Short Field Names
ClientAddress CLAD
ClientPort CLPT
ConnectionDuration CNDR
ConnectionFinishTime CNFT
ConnectionID CNID
ConnectionNumber CNNU
ConnectionsAttempted CNAT
ConnectionsRefused CNRF
ConnectionStartTime CNST
ConnectionStatus CNSC
ConnectionsTimedOut CNTO
MessageCount MSCT
MessageRate MSRT
PlaybackNumber PLNU
Protocol PROT
ScriptNumber SCNU
ServerAddress SVAD
ServerPort SVPT
A-8 Hiperstation for Mainframe Servers User Guide
CONNECTION Statistic Fields
REPORT any of the following statistics on customized CONNECTION reports.
Note: Use the Collect from Table column to determine the parameters for the collection statement required to report the given statistic. For example, to report MAXIMUM MessageDuration from the CONNECTION table, collect the MessageDuration field from the MESSAGE table. Collect all fields from all tables to simplify collection and to ensure a complete reporting database.
Statistics For Field (long names) Field Short Names Collect from Table
AVG, MIN, MAX, or SUM MessageDuration MSDR MESSAGE
AVG, MIN, MAX, or SUM InitialResponseTime RTIN MESSAGE
AVG, MIN, MAX, or SUM FinalResponseTime RTFN MESSAGE
AVG, MIN, or MAX BytesSentRate BYSR MESSAGE
AVG, MIN, or MAX BytesReceivedRate BYRR MESSAGE
AVG, MIN, MAX, or SUM RequestByteCount RQCT MESSAGE
MIN or MAX RequestVersionNumber RQVN MESSAGE
AVG, MIN, MAX, or SUM RequestHeaderCount RQHC MESSAGE
CNT RequestHeadersnnnn1
1. Where nnnn is the Header Field Identifier. See Table B-2 on page B-5, for a list of identifiers.
RQHDnnnn MESSAGE
AVG, MIN, MAX, or SUM RequestBodyLineCount RQBL MESSAGE
AVG, MIN, MAX, or SUM RequestBodyByteCount RQBB MESSAGE
AVG, MIN, MAX, or SUM ResponseByteCount RSCT MESSAGE
MIN or MAX ResponseVersionNumber RSVN MESSAGE
MIN or MAX ResponseStatusCode RSSC MESSAGE
AVG, MIN, MAX, or SUM ResponseHeaderCount RSHC MESSAGE
CNT ResponseHeadernnnn1 RSHDnnnn MESSAGE
AVG, MIN, MAX, or SUM ResponseBodyByteCount RSBB MESSAGE
AVG, MIN, MAX, or SUM ResponseBodyLineCount RSBL MESSAGE
AVG, MIN, MAX, or SUM ExpResponseByteCount EXCT MESSAGE
MIN or MAX ExpResponseVersionNumber EXVN MESSAGE
MIN or MAX ExpResponseStatusCode EXSC MESSAGE
AVG, MIN, MAX, or SUM ExpResponseHeaderCount EXHC MESSAGE
CNT ExpResponseHeadernnnn1 EXHDnnnn MESSAGE
AVG, MIN, MAX, or SUM ExpResponseBodyByteCount EXBB MESSAGE
AVG, MIN, MAX, or SUM ExpResponseBodyLineCount EXBL MESSAGE
SocketsNumber SONU
TimeForConnectionRefusal TMCR
TimeForConnectionTimedOut TMCT
TimeToConnect TMTC
Long Field Names Short Field Names
TCP/IP Data Collection and Reporting Tables A-9
MESSAGE TableThe MESSAGE table includes only report fields; not statistics fields.
MESSAGE Report Fields
COLLECT any or all of the following fields and REPORT them on customized MESSAGE reports.
Note: Some fields do not apply to all protocols. The columns on the right side of the table indicate the protocol the field applies to.
Long Field NamesShort Field
NamesHTTP,HTTPS
TCP, DB2C, IMSC ECI CTG
AF_family AFIN X X X X
BytesReceivedRate BYRR X X X X
BytesSentRate BYSR X X X X
ClientAddress6 CLA6 X X X X
ConnectionNumber CNNU X X X X
ExpResponseBody1 EXBD X X X X
ExpResponseBodyByteCount EXBB X X X X
ExpResponseBodyLineCount EXBL X
ExpResponseByteCount EXCT X X X X
ExpResponseHeaderCount EXHC X X X
ExpResponseHeadernnnn2 EXHDnnnn X
ExpResponseHeaders EXHS X X X
ExpResponseReasonPhrase EXRP X
ExpResponseStatusCode EXSC X
ExpResponseVersionNumber EXVN X
FinalResponseTime RTFN X X X X
InitialResponseTime RTIN X X X X
MessageDuration MSDR X X X X
MessageFinishTime MSFT X X X X
MessageID MSID X X X X
MessageNumber MSNU X X X X
MessageStartTime MSST X X X X
PlaybackNumber PLNU X X X X
RequestBody1 RQBD X X X X
RequestBodyByteCount RQBB X X X X
RequestBodyLineCount RQBL X
RequestByteCount RQCT X X X X
RequestHeaderCount RQHC X X X
RequestHeadernnnn2 RQHDnnnn X
RequestHeaders RQHS X X X
A-10 Hiperstation for Mainframe Servers User Guide
RequestMethod RQME X
RequestURI RQUR X
RequestVersionNumber RQVN X
ResponseBody1 RSBD X X X X
ResponseBodyByteCount RSBB X X X X
ResponseBodyLineCount RSBL X
ResponseByteCount RSCT X X X X
ResponseHeaderCount RSHC X X X
ResponseHeadernnnn2 RSHDnnnn X
ResponseHeaders RSHS X X X
ResponseReasonPhrase RSRP X
ResponseStatusCode RSSC X
ResponseVersionNumber RSVN X
ScriptNumber SCNU X X X X
ServerAddress6 SVA6 X X X X
SocketsNumber SONU X X X X
1. For ECI and CTG playback, this field reports ECI COMMAREA data.
2. Where nnnn is the Header Field Identifier. See Table B-2 on page B-5, for a list of identifiers.
Long Field NamesShort Field
NamesHTTP,HTTPS
TCP, DB2C, IMSC ECI CTG
B-1
Appendix B.
BTCP/IP Report Field Definitions App BDuring playback, you can set Hiperstation for Mainframe Servers to collect information on many separate fields. These fields are collected in five separate tables. The information in the final reports then comes from this data. The fields are:
Table B-1. Field Names and Descriptions
Field Name Description
AF_family (AFIN) The IP address format for the client and server. It can be either IPV4 or IPV6 format.
BytesReceivedRate (BYRR) Number of bytes received per unit time.
BytesSentRate (BYSR) Number of bytes sent per unit time.
ClientAddress (CLAD) The IP address of the client.
ClientAddress6 (CLA6) The IP address of the client in IPV6 format.
ClientPort (CLPT) The port number of the client.
ConnectionCount (CNCT) Number of CONNECTION instances, whether successful or only attempted, within a SCRIPT instance. This is not the number of attempts, but rather the number of <CONNECT> tags executed. For example, five attempts with the last attempt being successful counts as one CONNECTION. Five attempts with no success is also one CONNECTION.
ConnectionDuration (CNDR) Length in time of a CONNECTION instance (ConnectionFinishTime-ConnectionStartTime). If a connection is never established, equals 0.
ConnectionFinishTime (CNFT) Date and time when a CONNECTION instance finished, whether normally or not. This is when we issue the CLOSE verb during the playback or when we are notified that the partner has closed the connection.
ConnectionID (CNID) From the ID keyword on the <CONNECT> tag within a script.
ConnectionNumber (CNNU) Generated by Hiperstation for Mainframe Servers during playback, this uniquely identifies a CONNECTION instance within the scope of a SCRIPT instance. This value is NOT unique within the scope of the entire playback. Range: 4 byte unsigned integer.
ConnectionRate (CNRT) The number of CONNECTION instances created per unit time.
ConnectionsAttempted (CNAT) Number of times we tried to connect to a partner for a single <CONNECT> tag execution. If the user has a <CONNECT> and other tags within a REXX loop, each time the <CONNECT> tag is encountered is a new CONNECTION instance.
ConnectionsRefused (CNRF) Number of times a CONNECTION instance was refused by the partner.
ConnectionStartTime (CNST) If the connection is established, the TOD when we issued the successful CONNECT verb. If a connection is never established, the TOD when we issued the last attempted CONNECT verb.
B-2 Hiperstation for Mainframe Servers User Guide
ConnectionStatus (CNSC) The final status of the connection:
Normal: You established a connection, were able to send data on the connection, and received complete HTTP responses to all of the HTTP requests you transmitted.
TimedOut: You established a connection, have sent one or more HTTP requests on the connection, and might have received one or more HTTP responses on the connection, but did not receive a complete HTTP response for one of your HTTP requests (within the STDWAIT amount of time).
PrematureClose: You established a connection, might have sent one or more HTTP requests on the connection, might have received one or more HTTP responses on the connection, and then either ran out of CLIENT data in the script before you had a complete HTTP request to send or the partner (the server) closed the connection before it sent back a complete HTTP response. It is also a PrematureClose if the partner closes the connection at any point “in-flight”, e.g., while you are in the process of sending a request.
Reset: You established a connection, might have sent one or more HTTP requests on the connection, might have received one or more HTTP responses on the connection, and then received a TCP 'RESET' indicator.
CouldNotConnect: You could not establish a TCP connection with the partner, either because you timed out (STDWAIT) or because the partner refused the connection.
ConnectionsTimedOut (CNTO) Number of times a CONNECTION instance timed out rather than being established.
ExpResponseBody (EXBD) The (EXPECTED) entire response body. For ECI and CTG playback, this field reports ECI COMMAREA data.
ExpResponseBodyByteCount (EXBB)
(EXPECTED) Number of bytes in the response body.
ExpResponseBodyLineCount (EXBL)
(EXPECTED) Number of LINEFEED characters (x'0A') in the response body.
ExpResponseByteCount (EXCT) The (EXPECTED) number of bytes in a complete HTTP response.
ExpResponseHeadernnnn (EXHDnnnn)
The (EXPECTED) value of a particular HTTP response header, one of the values in Table B-2.
ExpResponseHeaderCount (EXHC)
The (EXPECTED) number of headers present in the HTTP response.
ExpResponseHeaders (EXHS) The (EXPECTED) value of all of the HTTP response headers present in the HTTP response.
ExpResponseReasonPhrase (EXRP)
The (EXPECTED) reason phrase present in the HTTP response.
ExpResponseStatusCode (EXSC)
The (EXPECTED) status code present in the HTTP response.
ExpResponseVersionNumber (EXVN)
The (EXPECTED) version number of the HTTP response, one of the following: HTTP/1.0, HTTP/1.1, or other version number.
FinalResponseTime (RTFN) The time elapsed from when the last byte of the HTTP request was sent until we see the last byte of the HTTP response.
InitialResponseTime (RTIN) The time elapsed from when the last byte of the HTTP request was sent until we see the first byte of the HTTP response.
JobName (JBNA) The MVS job name.
JobNumber (JBNU) The JES job number.
Table B-1. Field Names and Descriptions
Field Name Description
TCP/IP Report Field Definitions B-3
MessageCount (MSCT) Number of messages within a CONNECTION instance. This could be zero if the CONNECTION was never successful.
MessageDuration (MSDR) Length in time of a MESSAGE instance.
MessageFinishTime (MSFT) Date and time when a MESSAGE instance finished. This is when we received the last byte of data that makes up a complete HTTP response.
MessageID (MSID) The sequence number that is part of the <CLIENT> tag within a script for the first byte of the HTTP request.
MessageNumber (MSNU) Generated by Hiperstation for Mainframe Servers during playback, this uniquely identifies a MESSAGE instance within the scope of a CONNECTION instance. This value is NOT unique within the scope of the entire playback.
MessageRate (MSRT) The number of messages created per unit time.
MessageStartTime (MSST) Date and time when a MESSAGE instance started. This is when we first issue the SEND verb for the beginning of an HTTP request.
OwnerName (OWNA) Entered by the user on the CONTROL statement to provide the user with some indication of who did this playback (or other notes).
PlaybackDuration (PLDR) Length in time of the entire playback.
PlaybackFinishTime (PLFT) Date and time when the playback program finished.
PlaybackName (PLNA) Entered by the user on the CONTROL statement to provide the user with some indication of what this playback is about (or other notes).
PlaybackNumber (PLNU) Always set to 1 in this release of the product.
PlaybackReturnCode (PLRC) The return code of the entire playback jobstep. This will be the maximum of the internal return code (set by Hiperstation for Mainframe Servers when errors are detected) and the maximum script return code set by REXX code added by a user with a REXX EXIT or RETURNstatement.
PlaybackStartTime (PLST) Date and time when the playback program started.
Protocol (PROT) The application or network protocol used for a connection - either HTTP, HTTPS, or TCP.
RequestBody (RQBD) The entire request body, if present. For ECI and CTG playback, this field reports ECI COMMAREA data.
RequestBodyByteCount (RQBB) Number of bytes in the request body.
RequestBodyLineCount (RQBL) Number of LINEFEED characters (x'0A') in the request body.
RequestByteCount (RQCT) The number of bytes in a complete HTTP request.
RequestHeadernnnn (RQHDnnnn)
The value of a particular HTTP request header, where nnnn is one of the values in Table B-2 on page B-5.
RequestHeaderCount (RQHC) The number of headers present in the HTTP request.
RequestHeaders (RQHS) The value of all of the HTTP headers present in the HTTP request.
RequestMethod (RQME) The method sent in the HTTP request, one of the following: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, or other.
RequestURI (RQUR) The URI contained in the HTTP request.
RequestVersionNumber (RQVN) The version number of the HTTP request, one of the following: HTTP/1.0, HTTP/1.1, or -other-.
ResponseBody (RSBD) The (ACTUAL) entire response body. For ECI and CTG playback, this field reports ECI COMMAREA data.
ResponseBodyByteCount (RSBB)
(ACTUAL) Number of bytes in the response body.
Table B-1. Field Names and Descriptions
Field Name Description
B-4 Hiperstation for Mainframe Servers User Guide
ResponseBodyLineCount (RSBL) (ACTUAL) Number of LINEFEED characters (x'0A') in the response body.
ResponseByteCount (RSCT) The (ACTUAL) number of bytes in a complete HTTP response.
ResponseHeadernnnn (RSHDnnnn)
The (ACTUAL) value of a particular HTTP response header, one of the values in Table 8-2.
ResponseHeaderCount (RSHC) The (ACTUAL) number of headers present in the HTTP response.
ResponseHeaders (RSHS) The (ACTUAL) value of all of the HTTP response headers present in the HTTP response.
ResponseReasonPhrase (RSRP) The (ACTUAL) reason phrase present in the HTTP response.
ResponseStatusCode (RSSC) The (ACTUAL) status code present in the HTTP response.
ResponseVersionNumber (RSVN)
The (ACTUAL) version number of the HTTP response, one of the following: HTTP/1.0, HTTP/1.1, -other-.
ScriptDuration (SCDR) Length in time of a SCRIPT instance.
ScriptFinishTime (SCFT) Date and time when a SCRIPT instance finished.
ScriptName (SCNA) From the SCRIPT statement.
ScriptNumber (SCNU) Generated by Hiperstation for Mainframe Servers during playback, this uniquely identifies a SCRIPT instance within the scope of a SOCKETS instance. This value is NOT unique within the scope of the entire playback.
ScriptReturnCode (SCRC) The return code of a SCRIPT instance. This will be the maximum of the internal return code (set by Hiperstation for Mainframe Servers when errors are detected) and the maximum script return code set by REXX code added by a user with a REXX EXIT or RETURN statement.
ScriptStartTime (SCST) Date and time when a SCRIPT instance started.
ScriptStatementCount (SCSC) Number of SCRIPT instances under a specific SOCKETS instance.
ServerAddress (SVAD) The IP address of the server.
ServerAddress6 (SVA6) The IP address of the server in IPV6 format.
ServerPort (SVPT) The port number of the server.
SocketsDuration (SODR) Length in time of a SOCKETS instance.
SocketsFinishTime (SOFT) Date and time when a SOCKETS instance finished.
SocketsID (SOID) From the ID keyword on a SOCKETS statement.
SocketsNumber (SONU) Generated by Hiperstation for Mainframe Servers during playback, this uniquely identifies a SOCKETS instance within the scope of the playback. Analogous to PORT number in the VTAM version of Hiperstation for Mainframe Servers.
SocketsReturnCode (SORC) The return code of a SOCKETS instance. This will be the maximum of the internal return code (set by Hiperstation for Mainframe Servers when errors are detected) and the maximum script return code set by REXX code added by a user with a REXX EXIT or RETURN statement.
SocketsStartTime (SOST) Date and time when a SOCKETS instance started.
SocketsStatementCount (SOSC)
Number of SOCKETS instances in the playback.
SystemName (SYNA) The MVS system id, e.g., CW01.
TimeForConnectionRefusal (TMCR)
The amount of time between issuing the CONNECT verb and when the connection was refused by the partner.
TimeForConnectionTimedOut (TMCT)
The amount of time between issuing the CONNECT verb and when the connection request timed out.
Table B-1. Field Names and Descriptions
Field Name Description
TCP/IP Report Field Definitions B-5
The values in Table B-2 are valid values for the variable nnnn listed on several of the field names shown in Table B-1 on page B-1. Each of these valid values can be used on any field name that shows the variable nnnn.
TimeToConnect (TMTC) The amount of time between issuing the CONNECT verb and when the connection was actually established.
Table B-2. Valid Values for RequestHeadernnnn, ResponseHeadernnnn, ExpResponseHeadernnnn
Value
(ACPT) Accept
(ACCH) Accept-Charset
(ACEN) Accept-Encoding
(ACLA) Accept-Language
(ACRA) Accept-Ranges
(AGE) Age
(ALOW) Allow
(AUTH) Authorization
(CACO) Cache-Control
(CONN) Connection
(COEN) Content-Encoding
(COLA) Content-Language
(COLN) Content-Length
(COLO) Content-Location
(COMD) Content-MD5
(COOK) Cookie
(CORA) Content-Range
(COTY) Content-Type
(DATE) Date
(EXPC) Expect
(EXPR) Expires
(ETAG) ETag
(FROM) From
(HOST) Host
(IFMA) If-Match
(IFMS) If-Modified-Since
(IFNM) If-None-Match
(IFRA) If-Range
(IFUS) If-Unmodified-Since
(LAMD) Last-Modified
(LOCA) Location
(MXFW) Max-Forwards
Table B-1. Field Names and Descriptions
Field Name Description
B-6 Hiperstation for Mainframe Servers User Guide
(PRAG) Pragma
(PAUC) Proxy-Authenticate
(PAUZ) Proxy-Authorization
(RANG) Range
(REFR) Referer
(RTAF) Retry-After
(SRVR) Server
(TRLR) Trailer
(TREN) Transfer-Encoding
(TE) TE
(UPGD) Upgrade
(USAG) User-Agent
(VARY) Vary
(VIA) Via
(WARN) Warning
(WWWA) WWW-Authenticate
(OTHR) -concatenation of all others we see-
Table B-2. Valid Values for RequestHeadernnnn, ResponseHeadernnnn, ExpResponseHeadernnnn
Value
C-1
Appendix C.
CTCP Script Create Parameters App CTable C-1 describes the Script Create parameters found in the JCL generated during the script create process. Each parameter corresponds to a field or an option on the Script Create screens or to an operational parameter defined by the installer.
Table C-1. TCP/IP Script Create Parameters
Parameter Description
FILTERS._ACTION.n Action for filter n (INCL/EXCL)
FILTERS._CONTENT.0.n Number of <CONTENT> filters for filter n
FILTERS._CTG_APPLID.x.n CTG application ID for <CONTENT> filter x within filter n
FILTERS._CTG_APPLID_OP.x.n CTG application ID operator for <CONTENT> filter x within filter n
FILTERS._CTG_CAREA.x.n CTG COMMAREA (on CPMI records) for <CONTENT> filter x within filter n
FILTERS._CTG_CAREA_OP.x.n CTG COMMAREA (on CPMI records) for <CONTENT> filter x within filter n
FILTERS._CTG_PROGID.x.n CTG program ID for <CONTENT> filter x within filter n
FILTERS._CTG_PROGID_OP.x.n CTG program ID operator for <CONTENT> filter x within filter n
FILTERS._DB2_USRID.x.n DB2 user ID for <CONTENT> filter x within filter n
FILTERS._DB2_USRID_OP.x.n DB2 ushered operator for <CONTENT> filter x within filter n
FILTERS._ECI_CAREA.x.n ECI COMMAREA for <CONTENT> filter x within filter n
FILTERS._ECI_CAREA_OP.x.n ECI COMMAREA operator for <CONTENT> filter x within filter n
FILTERS._ECI_PROGID.x.n ECI program ID for <CONTENT> filter x within filter n
FILTERS._ECI_PROGID_OP.x.n ECI program ID operator for <CONTENT> filter x within filter n
FILTERS._ECI_USERID.x.n ECI user ID for <CONTENT> filter x within filter n
FILTERS._ECI_USERID_OP.x.n ECI user ID operator for <CONTENT> filter x within filter n
FILTERS._IMS_CDATA.x.n IMS client USERDATA for <CONTENT> filter x within filter n
FILTERS._IMS_CDATA_OP.x.n IMS client USERDATA operator for <CONTENT> filter x within filter n
FILTERS._IMS_CLIENT.x.n IMS client ID for <CONTENT> filter x within filter n
FILTERS._IMS_CLIENT_OP.x.n IMS client ID operator for <CONTENT> filter x within filter n
FILTERS._IMS_DSTORE.x.n IMS datastore ID for <CONTENT> filter x within filter n
FILTERS._IMS_DSTORE_OP.x.n IMS datastore ID operator for <CONTENT> filter x within filter n
FILTERS._IMS_SDATA.x.n IMS server USERDATA for <CONTENT> filter x within filter n
FILTERS._IMS_SDATA_OP.x.n IMS server USERDATA operator for <CONTENT> filter x within filter n
FILTERS._IMS_TRANS.x.n IMS transaction code for <CONTENT> filter x within filter n
FILTERS._IMS_TRANS_OP.x.n IMS transaction code operator for <CONTENT> filter x within filter n
FILTERS._IMS_USERID.x.n IMS user ID for <CONTENT> filter x within filter n
FILTERS._IMS_USERID_OP.x.n IMS user ID operator for <CONTENT> filter x within filter n
FILTERS._RDB_NAME.x.n Relational database name for <CONTENT> filter x within filter n
C-2 Hiperstation for Mainframe Servers User Guide
FILTERS._RDB_NAME_OP.x.n Relational database name operator for <CONTENT> filter x within filter n
FILTERS._SQL_ANSWER.x.n SQL answer set for <CONTENT> filter x within filter n
FILTERS._SQL_ANSWER_OP.x.n SQL answer set operator for <CONTENT> filter x within filter n
FILTERS._SQL_CODE.x.n SQLcode for <CONTENT> filter x within filter n
FILTERS._SQL_CODE_OP.x.n SQLcode operator for <CONTENT> filter x within filter n
FILTERS._SQL_STATE.x.n SQLstate for <CONTENT> filter x within filter n
FILTERS._SQL_STATE_OP.x.n SQLstate operator for <CONTENT> filter x within filter n
FILTERS._SQL_STMT.x.n SQL statement for <CONTENT> filter x within filter n
FILTERS._SQL_STMT_OP.x.n SQL statement operator for <CONTENT> filter x within filter n
FILTERS.0 Number of filters
TCPCSMSG Maximum message size, in kilobytes, that can be processed (32K is the default)
Note: This parameter does not correspond to a field or operational parameter. Add the parameter to the Script Create JCL prior to submitting the job. See “Select a Processing Option” on page 7-19 to find out how to access the JCL for edit.
TCPCRBLK New repository BLKSIZE
TCPCRPRM New repository Primary space
TCPCRSDC New repository DATACLASS
TCPCRSEC New repository Secondary space
TCPCRSMC New repository MGMTCLASS
TCPCRSPC New repository SPACE unit
TCPCRSSC New repository STORCLASS
TCPCRUNT New repository UNIT
TCPCRVOL New repository Volume name
TCPCSBRK Split line at LineFeed flag
TCPCSCIP Create scripts with connections grouped by Client IP address.
TCPCSCPT Create scripts with connections grouped by Client IP port.
TCPCSDBG Debug Flags “00000000”
TCPCSDD1 EXECSRC dataset name
TCPCSDD2 LOADLIB dataset name
TCPCSDS Store details together with client and/or server tags or separately (1...3).
TCPCSEDA End Time End day (1...31)
TCPCSEHR End Time End hour (0...23)
TCPCSEMI End Time End minute (0...59)
TCPCSEMO End Time End month (1...12)
TCPCSESE End Time End seconds (0...59)
TCPCSEYR End Time End year YYYY
TCPCSFMT Suppress protocol formatting
Table C-1. TCP/IP Script Create Parameters
Parameter Description
TCP Script Create Parameters C-3
TCPCSGRP Script Grouping 1/2/3
TCPCSI1 Input repository FIRST number
TCPCSI2 Input repository LAST number
TCPCSICL Data from client ALL/number
TCPCSIDN Input Repository specification
TCPCSISL Data from server ALL/number
TCPCSO1 Output repository FIRST number
TCPCSO2 Output repository LAST number
TCPCSOBD Combined detail dataset name
TCPCSOBN Combined detail DDname
TCPCSOBP Combined detail member prefix
TCPCSOBQ Combined detail required flag
TCPCSOBS Combined detail member suffix
TCPCSOCD Client detail dataset name
TCPCSOCN Client detail DDname
TCPCSOCP Client detail member prefix
TCPCSOCQ Client detail required flag
TCPCSOCS Client detail member suffix
TCPCSODN Output Repository specification
TCPCSOLD Log dataset name
TCPCSOLP Log member prefix
TCPCSOLQ Log required flag
TCPCSOLS Log member suffix
TCPCSOPD Output script PDSE name
TCPCSOPP Output script member prefix
TCPCSOPQ Output script required flag
TCPCSOPS Output script member suffix
TCPCSOSD Server detail dataset name
TCPCSOSN Server detail DDname
TCPCSOSP Server detail member prefix
TCPCSOSQ Server detail required flag
TCPCSOSS Server detail member suffix
TCPCSPRO Create Script by Protocol
TCPCSQDS Created Script Description
TCPCSQER Error event notification ‘/’
TCPCSQNR Normal event notification ‘/’
TCPCSQTD Trans detail data A2E flag
TCPCSQTM Suppress timestamps flag
TCPCSQTS Trans sample data A2E flag
Table C-1. TCP/IP Script Create Parameters
Parameter Description
C-4 Hiperstation for Mainframe Servers User Guide
TCPCSRD Create Details flag
TCPCSRL Create Log flag
TCPCSRS Create Script flag
TCPCSSDA Start Time day (1...31)
TCPCSSHR Start Time hour (0...23)
TCPCSSIP Create scripts with connections grouped by Server IP address
TCPCSSMI Start Time minute (0...59)
TCPCSSMO Start Time month (1...12)
TCPCSSPT Create scripts with connections grouped by Server IP port
TCPCSSRP Subset Repository wanted flag
TCPCSSSE Start Time seconds (0...59)
TCPCSSUB Processing option 1/2/3/X/x
TCPCSSYR Start Time year YYYY
TCPCSUPR Force messages uppercase flag
TCPCSWD Replace Details flag
TCPCSWL Replace Log flag
TCPCSWS Replace Script flag
TCPUSER Invoking user ID
Table C-1. TCP/IP Script Create Parameters
Parameter Description
D-1
Appendix D.
DCustomer Support Diagnostics App DThe Customer Support Diagnostic Report produces a list of PTFs that have been applied to your installation. Customer Support may ask you to generate the report to aid in diagnosing an issue.
Note: Generating this report requires READ access to the SMP/E datasets. Consult with your Security Administrator if you do not have the proper authority.
To generate the Customer Support Diagnostic:
1. On the Hiperstation Product Menu, type PTFS on the Option Line and press Enter. The Hiperstation - Diagnostics screen appears (Figure D-1).
Figure D-1. Hiperstation Diagnostics Screen
---------------------- Hiperstation - Diagnostics ------------------- Command ===> Specify the install and output datasets, then press ENTER to continue. Input datasets to use: Global CSI dataset . . 'COMPWARE.QQF800.GLOBAL.CSI' Target Zone . . . . . . QQF800 Output datasets to use: PTF output list . . . . 'JSMITH.PTFS.REPORT' Job statement information for batch job: ===> //USER05 JOB ('ACCOUNT',99),'J.SMITH',REGION=0M, ===> // NOTIFY=&SYSUID,CLASS=A,MSGCLASS=R,USER=JSMITH ===> //* ===> //*
The Global CSI dataset is the SMP/E Global CSI dataset. The Target Zone is the SMP/E Target Zone. These fields default to the dataset name and target zone established by your installer. The PTF output list is the sequential dataset to contain the report.
2. Complete the PTF output list field, insert a job card, and press Enter. Hiperstation submits the job.
3. Once the job has completed, view the report with ISPF. Figure D-2 shows a sample report.
D-2 Hiperstation for Mainframe Servers User Guide
Figure D-2. Customer Support Diagnostic Report
********************************* Top of Data ********************************** +---------------------------------------------------------------+ | Hiperstation PTF list 05/10/07 15:32:08 | | Loadlib: SYS2.HIPER.SQQFLOAD | +---------------------------------------------------------------+ QF43181 QF44415 QF45463 QF46350 QF47331 QF47364 QF47687 QF47857 QF48238 QF48264 QF48286 QF48302 QF48428 QF48749 QF48753 QF48864 QF48915 QF48950 QF48953 QF49143 QF49175 QF49197 QF49312 QF49420 QF49423 QF49451 QF49580 QF49647 QF50149 QF50220 QF50276 QF50354 QF50457 QF50731 ******************************** Bottom of Data ********************************
G-1
Glossary
This glossary gives a brief description of Hiperstation for Mainframe Servers terms, and other related terms referred to in this document.
abend. ABnormal END of task. The termination of a job, prior to normal completion, due to an unresolved error condition.
APPC. Advanced Program-to-Program Communi-cations. A protocol in a distributed environment that allows programs to talk to each other and interconnected systems to communicate and share the processing of programs.
APPC conversation. The activity that occurs between ALLOCATE and DEALLOCATE.
APPC script. Formatted human-readable data generated from a capture repository. You can gen-erate scripts from selected sessions or from entire capture repositories.
APPC summary report. A report that provides performance statistics and comparison results.
APPC unattended playback statements. State-ments that provide processing rules and define what conversations (scripts) to play back.
archive/search function. A Hiperstation option that allows you to create archive record requests. A request is started and repositories are generated based on filter criteria. The registry dataset con-tains entries that indicate the date and time ranges of each generated repository segment so that the Archive/Search function can locate specific datas-ets by date and time.
batch. Processing in which jobs are submitted and processed in the background. The jobs run unattended and are executed sequentially. Each job must be processed to completion before the following job can begin execution. Batch is the converse of an interactive or online task.
capture repository. A repository where recorded activity is written to a sequential dataset or series of datasets. Testing scripts are then generated from the capture repository. Capture repositories con-tain recorded activity in a compressed format. See also repository dataset.
capture segment summary report. A report that indicates when recording began and ended for
each segment of one or more specified capture repositories. You can use it to help you identify the information contained in each segment. For example, generate this report to script activity that was captured on Monday morning from 8:00 am to 12:00 pm if you are unsure which repository segment contains the information. You can import the report into a spreadsheet or database for easy manipulation.
CICS. Customer Information Control System. An IBM-licensed program that enables transactions entered at remote terminals to be processed con-currently by user-written application programs. It includes facilities for building, using, and main-taining databases.
CNOS. Change Number of Sessions.
command. Request from a terminal to execute an operation or program.
COMMAND field. Field in which you enter com-mands to execute an operation or program.
CPIC. Common Programming Interface for Com-munications.
customer support diagnostics report. A report that produces a list of PTFs that have been applied to your installation. Customer Support may ask you to generate the report to aid in diagnosing an issue.
CSV. Comma Separated Value. A report format that is available for custom Playback reports. Some basic reports support only HTML while others sup-port TEXT and HTML.
DASD. Direct Access Storage Device. Any periph-eral device that is directly addressable, such as a disk or drum.
data stream. A sequence of digitally encoded dat-apacket signals that send or receive information in transmission. Global recording does not support VTAM compressed data streams.
dataset. Refers to files stored on an IBM main-frame computer. Datasets can be organized in vari-ous ways, such as logical record and block structures.
DB2. DATABASE 2. IBM’s database management system that provides a relational model of data. DB2 runs as a subsystem of MVS and on other platforms.
G-2 Hiperstation for Mainframe Servers User Guide
DBCS. Double Byte Character Set. Used primarily to display Japanese Kanji characters during 3270 testing.
dump. Hexadecimal representation of storage that may contain data useful for diagnosing an error.
Enterprise Common Components (ECC). The shared components of mainframe Compuware products, that provide Compuware License Man-agement System.
exception. (1) An abnormal situation that may occur during a program’s execution that may cause a deviation from the normal execution sequence, and for which facilities exist in the pro-gramming language to define, recognize, ignore, or handle it. (2) An abnormal condition such as an I/O error encountered in processing a dataset or file.
file. Set of related records that are organized and treated as a unit.
GDG. Generation Data Group.
global record manager. A Hiperstation for VTAM function that builds lists of applications, termi-nals, and user IDs to include or exclude from recording. Global Record Manager Lists provide greater flexibility in defining Global Recording requests.
global recording. An option that captures the activity of one or more users. This option writes the activity to a repository that generates testing scripts. It records LU0 and3270 traffic to generate stress tests or to archive activity for audit pur-poses. It also captures LU6.2, TCP/IP and MQ data. You can record while groups of users perform their daily routines and choose the exact terminals, applications, and time frames to record. You can choose to include or exclude certain messages from recording based on a predefined list of mes-sages. Message filtering provides a script that con-tains a subset of the messages from the 3270 session. You can also create and reuse lists of user IDs, logical unit (LU) names, or applications that can be included or excluded from a session.
GMT. Greenwich Mean Time.
IMS. Information Management System. IBM’s hierarchical database information management system and transaction processor capable of man-aging complex databases and networks.
JCL. Job control language. A job or task control language that describes how a job or task will be executed. All non-operating system tasks (batch or online) use JCL to execute in MVS/JES2.
line command. Command that is typed directly on the line to be processed.
LUW. Logical Unit of Work.
masking. A function that prevents comparison of specified TCP/IP message data. Data masks are statements that specify qualification criteria and stipulate the positions to mask if the criteria is met. Masking date and time fields will prevent generating mismatches for data that you expect to be different.
MVS. Multiple Virtual Storage. The primary oper-ating system used on large IBM mainframe com-puters. It is packaged as the operating system component of OS/390 and z/OS. It was packaged separately as MVS/XA (eXtended Architecture), MVS/ESA (Enterprise Systems Architecture), and OS/MVS. Through its evolution, the core operat-ing system has remained fundamentally the same. Most programs written for MVS can run on z/OS without modification.
offset. A relative location or position within a data area.
operating system. Software that controls the execution of jobs. It may provide resource alloca-tion and scheduling.
operation exception. An operation exception occurs when the CPU attempts to execute an instruction with an invalid operation code. The operation code may be unassigned, or the instruc-tion with that operation code may not be installed on the CPU.
OS. Operating System.
PIU. Path Information Units.
PDS. Partitioned Dataset.
PDSE. Partitioned Dataset Extended.
PF keys. Program Function keys. ISPF uses PF keys for many commonly used functions such as <End>, <Repeat Find>, and <Scroll>. For example, pressing the PF3 key in ISPF usually sends the <End> command to the application. Most termi-nals have 24 PF keys.
PF key mapping. A method for assigning func-tions to your PF keys. If your terminal has 24 PF keys, you can assign some of them to the domain destination. ISPF uses the rest of the keys. Gener-ally, PF1 through PF12 are mapped to PF1 through PF12 for the domain destination, and PF13 through PF24 are seen directly by ISPF. This map correspondence is established on the Session Options screen.
G-3
PLU. Primary Logical Unit. The logical unit that is being accessed by the SLU. See SLU.
primary command. Command that provides a general function and is entered in the COMMAND field.
playback. A function that can be run in unat-tended mode for batch testing of applications that use APPC or TCP/IP.
repository dataset. The name of the dataset to use for storing captured information. For active requests, this is the dataset in which data is cur-rently being written. See also capture repository.
REXX log. A log that records the text of REXX SAY statements. These statements can be used to track script progress.
script language tokens. Consist of variable names, arithmetic operators, constants, and other language constructs.
STIME. Start time. STIME indicates the date and time value that controls the activation of the ALLOCATE statement. STIME is used on the CON-TROL statement.
storage. A functional unit into which data can be placed and from which it can be retrieved.
subtask. Task initiated and terminated by a higher order task.
TCP/IP. Transmission Control Protocol/Internet Protocol. Communication protocols on which the Internet and most commercial networks run.
TCP/IP script. Formatted human-readable data generated from a capture repository. You can script only the repository segments needed rather than the entire capture repository.
think time. The amount of time between each recorded user action.
THOPT. Think option. A playback parameter that forces the group to play back at approximately the same speed as it was recorded. THOPT in APPC is used on the ALLOCATE/ACCEPT statements. THOPT in TCP/IP is used on the CONTROL state-ment and/or the SOCKET statement.
THPCT. A parameter that sets a think time per-centage. This parameter is only valid in conjunc-tion with THOPT(2|3). For example, the statement: ALLOCATE … THOPT(2) THPCT(25) plays back the script at 25 percent of the original think time recorded in the script. The APPC data sent to the partner by Hiperstation for Mainframe Servers is sent after waiting for 25 percent of the amount of
time recorded in the script. THPCT values of less than 100 cause the script to be played back with a think time less than originally recorded. THPCT values greater than 100 cause the script to be played back with a think time greater than origi-nally recorded. THPCT in APPC is on the ALLO-CATE/ACCEPT statements. THPCT in TCP/IP is on the CONTROL statement and/or the SOCKET statement.
trace. Record of the execution of a computer pro-gram; it exhibits the sequences in which the instructions were executed.
transaction. A unit of processing, which consists of one or more application programs, begun by a single request (usually from a terminal).
unattended mode processing. An option for APPC testing that will build JCL used for unat-tended playback. This option is not in or available for TCP/IP options.
unattended playback. A function that allows you to play back scripts to test TCP/IP applica-tions. Provided that you collect the appropriate playback information, you can generate reports that compare the activity resulting from playback (actual) to the activity recorded in the script (expected).
USESTIME. Use Start Time. A playback CONTROL statement parameter that indicates that ALLO-CATE statements start at the time interval set on their respective STIME keywords, rather than at the beginning of the playback job. USESTIME pro-vides control over the start of conversations and the timing of the data sent from each conversa-tion. USESTIME is used on the CONTROL STATE-MENT for APPC and on the CONTROL and/or SOCKET statement for TCP/IP.
VSAM. Virtual Storage Access Method. An access method for direct or sequential processing of fixed and variable length records on direct access devices.
VTAM. Virtual Telecommunications Access Method. Set of programs that control communica-tion between terminals and application programs.
WebSphere MQ. An IBM network communica-tion technology that is part of a suite of Web-Sphere products. It provides the ability for independent programs on a distributed system to communicate with each other. Formerly called MQSeries.
XLN. Exchange Log Name.
XML. Extensible Markup Language. A language that is capable of describing many different kinds
G-4 Hiperstation for Mainframe Servers User Guide
of data. The XML file can contain the data as well as the data description or structure. Its purpose is to share data across different systems.
z/OS. IBM enterprise mainframe suite of product components, one of which is the MVS operating system. It is used to build and deploy Internet and Java-enabled applications, providing a compre-hensive and diverse application execution envi-ronment.
I-1
Index
Numerics
3270add Global Recording request, 2-11
A
ACCEPT statement, APPC, 4-2, 4-22, 4-54connection parameters, 3-4documentation parameters, 3-5LUW parameters, 3-6parameters, 3-4security parameters, 3-6timing parameters, 3-6
accessibilityfont and font size, xxiiikeyboard shortcuts, xxivwindows accessibility features, xxiii
activity grouping, 7-11ADD function, 2-42add Global Recording request
3270, 2-11APPC, 2-11TCP/IP, 6-9
administrator accessGlobal Recording, APPC, 2-13, 2-16monitor requests, TCP/IP, 6-10
Adobe Reader, xviiallocate datasets
for logs, scripts, details, 7-17for repositories, 7-19
ALLOCATE statement, APPC, 4-2, 4-22, 4-44, 4-54connection parameters, 3-4documentation parameters, 3-5LUW parameters, 3-6parameters, 3-4security parameters, 3-6timing parameters, 3-6
<ALLOCATE> tag, APPC, 4-12allocation parameters, TCP/IP, 6-16<APPC> protocol parameter, 2-19APPC statements
ACCEPT, 4-22ALLOCATE, 4-22APPCGRP, 4-29CACHEXCL, 4-20CACHINCL, 4-20COMPANY, 4-21CONTROL, 4-18SCRIPT, 4-32unattended playback statement descriptions, 4-16unattended processing statements, 3-2
APPC testingplayback, 4-2REXX variables, application data, 4-36REXX variables, environment data, 4-36
REXX variables, error determination, 4-35APPCGRP statement, APPC, 4-29, 4-54ASCII
from EBCDIC translation, 2-20to EBCDIC translation, 7-18
B
background processing, 2-14batch
edit job for script/subset repository creation, 7-20batch interface, APPC, 2-17BookManager
documentation output, xviiiknown issues, xix
browse scripts, 7-21BRULE macro, 7-34BRULES macro, 7-34
C
CACHE EXCLUDE statement, APPCparameters, 3-8
CACHE INCLUDE statement, APPCparameters, 3-8
CACHEXCL statement, APPC, 4-20CACHINCL statement, APPC, 4-20cancel
Global Recording request, APPC, 2-10, 2-41Global Recording request, TCP/IP, 6-8, 6-20
CANCEL function, 2-42cancel requests, 2-10capture criteria
APPC, 2-3output options, 2-6
capture fileallocation parameters, 2-27APPCSee also repository datasetsspecification tags, APPC, 2-49
capture file parameter tags, 2-26, 6-16capture files
segmented, 2-28capture parameter tags, scheduled, 2-26capture repository, TCP/IP, 6-1, 7-1Capture Segment Summary, 2-50, 7-1client IP addresses, 7-10<CLIENT> tag, TCP/IP, 7-25CMCFM, 4-11CMCFMD, 4-12CMCRTS, 4-13CMDEAL, 4-12CMFLUS, 4-12CMPTR, 4-13CMSEND, 4-13CMSERR, 4-14CMSNDX, 4-14COLLECT statement, TCP/IP, 9-16, A-1combined detail dataset, 12-6combined detail tags, APPC
I-2 Hiperstation for Mainframe Servers User Guide
allocation parameters, 2-35COMPANY statement, APPC, 4-21
parameters, 3-8Compuware
mailing address, xxvi<CONFIRM> tag, APPC, 4-11<CONFIRMED> tag, APPC, 4-12connect filters
DB2, 7-4IMS, 7-5
<CONNECT> tag, TCP/IP, 7-22connection log, 7-1, 7-15, 9-2, 12-10CONNECTION STATUS, B-2CONNECTION table, A-7<CONTENT> tag
APPC, 4-5TCP/IP
detail data, 7-15for external data, 7-29for inline data, 7-28
control script tags, 4-4control script tags, APPC
ALLOCATE, 4-12CONFIRM, 4-11CONFIRMED, 4-12CONTENT, 4-5DEALLOCATE, 4-12DETAIL, 4-5ERROR, 4-6EXTDATA, 4-6EXTRACT, 4-10FLUSH, 4-12INBOUND, 4-6OUTBOUND, 4-7PIU, 4-7PREPARE_TO_RECEIVE, 4-13REPLACE, 4-7REQUEST_TO_SEND, 4-13SEND_DATA, 4-13SEND_ERROR, 4-14SEND_EXPEDITED_DATA, 4-14TIME, 4-11UNKNOWN, 4-11VERSION, 4-5
CONTROL statement, APPC, 4-18parameters, 3-3
CONTROL statement, TCP/IP, 9-3, 9-18reporting, 10-3
conversation log, 12-5conversation log dataset, 12-6conversation log, APPC, 2-7, 2-31–2-32, 4-2, 4-22, 4-55
allocation parameters, 2-33subparameters, 2-32
create JCL, 4-56create scripts, 2-12, 7-1, 9-3
filter criteria, 7-1create TCP/IP scripts option
access, 7-1CTG
filters, 7-7suppress CONTENT data formatting, 7-18
<CTG> tag, TCP/IP, 7-26custom reports
TCP/IP, A-1custom reports, TCP/IP, 10-9customer support, xxv
Customer Support Diagnostic Report, G-1diagnostic report, D-1
D
datasetsoutput, 7-16
datastreamsplayback, APPC, 4-2
DB2connect filters, 7-4message pipelining, 9-21SQL statement, 7-26suppress CONTENT data formatting, 7-18
<DB2> tag, TCP/IP, 7-26DCIADXL6 sample, 2-20DCIJCL, APPC
check status of requests, 2-39create Global Recording request, 2-18generate a parameters skeleton, 2-43manage Global Recording requests, 2-40retrieve parameters from a request, 2-42
DCIJCL, TCP/IPcheck status of requests, 6-19create Global Recording request, 6-10generate a parameters skeleton, 6-22manage Global Recording requests, 6-20retrieve parameters from a request, 6-21
DCIPROC, 2-40<DEALLOCATE> tag, APPC, 4-12detail data, APPC
script tags, 4-14script tags syntax, 4-15
detail data, TCP/IPaccess MAPD help panels, 7-41DDname, 7-17edit with File-AID/MVS, 7-38number of bytes recorded, 7-25storage, 7-14translate ASCII to EBCDIC, 7-18troubleshoot message mapping, 7-41
detail datasetsLRECL, 7-17
<DETAIL> tagAPPC, 4-5TCP/IP, 7-17, 7-21
disableGlobal Recording request, APPC, 2-11, 2-41Global Recording request, TCP/IP, 6-9, 6-20
<DISCONNECT> tag, TCP/IP, 7-24documentation
master index, xvii
E
EBCDICfrom ASCII translation, 7-18to ASCII translation, 2-20
ECIfilters, 7-8suppress CONTENT data formatting, 7-18
<ECI> tag, TCP/IP, 7-27edit scripts, 4-4EHSBATCH program, 4-1end date and time
Global Recording (APPC), 2-4environment data REXX variables, 4-36
I-3
environment optionsplayback, 8-5
error determinationREXX variables, APPC, 4-35
error event notificationGlobal Recording, 2-5
error messagessuppress, 8-9
<ERROR> tag, APPC, 4-6event notification, 2-5event notification tags
recording options, 2-49example
data-driven testing, APPC, 4-44example jobs
unattended playback, APPC, 4-40<EXTDATA> tag, APPC, 4-6<EXTRACT> tag
APPC, 4-10
F
FEEDBACK DD, 2-18APPC request keys, 2-40TCP/IP request keys, 6-19VIEW, 2-42–2-43, 6-22
File-AID/MVSedit TCP/IP detail data, 7-38
filter IP addresses, 7-9filters
criteria, 7-1CTG, 7-7ECI, 7-8IPv4, 7-10IPv6, 7-10
first numberAPPC, 12-3TCP/IP, 12-8
<FLUSH> tag, APPC, 4-12font and font size, accessibility, xxiiiforce
Global Recording request, 2-4–2-5Global Recording request, APPC, 2-10, 2-41Global Recording request, TCP/IP, 6-9, 6-20
FORCE command, 2-28FORCE function, 2-42foreground processing, 2-14FrontLine, xviii
support Web site, xxv
G
general request parameters, 2-25, 6-15general script criteria tags, 2-29generate APPC unattended processing statements, 3-2getting help, xxvglobal CSI dataset, D-1Global Recording
accessing administration, 2-16error event notification, 2-5
Global Recording (APPC), 2-1, 2-10add requests, 2-2, 2-11administrator access, 2-16allocate dataset, 2-6
batch interface, 2-17cancel requests, 2-41capture file parameter tags, 2-26Capture Segment Summary, 2-50combined detail tags, 2-34conversation log tags, 2-32create include/exclude lists, 2-16create request, 2-2, 2-17create scripts, 2-43define manager lists, 2-16disable request, 2-41disable requests, 2-11end date and time, 2-4force request, 2-41force requests, 2-10general request parameters, 2-25general script criteria tags, 2-29inbound detail tags, 2-36KEYS function, 2-39manage requests, 2-40merge capture repositories, 2-52monitor requests, 2-3, 2-10outbound detail tags, 2-38parameter syntax, 2-18protocol parameter, 2-24record all sessions, 2-14recording option parameter tags, 2-28recording script tags, 2-29request activation, 2-2request parameters, 2-20request status, 2-39restart request, 2-41restart requests, 2-11retrieve parameters from an existing request, 2-42review captured activity, 2-42scheduled capture parameter tags, 2-26script create parameters, 2-44script creation option tags, 2-31start date and time, 2-4stop request, 2-41stop requests, 2-11summary report, 4-39, 5-1TN3270, 2-3trace conversation, 4-29troubleshoot failed requests, 2-50unattended processing, 3-1update a request, 2-41update requests, 2-11VIEW, 2-42view active sessions, 2-11
Global Recording (TCP/IP)add and manage recording requests, 6-1add request, 6-1, 6-9administrator access, 6-10allocation parameters, 6-16batch interface, 6-10cancel a request, 6-20cancel request, 6-8capture file parameter tags, 6-16check status of requests, 6-19collect data, 6-4collect data filtering, 6-3create request, 6-10create scripts, 7-1create scripts option, 7-1data collection, A-1data to keep tags, 6-17disable a request, 6-20
I-4 Hiperstation for Mainframe Servers User Guide
disable request, 6-9force a request, 6-20force request, 6-9general request parameter tags, 6-15KEYS, 6-19manage existing requests, 6-20masking statements, 10-7merge capture repositories, 6-23monitor requests, 6-3, 6-8parameter syntax, 6-11protocol parameter, 6-15recording option parameter tags, 6-17reporting, 10-1reporting tables, A-1request parameter syntax, 6-11request parameters, 6-13restart a request, 6-20restart request, 6-9retrieve parameters from existing request, 6-21scheduled capture parameter tags, 6-15segment capture repositories, 6-5start date and time, 6-3stop a request, 6-20stop request, 6-9subset repositories, 7-1suppress CONTENT data formatting, 7-18switch repository segments, 6-9, 6-21SYSPLEX job input parameters, 6-24TCP capture filter tags, 6-18TN3270, 6-2troubleshoot failed requests, 6-23unattended playback, 9-1update a request, 6-21update request, 6-9VIEW, 6-21view request, 6-9
Global Recording Manager, 2-1lists, 2-16
GMT (Greenwich Mean Time), 2-51grouping
activity, 7-11
H
help, Hiperstation customer support, xxvhierarchy, APPC playback statements, 4-22HTML
reports, TCP/IP, 10-13HTML documentation files, xviiiHTML Exception Report, 10-6, 10-17HTTP
message pipelining, 9-8, 9-15
I
IBMBookManager documentation output, xviiiIEBGENER utility, 2-20, 2-45Softcopy Reader, xviii
IEBGENER utility, 2-20, 2-45IMS
connect filters, 7-5datastore, 7-28suppress CONTENT data formatting, 7-18
<IMS> tag, TCP/IP, 7-27inbound detail dataset, 12-6inbound detail tags, APPC
allocation parameters, 2-37parameters, 2-36
<INBOUND> tag, APPC, 4-6include/exclude lists
Global Recording, APPC, 2-16index, master, xviiinformational messages
unattended playback, 4-33introduction to this guide
notation conventions, xxIP address
client, 7-3, 7-23server, 7-3, 7-23
IP address filters, 7-9IPv4 filters, 7-10IPv4 IP address filter, 7-10IPv6 filters, 7-9IPv6 IP address filter, 7-10ISPF
EDIT screen, 3-11keylist utility, 7-39view, 7-39
J
JCLgenerate for unattended statements, 3-10JCL for unattended playback, 4-1PERSONAL LIBRARIES, 9-25run sample reports, 10-2SYSPLEX sample, 2-52SYSPLEX samples, 6-23
K
key sharing logic, APPC, 4-49keyboard shortcuts, accessibility, xxivKEYS command, 6-19, 7-39KEYS function, 2-39
parameters, 2-40
L
last numberAPPC, 12-3TCP/IP, 12-8
length determination macros, 7-33LOCPOS macro, 7-34log datasets
LRECL, 7-17LRECL
for detail datasets, 7-17log datasets, 7-17script datasets, 7-17
I-5
M
macrosdata replacement offset and length determination,
7-33mailing address, xxvimanager lists
Global Recording, 2-16MAPD
access help panels, 7-41assign a PF key, 7-39detail dataset messages, 7-42general information and error messages, 7-42map entire data file, 7-40map individual message, 7-39script dataset messages, 7-41troubleshoot message mapping, 7-41
masking, TCP/IP, 10-6statements, 10-7
merge repositories, 2-52merge TCP/IP repositories, 6-23message
pipelining, 9-8, 9-15troubleshoot message mapping, 7-41
MESSAGE table, A-9messages
event notification, APPC, 2-29expected and actual, 10-19unattended playback, informational, 4-33
monitor requests, APPC, 2-1, 2-6, 2-10monitor requests, TCP/IP, 6-8
administrator access, 6-10
N
notation conventions, screens and commands, xx
O
offset macros, 7-33options
playback, interactive, 8-5outbound detail dataset, 12-6outbound detail tags, APPC
allocation parameters, 2-38parameters, 2-38
<OUTBOUND> tag, APPC, 4-7output datasets, 7-16output requirements, 7-14overview, Mainframe Servers, 1-1
P
parametersTCP script create, C-1
parameters, APPCgeneral request, 2-25generate Global Recording request skeleton, 2-43Global Recording request syntax, 2-18
retrieve parameters from Global Recording re-quests, 2-42
script creation, 2-44parameters, TCP/IP
generate Global Recording request skeleton, 6-22retrieve parameters from Global Recording re-
quests, 6-21pipelining, 8-10<PIU> tag, APPC, 4-7PLAYBACK
submit a job, 9-27playback
return codes, 9-28Playback Error Summary, 9-30
TCPRUN JCL sample, 9-30PLAYBACK table, A-1playback, APPC, 4-56
control parameters, 4-3control script tags, 4-4create control statements, 4-55datastreams, 4-2edit scripts, 4-4ignore traffic, 4-7review job logs, 4-57REXX variables, 4-36think-time parameters, 4-3timing, 4-3timing parameters, 4-3
Playback, interactive, 8-1basic reports, 8-15change options, 8-5create new, 8-2custom reports, 8-16delete, 8-14environment options, 8-5generate from script log, 8-4generate reports, 8-14script options, 8-11select previously saved, 8-14socket options, 8-8submit for execution, 8-12suppress error messages, 8-9
playback, TCP/IP, 9-1diagnostic parameters, 9-7, 9-21script caching performance, 9-4, 9-19timing parameters, 9-7, 9-13unattended, 9-1unsynchronized, 7-41wait time, 9-21, 9-23
portclient, 7-3, 7-23server, 7-3, 7-23
prefixfor output datasets, 7-16
<PREPARE_TO_RECEIVE> tag, APPC, 4-13PRGLOG DD, 6-23processing
background, 2-14foreground, 2-14, 7-20TCP/IP script options, 7-19
protocol parameterAPPC, 2-24, 2-49TCP/IP, 7-23, 9-15
protocol parameter, TCP/IP, 6-15PTFS, D-1
I-6 Hiperstation for Mainframe Servers User Guide
R
recording filterscreate, 12-7
recording options, 12-3recording, APPC
allocation parameters, 2-30errors, 2-50option parameter tags, 2-28record all sessions, 2-14script tags, 2-29XML parameters, 2-19
recording, TCP/IPadd and manage recording requests, 6-1option parameter tags, 6-17switch repository segments, 6-9
relational operatorsbinary, 10-8character, hex, packed decimal, 10-8DB2, 7-5, 7-7–7-9
<REPLACE> tag, 7-27APPC, 4-7TCP/IP, 7-26, 7-32
offset and length determination macros, 7-33report control library, 10-2, 10-16REPORT statement
TCP/IP, A-1reporting, APPC, 5-1
elapsed time, 5-3inbound performance, 5-2outbound performance, 5-2report generation parameters, 2-51REXX log, 5-3summary report, 5-1
reporting, TCP/IP, 10-1basic reports, 10-17CONTROL statement, 10-3create and manage control assets, 10-2field definitions, B-1HTML Exception Report, 10-6, 10-17input statements, 10-1Playback Error Summary, 9-30prepare reporting job, 10-13REPORT statements for basic reports, 10-6, 10-9REPORT statements for custom reports, 10-9sample jobs, 10-1, 10-13SET statements, 10-15statistic fields, A-1submit job, 10-16
reportsCapture Segment Summary, 2-50Customer Support Diagnostic Report, D-1generate playback reports, 8-14HTML Exception Report, 10-6, 10-17Response Time Report, 10-9Response Time Summary, 10-13, 10-22Script Timing Report, 10-9Script Timing Summary, 10-14, 10-20
repositoriesmerge APPC capture repositories, 2-52merge TCP/IP repositories, 6-23review option, 2-6review processing options, 2-13review sessions list, 2-1segmenting, 6-5storing captured information, 2-4
switch segments, 6-9repository datasets
delete, 2-10, 2-41, 6-8, 6-20segment the repository, 2-5switch segments, 2-41, 6-21view session list, 2-12wildcard characters, 2-5
repository set, 12-3request key
APPC, 2-39TCP/IP, 6-19
Request Parameter List (RPL), 4-35request status, 2-39<REQUEST_TO_SEND> tag, APPC, 4-13Response Time Report, 10-9Response Time Summary, 10-13, 10-22restart
Global Recording request, APPC, 2-11, 2-41Global Recording request, TCP/IP, 6-9, 6-20
return codes, APPCcustom, 4-33unattended playback, 4-32
return codes, TCP/IPplayback, 9-28
reviewcaptured activity, APPC, 2-12, 2-42repository, APPC, 2-12script create criteria, APPC, 2-15
review repositoryprocessing options, APPC, 2-13session list, APPC, 2-14
REXX log, APPC, 5-3REXX variables, APPC, 4-35, 4-39
application data variables, 4-36environment data variables, 4-36error determination, 4-35
REXX variables, TCP/IP, 7-35–7-38
S
sample datatranslate ASCII to EBCDIC, 7-18
sample message report, 10-4samples, APPC
MCSREPT, 2-51SCAPPC, 2-45
samples, TCP/IPreports, 10-2, 10-13SYSPLEX, 6-23
scheduled capture, APPCparameter tags, 2-26
scheduled capture, TCP/IPparameter tags, 6-15
scriptcontent, 12-4
script createoptions, 12-5settings, 12-4
script creation option tags, 2-31script language, REXX variables, 4-35–4-36script log
generate playback, 8-4SCRIPT statement, 9-1SCRIPT statement, APPC, 4-32
parameters, 3-7SCRIPT statement, TCP/IP, 9-15, 9-25
I-7
SCRIPT table, A-5script tags, APPC
CONFIRM, 4-11CONFIRMED, 4-12CONTENT, 4-5control script tags, 4-4DETAIL, 4-5ERROR, 4-6EXTDATA, 4-6FLUSH, 4-12INBOUND, 4-6OUTBOUND, 4-7PIU, 4-7PREPARE_TO_RECEIVE, 4-13REPLACE, 4-7REQUEST_TO_SEND, 4-13script creation options, 2-31SEND_DATA, 4-13SEND_ERROR, 4-14SEND_EXPEDITED_DATA, 4-14TIME, 4-11UNKNOWN, 4-11verb script tags, 4-11
script tags, TCP/IPCLIENT, 7-25CONNECT, 7-22CONTENT for external data, 7-29CONTENT for inline data, 7-28CTG, 7-26DB2, 7-26DETAIL, 7-21DISCONNECT, 7-24ECI, 7-27IMS, 7-27REPLACE, 7-32SERVER, 7-25TIME, 7-22VERSION, 7-21
Script Timing Report, 10-9Script Timing Summary, 10-14, 10-20scripts
generate APPC, 2-14scripts, APPC
create criteria, 2-15criteria tags, 2-50define script criteria, 2-6edit, 4-4errors, 2-50generate from selected sessions, 2-14not found messages, 4-32PIU traffic, 2-9, 12-5play concurrently, 4-54play serially, 4-54prevent automatic creation, 2-5restrict datasets, 3-11script creation parameters, 2-44select processing option, 2-15short CPIC format, 2-9, 12-5SNA service transactions, 2-9, 12-6suppress time stamps, 2-9, 12-5suspend creation, 2-6verb script tags, 4-11
scripts, TCP/IPallocate datasets for logs, scripts, details, 7-17browse, 7-21create, 7-1edit, 7-29manipulate playback, 7-29
message pipelining, 9-25minimize script size, 7-14options, 7-17processing options, 7-19source repositories, 7-13stress test, 7-29
security monitoring, 11-1audit trail, 11-2
<SEND_DATA> tag, APPC, 4-13<SEND_ERROR> tag, APPC, 4-14<SEND_EXPEDITED_DATA> tag, APPC, 4-14server IP address, 7-10<SERVER> tag, TCP/IP, 7-25SET statements in TCP/IP reporting jobs, 10-15side A LU, 12-2side A Netid, 12-2side B LU, 12-2side B Netid, 12-2skeleton
APPC Global Recording request parameters, 2-43TCP/IP Global Recording request parameters, 6-22
SMP/Eglobal CSI dataset, D-1target zone, D-1
socket optionsPlayback, interactive, 8-8
socket timing options, 8-9SOCKETS statement, TCP/IP, 9-1, 9-8, 9-22SOCKETS table, A-3SQL statement, 7-26SQQFSAMP, 2-18, 2-39–2-40, 2-42–2-43start and end date and time, 12-2start date and time
Global Recording (APPC), 2-4Global Recording, TCP/IP, 6-3script creation, TCP/IP, 7-23
statement descriptions, unattended modeACCEPT, 4-22ALLOCATE, 4-22APPCGRP, 4-29CACHEXCL, 4-20CACHINCL, 4-20COMPANY, 4-21CONTROL, 4-18SCRIPT, 4-32
statements, TCP/IPdefine for server testing, 9-3
stopGlobal Recording request, APPC, 2-11, 2-41Global Recording request, TCP/IP, 6-9, 6-20
STOP command, 2-6STOP function, 2-42storage requirements, APPC
unattended playback, 4-1stress test
unattended playback, APPC, 4-41subset repositories, 7-1
allocate datasets, 7-19datasets, 7-19
suffixfor output datasets, 7-16
summary report, APPC, 4-39, 5-1elapsed time, 4-40, 5-3inbound performance, 4-40, 5-2outbound performance, 4-40, 5-2
suppress CONTENT data formatting, TCP/IP, 7-18switch TCP/IP repository segments, 6-9, 6-21syntax
I-8 Hiperstation for Mainframe Servers User Guide
conventions, xxidiagrams, xxi
SYSIN DD statement, 2-18, 2-44SYSPLEX
job input parameters, 2-54SYSPLEX job input parameters, 6-24SYSTSIN DD statement, 2-18, 2-40, 2-44
T
tablesCONNECTION, A-7MESSAGE, A-9PLAYBACK, A-1SCRIPT, A-5SOCKETS, A-3
TCP/IPbasic reports, 8-15custom reports, 8-16
TCP/IP script tagssyntax rules, 7-30
TCP/IP unattended playback, 9-1COLLECT statement, 9-16CONTROL statement, 9-3, 9-18define statements for client testing, 9-18SCRIPT statement, 9-15, 9-25SOCKETS statement, 9-8, 9-22
TCPIPplayback return codes, 9-28
testing, APPCdata-driven example, 4-44extract the key, 4-47play back testing scripts, 4-47replace the key, 4-51share the key, 4-48
think timeAPPC playback parameters, 4-3TCP/IP, 9-7, 9-13unattended mode options, 4-28
time stampsuppress, APPC, 2-32suppress, TCP/IP, 7-18
<TIME> tagAPPC, 4-11TCP/IP, 7-22
TN3270record activity, 2-3recording, 6-2
traceAPPC conversation, 4-29TCP/IP, 9-7, 9-14, 9-21, 9-24
translatefrom ASCII to EBCDIC, 7-18, 7-23from EBCDIC to ASCII, 2-20
troubleshootGlobal Recording batch jobs, 2-50, 6-23playback error summary, 9-30
U
unattended playback, APPCACCEPT statement, 4-22ALLOCATE statement, 4-22APPCGRP statement, 4-29
CACHEXCL statement, 4-20CACHINCL statement, 4-20COMPANY statement, 4-21CONTROL statement, 4-18conversations started at intervals, 4-41conversations started in various ways, 4-43example jobs, 4-40lengthened conversation, 4-42multiple jobs, 4-41procedures for playback, 4-1return codes, 4-32statement sequencing, 4-16statement summary, 4-17stress test, 4-41submit batch job, 4-1two related conversations, 4-42
unattended playback, TCP/IP, 9-1create control statements, 9-1define statements for client testing, 9-18diagnostic parameters, 9-7message pipelining, 9-8, 9-15Playback Error Summary, 9-30repeat playback, 9-12script caching performance, 9-4, 9-19SCRIPT statement, 9-25SOCKETS statement, 9-8, 9-22statement hierarchy, 9-2timing parameters, 9-7, 9-13
unattended processing, APPC, 3-1build statements and JCL, 3-8generate statements, 3-2generation restrictions, 3-11restrict specified script datasets, 3-11SCRIPT statement, 4-32set unattended statement parameters, 3-2start, 3-1storage requirements, 4-1
<UNKNOWN> tag, APPC, 4-11update
Global Recording request, APPC, 2-11Global Recording request, TCP/IP, 6-9, 6-21
UPROCS statement, 2-40, 2-42, 2-44
V
verb script tags, 4-11<VERSION> tag
APPC, 4-5TCP/IP, 7-21
viewGlobal Recording active session, APPC, 2-11Global Recording request, TCP/IP, 6-9
VIEW function, 2-42–2-43, 6-21–6-22VTAM
compressed data streams, 2-17logical unit name, 2-3logon mode name, 2-4network ID, 2-4PIU, 2-32
W
wildcardsfor creating repositories, 7-19
I-9
segment a repository, 2-5, 6-5select source repositories, 7-14
X
XMLKEYS, 2-40parser, 2-19
I-10 Hiperstation for Mainframe Servers User Guide
