ca7 workload automation refgd

Interface Reference Guide r11.1 SP04

Fourth Edition

CA 7® Workload Automation

This documentation and any related computer software help programs (hereinafter referred to as the“Documentation”) are for your informational purposes only and are subject to change or withdrawal byCA at any time.

This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, inwhole or in part, without the prior written consent of CA. This Documentation is confidential andproprietary information of CA and may not be used or disclosed by you except as may be permitted in aseparate confidentiality agreement between you and CA.

Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in theDocumentation, you may print a reasonable number of copies of the documentation for internal use byyou and your employees in connection with that software, provided that all CA copyright notices andlegends are affixed to each reproduced copy.

The right to print copies of the Documentation is limited to the period during which the applicablelicense for such software remains in full force and effect. Should the license terminate for any reason, itis your responsibility to certify in writing to CA that all copies and partial copies of the Documentationhave been returned to CA or destroyed.

TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “ASIS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIEDWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE ORNONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRDPARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THISDOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT,BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISEDOF SUCH LOSS OR DAMAGE.

The use of any software product referenced in the Documentation is governed by the applicable licenseagreement and is not modified in any way by the terms of this notice.

The manufacturer of this Documentation is CA.

Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government issubject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) andDFARS Section 252.227-7014(b)(3), as applicable, or their successors.

All trademarks, trade names, service marks, and logos referenced herein belong to their respectivecompanies.

Copyright © 2007 CA. All rights reserved.

CA Product ReferencesThis document references the following CA products:

■ CA 7® Workload Automation (CA 7)

■ CA 7® Job Management Smart Console Option (CA 7 Job ManagementSmart Console Option)

■ CA 1® Tape Management (CA 1)

■ CA 11™ Workload Automation Restart and Tracking (CA 11)

■ CA APCDDS™ Automated Report Balancing (CA APCDDS)

■ CA APCDOC™ Automated Job Documentation (CA APCDOC)

■ CA AutoSys® Workload Automation (CA AutoSys)

■ CA Dispatch™ (CA Dispatch)

■ CA Easytrieve® Report Generator (CA Easytrieve)

■ CA Endevor® Change Manager (CA Endevor)

■ CA JCLCheck™ Utility (CA JCLCheck)

■ CA Jobtrac™ Job Management (CA Jobtrac)

■ CA Netman™ (CA Netman)

■ CA Librarian® (CA Librarian)

■ CA Opera™ (CA Opera)

■ CA OPS/MVS® Event Management and Automation (CA OPS/MVS)

■ CA Panvalet® (CA Panvalet)

■ CA Roscoe® Interactive Environment (CA Roscoe)

■ CA Scheduler® Job Management (CA Scheduler)

■ CA SYSVIEW® Performance Management (CA SYSVIEW)

■ CA Unicenter® Service Desk (CA Service Desk)

■ CA Unicenter® Network and Systems Management (CA Unicenter NSM)

■ CA Unicenter® Network and Systems Management Job ManagementOption (CA NSM Job Management Option)

■ CA Workload Control Center (CA WCC)

■ Unicenter® Event Console (Unicenter Event Console)

■ Unicenter® Universal Job Management Agent (Unicenter Universal JobManagement Agent)

Contact CAContact Technical Support

3

For your convenience, CA provides one site where you can access theinformation you need for your Home Office, Small Business, and EnterpriseCA products. At http://ca.com/support, you can access the following:

■ Online and telephone contact information for technical assistance andcustomer services

■ Information about user communities and forums

■ Product and documentation downloads

■ CA Support policies and guidelines

■ Other helpful resources appropriate for your product

Provide Feedback

If you have comments or questions about CA product documentation, youcan send a message to [email protected].

If you would like to provide feedback about CA product documentation,complete our short customer survey, which is also available on the CASupport website, found at http://ca.com/docs.

4 Interface Reference Guide

Contents

Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 2. Interfaces and Options . . . . . . . . . . . . . . . . . . . . . . 15Interfaces with Other Products . . . . . . . . . . . . . . . . . . . . . . . . . . 16

CA 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17TIQ Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

CA 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19ARTS Command Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . 20Automatic RMS Step Insertion . . . . . . . . . . . . . . . . . . . . . . . 21Automatic CMT Updating . . . . . . . . . . . . . . . . . . . . . . . . . . 21

CA Workload Control Center (UWCC) . . . . . . . . . . . . . . . . . . . 22CA APCDDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22CA APCDOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Compare FSTRUC to a Database Flowchart . . . . . . . . . . . . . . . 23CA Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Forecast Print Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Create a Plan Data Set . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

CA Earl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26CA Easytrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26CA JCLCheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

CA 7 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27CA Librarian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28CA Netman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

CA 7 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29CA Netman Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 30CA Netman Model Transactions . . . . . . . . . . . . . . . . . . . . . . 30CA Netman Model Transactions - Continuation Rules . . . . . . . . . 31CA Netman Model Transactions - Variables . . . . . . . . . . . . . . . 32

CA Opera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35CA OPS/MVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35CA Panvalet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36UNIX System Services Interface . . . . . . . . . . . . . . . . . . . . . . . 37

Invoke the Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

CA 7/API Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 40TSO/ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

VTAM Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44ISPF Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46CA 7 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Other CA Schedulers and Agents . . . . . . . . . . . . . . . . . . . . . . 51Unicenter Event Console . . . . . . . . . . . . . . . . . . . . . . . . . . . 52CA Service Desk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Configure CAISDI/els for CA 7 . . . . . . . . . . . . . . . . . . . . . . . 52Configure CA Service Desk for CA 7 . . . . . . . . . . . . . . . . . . . 53Configure CA 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Contents 5

CAISDI/els Events Provided by CA 7 . . . . . . . . . . . . . . . . . . . 54SERVDESK Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Event Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Critical Path Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Critical Path Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60CA 7 Requirements for Critical Path Monitoring . . . . . . . . . . . . . 62

CA 7 CA 7 Job Management Smart Console Option . . . . . . . . . . . . . 64Schedule UNIX System Services Jobs . . . . . . . . . . . . . . . . . . . . . 68Interface with IBM Workload Manager (WLM) . . . . . . . . . . . . . . . . . 69

CA 7 and ICOM IBM Workload Manager Resources . . . . . . . . . . . 69Automatic Scheduling Environment JOB Statement Insertion . . . . . . 70

Chapter 3. External Communicators . . . . . . . . . . . . . . . . . . . . . 71Batch Terminal Interface (BTI) . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Command Format and Sequence . . . . . . . . . . . . . . . . . . . . . . 74DBM List Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Non-DBM Batch Commands . . . . . . . . . . . . . . . . . . . . . . . . . 76Installation Process Batch Commands . . . . . . . . . . . . . . . . . . . 76Batch Terminal Interface Execution . . . . . . . . . . . . . . . . . . . . . 77

Processing Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77CA7BTI JCL Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Sample BTI JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78JCL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Trailer Step Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81U7SVC Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Batch Step Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Call U7SVC From a User Program . . . . . . . . . . . . . . . . . . . . . 89Interface with CAICCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Usage Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91CA 7 CAICCI Batch Interface Execution . . . . . . . . . . . . . . . . . . 93

CAL2X2WB JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94CAL2X2WB Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . 96

CA 7 CAICCI REXX Interface Execution . . . . . . . . . . . . . . . . . . 97CA-GSS REXX Address Environment Interface Execution . . . . . . . 99

CA 7 CAICCI Program to Program Interface Execution . . . . . . . . 101Call CAL2X2WP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101CAL2X2WP Response Buffer . . . . . . . . . . . . . . . . . . . . . . 103CAL2X2WP Return Codes . . . . . . . . . . . . . . . . . . . . . . . . 104Sample Invocation of CAL2X2WP . . . . . . . . . . . . . . . . . . . . 105

Batch Card Load Program (BCLP) . . . . . . . . . . . . . . . . . . . . . . . 106Use BCLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

CA 7 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107JCL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Control Statements for BCLP . . . . . . . . . . . . . . . . . . . . . . . 109OPTION Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Data Set Request Statements CREATE, REPLACE, MODDATA . . 115


End-of-Data Set (EODS) Statement . . . . . . . . . . . . . . . . . . . 118Control Statement Examples . . . . . . . . . . . . . . . . . . . . . . . 119

Chapter 4. CA Driver Procedures, Variable Parameters, andFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123JCL Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Procedure Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Create Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Call Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Nest Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Include Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Verify Data Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Code Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 132

Define Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Supply Values On The EXEC Statement . . . . . . . . . . . . . . . . 133Reference Variable Parameters in the Procedure . . . . . . . . . . . 134Use Variable Parameters In Nested Procedures . . . . . . . . . . . . 135Shift During Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Reserved-Name Variable Parameters . . . . . . . . . . . . . . . . . . 137CA Driver Reserved-Name Variable Parameters . . . . . . . . . . . 137

Substrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Null Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Attributes of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

The Type Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Test the Type Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . 144The Length Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Test the Length Attribute . . . . . . . . . . . . . . . . . . . . . . . . . 145The Number Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Test the Number Attribute . . . . . . . . . . . . . . . . . . . . . . . . . 146

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147CA Driver Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Arithmetic Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . 148Date Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . 149Day-Of-Month Functions . . . . . . . . . . . . . . . . . . . . . . . . . 152

Conditional Procedure Expansion . . . . . . . . . . . . . . . . . . . . . . . 153Define Step Names (DSTEP) . . . . . . . . . . . . . . . . . . . . . . . 154

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Branch (DGOTO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Define Conditions (DIF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Set Variable Parameters (DSET) . . . . . . . . . . . . . . . . . . . . . 158Control Loops (DLCTR) . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Abort Expansion (DFLUSH) . . . . . . . . . . . . . . . . . . . . . . . . 160Abort Expansion of the Current Procedure (DABORT) . . . . . . . . . 160

Contents 7

Comments Inside CA Driver Procedures . . . . . . . . . . . . . . . . . . . 161Comments for CPU Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . 161Comments for XPJOB Jobs . . . . . . . . . . . . . . . . . . . . . . . . 161

Use CA Driver in the CA 7 Environment -- Some Examples . . . . . . . . 162Conditional Execution Based on Schedule ID . . . . . . . . . . . . . . 162XPJOB Driver Procedures . . . . . . . . . . . . . . . . . . . . . . . . . 162

Chapter 5. NCF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165CA 7 NCF Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

CAIRIM (Resource Initialization Manager) . . . . . . . . . . . . . . . . 168SVC Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168ICOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Node Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Unknown Node Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169NCF Communications Data Set . . . . . . . . . . . . . . . . . . . . . . 170NCF Undeliverable Queue (UDQ) . . . . . . . . . . . . . . . . . . . . . 170NCF VTAM Application Program . . . . . . . . . . . . . . . . . . . . . 170

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170CA 7 NCF Test Data Generator . . . . . . . . . . . . . . . . . . . . . . 171

Planning and System Requirements . . . . . . . . . . . . . . . . . . . . . . 172General Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Resource Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 174Operating System Environment . . . . . . . . . . . . . . . . . . . . . 174Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 174DASD Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174DASD Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175CAIRIM System Requirements . . . . . . . . . . . . . . . . . . . . . . 176

Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 177Execution Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Sample NCF VTAM PARM . . . . . . . . . . . . . . . . . . . . . . . . 179Sample NCF VTAM JCL . . . . . . . . . . . . . . . . . . . . . . . . . 179

CA 7 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180DB.1 Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

User Execution JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181JOB Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181JES2 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182JES3 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182EXEC Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183DD Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183General Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

NCFNODE Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 184CA 7 LOAD Process . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

System Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186


Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Establish Communications . . . . . . . . . . . . . . . . . . . . . . . . . 186Standard Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Status Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Operator Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188STOP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189SHUTDOWN Command . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190STARTUP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191LOGON Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192LOGOFF Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193PURGE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194STATUS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196TRACE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Deactivate the Trace Facility . . . . . . . . . . . . . . . . . . . . . . . . 199

Chapter 6. Cross-Platform Scheduling . . . . . . . . . . . . . . . . . . 201CAICCI Cross-Platform Connections . . . . . . . . . . . . . . . . . . . . . . 203

Non-MVS CAICCI Connections . . . . . . . . . . . . . . . . . . . . . . 204MVS CAICCI Connections . . . . . . . . . . . . . . . . . . . . . . . . . 206

The XPS CLIENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Direct Submit Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Batch Submit Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Direct Submit Function Parameters . . . . . . . . . . . . . . . . . . . . 209Cross-Platform Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Cross-Platform Tracking Under the CA 7 Started Task . . . . . . . . 213Set up the High Availability Option (HAO) of CA 7 XTRK . . . . . . 214CA 7 Cross-Platform Tracking Commands . . . . . . . . . . . . . . . 215CA 7 Cross-Platform External Tracking . . . . . . . . . . . . . . . . . 218Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

The XPS SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223The XPS Submit Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Status Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

The Cross-Platform Scheduling Router (XPS Router) . . . . . . . . . 226Cross-Platform Server Password Requirements . . . . . . . . . . . . . 229

Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Manage the Cross-Platform Workload . . . . . . . . . . . . . . . . . . 232

Contents 9

CA 7 XPS Server Implementation Checklist . . . . . . . . . . . . . . . 234

Chapter 7. Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Email Address Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Email Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Email Test Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Data Set for TCP/IP Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Chapter 8. Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . 249The Substitution Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

CA 7 JOB Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 250CA Driver Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Standard Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Substitution Rules and Restrictions . . . . . . . . . . . . . . . . . . . . . . 251General Reserved Variable Names . . . . . . . . . . . . . . . . . . . . . . 253Job-Specific Reserved Variable Names . . . . . . . . . . . . . . . . . . . . 254Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Chapter 9. Jobflow Illustrator . . . . . . . . . . . . . . . . . . . . . . . . 257Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258Simulation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Ad Hoc Adds and Deletes . . . . . . . . . . . . . . . . . . . . . . . . 259Checkpoint Save and Start . . . . . . . . . . . . . . . . . . . . . . . . 259Flowchart Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

The Workflow Building Process . . . . . . . . . . . . . . . . . . . . . . . . . 260Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

CA 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Sample User JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Input DD Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Output DD Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Dynamically Allocated DD Statements . . . . . . . . . . . . . . . . . . 263

Initialization Parameters (INITDEF DD Statement) . . . . . . . . . . . . . . 264TYPE Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264CA7 Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265LOGON Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266CA7PASS Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267SIZE Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268NODE Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269RECEIVER Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 270CKPTDDN Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Building Parameters (PARMDEF DD Statement) . . . . . . . . . . . . . . 272Global Building Parameters . . . . . . . . . . . . . . . . . . . . . . . . 273

MAXJOBS Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 273FROM Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274TO Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276SPAN Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277


EXTRACT Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 278QTIME Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Search Building Parameters . . . . . . . . . . . . . . . . . . . . . . . . 279JOB Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279SCHID Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280SYS Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Filter Building Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 282JOBFILTER Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 282SCHFILTER Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 283SYSFILTER Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Commands (SYSIN DD Statement) . . . . . . . . . . . . . . . . . . . . . . 285Ad Hoc Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285System Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Output Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Command Coding Rules . . . . . . . . . . . . . . . . . . . . . . . . . . 286ADDJOB Command—Add a Job . . . . . . . . . . . . . . . . . . . . . 286ADDDS Command—Add a Data Set . . . . . . . . . . . . . . . . . . . 289DELJOB Command—Delete a Job . . . . . . . . . . . . . . . . . . . . 291SAVE Command—Write to the Checkpoint Data Set . . . . . . . . . . 294FLOWCHART Command—Generate a Jobflow Illustrator . . . . . . . 295

JCL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Example 1: Cold Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Example 2: Checkpoint Start and CSV Flowchart . . . . . . . . . . . . 304Example 3: Null Table Cold Start, Multiple Checkpoints . . . . . . . . 305Example 4: Delete Job and Print Flowchart to DASD . . . . . . . . . 306

CSV Flowchart File Description . . . . . . . . . . . . . . . . . . . . . . . . . 307Fields (Columns) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

FLOWCHART TYPE=PRINT Description . . . . . . . . . . . . . . . . . . . 314Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Sample FLOWCHART TYPE=CSV File (Partial) . . . . . . . . . . . . . . . 319

Appendix A. CA7TOUNI Conversion Utility . . . . . . . . . . . . . . . . 321PHASE I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Input JCL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Examples of SASSX2UN SYSIN Statements . . . . . . . . . . . . . . 327

Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Output JCL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 328SASSX2UN Return Codes . . . . . . . . . . . . . . . . . . . . . . . . 331CA7TOUNI Keyword Processing During Phase I of Conversion . . . 331

PHASE II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Execute the CONVERT Command Online . . . . . . . . . . . . . . . . 332Restore a Converted Member . . . . . . . . . . . . . . . . . . . . . . . 333

Clean-Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Contents 11

Conversion Utility Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 335Informational Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Pre-Conversion Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341How it Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Input JCL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Output JCL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 344SASSX2PD Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . 347Pre-Conversion Utility Messages . . . . . . . . . . . . . . . . . . . . . 348

Informational Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 348Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Appendix B. Batch Program CA7TOUNI . . . . . . . . . . . . . . . . . . 351CA7TOUNI Submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352CA7TOUNI Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Appendix C. XTRK as a STC or Job . . . . . . . . . . . . . . . . . . . . 361CA 7 Cross-Platform Tracking JCL . . . . . . . . . . . . . . . . . . . . . . 362CA 7 XPS Client Implementation Checklist . . . . . . . . . . . . . . . . . . 365

Appendix D. XTRK Under ICOM . . . . . . . . . . . . . . . . . . . . . . . 367Cross-Platform Tracking ICOM PARM Values . . . . . . . . . . . . . . . . 368Cross-Platform Tracking ICOM DD Statements . . . . . . . . . . . . . . . 369Cross-Platform Tracking ICOM WTOR/MODIFY Replies . . . . . . . . . . 370

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371


Chapter 1. Introduction

This guide contains information about several of the interfaces to CA 7®

Workload Automation (CA 7). Included are interfaces with other products,external communicators, CA Driver, the Network Communications Facility (NCF)component of CA 7, cross-platform scheduling, and UNIX System Servicesscheduling. It is designed for use by both the operator and data centerpersonnel concerned with software support (technical services).

Chapter 1. Introduction 13

Chapter 2. Interfaces and Options

This section contains the following topics:

Interfaces with Other Products . . . . . . . . . . . . . . . . . . . . . . . . . . 16CA 7 CA 7 Job Management Smart Console Option . . . . . . . . . . . . . 64Schedule UNIX System Services Jobs . . . . . . . . . . . . . . . . . . . . . 68Interface with IBM Workload Manager (WLM) . . . . . . . . . . . . . . . . . 69

Chapter 2. Interfaces and Options 15

Interfaces with Other Products


CA 7 was developed to interface with both CA and other software products.Combined with other products, CA 7 forms the base for a highly automated,efficient data center.

CA 7 provides interface support for the following products:

CA 1

CA 11

CA APCDDS

CA APCDOC

CA Dispatch

CA Earl

CA Easytrieve

CA JCLCheck

CA Librarian

CA Netman

CA Opera

CA OPS/MVS

CA Panvalet

CA WCC

UNIX System Services

TSO/ISPF

CA AutoSys

CA NSM Job Management Option

Unicenter Agents

Note: The Security Reference Guide contains descriptions of all securityproduct interfaces.



CA 1

CA 7 supports the CA 1 TIQ interface with TIQ and TIQU top line commands.TIQ allows access but no update while TIQU allows access and update to theCA 1 TMC. After a TIQ or TIQU command is entered, the terminal is placed inTIQ monitor mode. Input is exactly as documented in the CA 1 manuals.

The default for DSN verification is YES. Enter TIQU,DSN=NO to change this.

To exit from TIQ mode, enter C. The MONLIM value from the TERM statementin the initialization file can be used to cause an automatic cancel from TIQmode after a specified number of minutes of inactivity.

The CA 7 OPID used to log on to CA 7 is sent to CA 1 as the password. If it isnot defined to the CA 1 Security module, a message appears and a differentCA 1 password must be entered.

Messages produced by the CA 7 TIQ interface are in the Message ReferenceGuide. Those produced by CA 1 are documented in CA 1 manuals.

The CA 1 TMS load library must be concatenated to the CA 7 STEPLIB or belinklisted to use this feature.

When the TIQ interface is used, the CWORK value for CA 7 should beincreased by 10 for each concurrent TIQ session through CA 7 (see thechapter "Execution" in the Systems Programmer Guide).

Note: The CA 1 TIQ interface in CA 7 dynamically loads the appropriate TIQinterface module based upon the current release of CA 1 found on your systemduring execution. Therefore no special application statements are required.



TIQ Command

This command has the following format:

��─ ──┬ ┬─TIQ── ──┬ ┬──────────────── ─────────────────────────────────────�� └ ┘─TIQU─ │ │┌ ┐─YES─

└ ┘──,DSN= ──┴ ┴─NO──

UIndicates updating is to occur.

DSNIndicates whether the data set name is to be verified before CA 1 will allowupdating of the TMC record. YES is the default. This parameter is only validwith TIQU.



CA 11

CA 7 interfaces with CA 11 by supporting the ARTS command monitor, byallowing automatic RMS step insertion, and by providing automatic CMTupdating when jobs are restarted, forced to complete, or canceled.

The CA 11 interface is included automatically during the install of the CA 7base product (FMID CL2B100).

Note: A separate FMID is no longer required for the CA 11 interface. Sites nolonger need to assemble the CA 11 interface at APPLY time.

The CA 11 interface is delivered already assembled. Should a future release ofCA 11 require a re-assembly of the interface, you can use SAMPJCL memberUL2B143.

Add the following statements to the initialization file before the APPLCTNstatement for SASSPROG:

APPLCTN,NAME=SASSRMS1,ATTR=PERMAPPLCTN,NAME=SASSRMS2,ATTR=PERM

The CA 11 load library must be concatenated to the CA 7 STEPLIB or linklistedsince CA 11 modules perform part of the interface.

The following initialization file statement is required to turn on the CA 11interface:

RESTART,RMS=YES



ARTS Command Monitor

CA 7 supports the CA 11 ARTS interface with the ARTS top line command.This allows use of online tracking and maintenance of restart/rerun informationas described in CA 11 documentation. The ARTS interface is very similar to theTIQ interface. The monitor mode is entered and can be limited by the MONLIMvalue from the TERM statement in the initialization file.

The CA 7 OPID is passed to CA 11 as a password. If it is not defined to theCA 11 Security module, a message appears and a different CA 11 passwordcan be entered.

Messages produced by the CA 7 ARTS interface can be found in the MessageReference Guide. Those produced by CA 11 are documented in CA 11documentation.

The format of the ARTS command is as follows:

ARTS

No parameters are entered with this command.

When the ARTS command monitor is used, the CWORK execution parameterfor CA 7 should be increased by a count of 20 for each concurrent ARTSsession through CA 7. If CA 7 is being run in a large enough region, CWORKmay not need adjusting. Normally, five or less interfaces are concurrent even inlarge terminal networks. However, since CWORK reduces the external storageavailable to other CA 7 interfaces, it may be better to increase region size (seethe chapter "Execution" in the Systems Programmer Guide).

When issuing CA 11 commands that have multiple panels of output, it isnecessary to retype the first letter of the command (or a blank) before pressingEnter to view secondary panels.



Automatic RMS Step Insertion

For jobs submitted by CA 7, a job-level option can cause a CA 11 RMSprocedure to be inserted in the job's JCL. The default procedure name inserteddepends on the release level of CA 7. You can change the procedure name byusing the PROCRMS parameter of the RESTART statement in the initializationfile. (You can find a sample RMS PROC in the CA 11 SAMPJCL data set asmember CA11RMS.)

When CA 7 inserts the RMS procedure, the parameter passed is determinedas follows:

■ If restart data is present in the JCL as part of the //*UCC7RESTARTstatement, the restart data is passed as the parameter.

■ If you have no restart data for //*UCC7RESTART, the parameter is set to Punless Load processing is needed.

■ If you have no restart data and Load processing is needed, the parameter isset to F.

This parameter can be overridden by using the PARMRMS parameter of theRESTART statement in the initialization file.

To request automatic RMS step insertion for a job, set the INSERT-RMS fieldon the DB.1 panel to Y. (For more information, see the chapter "Jobs" in theDatabase Maintenance Guide.) If CA 11 is not installed, the insert feature isnot active regardless of the INSERT-RMS field on the DB.1 panel.

Note: If IBM OS Restart (JOB statement RESTART parameter) is used, then itis possible that the RMS step inserted by CA 7 will be bypassed. This couldresult in various problems depending on the steps that are not executed:possible abends, loss of data, loss of data set postings, and so on.

Automatic CMT Updating

When CA 11 is available and jobs are restarted, forced completed, or canceledthrough CA 7, the CMT is updated automatically. If CA 7 NCF is installed,then, for jobs executed at nonlocal NCF nodes, CMT updating cannot occurand the restart data is passed by the //*UCC7RESTART statement.

When a job is resubmitted, force completed, or canceled, the interface attemptsto clear the CMT flags. When a job is restarted, the interface posts the restartdata to the CMT then sets the restart data to P. If the QM.4 panel SET PARMfield is used, the CMT is not accessed and the PARM data is passed using the//*UCC7RESTART statement.

The CA 7 commands that cause CMT updating are CANCEL, RESTART, XQfunction C or F, and XRST.



CA Workload Control Center (UWCC)

The CA WCC (UWCC) is a portal-based application that allows you to monitorand manage CA 7 from a web browser. It was formerly known as the UnicenterEJM. UWCC provides user-friendly portlets to define and maintain CA 7definitions for jobs, schedules and other objects. It also allows graphicaldrag-and-drop scheduling along with graphical monitoring of the active CA 7workload. UWCC also allows you to manage and monitor your enterprise jobmanagement environment with multiple copies of CA 7 and CA AutoSys from asingle workspace.

To enable the CA 7 interface for CA WCC, see “CA 7/API Requirements” onpage 40.

CA APCDDS

CA APCDDS automates the manual, often neglected task of data verification,thereby increasing the accuracy and consistency of your output while reducingreruns and improving auditability.

CA APCDDS is a rule-based menu-driven system that provides comprehensivedata verification routines to catch errors in a timely fashion -- before mistakesare propagated throughout the system. CA APCDDS adds to the flexibility ofCA 7 by allowing an out-of-balance condition to directly affect the productionworkflow. CA APCDDS has the ability to directly issue a CA 7 command inresponse to an out-of-balance condition. No longer is it necessary to manuallybalance a report and then manually demand jobs for execution. Implementationof CA APCDDS requires no changes to your existing application programs.

CA APCDOC

If you have CA APCDOC (CA production documentation product) installed onyour system, you can use its flowcharting facility to show schedule and jobflowcharts from the CA 7 database. These flowcharts can be based on thecurrent workload or forecasted for a future date. Users with CA 7 can use theDOCCHART component to print flowcharts of jobs showing the job schedules,successor relationships, and other job-related information.



Compare FSTRUC to a Database Flowchart

CA 7 users have the option of producing a flowchart directly from the databaseor by reading an FSTRUC report. If the user chooses the FSTRUC option, theCA 7 FSTRUC command should be issued first, placing the output into asequential file, which DOCCHART then reads. The differences betweencreating a CA 7 flowchart from FSTRUC output and creating one from thedatabase include:

■ The database flowchart shows job and data set requirements, whichFSTRUC does not.

■ The database flowchart shows a starting point and continues on until itreaches the end, whereas FSTRUC just shows one job at a time.

■ The database flowchart is not time sensitive. It shows the relationshipbetween jobs regardless of the time it is run. It gives an undistorted view oftriggers and requirements, and database relationships.

■ The database flowchart runs independently of CA 7 and does not requireCA 7 address space or BTI. CA 7 does not even need to be active(although it usually is). The forecast commands such as FSTRUC use manyresources that the database flowchart does not.

■ Since the database flowchart issues its own reads to the database, it canrun against any copy of the database (current, old, or restored). A user cancompare the database today to the database as it was six months ago.



CA Dispatch

This interface consists of two parts where data is communicated either fromCA 7 to CA Dispatch or from CA Dispatch to CA 7.

■ The CA 7 to CA Dispatch part of the interface is discussed in “ForecastPrint Volumes” on page 24.

■ The CA Dispatch to CA 7 part of the interface is discussed in the CADispatch Reference Guide.

Forecast Print Volumes

When CA Dispatch is used for managing printed output, the forecasting of printvolumes by CA Dispatch may be desirable for planning activities associatedwith handling the actual printed output.

CA 7 provides an interface to CA Dispatch to support this function.

For more information about the forecast of print activity, see the CA Dispatchuser documentation.

Create a Plan Data Set

The interface is a three-step process requiring the following:

1. Issue a CA 7 top line FWLP command, or an equivalent batch commandthrough a batch terminal interface, to forecast the jobs for which printvolumes are wanted.

This places data in a data set reserved for FWLP purposes. Thiscard-image data identifies the jobs and when they are scheduled to run.

That data set must have been previously defined in the CA 7 JCL. Forfurther discussion of this command and its function, see the discussion ofthe FWLP command and the DDNAME keyword parameter in theCommand Reference Guide.

2. Run a batch job using module SASSDPCH to reformat the data from Step 1into plan records in the format required by CA Dispatch.

3. Using the output file from SASSDPCH, produce the forecast of printvolumes as described in the CA Dispatch user documentation.



Alternatively, the data set created in Step 1 could be modified or createdmanually by the user prior to Step 2. The following is a sample of the JCLneeded to produce a plan file for CA Dispatch.

Plan File JCL Sample

//jobname JOB user-defined-parameters.........................................// // // // CREATE FWLP DATA SET WITH DESIRED FORECAST INFORMATION // // // //STEP1 EXEC PGM=SASSBSTR,REGION=2�K,PARM=parm//STEPLIB DD DISP=SHR,DSN=cai.ca7.loadlib//UCC7CMDS DD DISP=SHR,DSN=ca7.communications.data.set//BATCHIN DD DISP=SHR,DSN=batch.input.data.set//BATCHOUT DD DISP=SHR,DSN=batch.output.data.set//SYSPRINT DD SYSOUT=A,DCB=BLKSIZE=133//SYSUDUMP DD SYSOUT=A//SYSIN DD /LOGON operatoridFWLP,....desired parameters go here...../LOGOFF// // // // // REFORMAT FWLP DATA INTO CA-DISPATCH 'PLAN' RECORDS // // // //STEP3 EXEC PGM=SASSDPCH//STEPLIB DD DISP=SHR,DSN=cai.ca7.loadlib//SYSUDUMP DD SYSOUT= //FWLPDATA DD DISP=SHR,DSN=dataset-containing-FWLP-data//DISPATCH DD DSN=input-plan-data-set-for-DISPATCH,// DISP=(NEW,CATLG),UNIT=SYSDA,SPACE=(TRK,(n,n)),// DCB=(RECFM=FB,LRECL=5�,BLKSIZE=nnnn)//



CA Earl

The interface between CA Earl and CA 7 requires the CAIMAC target librarygenerated during installation and a copy of CA Earl. If a full copy of CA Earl isinstalled, it can be used. If a full copy of CA Earl is not available, you can installthe service from the CA Common Services distribution tape. For moreinformation about installing the CA Earl subset product, see the InstallationGuide. For JCL and usage considerations, see the Report Reference Guide.

The CAIMAC EARL report member, prefix CA7ER, contains record and reportdefinitions used for the reports described in the Report Reference Guide.

CA Easytrieve

CA 7 provides a complete set of report definitions for use with CA Easytrieve, ifthat product is in use at your site. A standard set of reports can be producedusing either the CA 7 log history file or output from the CA 7 database backuputility as input to CA Easytrieve. For information about producing reports fromCA Easytrieve, see the chapter "CA Earl and CA Easytrieve Reporting" in theReport Reference Guide. The CA Easytrieve report definitions, prefix CA7EZ,are saved in the CAIMAC data set.

CA JCLCheck

The CA 7 interface for CA JCLCheck supports enhanced validation of JCL inthe CA 7 editor and on the LJCK command. It also supports batch validation ofJCL for a stream of forecasted jobs.

In the online environment, the interface greatly extends the CA 7 validationfacilities. For example, the interface displays procedure expansions, so thaterror messages are reported in a meaningful context. Also, the interfacesupports checking for the existence of data sets that may prove useful in testingproduction job streams.

The interface also includes a batch utility that uses the FJOB command toforecast a series of jobs and then the LJCK command to extract JCL for themso that CA JCLCheck can validate the JCL for the stream as a whole. Thisutility is requested from an ISPF panel that is provided with CA JCLCheck. Formore information, see the CA JCLCheck documentation.



CA 7 Considerations

The interface is requested through the JCLCHECK statement in the CA 7initialization file. An OS LOAD macro is used during CA 7 initialization to locatethe JCLCHECK load module. The address returned by the LOAD macro is usedfor all subsequent accesses of CA JCLCheck by CA 7. If the JCLCHECKmodule is not resident or in a linklist library, concatenate the library containingthe JCLCHECK load module to the CA 7 STEPLIB.

The storage requirement for CA 7 may increase significantly if the CA 7 CAJCLCheck interface is used. A CWORK increment of 250 is proposed as astarting value. However, this should be considered a tentative recommendationas the storage required may vary according to several factors such as thenumber of concurrent interface users and the number of input statements to beparsed. For more information about CA JCLCheck storage requirements, seethe CA JCLCheck documentation.

The execution JCL for CA 7 must be modified to include a DD statement thatpoints to the libraries on which cataloged procedures reside. The name of theDD statement must be SYSPROC. If this DD statement is not found, the CAJCLCheck option AUTOPROC can be specified. For more information aboutthe AUTOPROC option, see the CA JCLCheck documentation.

If the JCLCHECK statement in the CA 7 initialization file uses the DDNAMEparameter, an additional DD statement is required using the name from theDDNAME parameter. The DD references a card-image file specifying additionaloptions for CA JCLCheck. For a list of valid options, see the discussion of theJCLCHECK statement in the Systems Programmer Guide. For moreinformation about these options, see the CA JCLCheck documentation.



CA Librarian

Add the following DD statement to the CA 7 online JCL for each CA Librariandata set.

//JCLnnn DD DISP=SHR,DSN=name-of-librarian-data-set

Add the following JCL statement to the CA 7 initialization file for each CALibrarian data set.

JCL,DSN=name-of-librarian-data-set,INDEX=nnn,DSORG=LIB [,MCD=xxxx]

The nnn value of the INDEX parameter of the JCL statement must be the samevalue as nnn on the DD statement (leading zeros are required on the DDstatement). Access is read-only using JCL panels, list commands or jobscheduling functions such as DEMAND, RUN, and so forth.

Normal access expands "include" references, but a list option is available tosuppress expansion when doing an LLIB command.

You must add an APPLCTN statement to the initialization file. The format is:

APPLCTN,NAME=SASSLIBR,ATTR=PERM

CA Netman

CA Netman transactions are issued dynamically in response to CA 7 jobcompletions using the realtime CA Netman interface. When CA 7 detects a jobcompletion, one or more CA Netman API transactions are issued based oninformation about the job from the CA 7 status queues.

In the standard implementation, the realtime interface can be used to OPEN orUPDATE problems in CA Netman for CA 7 jobs that end abnormally andCLOSE CA Netman problems for those restarted CA 7 jobs when theycomplete normally.

A batch interface between CA 7 and CA Netman is also available that uses theMachine Generated Problem Tracking feature of CA Netman and the CA 7batch terminal interface. For information about the use of the batch interface,see the CA Netman publications.



CA 7 Considerations

The realtime interface will be initialized if the NETMAN statement is present inthe CA 7 initialization file. This statement is used to set CA Netman API controlvalues and parameters regulating the activity of the CA 7 subtask that invokesthe CA Netman API.

The interface also requires a NETMAN DD statement in the JCL used to startCA 7. This statement identifies a file containing CA Netman API transactionschema that are used to build the CA Netman API transactions that are issuedwhen a CA 7 job completes. For more information, see “CA Netman ModelTransactions” on page 30.

The realtime CA Netman interface uses CA Netman API deferred processing sothat API transactions created by the interface will be retained in the event thatthe CA Netman CAICCI receiver is inactive. This requires the presence of a CANetman API deferred request data set. Any CA Netman API request issued bythe interface will be written to this file for subsequent processing with theNTM920 utility. The data set must be defined as RECFM=FB and LRECL=80and must be identified in the CA 7 procedure with the ddname NTMADFR. Formore information, see the CA Netman documentation.

The CA Netman module, NTMAPI, is loaded by CA 7 at interface initialization.Ensure that NTMAPI resides on a library that can be accessed by CA 7.

CA Netman API transactions are issued under a CA 7 subtask, SASSPM00.When this task is ready to accept CA 7 job completions, a message is issuedindicating successful initialization of the CA Netman interface.

The storage requirement for CA 7 may increase significantly if the CA Netmaninterface is used. An increase in region size of 1MB is recommended as astarting value. A larger increase may be required depending on the volume ofCA Netman transactions to be issued.



CA Netman Considerations

If the realtime CA Netman interface is indicated, a task in the CA 7 addressspace will be created to asynchronously accept CA 7 job completion data, buildCA Netman transactions based on the schema in the model CA Netmantransaction file and issue API requests to send those transactions to CANetman.

The CA Netman API requires the presence of an active CA Netman CAICCIlistener. A listener can be requested either through a CA Netman transaction orthrough the use of the CA Netman Asynchronous Services Task (NTMASYN).For more information about implementing the CA Netman API, see the CANetman documentation.

Also see the CA Netman documentation for a discussion of security using theAPI. This interface requires CA Netman r4.9 or higher.

CA Netman Model Transactions

Model CA Netman transactions are coded in a sequential file identified in theCA 7 execution JCL by a NETMAN DD statement. Each time the CA Netmaninterface is invoked, CA Netman commands built from the model transactionswill be issued. For example, if the following model CA Netman transaction iscoded:

MGPT FUN=UPDATE SOURCE=XXX CAT=YYY SD='JOB 1'

Each time the CA Netman interface is invoked, an attempt is made to issue anMGPT transaction conforming to the above format.

The model transaction file must be defined as as DSORG=PS, LRECL=80 andRECFM=F or FB.

CA Netman transactions are issued in the order that they appear in the modeltransaction file for each invocation of the interface.

The next example illustrates the use of variables in model CA Netmantransactions:

SIGNON MJMMGPT FUN=&&MFUN SOU=CA7 CAT=U +DESC='&&L2PME_L2JOBN ENDED WITH &&L2PME_L2CC' +IDAT=�&&L2DATE ITIM=��&&L2PME_L2JOB# +OCCRD=&&L2OCDT OCCRT=&L2OCTISIGNOFF



Variables can be used in the model transactions to refer to useful data such asjob name, JES number, date, time, and so forth. With model transactions codedas in the above example the following CA Netman API transaction could begenerated when job ABC123 completes:

SIGNON MJMMGPT FUN=UPDATE SOU=CA7 CAT=U +DESC='ABC123 ENDED WITH S-�C4' +IDAT=��7161 ITIM=��2127 +OCCRD=�6�9�7 OCCRT=223�SIGNOFF

Values for most variables are determined based on CA 7 job completioninformation. In this example suppose that job ABC123 abended with a S-0C4on 07.161 at 10:30 at night. Note the use of the incident time keyword (ITIM).The CA 7 job number is inserted instead of a true incident time. In this way, theproblem can be referenced by incident date and CA 7 job number.

For a list of variable names and their values, see “CA Netman ModelTransactions - Variables” on page 32.

CA Netman Model Transactions - Continuation Rules

Model transactions can be continued. A continuation is indicated by theoccurrence of + as the last non-blank character on the line. The continuationresumes at column 1 of the next line. The length of a CA Netman transactionbuilt by this interface cannot exceed 1000 bytes. The number of continuationsfor CA Netman model transactions is limited by this restriction.



CA Netman Model Transactions - Variables

You can code the following variables in CA Netman model transactions:

Variable Name Length Value

&&L2NTM_DBASENM 16 The value of the DBASENM keyword on the CA NetmanSystem Information (SYST) panel

&&L2PME_L2JOBN 08 Name of the job scheduled by CA 7

&&L2PME_L2JES 05 JES number of the job scheduled by CA 7

&&L2PME_SYSID 04 Execution SMF ID of the job scheduled by CA 7

&&L2PME_L2JOB 05 CA 7 assigned job number

&&L2PME_L2SID 03 CA 7 schedule ID associated with the job

&&L2PME_L2SYSN 08 System name from the CA 7 job definition

&&L2PME_L2RSN 08 Restart step name

&&L2PME_L2CC 06 Completion code:

C-nnnn - normal completionCFnnnn - job forced completeJCLERR - JCL errorR-nnnn - condition code test failedS-nnnn - system abendU-nnnn - user abend

&&L2PME_L2RC 04 Restart count

&&L2PME_L2CPUT 08 CPU time

&&L2PME_L2JCLI 03 CA 7 JCL ID for the job

&&L2PME_L2DOYR 04 CA 7 due-out year

&&L2PME_L2DODY 03 CA 7 due-out day

&&L2PME_L2DOT 04 CA 7 due-out time

&&L2PME_L2DLYR 04 CA 7 deadline year

&&L2PME_L2DLDY 03 CA 7 deadline day

&&L2PME_L2DLT 04 CA 7 deadline time

&&L2PME_L2SMYR 04 CA 7 submit year

&&L2PME_L2SMDY 03 CA 7 submit day

&&L2PME_L2SMT 04 CA 7 submit time

&&L2PME_L2STYR 04 CA 7 start year

&&L2PME_L2STDY 03 CA 7 start day

&&L2PME_L2STT 04 CA 7 start time




&&L2PME_L2ETYR 04 CA 7 end year

&&L2PME_L2ETDY 03 CA 7 end day

&&L2PME_L2ETT 04 CA 7 end time

&&L2PME_L2EM 04 The entry mode of the job:

ADEM Job entered by DEMAND command in ARFrecovery

ADST Data set triggered in ARF recoveryAEXT Externally tracked job in ARF recoveryAJBT Job triggered in ARF recoveryANWT Network triggered in ARF recoveryAPS Job entered by Personal Scheduling in ARF

recoveryARFJ ARF recovery jobARUN Job entered by RUN command in ARF recoveryASSC Job entered by Schedule Scan in ARF recoveryDEMD Job entered by DEMAND commandDSTR Data set triggeredEXTL Externally tracked jobJBTR Job triggeredNWTR Network triggeredPSCH Job entered by Personal SchedulingRPET Repeat jobRUN Job entered by RUN commandSSCN Job entered by Schedule ScanXDEM Cross-platform scheduled using

XPSSCHD=DEMANDXPS Cross-platform scheduled using

XPSSCHD=RUNREFXRUN Cross-platform scheduled using XPSSCHD=RUN

&&L2PME_L2OVR 01 OVERRIDE=Y or N from CA 7 job definition

&&L2PME_L2MNT 01 MAINT=Y or N from CA 7 job definition

&&L2PME_L2EX 01 EXEC=Y or N from CA 7 job definition

&&L2DATE 05 CA 7 due-out date: format is YYDDD

&&L2OCDT 06 Occurrence date: format is MMYYDD

&&L2OCTI 04 Occurrence time: format is HHMM

&&DATE 06 System date: format is CYYDDD




&&TIME 06 System time: format is HHMMSS

&&MFUN 06 Expected value for MGPT FUNCTION keyword. If job endsabnormally, &&MFUN=UPDATE. If job ends normally but wasrestarted, &&MFUN=CLOSE.



CA Opera

CA Opera provides an interface to CA 7 using the U7SVC facility. Thisinterface allows CA 7 commands to be issued based on events recognized byCA Opera. Any commands issued using the CA Opera interface requireoperator security defined for the trailer terminal. For details on this interface,see the CA Opera documentation.

For CA Opera to monitor CA 7 browse data set messages, you need to addthe CA 7 browse event to your CAIENF database. To add this event, seemember L2DCM1 in the CA 7 sample JCL library.

CA OPS/MVS

CA OPS/MVS provides an interface to CA 7 using the U7SVC facility. Thisinterface allows CA 7 commands to be issued based on events recognized byCA OPS/MVS. Any commands issued using the CA OPS/MVS interface requireoperator security defined for the trailer terminal. For details on this interface,see the CA OPS/MVS documentation.

CA 7 commands can also be issued using the CA 7 CAICCI interface. Thisfacility returns the output from the CA 7 commands to the caller for evaluation.For information about using this facility in CA OPS/MVS, see “CA-GSS REXXAddress Environment Interface Execution” on page 99.

For CA OPS/MVS to monitor CA 7 browse data set messages, you need toadd the CA 7 browse event to your CAIENF database. To add this event, seemember L2DCM1 in the CA 7 sample JCL library.

CA OPS/MVS can also monitor CA 7 Critical Path Monitoring events. CAOPS/MVS can then interface with other CA solutions to track and display criticalpaths. For information about implementing Critical Path Monitoring in CA 7, see“Critical Path Monitoring” on page 60. For information about using CAOPS/MVS to monitor critical paths, see the CA OPS/MVS documentation.



CA Panvalet

The following DD statement must be added to the CA 7 online JCL for eachCA Panvalet data set.

//JCLnnn DD DISP=SHR,DSN=name-of-panvalet-data-set

The following JCL statement must also be added to the CA 7 initialization filefor each CA Panvalet data set.

JCL,DSN=name-of-panvalet-data-set,INDEX=nnn,DSORG=PAN

The nnn value of the INDEX parameter of the JCL statement must be the samevalue as nnn on the DD statement (leading zeros are required on the DDstatement). Access is read-only using JCL panels, list commands or jobscheduling functions such as DEMAND, RUN, and so forth.

Normal access expands "include" references, but a list option is available tosuppress the expansion when doing an LLIB command.

If a new version of CA Panvalet is installed, CA 7 needs to be recycled (aWARM start is sufficient).



UNIX System Services Interface

The UNIX System Services interface provides a method of communication forrequests to CA 7 from the UNIX System Services environment. The interfacecan be called directly from the UNIX shell or from the MVS batch interface UnixSystems Services MVS BPXBATCH. This includes user applications, shellscripts, and the command prompt. The request can be any valid CA 7command that is normally passed to U7SVC and must be syntactically correct.

For information about the installation and setup of the CA 7 USS Interfacemodules, see UNIX System Services Interface in the Systems ProgrammerGuide.

For a detailed discussion on using the UNIX Services with the shellenvironment, see the IBM documentation for the UNIX System Services User'sGuide and the UNIX System Services Command Reference. For invoking theCA 7 interface, see the following examples.

Invoke the Interface

From the UNIX shell environment command prompt, you can invoke theinterface as follows:

ca7oecom demandh,job=payjob1

The preceding example invokes the CA 7 UNIX Services interface executableCA7OECOM and passes the command on to CA 7 through U7SVC. In thiscase, a DEMANDH command for job PAYJOB1 is requested. A return code issupplied to indicate the status of the request to U7SVC.

The UNIX shell can be entered by issuing the TSO/E OMVS command fromwithin TSO.

If the command you want to submit to CA 7 contains special characters,blanks, or quotes, embed the entire command in single quotes. This preventsthe shell from evaluating the special characters as part of the command. Forexample:

ca7oecom 'addrq,job=payjob1,usr=this is a user requirement'



Environment Variables

CA7DIR: This environment variable specifies the fully qualified path name forthe location of the interface executable CA7OECOM. This variable is requiredto be set prior to execution of the interface.

Example Path

/users/applications/ca7/bin

CA7TRACE: This environment variable is used for diagnostic purposes. Whenset to a value of "ON", the interface module CA7OECOM will issue diagnosticmessages during execution to assist in problem determination.

Set Environment Variables: Environment variables can be set from within theshell by using the UNIX "export" command. If you are using the MVS Batchinterface Unix Systems Services MVS BPXBATCH, you can set theenvironment variables in a file pointed to by ddname STDENV.

Examples: To set the CA7DIR variable in the UNIX environment from thecommand prompt, issue the following command:

export CA7DIR=/users/applications/ca7/bin

To set the environment variables from within a file or PDS member, just set thevariable to the value as follows:

CA7DIR=/users/applications/ca7/bin



Special Considerations: The UNIX environment is case-sensitive. TheCA7DIR environment variable name must be specified in uppercase. The pathname itself can be mixed case.

The maximum length for the value of the path variable is 1024 characters.

//CA7UNIX JOB 'ACCOUNT,INFO','PROGRAMMER',// CLASS=A,MSGCLASS=X// // S A M P L E// // A sample batch job which executes BPXBATCH to invoke// the IBM UNIX shell and then execute the CA 7// interface module CA7OECOM. The files stderr and stdout// are allocated on the UNIX file system. The required// environment variables are defined in a standard PDS// member ENVARS.// // // //JS1� EXEC PGM=BPXBATCH,// PARM='sh /u/users/bin/ca7oecom demandh,job=payjob1'// //STDOUT DD PATH='/u/users/work/mystd.out',// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU// //STDERR DD PATH='/u/users/work/mystd.err',// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU// //STDENV DD DSN=USER.PDS(ENVARS),DISP=SHR// //SYSPRINT DD SYSOUT=



CA 7/API Requirements

The CA 7 SQL-based API is used by CA WCC (formerly Unicenter EJM) tocommunicate with CA 7. If you want to use one of these with CA 7, take thefollowing steps:

1. Add the CA 7 CAILOAD to the Server JCL

The CA 7 load library (CAILOAD) must be available to the server task thatcommunicates with CA 7. If the CA 7 CAILOAD is linklisted in yourenvironment, no changes to JCL or CLISTs should be required.

The CA 7 CAILOAD should be added to the STEPLIB concatenation for theServer Task (started task). For directions on how to identify/define theserver task, see your related interface product's documentation.

2. Add the CA 7 variables to the Server Profile PDS

Two variables must be added to the CACCENV member of the PROFILEdata set used by the CA 7/API. This is pointed to by the PROFILE DD inthe Server started task.

The variables that must be added to the CACCENV member are:

CA7APPL=applidThis variable identifies the VTAM APPLID for the CA 7 you want theAPI to communicate with. This can be found on the APPL= keyword ofthe UCC7VTAM statement in the CA 7 initialization file. For example, ifyour APPLID for CA 7 is PRODCA7 then specifyCA7APPL=PRODCA7.

Note: The CA 7/API can communicate with any CA 7 that is definedto the VTAM system where the API is executing. If you havecross-domain definitions to a CA 7 on a remote system, the CA 7/APIexecuting locally can communicate with that CA 7.

CA7SESS=high-acb-nameThis variable identifies the set of VTAM ACB names that can be usedby the CA 7/API locally to establish communications with CA 7. Forexample, if you have 10 ACBs (CA70001 through CA70010), youshould specify CA7SESS=CA70010. The interface will deduce from thisthat 10 ACBs are available to choose from (1 through 10) and willlocate an available ACB from that pool.

If the CA 7 TSO ISPF interface is installed, the same VTAM ACBs used bythat interface can also be used by the CA 7/API. If so, check to ensure youhave enough ACBs to satisfy both ISPF and API users.

If ACBs need to be defined, For detailed instructions, see “VTAMConsiderations” on page 44.



3. If CA 7 Jobflow Illustrator Microsoft Visio Option is installed, you can skipthis step unless you are connecting to multiple instances of CA 7 on thesame LPAR.

Three variables must be added to the CACCENV member of the PROFILEdata set used by the CA 7/API. This is pointed to by the PROFILE DD inthe Server started task.

WFDSN=datasetnameDefines the data set name to use for all Jobflow Illustrator checkpointfiles that are saved. This value must contain either a data set nameprefix or a fully qualified data set name that is part of a generation datagroup (GDG).

If datasetname contains a data set name prefix, the length of this valuemust not exceed 26 characters. When a Jobflow Illustrator checkpoint issaved, the data set name prefix is suffixed with the following format:

.Dyyyyddd.xhmmssth

where yyyyddd contains the Julian date and xhmmssth contains thehour, minute, second, tenth, and hundredth of a second when theJobflow Illustrator checkpoint file was saved.

If datasetname contains a fully-qualified data set name suffixed with"(+1)", the data set name must be part of a GDG.

WFALLOC=class=valueDefines the storage class, management class, data class or unit thatwill be allocated for the Jobflow Illustrator checkpoint data set namespecified in WFDSN.

classThis value must contain one of the following types where value canbe from 1-8 characters in length:

STORCLAS=value

MGMTCLAS=value

DATACLAS=value

UNIT=value

Note: If the WFALLOC variable is missing, the default is thefollowing:

WFALLOC=UNIT=SYSALLDA



WFSPACE=(type,primary,secondary)Identifies the type and the amount of disk space that will be used toallocate the Jobflow Illustrator checkpoint data set name specified inWFDSN.

typeThis value must contain one of the following types:

CYL (for cylinders)

TRK (for tracks)

primaryThis value must contain the primary space allocation. The valuemust be numeric and in a range of 1-9999.

secondaryThis value must contain the secondary space allocation. The valuemust be numeric and in a range of 1-9999.

Note: If the WFSPACE variable is missing, the default is the following:

WFSPACE=(CYL,1,1)

Additionally, all unused allocated space is released when the JobflowIllustrator checkpoint file is closed.

4. Add additional Virtual Terminal definitions if needed

Each CA 7/API session will use a Virtual Terminal on the CA 7 system withwhich it is communicating. If you do not have Virtual Terminals defined, or ifyou need to increase the number of Virtual Terminals, see the discussionsof the UCC7VTAM, LINE and TERM initialization statements in the SystemsProgrammer Guide.

5. Enable Online Calendar Maintenance facility

If you want to use the facilities in CA WCC to maintain your CA 7 basecalendars, you need to enable the Online Calendar Maintenance facility inCA 7. This feature allows you to create, update, and delete CA 7 basecalendars online without the need for batch assemblies.

If you want to enable Online Calendar Maintenance, see the CALENDARinitialization statement in the Systems Programmer Guide.



TSO/ISPF

CA provides an interface that gives the TSO/ISPF user access to a wide rangeof CA 7 functions. With the interface, the CA 7 user can now enjoy many ofthe benefits that derive from TSO/ISPF (such as split-panel capability and ISPFEditor) while using CA 7. However, it should be noted that the ISPF jumpfacility is not available from a CA 7 terminal session under ISPF. For example,one cannot go to the ISPF BROWSE panel by simply entering =1 in acommand area and pressing Enter. One must either split the panel or end theCA 7 terminal session.

In the TSO/ISPF environment, the ISPF user requests interface services bymeans of a CLIST. Programs executed under the CLIST acquire a CA 7 virtualterminal and a VTAM LU-LU session is set up between ISPF(SLU) andCA 7(PLU). With the exception of edit sessions, panel data is presented as it isin any CA 7 online terminal session. The interface processes panel input andoutput for the ISPF session by invoking the appropriate ISPF Dialog Managerservices. Interface modules issue VTAM SEND and RECEIVE macros tohandle the data traffic with CA 7.

Note: Because the interface uses a CA 7 VTAM terminal, all restrictions thatapply to VTAM terminals also apply to the ISPF sessions using the interface,such as the 255 page limit on output.

All CA 7 online terminal functions can be requested using the interface with theexception of /SHUTDOWN commands.

The JCL syntax checking facility that is used by the native CA 7 Editor is NOTavailable in the ISPF environment. JCL validation through CA JCLCheck can berequested using the !JCK edit macro. For more information about !JCK, seethe CA JCLCheck documentation if you are using the full CA JCLCheckproduct.

To use the CA 7 TSO/ISPF interface, virtual terminals must be defined in theCA 7 initialization file.

For more information about the installation of this interface, see the InstallationGuide.

This discussion of the CA 7 TSO/ISPF interface installation follows in threetopics:

■ VTAM considerations

■ ISPF considerations

■ CA 7 considerations



VTAM Considerations

The TSO/ISPF interface requires VTAM node definitions to support the LU-LUsession between CA 7 and ISPF. The following discussion provides informationabout the VTAM application that contains the nodes used by the interface.

The CA 7 TSO/ISPF interface uses only the node name that is defined usingthe ACBNAME keyword on the VTAM APPL statement. The interface imposesstrict conventions that must be observed when coding the value for thiskeyword. The application minor node name that is created by the label on theAPPL statement is not referenced by the interface directly. This name is usedby VTAM and must be unique within the network.

The ACBNAME values must be exactly seven bytes long. The first threecharacters can be chosen by the user, subject to VTAM naming conventions.The last four characters must be numeric and numbered consecutively from0001 to nnnn, where nnnn represents the maximum number of concurrent usesof the interface.

For example, suppose that all of the node names to be used by ISPF duringCA 7 sessions begin with the characters CA7. If the maximum number ofconcurrent interface uses is 4, then 4 nodes must be defined for this purpose.See the following example of a VTAMLST member defining the nodes for suchan installation.

CA7ISPF VBUILD TYPE=APPLCA71��1 APPL ACBNAME=CA7��1CA71��2 APPL ACBNAME=CA7��2CA71��3 APPL ACBNAME=CA7��3CA71��4 APPL ACBNAME=CA7��4

A sample VTAMLST member is included in the CA7ISPF member of MACLIB.This can be edited to reflect the specific needs of your installation. This shouldthen be copied to the appropriate VTAMLST library to correctly define theVTAM application.



Each request for a CA 7 terminal session from an ISPF panel requires the useof one of these nodes dedicated for interface use. Thus, in this example,anywhere from one to four ISPF users can be allowed depending on terminalcharacteristics. In most instances, an ISPF user requires the use of only oneCA 7 terminal session. However, nothing would prevent one ISPF user fromhaving more than one CA 7 terminal session going at one time using ISPF'ssplit panel capability. For example, one user could split the panel into four ISPFpanels, and from each screen maintain a CA 7 terminal session. This wouldimply four concurrent uses of the interface or four CA 7 terminal sessions goingon at once. In this example, any attempt to use the interface during this timefrom another terminal would fail since no nodes would be available for thispurpose.

Unlike the node for CA 7 that requires that AUTH=ACQ be coded on the VTAMAPPL statement, the ISPF nodes have no such special requirements.

A VTAM application similar to the one just described must be defined in eachVTAM domain where TSO/ISPF sessions with CA 7 are to be supported. ForCLIST compatibility, the ACBNAME values should be the same acrossdomains, only the node names that are created by the labels on the VTAMAPPL statements need be changed for network uniqueness. In the followingexample, the CA7ISPF member could be used as a model for an applicationdefinition in another domain of the network.

CA7ISPF2 VBUILD TYPE=APPLCA72��1 APPL ACBNAME=CA7��1CA72��2 APPL ACBNAME=CA7��2CA72��3 APPL ACBNAME=CA7��3CA72��4 APPL ACBNAME=CA7��4

When the install is complete, make sure to activate the applications where theinterface nodes are defined. In this example, issue a VARY command on theMVS console to make the VTAM nodes available for use; such as:

VARY NET,ID=CA7ISPF,ACT



ISPF Considerations

The TSO/ISPF interface requires several CLISTs, panel definitions, and loadmodules.

The CLIST used to invoke the interface is provided in the CA7CLIST memberof CAICLS0. This CLIST must be edited to reflect changes appropriate for yourinstallation. It should then be copied to a library that is part of the SYSPROCconcatenation in the TSO LOGON procedure to be made easily accessible.

PROC � CA7APL(CA7) SESSAPL(CA7��4) + LIB(CAI.CA7.CAILOAD) SET &CHCK = &SUBSTR(4:7,&SESSAPL) SET &NUMCHK = &DATATYPE(&CHCK) IF &NUMCHK = &STR(CHAR) THEN GOTO APPLERR CONTROL NOMSG NOLIST NOCONLIST NOSYMLIST ISPEXEC CONTROL ERRORS RETURN SET &CA7ACT = PASSTHRU ISPEXEC VPUT (CA7ACT) SHARED ISPEXEC VPUT (CA7ACT) SHARED IF &ZAPPLID ¬= CA7 THEN GOTO ENDPF ISPEXEC VGET (C7UIDRES) PROFILE IF &LASTCC = � THEN GOTO NEXT IF &LASTCC = 8 THEN &C7UIDRES =NEXT: + ISPEXEC VGET (INITVAR) PROFILE IF &LASTCC = � THEN GOTO ENDPF IF &LASTCC = 8 THEN GOTO UPDATE ELSE GOTO ERRORUPDATE: + %CA7INITENDPF: +

CALL '&LIB(L2ISPF��)' + 'CA7APL=&CA7APL,SESSAPL=&SESSAPL' FREE DA('&LIB') GOTO FINALERROR: + WRITE CA-7.X�45 - ERROR IN VGET FROM APPLICATION POOL GOTO FINALAPPLERR: +WRITE CA-7.X�46 - LAST 4 CHARACTERS OF SESSAPL MUST BE NUMERICFINAL: + SET &CA7ACT = ISPEXEC VPUT (CA7ACT) SHARED EXIT

In the CLIST above, the CA7APL keyword supplies the name of the ACB forCA 7. This value should be identical with the value coded for the APPLkeyword in the UCC7VTAM statement in the CA 7 initialization file. The valueon the SESSAPL keyword should be the ACBNAME with the highest value. Inthis example, CA70004 would be coded since four nodes were defined forCA 7 TSO/ISPF communication.



When performing an installation, you can run SMP/E USERMOD UL2B111 inthe SAMPJCL library. The job replaces the default TSO/ISPF CLIST with acopy that is customized by the CA 7 Stage I SYSGEN.

Also, several CLISTs are used as EDIT macros when the ISPF Editor is calledin the CA 7 environment. The edit macros are CA7EXIT, CA7SAVE, CA7SS,and CA7SR. These correspond respectively to EXIT, SAVE, SS, and SR in theCA 7 environment. Another edit macro CA7ED0 is supplied and is required forinternal use by the interface. These CLISTs are also supplied on CAICLS0.These must also be copied to a CLIST library that is included in the SYSPROCconcatenation in the TSO LOGON procedure.

The following load modules are required. They are used to handle the VTAMlink with CA 7, invoke Dialog Manager services and perform other interfacefunctions. These modules do not execute in the CA 7 address space but in theTSO user's address space.

L2ADDON L2ISPFWA L2ISPF�� L2ISPF1� L2ISPF2� L2ISPF21 L2ISPF4� L2ISPF42 L2ISPF45 L2ISPF46 L2ISPF9�

Since CA 7 does not need access to these modules, they can be moved fromthe CA 7 production load library to a smaller load library that is accessed byTSO users. In this way, use of the interface does not entail allocation of theCA 7 load library. The library containing the interface modules is dynamicallyallocated using a CALL statement.

Three ISPF panel definitions are supplied on CAIPNL0 and are required for theinterface:

CA7@PRIM CA7P�� CA7��3

The CA7@PRIM panel is the menu panel for CA 7 under ISPF. CA700003 is adocumentation panel that is invoked when the ISPF HELP command is issued.CA7P000 is the panel required for processing option 1 from the CA 7 menu.This panel is used for all online terminal panel handling. These panel definitionsshould be copied to a library that is part of the ISPPLIB concatenation in theTSO LOGON procedure.



Although a CA 7 online terminal session can be acquired by simply executingCA7PDRVR, ISR@PRIM should be modified to issue the CA7PDRVRcommand with NEWAPPL (CA7). If CA7PDRVR is invoked in this way, an ISPFapplication named CA7 is recognized by ISPF. If the interface is invoked in anyother way (for example, by executing CA7PDRVR or CA7CLIST from ISPFoption 6) then you have no CA 7 PF key support. See the sample ISR@PRIMprovided in CAI.SAMPJCL for an example of an ISPF primary menu where theCA 7 TSO/ISPF interface is an option.

If the CA7@PRIM panel is defined as a SELECT option with theNEWAPPL(CA7) parameter and if the CA 7 TSO/ISPF interface option isselected from the ISPF primary menu, then ISPF searches for a user profilenamed CA7PROF, an edit profile named CA7EDIT, and a command tablenamed CA7CMDS. The CA7CMDS member of CAITBL0 is provided as part ofthe installation. CA7PROF and CA7EDIT are built by ISPF dynamically. ISPFretrieves all profile information from CA7PROF while the CA7 application is incontrol, thus allowing the user the capability of defining ISPF PF key settingsthat are unique to the CA7 application.

When the online option (option 1 from the CA 7 TSO/ISPF menu) is invoked forthe first time, PF keys are assigned the following default settings:

PF�1 - HELP PF13 - HELP PF�2 - SPLIT PF14 - SPLIT PF�3 - END PF15 - END PF�4 - RETURN PF16 - RETURN PF�5 - RFIND PF17 - RFIND PF�6 - RCHANGE PF18 - RCHANGE PF�7 - UP PF19 - UP PF�8 - DOWN PF2� - DOWN PF�9 - SWAP PF21 - SWAP PF1� - LEFT PF22 - LEFT PF11 - RIGHT PF23 - RIGHT PF12 - CURSOR PF24 - CURSOR

In a CA 7 terminal session under ISPF there is no ISPF command input area,unless the ISPF editor is invoked. All input is interpreted as CA 7 terminal inputand is treated as such. CA 7 input can be entered either from the "top line" orfrom any area considered appropriate for a CA 7 formatted panel if a formattedpanel is displayed.

ISPF commands are usually issued from any area preceded by the characterstring '====>' or through the PF key. However from a CA 7 session underISPF, ISPF commands can be entered only through the PF key, since all panelinput is taken to be CA 7 terminal input.



CA 7 allows assignment of CA 7 commands to PF keys as does ISPF. In aCA 7 terminal session under ISPF, a PF key interrupt can be used for ISPFcommand input or CA 7 command input but not both. Since it is desirable touse PF keys for both types of command input, most users may want to specifythat certain PF keys provide ISPF command input, and that other PF keys aretreated like CA 7 PF keys. When using CA 7 formatted input panels, PF3 isused to return to the menu from which the current panel could be selected.(PF15 is not accepted as an equivalent function.) Assigning PF3 to any ISPFcommand will prevent that key from being used by CA 7 in any way; transfersbetween panels will require the user to enter the panel name each time.

When an ISPF command is entered, ISPF searches a table to determine theaction that should be taken when this command is input. Such a table is knownas an application commands table and can be modified using ISPF option 3.9.The table exists as a member of a PDS in the ISPTLIB concatenation in theTSO LOGON procedure. The name of the member (also the name of the table)is xxxxCMDS, where xxxx is the name of the ISPF application in control whenthe command was entered. If an ISPF command is entered from a CA 7terminal session under ISPF, then the application in control would be CA7.Thus, the table that ISPF would search is CA7CMDS. If an entry is found in thetable that matches the command entered, then ISPF takes the action specifiedon that table entry. Among the actions that can be specified are PASSTHRU,NOP, and blanks. If the action in a table entry is blank, then ISPF processesthe command as if there were no table entry for it. If NOP is specified, then thecommand associated with it is deactivated for that application. If PASSTHRU isspecified, then the command with its PF key interrupt is passed to theapplication in effect, which in this case is the CA 7 TSO/ISPF interface. Anaction can also be specified dynamically by using an ISPF variable.

A command table (CA7CMDS) is provided that is intended to be used with thedefault PF key settings for the CA7 application previously listed. Use of thistable with the default PF key settings allows all PF keys except PF02, PF03,PF09, PF14, PF15, and PF21 to be given their CA 7 interpretation in a CA 7terminal session unless the ISPF editor is invoked. If the ISPF editor is invoked,then all PF keys are taken as providing ISPF command input. Such anassignment allows the ISPF commands SPLIT, SWAP, and END to always beinput using PF keys when in the CA7 application. The CA7CMDS membershould be copied from CAITBL0 to a PDS that is in the ISPTLIB concatenationin the TSO LOGON procedure.



The following entries are in the CA7CMDS member supplied in CAITBL0:

VERB T ACTION DESCRIPTION

.... SUBMIT 3 NOP

.... HELP � &CA7ACT

.... RETURN � &CA7ACT

.... RFIND � &CA7ACT

.... RCHANGE � &CA7ACT

.... UP � &CA7ACT

.... DOWN � &CA7ACT

.... LEFT � &CA7ACT

.... RIGHT � &CA7ACT

.... CURSOR � &CA7ACT

The ACTION NOP on the entry for SUBMIT causes the ISPF SUBMITcommand to be deactivated for the CA7 application. This prevents users fromusing the ISPF SUBMIT command to submit jobs while in the ISPF editor in aCA 7 terminal session. This is strongly recommended since jobs submittedthrough the ISPF SUBMIT command are not tracked by CA 7.

Use of the &CA7ACT variable on the other table entries allows the interfaceprograms and CLISTs to set the action dynamically, so that the action can bechanged when the need arises. If the ISPF editor is invoked from a CA 7terminal session, then the value of &CA7ACT is set to blanks, otherwise thevalue of the variable is set to PASSTHRU.

To see how this works, suppose that the PF01 key has been pressed in aCA 7 terminal session where the ISPF editor is not currently being used.Suppose also, that the PF01 key is associated with the ISPF HELP commandunder the CA7 application. ISPF searches the CA7CMDS table for an entry forthe ISPF HELP command. The entry is found and the variable &CA7ACT hasbeen set by the interface programs to PASSTHRU. The HELP command is notprocessed by ISPF but instead is sent to the interface programs that send thePF01 interrupt to CA7. CA7 sees the interrupt and processes the command (ifany) associated with that PF key.



If, however, the ISPF editor has been invoked from a CA 7 terminal session,then the situation is different. Prior to entering the ISPF editor, the interfaceprograms set the value of &CA7ACT to blanks. Thus, the action associated withthe ISPF HELP command in the CA7CMDS table has been set to blanks. Thiscauses the ISPF HELP command to be processed normally when PF01 ispressed.

Most of the default PF key settings provided for the CA7 application equate withISPF commands that have no significance in a CA 7 terminal session unlessthe ISPF editor is invoked.

Great care should be exercised when modifying the ISPF PF key settings or thecommand table for the CA7 application. Only those PF keys that are associatedwith ISPF commands that appear in the CA7CMDS table with an action ofPASSTHRU or &CA7ACT are honored by CA 7. The default command tableCA7CMDS that is found in CAITBL0 does not include entries for SPLIT, SWAPand END. This causes these ISPF commands to always be honored. Werecommend that PF keys be set up (using option 0 from the CA 7 TSO/ISPFmenu) for all essential ISPF or TSO command input that must be entered fromthe CA 7 terminal session. If such command input is always to be handled byISPF or TSO then do not create entries for these commands in CA7CMDS.

In addition, if you are calling the CA7CLIST from a REXX program, the callneeds to be the following:

ADDRESS ISPEXEC "SELECT CMD(CA7CLIST) NEWAPPL(CA7)"

CA 7 Considerations

Virtual terminal definitions are required. The number of virtual terminals definedshould be greater than or equal to the number of nodes defined for CA 7TSO/ISPF communication.

For more information about installation of the TSO/ISPF interface for CA 7, seethe Installation Guide.

The ISPF display services used by CA 7 do not support scrolling. The displayof a CA 7 page always starts with the top of the page. You can use the CA 7/PAGE command to page through the CA 7 pages. This means that a CA 7panel image that has all 24 lines used does not show some of the bottom lines,depending on where the split is done (when using a split panel).

Other CA Schedulers and Agents

CA 7 has the capability to send and receive jobs to and from platformsmanaged by other CA schedulers and agents (cross-platform scheduling). Formore information, see Chapter 6, “Cross-Platform Scheduling” on page 201.



Unicenter Event Console

CA 7 can route master station messages to a designated Unicenter EventConsole. For more information about MSMR - Routing Master Station (Browse)Messages to a Unicenter Event Console, see the Systems Programmer Guide.

CA Service Desk

CA 7 can open requests (issues) in CA Service Desk when certain eventsoccur in CA 7. For example, if a payroll job abends, a request can beautomatically opened to track the problem.

The following CA 7 events can be used to create a request in CA ServiceDesk:

■ Job Completions

■ Scratch, DQTABLE, or trailer queue reaching 80% full

■ The /SDESK command

CA 7 requires CAISDI/els from the CA Common Services tape. CA ServiceDesk r11 or higher is also required.

You may not want requests open for all job completions or queue fullconditions. You can provide CA 7 with rules on when to open requests.

Configure CAISDI/els for CA 7

For information about how to install CAISDI/els from the CA Common Servicestape, see the CA Service Desk Integration Guide.

The CAISDI/soap started task must be running on at least one z/OS image.The image must be accessible to the image where CA 7 is executing usingCAICCI. In other words, there must be a CAICCI connection between thesystem where CA 7 is executing and the system where CAISDI/soap isexecuting. If CAISDI/soap is executing on the same system with CA 7, noCAICCI connection is necessary.

CA 7 provides an event library for CAISDI/els. The default name of this libraryis CAI.CA7.CAIEVENT.

Event library member AL2CNTL is called the control member. The controlmember may need some customization for some shops, but should be sufficientfor the vast majority of CA 7 sites.

The remaining members in the event library are CAISDI/els events.



We recommend against changing any of the event members provided withCA 7. If your site needs to tailor an event, copy the event member to anothername and change the copy.

Event member names have the format xxxxxxnn where xxxxxx is thesix-character CAISDI/els event name, and nn is the language. For example,CAISDI/els event ABEND2 for English is named ABEND2EN.

Each event member is divided into three sections: summary, description, andoptions. The summary section contains a one-line problem description. Thedescription section contains a lengthy HTML-formatted description of theproblem. The final section, options, specifies the priority (severity) of theproblem.

The summary and description sections can contain variables that will be filledby CA 7. For example, a job completion event in CA 7 will provide variables forthe job name, JES number, completion code, and so forth. For a complete listof the variables available, see the topic Event Variables.

After each IPL or change to the event library, the event library must be loadedby CAISDI/els on the system where CA 7 is executing. The load is done by theCAISDI/els CASDIELS procedure. The CASDIELS define statement for CA 7should look like this:

define product=CA-7,eventlib=cai.ca7.caievent,prodcntl=al2cntl

Case does not matter on the define statement. "CA-7" and "al2cntl" must bespelled exactly as shown. The event library name must be specified.

Configure CA Service Desk for CA 7

The control member in the event library (member AL2CNTL) contains contactand asset names. These names must be defined to CA Service Desk, or theappropriate options must be set in CA Service Desk to allow the contacts andasset names to be dynamically added.

Read the comments in the control member and the CA Service Deskdocumentation for more information.

Configure CA 7

The CA Service Desk interface is activated by the SERVICEDESK initializationfile statement. SERVICEDESK has no keywords.



When CA 7 finds the SERVICEDESK initialization file statement, it readsfiltering rules from the SERVDESK DD statement. The filtering rules controlwhen a CA Service Desk request is to be created. For example, the rules mayindicate that requests should be opened for job names that start with PAY andthat abend. For more information, see SERVDESK Rules.

CA 7 will write the CA Service Desk request number that was opened to theSERVLOG DD statement. SERVLOG should be a SYSOUT file allocated to theCA 7 started task.

CAISDI/els Events Provided by CA 7

CAISDI/els events are used by CA 7 to create requests in CA Service Desk. Inaddition to the text (contents) of the request, the events also control theformatting and priority of the request.

CA 7 provides events both with and without HTML formatting for thedescription. Using the HTML formatting may require you to change installationoptions in CA Service Desk.

Events that start with @ do not use HTML formatting. Events that do not startwith @ do use HTML formatting.

The following CAISDI/els events are provided by CA 7.

Any number of additional CAISDI/els events can be created at your site byadding additional members to the event library.

Name withoutHTML Formatting

Name withHTMLFormatting

Intended Use

@ABND1@ABND2@ABND3

ABEND1ABEND2ABEND3

Job completions where the job hasabended. Event names ending in 1create priority 1 requests, ending in2 create priority 2 requests, etc.

@FAIL1@FAIL2@FAIL3

FAILD1FAILD2FAILD3

Job completions where the job hasended with an unacceptable returncode. Event names ending in 1create priority 1 requests, ended in 2create priority 2 requests, etc.

@QFUL1 QFULL1 One of the CA 7 queues (scratch,DQTABLE, or trailer) is at or above80% full. These events create apriority 1 request.



SERVDESK Rules

The SERVDESK DD statement points to an FB 80 data set containing the rulesfor when CA 7 should create requests in CA Service Desk. The SERVDESKrules are read at CA 7 startup when the SERVICEDESK initialization filestatement is processed. The rules are then stored in memory. The SERVDESKrules can be refreshed without restarting CA 7 by using the/REFRESH,MOD=SERVDESK command.

The /DISPLAY,ST=SDESK command can be used to display the currentlyactive SERVDESK rules.

SERVDESK rules start in column one and have the following general syntax:

type,keyword=value,keyword=value,

Rules can be continued after any "keyword=value," and start again in anycolumn.

The following are valid types:

JOBCOMPJob completion. All CA 7 job completions are compared againstJOBCOMP rules to determine whether a request should be opened. Thisincludes job abends, job condition code failures, normal (successful)completions, and "force completes."

Note: Non-executable jobs and "force completes" are treated as zeroreturn code completions (C-C0000). Also, cross-platform jobs (CA7TOUNI)are not evaluated if the MVS submit execution of the CA7TOUNI step issuccessful. In that case, the completion code reflects the return codereturned by the cross-platform target node.

QFULLQueue full. QFULL rules are evaluated when message CA-7.306 is issued(CA-7.306 - ** WARNING ** 80% xxxxxxx QUEUE UTILIZATION **WARNING **).



The following keywords can be included on SERVDESK rules (not all keywordsare valid for all rule types):

ATIME=, BTIME=Specifies after and before times used for all rule types. If the after time isless than the before time, then the event (that is, job completion) mustoccur between the two times. If the after time is greater than the beforetime, the event must occur outside of the time range. ATIME defaults to0000. BTIME defaults to 2359.

COMP=Specifies a required completion code or completion code mask used forJOBCOMP rules. The completion code uses the same format as seen onthe LQ command (that is, an S806 abend would be "A-S806"). COMP= isrequired on JOBCOMP rules.

A value of FAILED can be used to match any code that is not a successfulcompletion. For example, COMP=FAILED matches any abend, bad returncode, or JCL error.

EVENT=(Required for all rule types) Specifies the six-character name of theCAISDI/els event that will create the request in CA Service Desk. TheCAISDI/els event determines the priority of the request in CA Service Desk.

JOB=Specifies a job name or job name mask used for JOBCOMP rules to matchjob completion events in CA 7. JOB= defaults to *.

QUEUE=Specifies a queue name or queue name mask used for QFULL rules. Seemessage CA-7.306 for the queue names that can be specified.

SYSTEM=Specifies a system name or system name mask used for JOBCOMP rules.SYSTEM= defaults to *.

A CA 7 event must match all of the keywords on a rule before a request isopened in CA Service Desk. If multiple rules would match an event, then thefirst rule is used.



Masking: Any of the maskable fields in the rules (such as JOB, COMP, etc.)can use the wildcard characters "*" and "?". The asterisk "*" can be used tomatch any number of characters, including zero characters. The question mark"?" can be used to match any non-blank character.

Any number of asterisks and question marks can be used in any combination inany of the SERVDESK fields that accept masks.

Example SERVDESK Rules: This example creates a priority 1 request if anyjob that starts with PAY abends:

JOBCOMP,JOB=PAY ,COMP=A ,EVENT=ABEND1

This example creates a priority 2 request for any job in the ACCT system thatabends or gets a bad return code:

JOBCOMP,SYSTEM=ACCT,COMP=A ,EVENT=ABEND2JOBCOMP,SYSTEM=ACCT,COMP=R ,EVENT=FAILD2

This example creates a request for abending jobs with an X in column 3 andthat end in $ and are in the BILLING system. If the abend occurs during theday, use priority 2, otherwise use priority 1.

JOBCOMP,JOB=??X $,SYSTEM=BILLING,ATIME=�8��,BTIME=17��, COMP=A ,EVENT=ABEND2JOBCOMP,JOB=??X $,SYSTEM=BILLING,COMP=A ,EVENT=ABEND1

Note: The second JOBCOMP rule does not need the ATIME and BTIME fieldsbecause it will only be checked if the first rule did not match the job completion.



Event Variables

The CAISDI/els events used by CA 7 to create requests in CA Service Deskcan contain variables. Variables start with an ampersand (&) and are inuppercase. When the values are substituted into the CAISDI/els events, anytrailing blanks are dropped.

The following variables are available. Note that not all variables are availablefor all CA 7 event types.

Variable CA 7 EventTypes

Description

&DLDATE JOBCOMP Deadline date

&DLTIME JOBCOMP Deadline time

&DODATE JOBCOMP Due out date

&DOTIME JOBCOMP Due out time

&EDATE JOBCOMP End date

&ENTRYMOD JOBCOMP Entry mode of the job (demanded, auto,sscan)

&ETIME JOBCOMP End time

&EXEC JOBCOMP EXEC flag

&EXSYS JOBCOMP Execution system SYSID (is 7UNI forcross-platform jobs and 7XPJ for XPJOB)

&INSTANCE All CA 7 instance name (that is, CA71)

&JESNUM JOBCOMP JES number (can be *NA* for forcecomplete and cross-platform jobs)

&JOB JOBCOMP Name of the job

&JQUSER JOBCOMP Contents of the JQUSER field

&MAINT JOBCOMP MAINT flag

&NL All Single carriage return (new line)

&NUM JOBCOMP CA 7 job number

&P All Double carriage return

&QUEUE QFULL Name of the queue that is 80% full

&RESTARTS JOBCOMP Number of times job has been restarted

&SCHDID JOBCOMP Schedule ID

&SDATE JOBCOMP Start date



Variable CA 7 EventTypes

Description

&STAT8 JOBCOMP The 8-byte status of the job, as seen onthe LQ command

&STAT80 JOBCOMP A longer, user-friendly, status of the job

&STIME JOBCOMP Start time

&SUBDATE JOBCOMP Submission date

&SUBTIME JOBCOMP Submission time

&SYSDATE All Current date in format MM/DD/YYYY

&SYSEDATE All Current date in format DD/MMM/YYYY

&SYSID All SMF ID where CA 7 is executing

&SYSTEM JOBCOMP Job's SYSTEM

&SYSTIME All Current time

&SYSJOB All Name of the CA 7 task



Critical Path Monitoring

Large production workloads can be difficult to manage in the absence ofmonitoring tools that afford integrated views of key segments of the workload.Critical Path Monitoring (CPM) provides tools that can be used for this purpose.CA 7 can report on the status of jobs within key segments of the workload.This information can be used to track the progress of critical production jobstreams, "critical paths".

Two tools can be used to track and display CA 7 critical path information:

■ CA OPS/MVS can work with other CA solutions to track and graphicallydisplay the status of CA 7 critical paths. These solutions are not providedas part of the CA 7 installation package. For more information about thisoption, see the CA OPS/MVS documentation.

■ Critical Path Monitor Version 3 is supplied as part of the CA 7 installationpackage. You can use it to track CA 7 critical paths and to display criticalpath information in text-based formats on ISPF panels. For moreinformation about this option, see the Critical Path Monitor Version 3 UserGuide.

Critical Path Definition

The definition of CA 7 critical paths and the creation of critical path events byCA 7 is the same regardless of which CPM tracking tool is being used. Unlessotherwise noted, the following description of Critical Path Monitoring applies toeither tracking method that is referred to generically as the 'CPM Tracker'.

Within CA 7 a named segment of a triggered stream of jobs is known as aFLOW. The following elements are required for FLOW definition:

■ The name of the FLOW.

■ The name and schedule ID of the starting job.

■ The name and schedule ID of the ending job.

■ The expected completion time of the ending job (Service Level Agreement,or SLA time).



A FLOW initiates when VRM resources are attached to the starting job andterminates when its ending job completes successfully. CA 7 considers anactive FLOW to include the beginning job and all of its job and dataset triggereddescendants up to and including the ending job. The CA 7 command FLOWLcan be used to display active FLOWs in CA 7. For information about theFLOWL command, see the Command Reference Guide.

CA 7 uses ENF to report status information for all FLOW jobs to the CPMTracker. When CA 7 notifies the CPM Tracker that a FLOW has begun, theCPM Tracker will request forecast information from CA 7 to chart the "criticalpath" that connects the FLOWs beginning and ending jobs. The CPM Trackerthen uses the CA 7 ongoing status information to monitor the progress of thecritical path.

FLOW initiation occurs at job submission as part of the VRM resourceevaluation process. This implies a restriction on defining the starting job in aFLOW. A job must be eligible to use VRM resources to initiate a FLOW. Thismeans that a nonexecutable job cannot start a FLOW. However, nonexecutablejobs can be included in a FLOW and can be defined as the ending job of aFLOW.

Note: If flows are not properly defined, active flows may become stranded. Forexample, if the specified ending job is no longer in the trigger flow, all relatedjobs may complete without finding the end of flow. Also, if a job in the criticaltrigger path is CANCELed, the flow never recognizes the ending job. Currentreleases of CA 7 automatically delete active flows if there are no longer anyjobs connected to it (see message CAL2P099W). However, you shouldperiodically issue a FLOWL command and check for active flows that have notcompleted as expected, and use the FLOWD command to delete them becauseactive flows take up memory in the CA 7 address space.



CA 7 Requirements for Critical Path Monitoring

The following steps are required to activate CPM functionality for CA 7:

1. Enable CPM in the CA 7 initialization file options.

The CA 7 CPM interface is activated at CA 7 startup when CPM=YES iscoded on the OPTIONS statement in the CA 7 initialization file. Whenactive, this interface provides services that can be used to define thoseportions of the triggered workload that require special management attentionusing CPM. These services are used to define the limits of a key segmentof the triggering stream and to assign a name to the segment forsubsequent references in the CPM environment. For information aboutinitialization file options, see the Systems Programmer Guide.

2. Enable the CA 7 CAICCI interface in the CA 7 initialization file options.

The CA 7 CAICCI Interface is used to extract information from CA 7 for theCPM Tracker to build an image of a critical path. At least one CA 7 CAICCIterminal must be defined in the CA 7 initialization file. For informationabout the interface, see “Interface with CAICCI” on page 90. Forinformation about GROUP, LINE, and TERM statements for CA 7 CAICCIterminals (DEVICE=CCI), see the Systems Programmer Guide.

3. Tailor the CPM Tracker JCL.

If you are using Critical Path Monitor Version 3, the CPM Tracker JCL is theCPMSRVR started task JCL. If you are using CA OPS/MVS then the OSFserver task JCL acts as the CPM Tracker. The CPM Tracker must haveaccess to the CA 7 load library. If the library is not in the LNKLST orLPALIB, you must add them to the OSF server's STEPLIB DD.

Optionally, you may need to add a CA7PARMS DD statement to the CPMTracker JCL to set parameters to be used by the CA 7 CAICCI interface togather information about active flows. If specified, the CA7PARMS DDmust point to an 80-byte card-image data set or PDS member.



CA7PARMS keywords must start in column 1 with no embedded blanks.Lines that begin with a blank or asterisk are considered comment lines. Thefollowing lists keywords and their defaults:

CA7NODE=Specifies the CAICCI node where CA 7 resides. The default is localnode.

CA7SSCT=Specifies the CA 7 instance name (CA71, CA72, and so forth). Thedefault is CA71.

CA7USER=Specifies the user ID to log on to CA 7 with. The default is CPM Trackeruser ID.

CA7PSWD=Specifies the user ID password. No default.

CA7SNAP=Specifies the ddname for trace snaps. The default is CA7TRACE.

CA7DBUG=Specifies the debug/trace options as follows:

0Suppresses trace

1CPMF WTO trace only

2CPMF and CCI interface WTO trace only

3CPMF WTO trace and CPMF snap trace only

4CPMF and CCI interface WTO and CMPF snap trace (full)

There is no default.

If you want to use one of the snap trace options, you should add aCA7TRACE SYSOUT DD to the JCL.

If a CA 7 user ID is not specified in the CPM Tracker or in CA7PARMS,then the user ID under which the CPM Tracker task itself is running will beused to log on to CA 7. Regardless of the source, the CA 7 user ID usedby the CPM Tracker must have authority to issue FJOB, FLOWL, FQJOB,FRJOB, LQ and LRLOG CA 7 commands as well as having CA 7 UIDaccess to all jobs in critical path flows.


CA 7 CA 7 Job Management Smart Console Option


For CA 7 CA 7 Job Management Smart Console Option to monitor CA 7browse data set messages, you need to add the CA 7 browse event to yourCAIENF database. To add this event, see member L2DCM1 in the CA 7sample JCL library.

The CA 7 CA 7 Job Management Smart Console Option Cross SystemCommunication provides for two major functions: CA 7 CA 7 Job ManagementSmart Console Option to CA 7 CA 7 Job Management Smart Console Optionand CA 7 CA 7 Job Management Smart Console Option Multi-System Console.

■ CA 7 CA 7 Job Management Smart Console Option to CA 7 CA 7 JobManagement Smart Console Option

Users can define cross system actions where a message is selected byCA 7 CA 7 Job Management Smart Console Option on one system andspecific actions are performed on another system executing CA 7 CA 7 JobManagement Smart Console Option.

A list of actions that can be cross system actions follows:

– CICSTRAN– MVSCMD– SENDOPER

■ CA 7 CA 7 Job Management Smart Console Option Multi-System Console

Systems executing CA 7 CA 7 Job Management Smart Console Option willhave their console messages routed to all defined systems executing CA 7CA 7 Job Management Smart Console Option. Commands issued from asystem executing CA 7 CA 7 Job Management Smart Console Option canbe routed to another system executing CA 7 CA 7 Job Management SmartConsole Option. The command output is returned to the console that issuedthe command. The principle of integrated services will be used tocommunicate between systems. The use of CA Common CommunicationInterface (CAICCI) insulates CA products from the dependencies of theoperating system.

– Messages are routed to all defined systems.

– Operator commands can be issued to another system.

– Single character system identification.

– Messages from other systems will be available to CA 7 CA 7 JobManagement Smart Console Option for message selection.

– Route codes can control console message traffic.

– Remote operations availability.

– Console hardware reduction.



Note: When using the CA 7 CA 7 Job Management Smart Console OptionMulti-System Console Facility, only console messages are routed betweensystems executing CA 7 CA 7 Job Management Smart Console Option.CICS messages are not routed unless they are issued to the console usingthe SENDOPER action.

■ Simulate Mode

– This feature functions at the action record level. By defining an actionrecord in the SIMULATE state, you instruct the action processor not toactually perform the action, but to record that it would have beenperformed in the log instead. The log entry can also be sent to theconsole as a WTO or system log based on the CA 7 CA 7 JobManagement Smart Console Option system parameters. The inclusionof an action record in the simulate state within a list of actions has noeffect on any of the other actions; they are still processed normally. Youcan set one, some, or all of the actions in a list to the simulate state.

■ Selection Processing

– This selection process will allow messages to be selected only aspecified number of times within a time frame. After this maximum hasbeen reached, the selection record can be suspended for a specific timeperiod.

– This selection process will allow messages to be selected only after aspecified number of occurrences. After this frequency has beenreached, the selection record can be suspended for a specific timeperiod.

– You can specify substitution variables as scan text. Substitutionvariables work with the SETEVENT action. When the SETEVENT actionoccurs, all the variables for that message are saved. By entering theEvent ID in the token field and the actual variable name in the SCANTEXT field, the selection processor will resolve the variable and performthe SCAN using the data that variable contains.

– The selection processor allows specification of up to eight SCAN TEXTqualifications.

– Selection processing supports lowercase characters as your SCANTEXT data. Be aware that, SCAN TEXT data defaults to lowercasewhen specifying the data in the CA 7 CA 7 Job Management SmartConsole Option Dialog.

Also, the scan options allow positional offset specification (offset fromthe start of text). If positional offset is present, Boolean logic (GT, LT,GE, LE, EQ, NE) can be specified.



– A selection field, SUBSYSTEM, qualifies what is being processed. Validparameters for this field are: WTO, CMD, and CICS. The default isWTO, which is used to define console messages. CMD is used forselection of operator commands. CICS is used for the selection ofinternal CICS messages that are typically written to the MSGUSR DCB.Use these messages to detect terminal and printer errors, transactionabends, and other information relevant to a CICS address space.

Use the SUBSYSTEM field with the JOBNAME field to select CICSmessages from specific address spaces.

– The selection processor allows for selection of the MVS NucleusInitialization Program (NIP) messages. NIP messages are producedfrom the time the system operator selects the LOAD function at thesystem console to the time that the operating system is initialized.System initialization is considered the point in time when the system logbecomes available. To select NIP messages, CA 7 CA 7 JobManagement Smart Console Option must be initialized before the JobEntry Subsystem (JES) is started. Keep in mind that the NIP messageshave already occurred by the time CA 7 CA 7 Job Management SmartConsole Option initializes; these messages are not selected realtime.CA 7 CA 7 Job Management Smart Console Option processes them asif the messages were occurring at CA 7 CA 7 Job Management SmartConsole Option initialization time. This provides the ability to determinethat an IPL has occurred or perform action processing based on theproduced NIP messages. Since the NIP messages occur before theCA 7 CA 7 Job Management Smart Console Option address space isactive, CA 7 CA 7 Job Management Smart Console Option does notrespond to them; however, CA 7 CA 7 Job Management Smart ConsoleOption does provide action processing capability for the messages.

– Date Qualification is available. This will allow you to specify a date orrange of dates on which the selection record will be active.

– Day/Time Qualification is available. This will allow you to specify acertain day or days and also specific time ranges on those days withinwhich the selection record will be active.



■ Audit Trail

– All messages and actions are optionally logged.– Logging is to SMF.

■ Automatic Table Refresh

– The CA 7 CA 7 Job Management Smart Console Option in-coreselection, action, and event tables are automatically refreshed uponchanges to the selection or action database file.

■ Four-Digit Reply IDs

– Support is provided for four-digit Reply IDs that were introduced withMVS/ESA SP4.

■ Automatic Time Commands

– You can have an unlimited number of automatic time commands(>TIMECMD). For each time command selection record that qualifies,the associated actions will be performed. Time command processingoccurs every minute.

■ Licensing Management Program (LMP)

– CA 7 CA 7 Job Management Smart Console Option interfaces withCAIRIM to determine product licensing authorization.


Schedule UNIX System Services Jobs

Schedule UNIX System Services Jobs

The mainframe environment provides a UNIX implementation referred to asUNIX System Services. These services allow UNIX users to operate from withinthe mainframe environment without having to learn the MVS system internalswhile using most of the standard UNIX facilities such as shell commands, shellscripts, and binary executables. This UNIX shell runs as an MVS system taskand can be accessed from any MVS batch job through a program calledBPXBATCH.

The BPXBATCH program is invoked from MVS batch and executes shell scriptsor executables on the UNIX file system. Since this is standard MVS batch JCL,CA 7 can schedule these tasks just like any other MVS batch job.

For a detailed discussion of the BPXBATCH utility, see the IBM documentation.

The following is a sample invocation of BPXBATCH:

//JOBNAME JOB 'ACCOUNT,INFO','PROGRAMMER',CLASS=A,MSGCLASS=X// // S A M P L E // // Sample batch JCL which executes BPXBATCH to invoke the IBM // UNIX shell and then executes a shell command under // UNIX System Services. // // // //JS1� EXEC PGM=BPXBATCH,PARM='sh /bin/ls'// //STDOUT DD PATH='/u/users/work/mystd.out',// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU// //STDERR DD PATH='/u/users/work/mystd.err',// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU// //STDENV DD DSN=USER.PDS(ENVARS),DISP=SHR// //SYSPRINT DD SYSOUT=


Interface with IBM Workload Manager (WLM)


IBM Workload Management services (WLM) enable installations to manageworkload distribution, transaction balancing, and resource distribution in z/OSenvironments. WLM allows the specification of policies to control the distributionof workloads throughout a sysplex. While used primarily to control and manageonline transaction workloads, such as CICS user transactions, WLM also hasfeatures you can use to help manage batch workloads.

CA 7 provides interfaces which help you to use IBM WLM to treat CA 7 andthe CA 7 Independent Communications Manager (ICOM) as WLM resources.CA 7 also provides features which help you use WLM scheduling environmentsto manage your batch workload. Use these interfaces separately or concurrentlybased on your processing requirements.

CA 7 and ICOM IBM Workload Manager Resources

CA 7 provides interfaces which help you to use IBM WLM to treat CA 7 andthe CA 7 Independent Communications Manager (ICOM) as WLM resources.You can group WLM resources into scheduling environments. Schedulingenvironments allow you to manage the scheduling of tasks in a sysplex wheredifferent hardware or software applications are available on each system.

The resources which make up scheduling environments are defined to the IBMWorkload Manager. They can represent something physical such as a hardwaredevice. They can represent the presence of a software application such asDB2. Or, they can represent something intangible, such as a day of the week.MVS or JES operator commands can set WLM resource states. Interface callsto WLM by software applications can also set them.

You can assign IBM WLM resource names to the CA 7 online started task andthe CA 7 Independent Communications Manager (ICOM) started task. Whenspecified CA 7, ICOM, or both will call the IBM Workload Manager to set thestate of the designated resource to ON when the started task is initiated. Whenthe started task terminates, a call is made to set the state of the resource toOFF.

One possible use of these resources is to control which MVS images CA 7Batch Terminal Interface (BTI) jobs are directed to. Since these jobs require thesame CA 7 system interfaces as CA 7 ICOM, you could use an IBM WLMscheduling environment to ensure that these jobs are only directed to imageswhere ICOM is running.

To assign an IBM WLM resource name to the CA 7 started task, see thedocumentation for the WLMCA7= keyword on the CA 7 initialization fileOPTIONS statement in the Systems Programmer Guide.



To assign an IBM WLM resource name to the ICOM started task, see thedocumentation for ICOM Execution in the Systems Programmer Guide.

Automatic Scheduling Environment JOB Statement Insertion

CA 7 provides features which can facilitate your use of IBM WLM schedulingenvironments to manage your batch workload. A scheduling environment is alist of WLM resource names and their required states (ON, OFF, or RESET).They allow you to manage the scheduling of tasks in a sysplex where there aredifferences in the hardware or software applications available on each system.If an MVS image matches the scheduling environment requirements, then thattask can be routed to that system.

Through CA 7 Virtual Resource Management (VRM) definitions, you can assignIBM WLM scheduling environments to individual jobs and have CA 7automatically add the appropriate SCHENV= keyword at job submission time.These VRM definitions use the variable (VAR) resource type and can beassociated based on CA 7 schedule ID.

Also, CA 7 can optionally validate the specified scheduling environment withthe current IBM WLM policy prior to job submission. This avoids pre-executionJCL errors that occur when a SCHENV= keyword is specified with a schedulingenvironment that is not defined in the current IBM WLM policy.

To activate the insertion and validation of scheduling environments in CA 7,see the WLMSE= and WLMSEVAL= keywords in the CA 7 initialization fileOPTIONS statement in the Systems Programmer Guide.

To create Virtual Resource Management (VRM) definitions to associatescheduling environments with individual jobs, see VRM Variable Definitions inthe Database Maintenance Guide.


Chapter 3. External Communicators


Batch Terminal Interface (BTI) . . . . . . . . . . . . . . . . . . . . . . . . . . 73Trailer Step Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81U7SVC Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Interface with CAICCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Batch Card Load Program (BCLP) . . . . . . . . . . . . . . . . . . . . . . . 106

External communicators enable the processing of work that is under CA 7control, based on events that are not under CA 7 control.

One example would be an RJE site transmitting data to a central location forprocessing. The remainder of the processing, to be done under the control ofCA 7, must consider the creation of the data file as a prerequisite task and istriggered when the data file is received from the RJE site. Such activities arehandled by CA 7 facilities such as batch terminal interface, trailer step, U7SVC,and batch card load program (BCLP).

The batch terminal interface facility (BTI) is used to perform mainly databasefunctions within a batch job instead of through an online terminal. Many of thesame commands that are available online can be performed through a batchterminal when a CA 7 online terminal is unavailable or impractical.

Trailer steps communicate queue posting commands to CA 7 for some actionthat has taken place. On receiving this communication, CA 7 automaticallyinitiates all tasks defined as dependent on that posting action.

The U7SVC program combines the BCLP and trailer step functions. U7SVCcan be executed as a step, in the same manner as a trailer step, or it can becalled from another program to send commands to CA 7 or post a data setcreation. Through U7SVC, the user can post to CA 7 the creation of anoncard-image data set or request commands not supported by the trailer step.

The CA 7 CAICCI interface combines aspects of the BTI and U7SVC facilities.It uses the CA Common Communication Interface (CAICCI) to send batchcommands to CA 7 on the same or another MVS image. It also receives backthe CA 7 output from those commands so that the caller can evaluate thesuccess of the command string, extract information from the command outputfor future processing, or both. The CA 7 CAICCI interface can be executed in abatch mode, called from a REXX CLIST or environment, or called directly fromanother program.

Chapter 3. External Communicators 71

BCLP is used to transfer batches of card-image data to disk or tape. Once thedata files are created, work under CA 7 control can use those files. On creationof the file, completion information is posted to the CA 7 log data set and alldependent processing tasks are initiated.

These facilities provide the ability to have work performed outside of the datacenter, perhaps at an RJE site, with the production control functions remainingat the central computer location. Inherent advantages of having full data centersecurity are maintained. Remote personnel need not be involved in data centeroperations, JCL, and so forth. Of course, work that begins with any taskexternal to CA 7 can still realize the advantages of automated productioncontrol.


Batch Terminal Interface (BTI)


Batch terminals provide the ability to process commands in batch as if from anonline terminal. You can perform many of the same commands available onlinein this manner if no CA 7 online terminal is available, if hardcopy output isdesired from the commands performed, or if more than 255 pages of outputcould be produced. Each batch terminal is actually a pair of disk data sets, oneinput and one output. These data sets must be defined in the online CA 7 JCL.

When using a batch terminal, ICOM does not have to be active on the CPUwhere SASSBSTR is running; but the batch terminal must have access to theCommunications data set. However, when using the trailer step, U7SVC orBCLP facilities, ICOM must be active on the CPU where it runs.

Commands must follow the same sequence as if using a CA 7 online terminal.Queue maintenance commands, such as XQ or XUPD, are not available inbatch mode, and the DB.2.7 panel and other menu-type panels.

The SASSBSTR program does the following:

■ Locates and allocates an available pair of batch terminal data sets.

■ Loads commands to be processed from SYSIN into the batch input dataset.

■ Notifies CA 7 to start the batch terminal for processing.

■ Waits for CA 7 to process the commands in the input data set and placeresponses in the output data set.

■ Retrieves the output and writes it to a SYSOUT data set. The BTI outputcan be checked against a user-defined table of messages to detect error orwarning conditions. For more information about the batch terminal interfaceerror message table (SASSXXBT), see the chapter "User Exits andModifications" in the Systems Programmer Guide.



Command Format and Sequence

The input to the program (SYSIN) consists of CA 7 commands. The /LOGONand /LOGOFF commands are the required first and last records, respectively,for each batch terminal interface input data set. They must begin in column 1 ofthe record.

To log on, the format is:

��──/LOGON──opid─ ──┬ ┬───────────── ────────────────────────────────────�� └ ┘ ─,──password─

opidSpecifies the required operator identification.

passwordSpecifies an optional password (site-specific).

Note: When using an external security interface, the /LOGON statement canbe omitted, and the batch terminal interface program generates one using anextracted security ID for the user who submitted the BTI job.

The format of the DBM batch commands consists of placing the equivalentpanel top line command by itself in the first statement. In the second andfollowing statements are the function, positional parameters and optionalkeywords. Statements begin in column 1. If the statement is to be continued itmust end with a comma following the last value entered. There must be anon-blank character in column 72 and the next statement must begin in column1.

In the following, notice that function is a positional parameter and must appearwhere it is shown.

commandfunction,positional-parameter,optional-keywords...

The following is an example of the command format:

JOBADD,jobname,SYSTEM=sys,...,(other optional keywords)



To terminate database maintenance mode, enter DBM starting in column 1. Forexample:

/LOGONJOBADD,ACCT��1,SYSTEM=S1UPD,ACCTPAY,USERID=��3JOBCONNUPD,JDEP,ACCTPAY,DEPJOB=ACCT��1,OPT=CDBMLJOB,JOB=ACCTPAY,LIST=RQMT/LOGOFF

To log off, the format is:

��──/LOGOFF───────────────────────────────────────────────────────────��

DBM List Functions

The DBM LIST function in batch commands only validates the existence of thetarget and does not actually provide an image of the equivalent online formattedpanel containing field names and values. For example:

JOBLIST,ACCTPAY

Does not list the ACCTPAY job, but does indicate that it either found or did notfind the job.



Non-DBM Batch Commands

Non-DBM batch commands are similar to DBM commands in that they must:

■ Be card-image statements

■ Be preceded by a /LOGON statement

■ Be followed by a /LOGOFF statement

■ Have a comma after the last value on a statement if that statement is to becontinued (do not go past column 71)

■ Begin in column 1 regardless of whether it is a new or continued statement

Although there are many similarities between the formats for DBM andnon-DBM commands, there is a significant difference:

■ For non-DBM commands, the batch statement format is the same as theonline top line format of the command:

��─ ──command(,positional parameter) ──┬ ┬─────────────────── ────────────�� │ │┌ ┐─,──────────

└ ┘──, ───� ┴keyword=parm

For example:

LPROS,JOB=jobname

Installation Process Batch Commands

The CA 7 installation (or SYSGEN) process creates a job, N220, whichincludes many commands in BTI format. These commands perform databasemaintenance (DBM) functions and some inquiry functions.

These commands provide a good example of how to use the BTI facilityeffectively. The user can benefit from reviewing that data and understandingbetter how this facility can be used to accomplish many user needs.

Note: The N220 job itself should not be run while CA 7 is active online, as theN220 job is an execution of CA 7 in batch mode. The same commands,however, can be used with the Batch Terminal Interface program. The batchcommands for job N220 reside in member N220DECK in the JCLLIB frominstallation. Check with your installation's CA 7 specialist or systemsprogrammer who installed CA 7 for the data set name.



Batch Terminal Interface Execution

Processing Flow

The batch terminal interface program (SASSBSTR) controls the BTI processingflow. It performs the following functions:

■ Locates and allocates an available pair of batch terminal data sets.

■ Copies SYSIN data to the BATCHIN data set.

■ Requests processing by CA 7 of the contents of the BATCHIN data set.

■ Awaits completion of the processing by CA 7.

■ Copies output (from the processing) from the BATCHOUT data set to theSYSPRINT data set.

If the user-defined batch error message table module SASSXXBT isavailable, each line of output is compared against entries in the table. Ifmatched, a message is written to the ERRORS DD (if available). Also, thematching table entry return code is saved if it is higher than any previouslysaved return code.

The following are the possible return codes:

0Indicates that the SASSBSTR program successfully completed its functionswithout detecting an error. SASSBSTR does not validate that the SYSINcommands were processed successfully by CA 7.

8Indicates that SASSBSTR detected an error condition that preventedsuccessful completion of its tasks. Usually, a WTO or message in theSYSPRINT is issued indicating the error condition.

Note: If a /SHUTDOWN, Z3 (or Z5) is done with the batch terminal, it getsa return code of 8.

16Indicates that a security violation occurred that prevented successfulexecution of SASSBSTR.

Usage of the SASSXXBT message table may generate additional return codevalues. For more information about SASSXXBT, see the Systems ProgrammerGuide.



You should never cancel a BTI job while it is executing. This kind of canceldoes not interrupt the execution of the CA 7 commands that the BTI has givento CA 7 to process on the specified (or pooled) batch terminal. All of thesecommands have to complete before CA 7 can make the batch terminalavailable for another BTI execution.

If you do a cancel, the only way to possibly recover (reuse) that batch terminalis to run another BTI specifying the appropriate ID number. This causes CA 7to produce the CA-7.252 WTOR, and a reply of RESET allows the BTI toproceed. However, if the previous BTI commands have not yet completed, thecurrent BTI still fails. Also, no BTI using pooling is able to use the same IDagain of the canceled one until a recycle of CA 7 or the use of the aboveprocedure.

CA7BTI JCL Procedure

The CA 7 installation procedures generate a batch terminal interface JCLprocedure to use for BTI jobs. The default name of the procedure is CA7BTI.

CA-7 BATCH TERMINAL INTERFACE JCL PROCEDURE (CA7BTI)

//CA7BTI PROC ID=�,POOL='1-8',DSNPFX=,OPT=,CA7=CA7n,PG=SASSBSTR//BTERM EXEC PGM=&PG,// PARM='&ID,POOL=(&POOL),DSNPFX=&DSNPFX,CA7=&CA7,&OPT'//STEPLIB DD DISP=SHR,DSN=cai.ca7.loadlib//UCC7CMDS DD DISP=SHR,DSN=cai.ca7.commds//SYSPRINT DD SYSOUT= ,DCB=BLKSIZE=133//ERRORS DD SYSOUT= ,DCB=BLKSIZE=133//SYSUDUMP DD SYSOUT= //SYMDUMP DD DUMMY

Sample BTI JCL

This is an example of a job using the CA7BTI procedure.

//jobname JOB (user job parms)//JS1� EXEC CA7BTI//SYSIN DD ..... ..... (CA-7 commands go here) ..... ...../ //



JCL Parameters

The PARM values for SASSBSTR are shown in the following format:

PARM=(n,POOL=(x-y,b,c),DSNPFX='batch dsn prefix.',CA7=instance,NOMCHK,NOWAIT)

nCan be 0 or specific BTI terminal. A value of 0 (zero) indicates thatDynamic BTI Management should be used. (The program automaticallylocates and uses an available BTI terminal.) A specific BTI terminalnumber (1-8) indicates that the program should use that specific batchterminal. If that terminal is already in use by another job, the current jobchecks every five seconds for a total of one minute to see if the terminalbecomes available. If the terminal is still unavailable, a CA-7.252 WTOR isissued so that you decide whether you want this job to wait for the terminalto become available or cancel this job. Remember that if a specific BTIterminal number is coded, then the POOL parameter is ignored.

POOL=(x-y,b,c)The POOL= keyword can be used with Dynamic BTI Management tospecify the pool of batch terminals to be considered when searching for anavailable terminal. POOL= can be specified as a range of terminals x-y,and/or can be specified as a list of terminals b,c,... The default terminal poolis all eight possible batch terminals.

The POOL= parameter can be used to reserve particular batch terminals forspecific jobs. If these terminal numbers are excluded from the pool,Dynamic BTI Management never allocates them, thus they should alwaysbe available for BTI executions that reference them specifically.

If all batch terminals in the pool are busy, the BTI program enters a cyclewhere it looks for an available batch terminal every five seconds. Thiscontinues for five minutes. If no batch terminals have become availableduring that time, WTOR CA-7.253 is issued. If there is a system problem,the operator can reply CANCEL to terminate the BTI job with a return codeof 8. If a reply of WAIT is issued, the BTI program continues its wait/checkcycle indefinitely. If several BTI jobs are waiting on any available batchterminal, there is no serialization in the order in which they obtain aterminal.



DSNPFX='batch.dsn.prefix.'Specifies an alternate data set name prefix for the BATCHIN andBATCHOUT data sets. The BTI program dynamically allocates theBATCHIN and BATCHOUT files associated with a specific batch terminal.Normally, the BTI program constructs the data set names for these filesusing the data set name prefix from the CA 7 communication data set(UCC7CMDS DD). The suffix BATCHI#n/BATCHO#n is appended to theprefix to construct the full data set names (where n is the associated batchterminal number).

Note: If a specific batch terminal (1-8) is specified and the BATCHIN andBATCHOUT DDs in the BTI JCL are coded, no dynamic allocation occurs.

CA7Specifies the instance of CA 7 used to determine whether submit checkingis turned on. instance can be one of the following values. The default isCA7=CA71.

CA7nSpecifies the true instance name to use where n is a value from 1through 8.

aliasDefines a one- to four-character alias specified at CA 7 resourceinitialization.

PRODDefaults to instance CA71.

UC07Defaults to instance CA71.

TESTDefaults to instance CA72.

UCT7Defaults to instance CA72.

NOMCHKSuppresses BTI output message checking against the SASSXXBTmessage table. If this parameter is not specified and a user-codedSASSXXBT table module is available, the message checking is done. Fora description of the SASSXXBT message table, see the chapter "User Exitsand Modifications" in the Systems Programmer Guide.

NOWAITIf this parameter is specified, BTI terminates with an RC=8 if CA 7 is notactive when the BTI job starts. If this parameter is not specified and theCA 7 address space is not active when the BTI process starts, it issues aWTOR (CA-7.255) and waits for CA 7. When CA 7 becomes active, BTIprocessing continues without any intervention.

If no PARM data is supplied to SASSBSTR, an ID of 0 is used.


Trailer Step Facility


CA 7 trailer steps are special purpose job steps that can be added to any jobto cause the processing of CA 7 commands at strategic points within theprocessing. Jobs executing trailer steps need not be defined to CA 7, but canbe if so desired.

Use the CA 7 trailer step by including an extra step in the job stream. This stepdoes not affect the operational function of the job but causes activity withinCA 7. A CA 7 application is executed that performs the operation requested intrailer step JCL. You can use the trailer step to perform any of the commandsbelonging to the queue maintenance application as defined by SPO0 security.The following is an illustration of trailer step data flow.



You can use the trailer step for special situations. One example is an early postof a data set requirement. Normally, CA 7 does not post data set requirementsfor jobs in the request queue until normal completion of the job that creates thedata sets. This is due to the possibility of a restart that would again create thedata set. A trailer step could be inserted after the step that creates the data set(before other steps of the job) to post requirements for another job in therequest queue that is waiting for that data set creation.

Another example is jobs that cannot run until an online system is down. The jobdependency could be established even though the online system is not a CA 7job. The final step of the online system could post these jobs with a trailer stepto satisfy this requirement.

The /MSG command is also allowed in the trailer step. You can send messagesto logical terminals by this process.

The /WTO command is allowed in the trailer step. You can send messages tothe console operator on the system where CA 7 is running.

The /WLB command is allowed in the trailer step. You can turn workloadbalancing ON or OFF and can adjust certain resources.

Once the trailer terminal is used, it cannot be logged off. This means that a/LOGOFF command is ignored other than to terminate a block of input data asnoted later in this chapter.

To use the trailer step facility, a trailer terminal must be defined in theinitialization file and ICOM must be active on the CPU where the trailer step isto run. Only one trailer terminal can be defined. See 83 for a trailer step JCLsample. A JCL procedure similar to this is provided during installation andshould be used to ease maintenance and release upgrades. Check with yoursystems programmer or your installation's CA 7 specialist for the correctprocedure name.



//CA�7TRLR EXEC PGM=SASSTRLR,PARM=//STEPLIB DD DSN=cai.ca7.caiload,DISP=SHR//SYSOUT DD SYSOUT=A//SYSUDUMP DD SYSOUT=A//SYSIN DD DATA,DLM=##/LOGON operator-IDCA 7 queue posting commands go here/MSG,LT=station,M=message##//

You can specify an optional PARM value on the EXEC statement.

The PARM values have the following format:

��─ ──┬ ┬─────────── ──┬ ┬────────────────── ──┬ ┬─────────────────── ───────��│ │┌ ┐─INACT─ │ │┌ ┐─CA71── └ ┘──,NCFNODE=xxxxxxxx

└ ┘──┼ ┼─────── └ ┘──,CA7= ──┼ ┼──CA7n ─ └ ┘─ACT─── ├ ┤─alias─ ├ ┤─PROD── ├ ┤─UC�7── ├ ┤─TEST── └ ┘─UCT7──

ACT|INACTACT indicates that ICOM must be active or the data is not sent. If ACT isspecified and ICOM is not active, the program issues an error message andends with RC=8. When the parm value of INACT is used, the data is heldin CSA to be processed when ICOM is started. INACT is the default.

CA7Specifies the CA 7 instance name. If omitted, the default is CA71. If used,the value must be ',CA7=xxxx' where xxxx is one of the following:

CA7nwhere n is a value from 1 through 8. This is the true instance name touse.

aliasIs a one- to four-character alias specified at CA 7 resource initialization.

PRODDefaults to instance CA71.

UC07Defaults to instance CA71.

TESTDefaults to instance CA72.

UCT7Defaults to instance CA72.



NCFNODEIndicates the name of an NCF node for routing. If NCFNODE is specified,the CA7= parameter must be CA71.

The following are possible return codes:

0Indicates PARM value supplied.

4Indicates that PARM defaulted to INACT and/or an invalid command wasfound in the input. If an invalid command is found, the following WTO isissued: CA-7.TRLR-10 COMMAND NOT IN SPO0 APPLICATION.

8Indicates an invalid PARM, INACT assumed. Various error conditions,denoted with a WTO that describes the error. For more information aboutthe various WTOs, see the Message Reference Guide.

For more information about SASSTRLR and the /LOGON statement, see theSecurity Reference Guide. For information about the use of SASSTRLR with atest copy of CA 7, see the Systems Programmer Guide.

To prevent command interleaving among multiple tasks on the same CPU andtasks among multiple CPUs, trailer input is blocked with the /LOGON statement.As a result, if many commands are input, it may be necessary to intersperse/LOGON statements to avoid blocking errors. (A /LOGOFF can be used toterminate a block.)

In some situations, it may be necessary to add the DCB parameter to theSYSIN DD statement. The attribute should be BLKSIZE=80.


U7SVC Facility

U7SVC Facility

The CA 7 SVC is used for several different functions. The Batch Card Loadprogram (SASSBCLP) uses the SVC to post to CA 7 the creation of a data set.The trailer program (SASSTRLR) uses the SVC to issue various postingcommands. A program is provided to allow the user flexibility in the use of theSVC. The name of this program is U7SVC and it can be executed as a job stepin batch or called from a user program.

U7SVC allows the user to post to CA 7 that a data set has been created. Thedata set may have been created in a previous step of a job that is runningexternal to CA 7. The created data set need not be fixed blocked with a recordlength of 80, as is the case with BCLP.

The program also allows the user to issue CA 7 batch commands. Allcommands that are authorized for the trailer terminal may also be issued. Thus,the U7SVC program is not limited to queue maintenance commands as is thecase with SASSTRLR.

Note: If the U7SVC program is used to post a data set creation, then the dataset should not be specified by the SASSXDSN exit table, or possible doublepostings (and double triggering) can occur.


U7SVC Facility

Batch Step Execution

The input to U7SVC consists of PARM and/or DD * data. Both are optional, butat least one is required. The ddname for the DD * input data is CA7DATA.Each command must be on one line and cannot be continued. Each entry is aCA 7 batch command or a data set creation statement. (Each entry can beginand end with one or more blanks.)

The format of the PARM consists of an optional instance name and one ormore entries separated by semicolons. Each data record consist of one or moreentries separated by semicolons.

Parameter

By default, U7SVC communicates with instance CA71. To communicate with adifferent instance, place a 'CA7=xxxx;' at the beginning of the PARM= string,using the following format:

┌ ┐─CA71──��─ ──CA7= ──┼ ┼─alias─ ─;────────────────────────────────────────────────��

├ ┤──CA7n ─ ├ ┤─PROD── └ ┘─TEST──

CA71Indicates the default, which maps to what used to be called the "production"copy of CA 7.

aliasIndicates a one- to four-character alias. This alias must correspond to analias assigned to a CA 7 instance during initialization by CAIRIM.

CA7nIndicates an instance where n can be an integer from 2 to 8.

PRODIndicates to map to instance CA71.

TESTIndicates to map to instance CA72.


U7SVC Facility

Syntax

To indicate that the creation of a data set has completed, a statement in thefollowing format is required:

��─ ──D=dsname ─,─ ──┬ ┬──────── ─,─ ──┬ ┬───── ──┬ ┬─────────── ───────────────��└ ┘──vvvvvv └ ┘──xxx └ ┘──,tttttttt

dsnameSpecifies the data set name.

Limits: 1 to 44 alphanumeric characters

vvvvvv(Optional) Indicates a positional parameter specifying the volume serialnumber where the data set was created. Not needed if the data set hasbeen cataloged. If not specified, a comma must be used to denote itsabsence.


xxx(Optional) Indicates a positional parameter specifying the schedule ID to beused for the data set creation. If not specified, a comma must be used todenote its absence.

Default: 1

Limits: 1 to 3 numeric characters from 1 to 255

tttttttt(Optional) Indicates a positional parameter specifying the logical terminal orstation name to be notified of the data set creation.

Default: MASTER


Note: When external security is present, a resource check is made for all dataset creation requests. Since CA 7 treats these requests as if the data set wasreally created, it can cause posting or triggering to occur. Therefore, a securityresource check is made to verify the current user is authorized to create thenamed data set (even though it may not exist.)


U7SVC Facility

Examples

The following are two examples of the use of the U7SVC program. TheCA7SVC procedure is written to a user-specified PROCLIB during the executionof the N020 installation job.

Example 1: This example indicates creation has been completed for data setCA7.TEST with a schedule ID of 50.

// EXEC CA7SVC,PARM='D=CA7.TEST,,5�'

Example 2: This is the same as Example 1 except U7SVC communicateswith instance CA74.

// EXEC CA7SVC,PARM='CA7=CA74;D=CA7.TEST,,5�'

Example 3: This example indicates a logon, demand scheduling of job TEST,posting creation of data set CA7.TEST2, demand scheduling of jobs TEST2and TEST3, and a logoff. All could have been provided in the CA7DATA dataset if so desired. Each could also be provided as a separate record.

// EXEC CA7SVC,PARM='/LOGON MASTER;DEMAND,JOB=TEST'//CA7DATA DD D=CA7.TEST2 ; DEMAND,JOB=TEST2DEMAND,JOB=TEST3 ; /LOGOFF/

Note: When using the U7SVC program for posting GDG data set creations,use the relative GDG number format. The relative GDG number is converted tothe corresponding absolute generation number. For example, if D=A.B(+1) isspecified, it is converted to D=A.B.GnnnnVnn where GnnnnVnn is thecorresponding absolute generation number. The absolute zero generationnumber can also be specified, for example D=A.B.G0000V00. This format is notconverted, but it is recognized as a GDG data set.

If queue maintenance commands (other than D commands) are enteredthrough the U7SVC facility, they must follow the same sequence as if using aCA 7 batch terminal. The command sequence must start with a /LOGON,followed by the desired commands and end with a /LOGOFF.

Note: When external security is being used, a password may be required. Formore details on security interfaces, see the Security Reference Guide.

The U7SVC facility uses the same blocking technique noted for the trailer stepfacility on the Trailer Step JCL Sample on page 83.


U7SVC Facility

Call U7SVC From a User Program

To call U7SVC from a user program, the CA 7 LOADLIB must be available tothe program being executed. A standard parameter list is passed in register 1.One or more commands may be passed for each call.

U7SVC can be called by using the LINK macro. Register 1 must contain theaddress of the parameter list. The parameter list must be on a halfwordboundary where the first 2 bytes are the length of the parameter (commands).These are normal IBM conventions. The format of the command area is thesame as if the EXEC statement had a PARM keyword included with it.

U7SVC can modify the parameter list that is passed to it. If a user program iscalling the U7SVC multiple times during a single execution, then the parameterlist needs to be reinitialized by the user program between calls.

The following is a sample program to call U7SVC.

ZSVCTEST TITLE '-- SAMPLE PROGRAM TO CALL U7SVC'ZSVCTEST START SASSVRSN VRSN=TST, X

REGS=R1�, IDENTIFY BASE REGISTER XLINK=OS, REQUEST OS LINKAGE XEQU=YES REQUEST REGISTER EQUATES

LA R1,PARMA POINT TO PARAMETER ADDRESS LINK EP=U7SVC,ERRET=OOPS

B #UCC7RET RETURN TO CALLEROOPS DS �H

WTO 'U7SVC NOT LINKED'LA R15,16 SET ERROR CODEB #UCC7RET RETURN TO CALLER

PARMA DC A(PARMS)PARMS DC Y(PARML) COMMANDS DC C'CA7=CA7n;' (REQUIRED IF INSTANCE NOT CA71) REMOVE "COMMANDS" TAG FROM NEXT LINE IF PREVIOUS LINE IS NOT COMMENTEDCOMMANDS DC C'/LOGON;DEMANDH,JOB=CA�7TEST;/LOGOFF'PARML EQU -COMMANDS END


Interface with CAICCI


The CA 7 CAICCI interface uses the CA Common Communications Interface(CAICCI) to send batch commands to, and receive command output from theCA 7 address space. The interface can be executed from batch, from a REXXaddress environment, or in a program-to-program mode. Because the interfaceuses CAICCI, there is no requirement for shared DASD between the MVSimages where CA 7 executes and where the CA 7 CAICCI interfaceenvironment executes.

CAICCI is a CA common component that allows CA applications tocommunicate with each other without dealing with the specifics of a particularcommunication protocol. The actual transfer of data may be in the form ofcross-memory, VTAM to VTAM connection, or some form of TCP/IP connection.However, the application code is not dependent on any particular protocol.CAICCI is a sub-component of the CAIENF (Event Notification Facility) commoncomponent.

The CA 7 CAICCI interface establishes communication with the CA 7 CAICCIreceiver in the CA 7 address space. This receiver is created when there areone or more CA 7 CAICCI Terminals (DEVICE=CCI) defined in the CA 7initialization file. For information about the CA 7 initialization file options, seethe Systems Programmer Guide.

The CA 7 CAICCI interface uses the CA 7 batch format for CA 7 commands.The output from these commands is also returned in the CA 7 batch format.For more information about CA 7 batch formats, see “Batch Terminal Interface(BTI)” on page 73.

For information about implementing CAICCI, see the CA Common Services forz/OS Administrator Guide.



Usage Considerations

| ■ In general, the CAICCI terminals should be used for short-running CA 7| commands that do not generate a lot of output. For more information about| command input syntax, see “Command Format and Sequence” on page 74.

■ CAICCI must be active on both the MVS image where the CA 7 addressspace is executing and where the CA 7 CAICCI interface environment isexecuting. There must be a CAICCI connection between these systems.

■ The CA 7 address space must be active.

■ There must be one or more CA 7 CAICCI terminals (DEVICE=CCI) definedand active in the CA 7 address space. Note that if you executelong-running commands, the associated CAICCI terminal is not available forother commands until the first command is complete. You may want to usea Batch Terminal (BTI) for long-running commands such as large forecastsor generic RESOLVes.

■ A valid CA 7 operator ID must either be supplied explicitly in a /LOGONcommand, or the security owner of the environment where the CA 7CAICCI interface is executing must be a valid CA 7 operator.

■ There is no requirement for shared DASD between the MVS image wherethe CA 7 CAICCI interface executes and the image where CA 7 itselfexecutes.

■ There is no requirement that CA7ICOM executes on the MVS image wherethe CA 7 CAICCI interface executes.

■ If no CAICCI terminal is available for two minutes, then the "connection"fails, and an appropriate message is produced.

■ The CA 7 CAICCI receiver name in the CA 7 address space is CA-7. XTMxxxx, where xxxx is the CA 7 instance name, or a value specified on theXTMNAME= keyword of the SVCNO statement in the CA 7 initialization file.



■ Prior to r11, the default values for CA 7 instance names (previously calledssct names) were UC07 for the production copy (alias of PROD) and UCT7for the test copy (alias of TEST). With r11, the default instance name forPROD is CA71, and the default instance name for TEST is CA72. To makethe transition from previous releases smoother, the interface canautomatically search for alternate instance names if the requested instanceis not found. This substitution is made under the following conditions:

– If instance=PROD and CA71 is not found, the search looks for instanceUC07 if the local CA 7 system environment is in release compatibilitymode.

– If instance=TEST and CA72 is not found, the search looks for instanceUCT7 if the local CA 7 system environment is in release compatibilitymode.

– If instance=UC07 and UC07 is not found, the search looks for instanceCA71 if the local CA 7 system environment is not in releasecompatibility mode.

– If instance=UCT7 and UCT7 is not found, the search looks for instanceCA72 if the local CA 7 system environment is not in releasecompatibility mode.

Message CAL2C405I is issued if a different instance is successfullysubstituted.



CA 7 CAICCI Batch Interface Execution

The CA 7 CAICCI Batch Interface program (CAL2X2WB) provides thecapability to send commands to CA 7 and receive the output from thosecommands as a step in a batch job.

The CAL2X2WB program does the following:

■ Reads the commands to be processed from SYSIN and builds a commandblock.

■ Calls the CA 7 CAICCI interface module CAL2X2W0 passing the commandblock.

■ Receives CA 7 command output through CAL2X2W0 and writes each lineto SYSPRINT.

If the user-defined batch error message table module SASSXXBT isavailable, each line of output is compared against entries in the table. Ifmatched, a message is written to the ERRORS DD (if available). Also, thematching table entry return code is saved if it is higher than any previouslysaved return code.



CAL2X2WB JCL

The following JCL can be used to execute the CA 7 CAICCI batch interface:

//jobname JOB (user job parms) //JS1� EXEC PGM=CAL2X2WB,PARM='optional.parms' //STEPLIB DD DISP=SHR,DSN=cai.ca7.caiload//SYSPRINT DD SYSOUT= //ERRORS DD SYSOUT= //SYSIN DD .....

(CA 7 commands go here) ..... //

The optional parameters that can be specified on the EXEC statement are:

PARM='ca 7 cci node,ca 7 instance name,options,cmdin ddname,cmdout ddname,errors ddname'

CA 7 CCI NODESpecifies the CAICCI node name where the CA 7 address space isexecuting. The default is to attempt to communicate with a CA 7 executingat the same CAICCI node where the batch job is executing (local node).

Note: The reserved value *AUTO* can be used to indicate that the CA 7CAICCI interface should attempt to dynamically locate the CAICCI nodewhere a CA 7 with a matching instance name resides.

CA 7 INSTANCE NAMESpecifies the instance name of the CA 7 you want to communicate with.The primary copy of CA 7 (called the production copy in r3.3) has aninstance name of CA71. The secondary copy of CA 7 (called the test copyin r3.3) has an instance name of CA72. Other values include instancenames CA73 through CA78 and a 1-4 character alias if one was set atCA 7 resource initialization. The value PROD can be used instead ofCA71 and the value TEST can be used instead of CA72. For moreinformation about instance names, see “Usage Considerations” on page 91.



OPTIONSSpecifies a one- to four-character option string:

TRACE OPTIONIf set to 'Y' it turns on diagnostic WTOs for the CA 7 CAICCI interfaceprocess. Any value other than a capital Y results in no trace. Thedefault is no trace.

CMD SEPARATORThe character used to separate commands when they are read fromSYSIN and stacked into a command block. The default commandseparator character is a semicolon (;).

-- unused --The third and fourth characters of the options are reserved for futureuse.

CMDIN DDNAMESpecifies the ddname of the source for CA 7 commands. The default isSYSIN.

CMDOUT DDNAMESpecifies the ddname for the CA 7 command output. The default isSYSPRINT.

ERRORS DDNAMESpecifies the ddname for messages produced when a CA 7 commandoutput line matches an entry in the batch error message table, SASSXXBT.The default is ERRORS.

If you do not want error message checking to occur, even when aSASSXXBT table is available, specify *NOMCHK* as the override ddnamein the parameter list.



CAL2X2WB Return Codes

Module CAL2X2WB issues WTO CAL2C509I when processing completes thatlists the return code and condition code for the process. The possible returnand condition codes from CAL2X2WB are as follows:

0Indicates that the CAL2X2WB program was able to successfully completeits functions without detecting an error.

8Indciates a processing error:

CC=1No valid CA 7 commands were read from SYSIN.

CC=2No command output responses were received from CA 7.

CC=8Nonzero return code from CA 7 CAICCI interface module(CAL2X2W0). See message CAL2C596E.

CC=9Error attempting to GETMAIN storage. See message CAL2C594E.

CC=10Error attempting to LOAD a needed module. See messageCAL2C595E.

16Indicates a parameter list error:

CC=1Invalid parameter list. See message CAL2C590E.

CC=2Invalid parameter value. See message CAL2C591E.

CC=3Required DD statement missing or invalid. See message CAL2C592E.

CC=4DCB open error. See message CAL2W593E.

Note: Usage of the SASSXXBT error message table may generate additionalreturn code values. For more information about SASSXXBT, see the SystemsProgrammer Guide.



CA 7 CAICCI REXX Interface Execution

The CA 7 CAICCI REXX interface programs (CAL2X2WA and CAL2X2WR)provide the capability to send commands to CA 7 and receive the output fromthose commands in a REXX environment. Program CAL2X2WA establishes theREXX CA 7 Address environment, and program CAL2X2WR processes thecommand handling.

CA 7 provides a REXX example in the CAICLS0 installation library. The sampleEXEC is CA7REXX:

/ REXX // --------------------------------------------------------------- // // Sample CA 7 REXX to invoke CA 7 CCI REXX Interface to // pass commands to CA 7 and receive back the output from those // commands. // // Syntax : CA7REXX cmda...;cmdb...;cmdc // // Environment Variables : // // ca7_node = CCI Node where CA 7 resides (default= local node) // ca7_ssct = identifies instance of CA 7 to communicate with. // This is the suffix of the CCI receiver name of // the CA 7 instance. // // The default is the CA 7 instance name (CA71-CA78). // However, this value can be overridden using // either of the following keywords on the SVCNO // statement in the CA 7 init file: // // XTMNAME= // RNAME= // // The CCI receiver name is announced at CA 7 // startup with the following message: // // CA-7.XTM� - CCI RECEIVER IS: #NNNNNNNN CA-7 XTM xxxx // // Use the receiver name suffix (xxxx) of the // desired instance as the value of this variable. // // ca7_debug= 4 character string to pass to CA 7 CCI Interface: // char 1 : Y = debug trace (default=N) // char 2 : command separator character (default=;) // char 3 : --- reserved for future use --- // char 4 : --- reserved for future use --- // // NOTE: If you execute this REXX EXEC in a TSO/ISPF // environment, the default separator character (;) may // conflict with the TSO/ISPF command separator. If so, // override the default in the ca7_debug variable to a // different character, such as a pound sign (#). // --------------------------------------------------------------- /



parse UPPER arg commandrslt = cal2x2wa()

/ ca7_node = 'xxxxxxxx' // ca7_ssct = 'CA71' // ca7_debug = 'N; ' /

address CA7 commandsay 'rc =' rcx = queued()say 'queued() =' x do i = 1 to x/ Note that the parse function allows for mixed case /

parse pull lineline2 = substr(line,2) / strip carriage control char /

say line2 end

return

Note: The reserved value *AUTO* can be used for the ca7_node variablevalue to indicate that the CA 7 CCI interface should attempt to dynamicallylocate the CAICCI node where a CA 7 with a matching instance name resides.

The name used to identify the CAICCI receiver for a given copy of CA 7 can beexplicitly set with the XTMNAME= or RNAME= keywords of the SVCNOstatement in the CA 7 initialization file. This allows each copy of CA 7 to beunique across a CAICCI network even though more than one may beproduction or test copies. Assignment of unique CAICCI receiver names allowsthe *AUTO* ca7_node variable to be used to dynamically target a specific copyof CA 7.

For more information about instance names, see “Usage Considerations” onpage 91.



CA-GSS REXX Address Environment Interface Execution

OPS/REXX (the REXX implementation used by CA OPS/MVS) uses CA-GSS toexecute CA 7 commands and return the response lines to the external dataqueue (stack) of the OPS/REXX program that issues the ADDRESS CA7command.

CA 7 provides the following OPS/REXX EXEC in the CAICLS0 installationlibrary. Copy this EXEC to a data set in your SYSEXEC concatenation. Thesample EXEC is CA7OPSRX.

/ -------------------------------------------------------------- // // Sample OPS/REXX exec to invoke CA 7 CCI REXX Interface via // CA-GSS to pass commands to CA 7 and receive back the output // from those commands in the external data queue. // // Syntax : OI CA7OPSRX cmda...;cmdb...;cmdc // // NOTE: If you execute this CLIST in a TSO/ISPF environment // the default separator character (;) may conflict with // the TSO/ISPF command separator. If so, override the // second byte of the CA-GSS GLOBVAL variable &CA7_DEBUG // to a different character, such as a pound sign (#). // // -------------------------------------------------------------- /parse UPPER arg command

address CA7 commandsay 'rc =' rclines = queued()say 'queued() =' linesdo i = 1 to linesparse pull line

say lineend

return

Note: The following statement should be added to the CA-GSS initializationparameters:

ADDRESS CA7 CAL2X2WR 15 TYPE �



Also, the following variables can be customized as needed using the followingCA-GSS initialization parameters:

GLOBVAL &CA7_NODE /xxxxxxxx/ / CCI Node where CA 7 resides (default - local node) /GLOBVAL &CA7_SSCT /xxxx/ / CA 7 instance name (CA71-CA78) /GLOBVAL &CA7_DEBUG /xxxx/ / CA 7 CCI interface options /

Address commands can be established for multiple copies of CA 7 in the sameCA-GSS environment. For each copy, add an ADDRESS statement with aunique 1-4 character name and global variables with the name as the prefix.For example, to establish ADDRESS commands for a primary copy of CA 7,CA7, and a second copy, in this case CA72, add the following CA-GSSinitialization statements.

ADDRESS CA7 CAL2X2W� 15 TYPE � ADDRESS CA72 CAL2X2W� 15 TYPE �

GLOBVAL &CA7_NODE /xxxxxxx/ / Node where primary CA 7 resides / GLOBVAL &CA7_SSCT /xxxx/ / Instance name for primary CA 7 / GLOBVAL &CA7_DEBUG /xxxx/ / Optional Debug options /

GLOBVAL &CA72_NODE /yyyyyyyy/ / Node where second CA 7 resides / GLOBVAL &CA72_SSCT /yyyy/ / Instance name for second CA 7 / GLOBVAL &CA72_DEBUG /yyyy/ / Optional Debug options /

Note: The reserved value *AUTO* can be used to indicate that the CA 7CAICCI interface should attempt to dynamically locate the CAICCI node wherea CA 7 with a matching instance name resides. Because the character string'/*' indicates the start of a comment, you should use a delimiter other than slashif you are going to specify *AUTO*. For example: GLOBVAL &CA7_NODE?*AUTO*?

The name used to identify the CAICCI receiver for a given copy of CA 7 can beexplicitly set with the XTMNAME= or RNAME= keywords of the SVCNOstatement in the CA 7 initialization file. This allows each copy of CA 7 to beunique across a CAICCI network even though more than one may beproduction or test copies. Assignment of unique CAICCI receiver names allowsthe *AUTO* &CA7_NODE variable to be used to dynamically target a specificcopy of CA 7.

For more information about instance names, see “Usage Considerations” onpage 91.



CA 7 CAICCI Program to Program Interface Execution

The CA 7 CAICCI Program-to-Program Interface (CAL2X2WP) can be calleddirectly from another program. The calling program passes a string of CA 7batch commands. CAL2X2WP interfaces with CA 7 and builds a buffer instorage that contains the command responses from CA 7. The calling programcan then parse the responses and take other appropriate actions based on theresults.

Call CAL2X2WP

To invoke the CA 7 CAICCI Program-to-Program Interface, the CA 7 loadlibrary must be available to the program being executed. A standard parameterlist is passed in register 1. The format of the parameter list is:

+ 0Address of the CA 7 batch command string. If there is more than onecommand they must be separated by a command separator character. Thedefault is semicolon (;). This parameter is required.

+ 4Length of the string of CA 7 batch commands. This parameter is required.

+ 8Address of an eight-byte field where the address and length of the CA 7response buffer is placed. The first four bytes will contain the address, andthe second four bytes will contain the length of the buffer. If the callerwants the response buffer to be in storage above the 16 MB line, the firstbyte of the 8-byte field should contain the value X'80'. Otherwise, the bufferstorage is GETMAINed below the 16 MB line. This parameter is required.

IT IS THE CALLER'S RESPONSIBLITY TO FREEMAIN THE RESPONSEBUFFER STORAGE.

+12Pointer to a 64-byte field that contains the CAICCI node name where theCA 7 address space executes. The default is the local node. Thisparameter is optional.

Note: The reserved value *AUTO* can be used to indicate that the CA 7CCI interface should attempt to dynamically locate the CAICCI node wherea CA 7 with a matching CA 7 instance name resides.



+16Pointer to the instance name of the CA 7 to communicate with. The valueCA71 or PROD can be used to indicate the primary instance. The valueCA72 or TEST can be used to indicate the secondary, or "test" instance.Other values include instance names CA73 through CA78 and a 1-4character alias if one was set at CA 7 resource initialization.

For more information about instance names, see “Usage Considerations”on page 91.

Note: The name used to identify the CAICCI receiver for a given copy ofCA 7 can be explicitly set with the XTMNAME= or RNAME= keywords ofthe SVCNO statement in the CA 7 initialization file. This allows each copyof CA 7 to be unique across a CAICCI network even though more thanone may be production or test copies. Assignment of unique CAICCIreceiver names allows the *AUTO* CA-7 CAICCI node parameter to beused to dynamically target a specific copy of CA 7.

+20Pointer to a four-character Options field. The first character indicateswhether diagnostic trace messages are to be generated (value of Y). Thedefault is to not produce trace messages. The second character canspecify the command string separator character. Any non-blank non-nullcharacter can be used as a command separator. The default separator is asemicolon (;). The third and fourth characters are reserved for future use.This parameter is optional.



CAL2X2WP Response Buffer

The response buffer returned by CAL2X2WP contains all of the output linesreceived from CA 7 in response to the command string provided. If noresponses were received from CA 7 because of an error, no response buffer iscreated, and the address/length field supplied by the caller is null. If an errorwas encountered after CAL2X2WP began receiving responses from CA 7, aresponse buffer is still created, and the address and length are set in thecaller's address/length field. IT IS POSSIBLE TO RECEIVE A NONZERORETURN CODE FROM CAL2X2WP AND STILL HAVE A RESPONSEBUFFER.

CA 7 responses in the response buffer are fixed length records. Each record is133 bytes in length. If you wish to calculate the number of lines in the buffer,simply divide the overall length by 133. Each response is blank-padded andbegins with a carriage control character.

It is the caller's responsibility to FREEMAIN the response buffer once it is nolonger needed. The buffer is obtained from subpool 0. If the first byte of thecaller's 8-byte address/length field contains X'80' on entry to CAL2X2WP, theresponse buffer is obtained from storage above the 16 MB line (LOC=ANYGETMAIN option). IT IS THE CALLER'S RESPONSIBLITY TO FREE THERESPONSE BUFFER STORAGE.



CAL2X2WP Return Codes

On exit from module CAL2X2WP, the return code is in register 15, and thecondition code is in register 0. The possible return and condition codes fromCAL2X2WP are:

0Indicates the CAL2X2WP program was able to successfully complete itsfunctions without detecting an error.

4Indicates no responses from CA 7 received.

8Indicates a processing error:

CC=9Error attempting to GETMAIN storage.

CC=10Error attempting to LOAD a needed module.

12Indicates error return from CAL2X2W0 (nonabend)

CC=AL2(CAL2X2W0 rc),AL2(CAL2X2W0 cc)

16Indicates parameter list error:

CC=1Invalid parameter list.

CC=2Invalid parameter value.

20Indicates error return from CAL2X2W0 (abend)

CC=Sxxx or Uxxxx that is the printable abend code.



Sample Invocation of CAL2X2WP

X2WPSAMP START -------------------------------------------------------------------- SAMPLE PROGRAM TO CALL CA 7 CCI PROGRAM-TO-PROGRAM INTERFACE -------------------------------------------------------------------- SASSVRSN VRSN=TST,LINK=OS,REGS=R1�,EQU=YES

LA R1,X2WPPARM R1 -> PARM LISTLINK EP=CAL2X2WP CALL CA 7 CCI PGM-PGM

CLC BUFFADR,=A(�) ANY CA 7 RESPONSES ?BE #UCC7RET NO - EXIT WITH RCL R2,BUFFADR R2 -> RESPONSESL R3,BUFFLEN R3 = BUFFER LENGTHLA R3,�(R2,R3) R3 -> END OF RESPONSES

LOOP DS �HCLC SPO7��,�(R2) GOOD DEMAND RESPONSE ?BE GOOD YES - EXIT LOOPLA R2,133(,R2) R2 -> NEXT LINECR R2,R3 REACHED END ?BL LOOP NO - CYCLEWTO 'X2WPSAMP : JOB DEMAND NOT SUCCESSFUL 'B #UCC7RET BRANCH TO PROGRAM EXIT

GOOD DS �H

WTO 'X2WOSAMP : JOB DEMANDED SUCCESSFULLY 'B #UCC7RET BRANCH TO PROGRAM EXIT

SPO7�� DC CL1�' SPO7-�� ' GOOD DEMAND MSG PREFIX X2WPPARM DS �F CA 7 CCI IFACE PARM LIST

DC A(CMDLIST) ADDRESS OF COMMAND STRINGDC A(CMDLISTL) LENGTH OF COMMAND STRINGDC A(BUFFSET) BUFFER ADDRESS/LENGTH FIELDDC X'8�',AL3(�) END OF PARMLIST

BUFFSET DS �D SPOT FOR BUFFER ADDR/LENGTHBUFFADR DC A(�) ADDR OF CA 7 RESPONSE BUFFERBUFFLEN DC F'�' LENG OF CA 7 RESPONSE BUFFER CMDLIST DC �C DC C'CA7=CA7n;' (REQUIRED IF INSTANCE NOT CA71) DC C'/LOGON USERX;DEMAND,JOB=TESTJOB;/LOGOFF'CMDLISTL EQU (L'CMDLIST) END X2WPSAMP


Batch Card Load Program (BCLP)


The Batch Card Load program (BCLP) loads card-image data to sequentialdata sets required for CA 7 jobs. Through BCLP, sequential data sets may becreated, replaced or modified. When BCLP is executed, CA 7 is notified byICOM of successful data set manipulation through the communications data set.In this way, the database index entries are updated to reflect a new creationdate and time.

Use BCLP

When BCLP is used, CA 7 is notified of successful data set manipulation. CA 7then scans the request queue for jobs that use this data set as an inputrequirement. Jobs triggered by the data set are brought into the request queue.

Multiple data sets may be created, replaced or modified in a single run ofBCLP. These data sets cannot be members of a PDS.

BCLP can also be run as a CA 7 job under CA 7 control. However, it must bemarked as a maintenance job to prevent the posting of SMF records. To markBCLP as a maintenance job, use the DB.1 panel that is defined in theDatabase Maintenance Guide or the #MNT special purpose override statement.For further information about the #MNT statement, see the chapter "JCLManagement" in the Database Maintenance Guide.

If the job is not marked as a maintenance job, then message SMF0-17 isissued (unless suppressed with SASSMSGS) and the type-99 record (DSNcreation) is ignored. This could cause improper scheduling if the data setrequest included the SCHID keyword.

BCLP dynamically allocates space required for each data set. This isaccomplished by spooling card images to a work data set and calculating thenumber of disk tracks required to store the data.

Generation data groups can be handled through BCLP; however, the followingdifferences exist:

■ Since new generation data set catalog maintenance is done at the time ofcreation, relative GDG numbers greater than +1 are not allowed. That is, ifthe user wishes to create three new GDG versions in one run, each mustbe referenced as +1.

■ A model DSCB is not required.

■ An attempt to catalog a generation that has already been dropped results inan error.

If BCLP terminates with an error, the completion code is the hexadecimalequivalent of the error message number. Error messages are listed in theMessage Reference Guide.



Note: BCLP cannot process data sets on SMS managed volumes.

CA 7 Requirements

All data sets created, replaced or modified by BCLP must be defined in theCA 7 database unless REQSAT=NO is used.

To post requirements as available, ICOM must be active. If ICOM is not active,requirements are not posted until ICOM is brought up.

JCL Requirements

PARMs: PARM information about the BCLP execute statement can consist ofone or more of the following parameters. If more than one is entered, they mustbe separated by commas.

CA7=xxxxIndicates which instance of CA 7 BCLP communicates with, where xxxx isone of the following:

■ an instance name from CA71 through CA78

■ a one- to four-character alias specified during CA 7 initialization withCAIRIM

■ PROD, which defaults to CA71

■ TEST, which defaults to CA72

If CA7 is omitted, the default is CA71.

EXITPROG=xxxxxxxxDescribes the name of the user exit routine that is to receive controlimmediately after each statement is read (including the OPTION statement).This exit program name can be overridden on either the OPTION statement(for all other statements), or on a data set request statement (for datastatements pertaining to that data set only). If EXITPROG is omitted,SASSBCX1 is assumed.

ERR=ABORTIndicates that whenever any error is detected, the run should be abortedwith a dump. If this option is not specified, then a dump is not produced.

DD Statements: The following DD statements are required:

SYSPRINTReceives a listing of all statements read and any messages generated.

SYSUDUMPUsed for a dump under certain error conditions.

UCC7IDSSpecifies the index data set. See the DBPARMS DD discussion in theSystems Programmer Guide.



UCC7JLIBSpecifies the job data set. See the DBPARMS DD discussion in theSystems Programmer Guide.

UCC7DLIBSpecifies the dataset data set. See the DBPARMS DD discussion in theSystems Programmer Guide.

DBPARMSUsed to define parameters in the database. See the Systems ProgrammerGuide for a description of this data set. The same values used in theUCC7DBASE statements when the database was last loaded must also beused here to ensure correct access to the database.

UCC7WORKAllocates a work file that is to temporarily contain card images for a dataset. Enough space must be allocated to contain the largest data set to beprocessed.

U7xxxxxxxxOne U7 statement must be present for each volume referred to by the VOLkeyword, or used as a result of a catalog search. xxxxxx should match theVOL=SER of the DD statement. If it does not match, a warning message isgenerated. Volumes are located by VOL=SER, not by ddname.

Note: Only one DD for nonspecific volume allocation is allowed. The namemust be U7VOLSER and it should be the first U7 statement in the JCL.

SYSINSource of input control statements and data.

BCLP JCL: The following is a sample of BCLP JCL with CA7 and EXITPROGPARMs.

//ST1 EXEC PGM=SASSBCLP,PARM=('CA7=CA74,EXITPROG=PX1')//STEPLIB DD DSN=cai.ca7.caiload,DISP=SHR//SYSPRINT DD SYSOUT=A//SYSUDUMP DD SYSOUT=A//UCC7IDS DD DSN=user-defined-index-data-set,DISP=SHR//UCC7JLIB DD DSN=user-defined-job-data-set,DISP=SHR//UCC7DLIB DD DSN=user-defined-dataset-data-set,DISP=SHR//DBPARMS DD DSN=user-defined-location-of-DBPARMS,DISP=SHR//UCC7WORK DD VOL=SER=111111,UNIT=SYSDA,// DISP=(NEW,DELETE),SPACE=(TRK,(1�,1�))//U7VOLSER DD UNIT=SYSDA,SPACE=(TRK,�)//U7111111 DD VOL=SER=111111,UNIT=SYSDA,DISP=SHR//U7222222 DD VOL=SER=222222,UNIT=SYSDA,DISP=SHR//U7333333 DD VOL=SER=333333,UNIT=SYSDA,DISP=SHR//SYSIN DD UCC7 CREATE DSN=A.B.C,VOL=111111statement1 UCC7 REPLACE DSN=X.Y.Z,VOL=222222statement1statement2 UCC7 EODS/



Control Statements for BCLP

Control statements for the Batch Card Load Program must contain an identifier,an operation, and optionally one or more keyword operands. The identifier andoperation fields are separated by one or more blanks. The operation field andthe first keyword parameter are separated by one or more blanks. Keywordoperands are separated by commas.

Following is the format for entering control statement data:

■ Identifier

The identifier is always *UCC7 and must appear in columns 1 through 5 ofeach control statement, including continuation statements.

■ Operation Field

The operation field must be separated from the identifier by one or moreblanks. If multiple statements are used for the same operation, theoperation field must appear on the first statement.

■ Keyword Parameters

The operation field and the first keyword parameter are separated by one ormore blanks. Keyword parameters can appear in any order. For acontinuation, the last keyword on a statement to be continued must befollowed by a comma. The next keyword parameter and its operand (withthe exception of JOBS) must appear on the next statement. On continuationstatements, the identifier (*UCC7) and the first keyword parameter must beseparated by at least one blank.

■ Comments

Comments can be entered in two ways. A comment can be entered beyondthe last keyword of a statement. It must be separated from the keyword andits operand by one or more blanks. If an entire statement is to containcomments, the first character of the comments must be an asterisk (*).Even if the entire statement is to contain a comment, the identifier (*UCC7)must be present.



Examples:

UCC7 operation1 keyword1=x,keyword2=y UCC7 operation2 UCC7 keyword=x, THIS VALUE IS UCC7 REQUIRED ON MONDAYS

UCC7 keyword=y,keyword=z, UCC7 keyword=zz

The possible operation field values are:

OPTION CREATE REPLACE MODDATA EODS

Examples are provided following the keyword formats and options.



OPTION Statement

Use the OPTION statement to set up default parameters for the execution ofBCLP. If the OPTION statement is used, it must be first. If standard defaults aresufficient, you can omit this statement. Options specified in the statement canbe overridden at the data set level.

This statement has the following format:

��── UCC7 OPTION─ ──┬ ┬─────────────────────── ──┬ ┬──────────────────── ───� │ │┌ ┐─MASTER─── │ │┌ ┐─YES─

└ ┘──,LTERM= ──┴ ┴─xxxxxxxx─ └ ┘──,DETLIST= ──┴ ┴─NO──

�─ ──┬ ┬─────────────────── ──┬ ┬─────────────────── ───────────────────────� │ │┌ ┐─NO── │ │┌ ┐─YES─

└ ┘──,VOLROT= ──┴ ┴─YES─ └ ┘──,REQSAT= ──┴ ┴─NO──

�─ ──┬ ┬────────────────────── ──┬ ┬────────────────────────── ─────────────� │ │┌ ┐─312�── │ │┌ ┐─SASSBCX1─

└ ┘──,BLKSIZE= ──┴ ┴─nnnnn─ └ ┘──,EXITPROG= ──┴ ┴─xxxxxxxx─

�─ ──┬ ┬──────────────────── ──┬ ┬────────────────── ───────────────────────� │ │┌ ┐─1�── │ │┌ ┐─1───

└ ┘──,MAXJOBS= ──┴ ┴─nnn─ └ ┘──,SCHID= ──┴ ┴─nnn─

�─ ──┬ ┬──────────────────── ────────────────────────────────────────────�� │ │┌ ┐─SYSRES─

└ ┘──,CVOL= ──┴ ┴─xxxxxx─

LTERM(Optional) When CA 7 has completed updating the database index entriesand input requirement posting, a data set completion message isgenerated. The LTERM keyword designates the logical terminal to receivethe data set completion message. This message is generated when CA 7has updated its database index entries and appropriate requirements areposted as satisfied. This action, and the associated message, are notproduced unless REQSAT=YES was either specified or taken as a default.Also, the message is not produced for data sets that are defined as PERM(permanent) in CA 7. If LTERM is specified, it must match a logical terminalname (STANIDS) in the CA 7 initialization file. If this keyword is omitted,MASTER is assumed.

Default: MASTER

MASTERSpecifies the master terminal is to receive the data set completionmessage.

xxxxxxxxSpecifies the logical terminal name to receive the completion message.




DETLIST(Optional) Specifies whether to produce a detail list of all statementsentered.

Default: YES

YESSpecifies a list of all statements is to be produced.

NOSpecifies only control statements and messages are to be listed.

VOLROT(Optional) Indicates whether, on a specific volume request, an insufficientspace condition results in a search of other volumes for the space.

Default: NO

NOIndicates an insufficient space condition resulting in an error.

YESSpecifies a search of U7xxxxxxxx volumes, in DD statement sequence,is made for sufficient data set space. Rotation begins with the firstvolume and proceeds as if it were a nonspecific request.

REQSAT(Optional) Specifies whether a successful operation on a data set shouldresult in either a requirement being satisfied or a job being triggered.

Default: YES

YESIndicates that CA 7 is notified of the successful operation with atype-99 record generated by BCLP.

NOIndicates that the operation is performed but a type-99 record is notgenerated and CA 7 is not notified.



BLKSIZE(Optional) Designates the block size to be used when creating data sets.

This keyword can also be used to assign a default block size for all datasets or for a single data set.

Default: 3120


3120Specifies the block size of 3120.

nnnnnSpecifies the block size. The block size specified must be divisible by80 and cannot be larger than the track size of the receiving device or32720, whichever is smaller.

EXITPROG(Optional) Designates the name of the user exit routine to receive controlafter each statement is read. This can be done for all statements in the job(specified in the PARM field of the EXEC statement), for all controlstatements (except OPTION) and data statements (specified on theOPTION statement), or only for the data statements of a specific data setrequest. The various options available to the exit program are discussed inthe Systems Programmer Guide.

Default: SASSBCX1


SASSBCX1If EXITPROG keyword is omitted (and is not present in the PARMinformation about the EXEC statement), SASSBCX1 is the default.

xxxxxxxxSpecifies the name of the user exit routine.



MAXJOBS(Optional) Specifies the maximum number of job names to appear in anyJOBS parameter on a data set request statement. If a data set request isencountered that contains more job names than the maximum, the data setrequest is bypassed.

Default: 10


10Specifies ten job names are to appear in JOBS parameter on a dataset request statement.

nnnSpecifies the number of job names to appear in JOBS parameter on adata set request statement.

SCHID(Optional) Specifies which schedule ID created the data set. This can bedone on a data set basis or for the whole job.

Default: 1


1Specifies the default schedule ID to be associated with each data set.

nnnSpecifies the schedule ID to be associated with each data set.

CVOL(Optional) Specifies the volume containing the system catalog to besearched and/or updated. This keyword is required only if a proper indexstructure has not been established for a data set.

Default: SYSRES


SYSRESSpecifies the system resident device as the volume containing thesystem catalog.

xxxxxxSpecifies the volume containing the system catalog.



Data Set Request Statements CREATE, REPLACE, MODDATA

Use the data set request statements to define the operation performed to adata set. A data set statement always immediately precedes the first datastatement for the data set being acted on.

These statements have the following format:

��── UCC7─ ──┬ ┬─CREATE── ──,DSN=xx...xx ──┬ ┬────────────────────── ────────� ├ ┤─REPLACE─ │ │┌ ┐─312�──

└ ┘─MODDATA─ └ ┘──,BLKSIZE= ──┴ ┴─nnnnn─

�─ ──┬ ┬──────────────────── ──┬ ┬──────────────────── ─────────────────────� │ │┌ ┐─NO── │ │┌ ┐─YES─

└ ┘──,CATALOG= ──┴ ┴─YES─ └ ┘──,DETLIST= ──┴ ┴─NO──

�─ ──┬ ┬──────────────── ──┬ ┬───────────────── ──┬ ┬─────────────────── ─────�└ ┘──,JOBS=xxxxxxxx └ ┘──,LTERM=xxxxxxxx │ │┌ ┐─YES─

└ ┘──,REQSAT= ──┴ ┴─NO──

�─ ──┬ ┬────────────────── ──┬ ┬───────────── ──┬ ┬─────────────────── ───────�│ │┌ ┐─1─── └ ┘──,VOL=xxxxxx │ │┌ ┐─YES─└ ┘──,SCHID= ──┴ ┴─xxx─ └ ┘──,VOLROT= ──┴ ┴─NO──

�─ ──┬ ┬──────────────────── ──┬ ┬────────────── ──────────────────────────��└ ┘──,EXITPROG=xxxxxxxx └ ┘──,CVOL=xxxxxx

CREATECreates a new data set. The data set must not already exist on the volume.If the data set is cataloged and the data set still exists on the volumepointed to by the catalog, the VOL keyword must be specified. In this case,CATALOG=YES results in an update of the catalog, but the original dataset is not scratched. If VOLROT=YES is specified and the data set is foundduring volume rotation, an error occurs and the data set request isbypassed.

REPLACEReplaces an existing data set. The data set specified in the DSN keywordmust exist on the volume pointed to by the catalog, or if VOL has beenspecified, on that volume. If VOLROT=YES was specified and there is notenough space on the volume originally containing the data set, anothervolume is assigned and the catalog is updated.

MODDATAAdds data to an existing data set if it exists, or creates a new data set if itdoes not exist. If the data set does exist, the keyword VOLROT has nomeaning. When creating a new data set, the rules described under theCREATE option apply.



DSNDescribes the name of the data set operated on. The name must be a validOS data set name. GDG can be described either by a relative number (+1)or by an absolute generation number. The data set name must be definedin the CA 7 database.


BLKSIZE(Optional) Describes the output block size to be used for this data set. Therules for BLKSIZE are described in the BLKSIZE keyword of the “OPTIONStatement” on page 111.

CATALOG(Optional) Indicates whether the data set is to be cataloged after asuccessful operation.

Default: NO

NOSpecifies that the system catalog is not modified.

YESSpecifies that the data set is to be cataloged.

May also be used to catalog a data set being created, replaced, ormodified.

DETLIST(Optional) Specifies whether a detail list of all statements entered is to beproduced.

Default: YES

YESSpecifies a detail list of all statements entered is to be produced.

NOSpecifies that only control statements and messages are to be listed.

JOBS(Optional) Indicates that a data set request is to occur only if the specifiedjob or jobs have run since the last data set update. A maximum of ten jobscan be entered with this keyword unless MAXJOBS has been entered onthe OPTION statement to increase the maximum number. If more than onejob is entered, the group of job names must be enclosed in parentheses.The JOBS keyword is the only keyword whose operand can be continued. Ifcontinued, the last job name on a statement must be followed by a comma.The next job name can start anywhere on the next statement. The rightparenthesis must appear immediately after the last job name.




LTERM(Optional) Overrides the default logical terminal and follows the rulesdescribed in the LTERM keyword of the “OPTION Statement” on page 111.If present, this keyword overrides the default only for this data set.


REQSAT(Optional) Described in the OPTION statement. If present, it overrides thedefault only for this data set.

SCHID(Optional) Specifies which schedule ID created the data set. It overrides thedefault schedule ID. SCHID is described in the “OPTION Statement” onpage 111.

VOL(Optional) Indicates the volume to be used for this data set. The keywordoverrides the catalog if the data set is cataloged. If a volume is entered itmust be described with a U7xxxxxxxx DD statement. If VOLROT=YES isspecified and there is insufficient space on the volume, another volume ischosen. If VOLROT=NO or is defaulted, an insufficient space conditionresults in an error.

Specific Requests. If VOL is not specified, the system catalog is searchedin an attempt to locate the data set. If the data set is located both in thesystem catalog and on the volume pointed to by the system catalog, thedata set is replaced or added to on the volume. If a data set is not found fora REPLACE, an error has occurred. If a data set is found for a CREATE,an error has occurred. If a data set is found for a MODDATA, data is addedto the data set. If the data set is not found for a MODDATA, the data set iscreated.

Nonspecific Requests. If a CREATE request is encountered or if aMODDATA data set is not found, and the VOL parameter is not present,the data set is assigned to the first U7xxxxxxxx volume. If there isinsufficient space on that volume, an attempt is made to obtain space onsubsequent volumes. Volumes are assigned in the same sequence as theirrespective DD statements in the job stream.

Note: For nonspecific requests, the U7xxxxxxxx JCL statements musthave a volume specified or the first U7xxxxxxxx must be namedU7VOLSER.

VOLROT(Optional) Described in the “OPTION Statement” on page 111. If present,it overrides the default only for this data set.



EXITPROG(Optional) Described in the “OPTION Statement” on page 111. If present,it overrides the default only for this data set request. The user exit programspecified here is used only for data statements and the EODS controlstatement that can optionally follow the data statements.

CVOL(Optional) Described in the “OPTION Statement” on page 111. If present,it overrides the default only for this data set request.

End-of-Data Set (EODS) Statement

Use this statement optionally to indicate end-of-statement input for a data setrequest. If the EODS statement is omitted, an EODS is generated if anothercontrol statement is encountered. If EODS is entered, it must be followed byanother data set request control statement or end-of-file.

This statement has the following format:

��── UCC7 EODS────────────────────────────────────────────────────────��

A null data set is created if no data statements follow the control statement.You can use this to indicate no transaction input is available for today's run of agiven job.



Control Statement Examples

Example 1: Create data set A on volume 111111. The data set is an inputrequirement for JOB Z. The data set is to be cataloged after creation. TheBCLP control statements would appear as follows.

UCC7 CREATE DSN=A,VOL=111111,CATALOG=YES statement1 statement2 UCC7 EODS

Note: Since the default of REQSAT is YES, the keyword is not required.

All keywords not entered will default.

The EODS statement is optional.

Volume 111111 must be defined by a U7xxxxxxxx DD statement.

Example 2: Same as Example 1, with the addition that JOB Z must have runsince the last creation (see the JOBS description for restrictions discussedearlier in this chapter).

UCC7 CREATE DSN=A,VOL=111111,CATALOG=YES, UCC7 JOBS=Z statement1 statement2 UCC7 EODS

Example 3: Replace cataloged data set A.

UCC7 REPLACE DSN=A statement3 statement4 statement5

Note: Since the data set was cataloged, VOL and CATALOG are not required.

An EODS statement is generated.

The volume on which the data set is cataloged must be defined by aU7xxxxxxxx DD statement.



Example 4: Add data to the end of a cataloged data set B. JOBS X, Y, and Zmust have run since the last update of data set B (see the JOBS description forrestrictions discussed earlier in this chapter).

UCC7 MODDATA DSN=B,JOBS=(X,Y,Z) statement M statement N . . . . statement Z UCC7 EODS

Note: If data set B does not exist on the volume, the MODDATA is changed toCREATE.

The volume on which the data set does (or will) exist must be defined by aU7xxxxxxxx DD statement.

Example 5: Replace data set C. Data set C is not presently cataloged, but isto be cataloged after this run.

UCC7 REPLACE DSN=C,VOL=111111,CATALOG=YES statement A statement B statement C

Note: Volume 111111 must be defined with a U7xxxxxxxx DD statement.


Chapter 4. CA Driver Procedures,Variable Parameters, and Functions


Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123JCL Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Procedure Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Conditional Procedure Expansion . . . . . . . . . . . . . . . . . . . . . . . 153Comments Inside CA Driver Procedures . . . . . . . . . . . . . . . . . . . 161Use CA Driver in the CA 7 Environment -- Some Examples . . . . . . . . 162

This section describes how to store JCL, variables, and data in the CA Driverprocedure library, and how to use CA Driver to:

■ Nest procedures

■ Insert data at a predetermined point in a procedure

■ Use variable parameters in procedures and supply values when theprocedures are retrieved

■ Use CA Driver functions

■ Conditionally expand procedures based on logic or variables in theprocedure.

CA Driver is activated when the //CARPROC DD statement is added to theCA 7 execution JCL. CA 7 calls CA Driver for each statement in a job at thejob's submission time. For CPU jobs, CA Driver scans the JCL statementslooking for either of the following control statements embedded in the jobstream.

// EXEC procname

or

// EXEC PROC=procname

For XPJOB jobs, CA 7 scans the parameters looking for DPROC=name andchanges this into a statement recognizable by CA Driver.

Chapter 4. CA Driver Procedures, Variable Parameters, and Functions 121

When one statement is encountered, CA Driver searches all allocated CADriver procedure libraries looking for a matching procname (procedure name). Ifthat procedure name is found in a procedure library, CA Driver expands theprocedure and passes back a set of expanded statements to the job streamone statement at a time instead of passing back the // EXEC procname or //EXEC PROC=procname or DPROC= statement. If the procedure name is NOTfound in a CA Driver procedure library, the statement is passed back to the jobstream unchanged. Thus, CA Driver procedure calls can be embeddedanywhere in the job stream. If the DPROC= statement is returned for anXPJOB job, this produces a JCL error status for the job, forcing it back to therequest queue.

The allocation of CA Driver procedure libraries is normally determined by theCARPROC DD statement. However, this allocation can be altered in anydefined CA 7 JCL or PARM library. If the definition of the CA 7 JCL or PARMlibrary includes a reference to a CA Driver procedure library, that procedurelibrary is searched prior to the libraries in the CARPROC concatenation whenCA Driver is invoked for statements from that library. For more informationabout associating a CA Driver procedure library with a CA 7 JCL or PARMlibrary, see the discussion of the DPROC keyword on the JCL initialization filestatement in the Systems Programmer Guide or the discussion of the DPROCkeyword on the /JCL command in the Command Reference Guide.


Usage Notes

Usage Notes

■ Because the JCL or PARM data is modified by CA Driver at job submission,these changes are not reflected in the job's queue JCL.

■ If the SASSXX02, SASSXX20, or SASSXX21 user exit is being used, theexit receives the statements after they have been manipulated by CADriver. If the user exit inserts or modifies statements, the changedstatements are not inspected by CA Driver.

■ If the SASSXX05 user exit is being used, it receives the statements as thejob enters the queues (prior to submission). Therefore, any statementsinserted or changed are available to CA Driver.

■ All scheduled overrides (such as #JI and #XO) are applied prior to CADriver invocation.

■ The JOB statement cannot be in a CA Driver PROC.

■ For XPJOB job types, the CA Driver invocation is started with the DPROC=keyword. The Driver procedure must use the same first statement (//nameDPROC variables), but then include PARMnn keywords that will be insertedin the data transmitted to the destination scheduling agent. All referencesto CA Driver specific statements are coded as if they would be used in aCPU job. For example, the // DNEST procname would be used to callanother CA Driver procedure.

■ Although XPJOB job data is case sensitive, all CA Driver keywords must bespecified in uppercase only.

■ For XPJOB jobs, an alternative to CA Driver Procedures would be to usethe Global Variable features, which allow variable substitution directly intothe parameter data.


JCL Verification

JCL Verification

The CA 7 interface with CA Driver is invoked at job submission time. It is alsoinvoked when the LJCK command is issued, and for CPU jobs, when certainCA 7 editor subcommands are used (any JCLxx command). Default CA 7variable values vary depending on the command environment. For example, thevalue of &C_L2JN will be the job name defined in the CA 7 database ifevaluated in LJCK processing. If CA Driver is invoked using the JCLL editorsubcommand for a CPU job, the value of &C_L2JN is the character stringUNKNOWN because the job name is unavailable when the command isentered. Use these commands to verify that CA Driver is modifying thestatements appropriately. For information about the LJCK command, see theCommand Reference Guide. You can find details on the use of JCLL and otherCA 7 editor subcommands in the "Edit Facility" chapter of the DatabaseMaintenance Guide.


Procedure Library

Procedure Library

The CA Driver procedure library is a standard OS partitioned data set.Therefore, you can use ISPF or any other editor for all library maintenance.

Create Procedures

To create a procedure in the CA Driver procedure library, place a DPROCstatement as the first statement in the procedure. The contents of theprocedure consist of all the statements following the DPROC statement. Whena procedure is called (retrieved from the library), CA Driver replaces the callingstatement with the contents of the procedure.

Give the name of the procedure immediately following the slashes on theDPROC statement. This name must be one to eight alphanumeric characters,beginning with an alpha or national character.

//procname DPROC

Use ISPF or any other editor to code procedures.

Call Procedures

For CPU jobs to retrieve a procedure from the CA Driver procedure library, usea standard OS EXEC statement and specify the name of the procedure afterPROC=.

//stepname EXEC PROC=procname

-- or specify --

//stepname EXEC procname

For XPJOB jobs, to retrieve a procedure, use the keyword DPROC:

DPROC=procname

This sample job stream calls the LVTOC procedure.

//LIST JOB ,JOHN.DOE,CLASS=A//LIST1 EXEC PQM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD //CALL EXEC PROC=LVTOC//


Procedure Library

CA Driver replaces the EXEC statement with the contents of the procedure andsubmits this expanded job stream to JES for execution.

//LIST JOB ,JOHN.DOS,CLASS=A//LIST1 EXEC PGM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD LISTVTOC VOL=339�=VSIAUX,FORMAT//

Note the following about this expansion process:

■ Any EXEC statements that are part of the contents of a procedure areincluded in the expanded job stream that is submitted to JES.

■ For CPU jobs, if there is no member of the CA Driver procedure library bythe name specified on the EXEC statement, the search passes to the OSprocedure library. (This is what would happen if the EXEC statementmisspelled LVTOC as LVTIC.)

■ If CA Driver detects any error conditions during its expansion, a DERRstatement with an appropriate error message passes to JES. This is thenflagged as an invalid statement by JES and displayed on the SYSLOGlisting.

■ For XPJOB jobs, if there is no member of the CA Driver procedure libraryby the name specified, the DPROC keyword is returned and the XPJOB willfail with a JCL error. Because you cannot correct errors to the output datastream, use the command LJCK to resolve any errors before allowing theXPJOB job to execute in a production stream.

Nest Procedures

One procedure can call another procedure, which can, in turn, call otherprocedures. Each time a procedure calls another procedure, this is counted asa nesting level. When the first procedure is retrieved, any procedures nested init are also retrieved.

You can use procedure nesting to store commonly used pieces of JCL and data(especially data tables) as separate procedures. These procedures can then beretrieved, as needed, by nesting them in other procedures. If one of theseseparate procedures needs modification, you only need to make the changes tothat one procedure. When the procedure is called by another procedure, theupdated version is automatically retrieved; so the expanded job stream reflectsall changes.

Use a DNEST statement to introduce each nested procedure.

// DNEST procname


Procedure Library

This sample shows both the LVTOC procedure and the LVTOCS procedurethat is nested in the LVTOC procedure.

//LVTOC DPROC//LIST1 EXEC PGM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD // DNEST LVTOCS

//LVTOCS DPROC LISTVTOC VOL=339�=VSIAUX,FORMAT

When the LVTOC procedure is retrieved, it calls the LVTOCS procedure that isnested in it. Therefore, this sample job stream calls both procedures.

//LIST JOB ,JOHN.DOS,CLASS=A//CALL EXEC PROC=LVTOC//

The EXEC statement is replaced by the contents of both procedures and thisjob stream is submitted to JES for execution.

//LIST JOB ,JOHN.DOE,CLASS=A//LIST1 EXEC PGM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD LISTVTOC VOL=339�=VSIAUX,FORMAT//

Include Data

You can design a procedure to:

■ Stop expansion at predefined points,

■ Read one or more records from the job stream,

■ Continue expansion of the procedure from the stopping point.


Procedure Library

This is useful for job streams that process data that change each time the job isrun and for those jobs that read such data as a date card.

To use this facility, insert a DATA statement in the procedure at the point atwhich you want expansion to stop.

// DATA

CA Driver will replace the DATA statement with the statements that follow theEXEC statement in the input job stream. When CA Driver reaches a DENDstatement, it returns to the procedure and continues expansion.

For example, we could have designed procedure LVTOC so that the LISTVTOCstatement is submitted from the job stream rather than from within theprocedure itself. Instead of including LISTVTOC in the procedure, we use theDATA statement at the same point.

//LVTOC DPROC//LIST1 EXEC PGM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD // DATA

Then we include the LISTVTOC statement on the input job stream followed bya DEND statement.

//LIST JOB ,JOHN.DOE,CLASS=A//CALL EXEC PROC=LVTOC LISTVTOC VOL=339�=VSIAUX,FORMAT// DEND//

When the procedure is expanded, the LISTVTOC statement replaces the DATAstatement.

You can use any number of DATA statements in a procedure. Each DATAstatement directs CA Driver back to the job stream until a DEND statement isfound. Therefore, if a job procedure contains three DATA statements, the jobstream submitted for processing must contain three DEND statements. Variableparameters must be within the DPROC and cannot be within the statementsthat the DATA and DEND include.


Procedure Library

Verify Data Inclusion

To ensure that the correct data is inserted into the expanded procedure at theappropriate places, you can use a verification name on each DATA statementand the same name on the DEND statement that terminates that data.

// DATA LVTOCX

// DEND LVTOCX

If the name on the DATA statement and the name on the DEND statement arenot the same, CA Driver flags the condition as an error. The verification namemust be one- to eight-alphanumeric characters, beginning with an alphacharacter, and does not have to relate to the name of the procedure.

This example shows the same procedure with a data verification name.

//LVTOC DPROC//LIST1 EXEC PGM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER,VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD // DATA LVTOCX

The same verification name is coded on the DEND statement that signals theend of the data inclusion statements.

//LIST JOB ,JOHN.DOE,CLASS=A//CALL EXEC PROC=LVTOC LISTVTOC VOL=339�=VSIAUX,FORMAT// DEND LVTOCX//


Variable Parameters

Variable Parameters

A procedure in the CA Driver library can contain up to 64 symbolic parameters.A default value can be defined for each parameter when the procedure iscreated. When the procedure is expanded, each parameter is replaced by itsdefault value or by a value on the EXEC or DPROC statement that calls theprocedure. (If no default value is defined, a value must be supplied on theEXEC or DPROC statement or on a DSET statement.)

To use these symbolic parameters, list them on the //DPROC statement whenthe procedure is created, with or without a default value. (For specific codingrequirements, see “Code Variable Parameters” on page 132.)

//procname DPROC parmname=value,parmname=value,...

Then precede them with an ampersand (&) whenever they are referenced in thebody of the procedure. When the procedure is expanded, CA Driver replaceseach occurrence of the parameter with:

■ The value supplied on the EXEC or DPROC statement or on a DSETstatement.

■ The default value if no value is supplied on the EXEC or DPROC statement.

This example shows the LVTOC procedure with two parameters, each with adefault value.

//LVTOC DPROC VOL=339�,ID=VSIAUX//LIST1 EXEC PGM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD DD LISTVTOC VOL=&VOL=&ID,FORMAT

If this procedure is called with no supplied values:

//CALL EXEC PROC=LVTOC


Variable Parameters

It is expanded with the default values inserted in the body of the procedure inplace of &VOL and &ID.

//LIST1 EXEC PGM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD LISTVTOC VOL=339�=VSIAUX,FORMAT//

If this procedure is called with a value for the VOL parameter only:

//CALL EXEC PROC=LVTOC,VOL=338�

It is expanded with this value replacing &VOL and the default value replacing&ID.

//LIST1 EXEC PGM=IEHLIST//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR//SYSPRINT DD SYSOUT=V//SYSIN DD LISTVTOC VOL=338�=VSIAUX,FORMAT//


Variable Parameters

Code Variable Parameters

Up to 64 variable parameters can be defined for each procedure. Eachparameter must be named on the //DPROC statement when the procedure isdefined. The name must be from one to seven alphanumeric characters(A-Z,0-9), beginning with an alphabetic character. The underscore character (_)is also acceptable except in the first character position. However, werecommend that you do not use the underscore character in a variable namedefined on the //DPROC statement so that you avoid conflicts withreserved-name variable parameters.

Define Default Values

A default value of up to 64 characters can be optionally defined for eachparameter:

■ If the value contains any blanks or special characters, it must be enclosedin quotes or other special character delimiters like apostrophes or slashes.(The following cannot be delimiters: spaces, commas, periods, ampersands,plus or minus signs.)

■ If the value contains only alphanumeric characters, delimiters are optional.

Examples:

//LVTOC DPROC VAR1=YES//LVTOC DRPOC VAR2='A B C'//LVTOC DPROC VAR3=/JOHN'S///LVTOC DPROC VAR4=

In the first example, the default value for VAR1 is YES. Since this consists onlyof alphanumeric characters, no quotes or other delimiters are needed. In thesecond example, VAR2 has a default value of A B C. Since this containsspaces, it must be enclosed in quotes or other delimiters. In the third example,the default value for VAR3 is JOHN'S. Since this character string contains aquote, a special character other than a quote must be used as a delimiter. Inthis example, a slash (/) is used. In the fourth example, no default value isdefined.


Variable Parameters

Supply Values On The EXEC Statement

If no default value is defined on the procedure, a value for the parameter mustbe given on the calling EXEC or DPROC statement. (If values are given in bothplaces, the value on the EXEC or DPROC statement overrides the defineddefault value.)

Values supplied on the calling EXEC or DPROC statement are coded the sameway as default values:

■ If the value contains other than alphanumeric characters, delimiters arerequired.

■ If the value contains only alphanumeric characters, delimiters are optional.

Examples:

//CALL EXEC PROC=LVTOC,VAR1=NO//CALL EXEC PROC=LVTOC,VAR2='D E F'//CALL EXEC PROC=LVTOC,VAR3=/MARY'S///CALL EXEC PROC=LVTOC,VAR4='REPLACEMENT VALUE'DPROC=LVTOC,VAR5='NEW PARM DATA FOR XPJOB ONLY'

Multiple variable parameters can be listed one after the other, separated bycommas.

For CPU jobs to continue an EXEC statement to the next line, end the first linewith a completed parameter, including the separation comma. Code the secondline with slashes in columns 1 and 2, and the additional parameters beginningin column 16 or before.

For XPJOB jobs to continue the statement with additional variables, end thefirst line with a completed parameter, including the separation comma. Code thesecond line with the variable name starting in column 1. Note, the line beingcontinued does not need to have a plus (+) sign on the end. If you desire to puta plus sign, leave at least one space between the command and the plus (+)sign.

Examples:

//CALL EXEC PROC=LVTOC,VAR1=NO,VAR2='D E F',VAR3=/MARY'S/

//CALL EXEC PROC=LVTOC,VAR1=NO,VAR2='D E F',VAR3=/MARY'S/,// VAR4='REPLACEMENT VALUE'

DPROC=LVTOC,VAR1=XPJOB,VAR2='has a different syntax',VAR3='BUT DPROCs will still work'


Variable Parameters

All variable parameters must be given a value before they are used. If a valueis not specified on the DPROC or EXEC statements, it can be specified on theDSET statement. You can test for an omitted variable value with the Type testof the DIF statement.

// DIF T'VAR1 NE O GOTO VAR1OK// DSET VAR1=DEFAULT//VAR1OK DSTEP

Reference Variable Parameters in the Procedure

An ampersand must precede the variable parameter wherever it is coded in thebody of the procedure. (Never use an ampersand on the DPROC or EXECstatements.) It is the ampersand that signals CA Driver to replace the variableparameter with a value. For example, assume the default value FILE has beendefined for the variable parameter VAR1.

This statement in the procedure will be expanded as:

//&VAR1 DD DSN=DATA.SET //FILE DD DSN=DATA.SET//SYSUT1 DD DSN=DATA.&VAR1 //SYSUT1 DD DSN=DATA.FILE

If the variable parameter is followed immediately by an alphanumeric character,it must be terminated by a period in the procedure. If the variable parameter isto be followed by a period after replacement, it must appear in the procedurefollowed by two periods. For example:

This statement in the procedure will be expanded as:

//SYSUT1 DD DSN=&VAR1.DATA //SYSUT1 DD DSN=FILEDATA//SYSUT1 DD DSN=&VAR1..DATA //SYSUT1 DD DSN=FILE.DATA

A variable parameter is NOT preceded by an ampersand when it is the objectof a DSET statement (that is, a value is being assigned to it), or the FIRSTobject of a DIF statement.

// DSET VAR1=&VAR2 will assign VAR1 the contents of VAR2// DSET VAR1=VAR2 will assign VAR1 the string 'VAR2'// DIF VAR1 EQ &VAR2 GOTO STEP will compare the contents of VAR1 and VAR2// DIF VAR1 EQ VAR2 GOTO STEP will compare the contents of VAR1

with the string 'VAR2'


Variable Parameters

Use Variable Parameters In Nested Procedures

Variable parameters can be passed from a calling procedure to a nestedprocedure. To do this, the variable parameter must be defined in eachprocedure using either the same parameter name or different parameter names.For example, a nested procedure being passed a parameter from a callingprocedure could be created as:

//LVTOC DPROC VAR1=YES . . .// DNEST LVTOCS,VAR2=&VAR1//LVTOCS DPROC VAR2=

The calling procedure defines VAR1, and the nested procedure defines VAR2.


Variable Parameters

Shift During Expansion

During variable parameter substitution, the substitution character string can beshorter or longer than the parameter name. CA Driver shifts the character stringduring procedure expansion according to these guidelines:

■ If the replacement character string is shorter than the variable parameter(including the ampersand and concatenation character, if present), thecharacter string will be shifted left the number of bytes that the replacementcharacter string is shorter than the variable parameter. This shift willcontinue until a string of two or more spaces is encountered, at which pointthe shift will terminate. As a result, these spaces will be increased by thenumber of bytes that the variable parameter exceeds the replacementcharacter string.

■ If the replacement character string is longer than the variable parameter, allfollowing bytes will be shifted right by the number of bytes that thereplacement character string is longer than the variable parameter. Thisshift will continue until a string of spaces long enough to contain the numberof characters shifted, plus one blank, is encountered at the end of thestatement. If such a string of spaces is not available, an error message willbe issued and the procedure expansion will terminate. Two or morecharacter strings can also be shifted right if the number of spaces betweenthem is sufficient to contain the number of characters shifted and still leaveone space.

In these examples, the variable parameter &F has a replacement value of FILEand &DATASET has a replacement value of DSN.

Original stmt: //&F DD DSN=PAYROLL.MASTER COMMENTExpanded stmt: //FILE DD DSN=PAYROLL.MASTER COMMENTOriginal stmt: //INP DD DSN=&DATASET..XYZ COMMENTExpanded stmt: //INP DD DSN=DSN.XYZ COMMENTOriginal stmt: //INP DD DSN=MASTER.&F..INPUT COMMENTExpanded stmt: //INP DD DSN=MASTER.FILE.INPUT COMMENT

Note: We do not recommend the use of sequence numbers or extraneousdata such as comments on lines containing variables in CA Driver DPROCs.Shifting during DPROC expansion may produce undesirable results.


Variable Parameters

Reserved-Name Variable Parameters

CA Driver provides a set of reserved-name variable parameters that you canreference anywhere that a variable parameter can be referenced in a CA Driverprocedure. Values are automatically assigned by CA Driver when thereserved-name variable parameter is referenced during procedure expansion.These reserved-name variable parameters cannot be defined in a DPROCstatement, and assigned values cannot be changed using the DSET statement.All reserved-name variable parameters begin with &C_ to avoid conflicts withvariable names defined on the DPROC statement.

CA Driver Reserved-Name Variable Parameters

The following are the reserved-name variable parameters that CA Driver offers:

&C_DATEIndicates the current system date in mm/dd/yy format.

&C_DAYIndicates the current day of the week (MONDAY, TUESDAY, ...).

&C_JDATEIndicates the current system Julian date in yyddd format.

&C_L2CA7Indicates the CA 7 instance name.

&C_L2SMFIndicates the SMF ID of the LPAR where CA 7 is executing.

&C_L27RLIndicates the CA 7 release.

&C_MONTHIndicates the current month name (JANUARY, FEBRUARY, ...).

&C_TIMEIndicates the current system time in hhmmss format.

Example

This example procedure uses four of the CA Driver reserved-name variableparameters.

//TIMER DPROC// IT IS &C_TIME ON &C_DAY IN &C_MONTH AND THE DATE IS &C_DATE


Variable Parameters

The procedure would be retrieved with the following statement:

//CALL EXEC PROC=TIMER

and would be expanded like this.

// IT IS 1�3545 ON MONDAY IN APRIL AND THE DATE IS �4/�5/�7

Information for a specific run of a CA 7 scheduled job can be referencedthrough the use of the following variables:

&C_L2JNIndicates the name of CA 7 scheduled job.

&C_L2UIDIndicates the UID of CA 7 scheduled job.

&C_L2MIDIndicates the MAINID value for CA 7 scheduled job. This variable is notapplicable to XPJOB jobs.

&C_L2SNIndicates the SYSTEM name of CA 7 scheduled job.

&C_L2QNIndicates the name of queue where CA 7 scheduled job resides.Value is REQUEST on LJCK displays.

&C_L27#Indicates the CA 7 job number for CA 7 scheduled job.Value is 00001 on LJCK displays.

&C_L2LTIndicates the LTERM value for CA 7 scheduled job. Value is the job nameon LJCL displays.

&C_L2ROIndicates the RO value for job level COND-CODE test.

&C_L2CCIndicates the value for job level COND-CODE test.

&C_L2PRYIndicates the PRIORITY value for CA 7 scheduled job as defined on thejob definition panel.

&C_L2CLSIndicates the CLASS value for CA 7 scheduled job as defined on the jobdefinition panel.

&C_L2SIDIndicates the SCHEDULE-ID value for CA 7 scheduled job.Value supplied from SCHID keyword on LJCK displays.


Variable Parameters

&C_L2#T1Indicates the number of TAPE1 tape drives for CA 7 scheduled job asdefined on the job definition panel. This variable is not applicable to XPJOBjobs.

&C_L2#T2Indicates the number of TAPE2 tape drives for CA 7 scheduled job asdefined on the job definition panel. This variable is not applicable to XPJOBjobs.

&C_L2EMIndicates the entry mode for CA 7 scheduled job, such as DEMAND orRUN. Value is SSCAN on LJCK displays.

&C_L2DODIndicates the due-out date for CA 7 scheduled job (YYDDD).

&C_L2DOTIndicates the due-out time for CA 7 scheduled job (HHMM).

&C_L2DLDIndicates the deadline date for CA 7 scheduled job (YYDDD).

&C_L2DLTIndicates the deadline time for CA 7 scheduled job (HHMM).

Note: All values for the CA 7 reserved-name variables are derived fromJQREC for the CA 7 submitted job, unless CA Driver is invoked from LJCK inwhich case some values are determined from database information.

Example: This example illustrates the use of CA 7 reserved-name variableparameters.

//COMMENTS DPROC// &C_L2JN was scheduled via &C_L2EM and was assigned the following// CA 7 job number: &C_L27#. Thank you for your support.

The procedure would be retrieved using the following statement:

//STEP EXEC PROC=COMMENTS

If job ABC123 was demanded and received a CA 7 job number of 02233 andused the JCL mentioned above, the following expansion would result:

// ABC123 was scheduled via DEMAND and was assigned the following// CA 7 job number: �2233. Thank you for your support.


Variable Parameters

Substrings

You can reference part of the value given to a variable parameter instead of theentire value. To do this, specify two numbers in parentheses following theparameter name.

&parmname(n,m)

nIs the location within the value of the start of the substring.

mIs the length of the substring (one or more bytes).

These examples show how the two numbers identify the substring that is beingreferenced.

Substrings can also be identified by variable parameters that representnumbers. This is illustrated below.

Parameter Value Substring Reference Substring Value

&VAR1 HOWDY &VAR1(1,2) HO

&VAR1 89 &VAR1(2,1) 9

Parameter Value Substring Reference Substring Value

&VAR2 4

&VAR3 2

&VAR4 12/31/07 &VAR4(&VAR2,&VAR3) 31


Variable Parameters

These sample control statements show how procedure expansion can be basedon the contents of a substring, rather than on the entire parameter value:

This control statement References a substring to

// DIF C_DATE(1,2) NE 01 GOTOMONTHERR

Test only the month portion of thedate value (1st and 2nd positions)

// DIF C_DATE(3,1) NE '/' GOTOERROR

Check for a slash in the date (3rdposition)

// DSET VAR1=&C_DATE(7,2) Set VAR1 equal to year portion ofdate value (7th and 8th positions)

// DIF VAR1(&VAR2,&VAR3) EQ 9GOTO OK1

Test only part of VAR1 (VAR2 andVAR3 represent numbers)


Variable Parameters

Arrays

A variable parameter can be assigned multiple values or array elements. Toindicate that a parameter has an array of values, give the total number ofvalues in parentheses following the parameter name on the DPROC statement.For example, VAR(4) indicates that a parameter has four values. When thisprocedure is expanded, each of these four values can be individuallyreferenced as:

&VAR(1)

&VAR(2)

&VAR(3)

&VAR(4)

To define default values for any of these elements, specify the values inparentheses separated by commas in the order of the array elements. To omita default value, code a comma instead of the value.

//NAME DPROC X(1�),Y(3)=(A,B,C),Z(5)=(,,TESTJOB)

This example defines:

■ A parameter named X, which consists of ten elements in an array, none ofwhich have default values.

■ A parameter named Y, which consists of three elements in an array, eachof which has a default value:

&Y(1) = A

&Y(2) = B

&Y(3) = C

■ A parameter named Z, which consists of five elements in an array, only thethird of which has a default value (TESTJOB).

To supply array values on the calling EXEC statement, list the values, enclosedin parentheses and separated with commas. To omit a value, code a comma inplace of the value.

//CALL EXEC PROC=LVTOC,VAR=(A,B,,D,,F)

This statement retrieves the LVTOC procedure and supplies override values forthe first, second, fourth, and sixth array elements of the VAR parameter. Thethird and fifth elements would retain their default values. (These default valuesmust be defined when the procedure is created.)


Variable Parameters

Null Values

You must supply a value for every variable parameter listed on the DPROCstatement or else the procedure cannot be expanded. However, this value canbe a null value. A null value can be used either as the default value when theprocedure is created or as the override value when the procedure is called. Tospecify a null value on either the DPROC or EXEC statement, code twodelimiters with nothing in between.

//CALL EXEC PROC=LVTOC,Y=(1,2,'',4)

This example supplies override values for array elements one through four ofthe Y parameter. The value for the third element is a null value. (If the defaultvalue were really supposed to be two apostrophes, you could use slashes asthe delimiters: /''/). If &Y(3) is referenced in the procedure, it will be replacedwith nothing; in other words, the statement will be expanded as though theparameter reference were not there.

The same thing would happen if the default value is a null value and nooverride is supplied. For example, assume that the parameter Y was definedwith a null default value. No override value is supplied when the procedure iscalled. When the procedure is expanded, each occurrence of Y is replaced witha null character string; therefore, Y is effectively removed from the expandedstatement as these examples show.

This statement in the procedure: will be expanded like this:

//SYSUT1 DD DSN=&Y.FILE.DATA //SYSUT1 DD DSN=FILE.DATA//SYSUT1 DD DSN=FILE&Y //SYSUT1 DD DSN=FILE

A null value is different from having no value associated with a variableparameter. If a parameter has no default or override value, an error message isissued indicating that the procedure cannot be expanded.


Variable Parameters

Attributes of Variables

Every variable parameter has two attributes: type and length. Variableparameter arrays also have a third attribute: number. Each of these attributescan be tested during conditional expansion using the following format:

To test for Specify

Type T'parmname

Length L'parmname

Number N'parmname

The Type Attribute

Variable parameters (or parameter array elements) fall into one of fourcategories, depending on the type of value that replaces them when theprocedure is expanded. (The type is determined by the actual replacementvalue, not by the defined value or how the value was stated.)

If the replacement value is The type is

A character format C

A positive integer N

A negative integer M

Omitted (not the same as a null value) O

Test the Type Attribute

To test a variable parameter for type, prefix it with T'.

// DIF T'VAR1 EQ C GOTO CHARVALU// DIF T'VAR2 EQ N GOTO ISNUMERC

Since variable parameters that are used in array indexing and segmentsubscripting must be positive integers (type N), it is a good idea to test the typeattribute of a variable parameter before using it for such a purpose.


Variable Parameters

The Length Attribute

The length attribute of a variable parameter (or an array element) is the numberof bytes in the replacement value.

If the replacement value is The length is

CA Driver 9

X 1

0049 4

(null) 0

27 2

Test the Length Attribute

To test a variable parameter for length, prefix it with L'.

// DIF L'VAR3 EQ � GOTO NOVALUE (zero length - null value)// DIF L'VAR4 GT 4 GOTO TOOLARGE


Variable Parameters

The Number Attribute

The number attribute gives the number of elements in a variable parameterarray that have values assigned to them, regardless of whether the value wasassigned by default or on the DPROC statement. For example, assume theprocedure XYZ was created with the following statement:

//XYZ DPROC Q(8)=(A,B,C,,,,J)

If it is retrieved with an EXEC statement containing no override values, thenumber attribute of the parameter Q is 4, since four of the eight array elementshave default values. If it is retrieved with an EXEC statement that supplies twoadditional values for the fourth and fifth elements:

//CALL EXEC PROC=XYZ,Q=(,,,D,E)

It now has a number attribute of six.

Test the Number Attribute

To test a variable parameter for number, prefix it with N'.

// DIF N'VAR6 LT 1 GOTO NOVALUES// DIF N'VAR7 EQ 5 GOTO DONEALL


Functions

Functions

CA Driver also recognizes a set of predefined functions. A CA Driver functionhas a reserved name and accepts one or more parameters. The general formatof a function is:

function(parameter1,parameter2,..)

Function parameters can be absolute constants or can be coded as variableparameters containing valid values that the function expects. In either case,parameters values must be in valid format and must follow the order requiredby the function.

CA Driver functions are recognized on the right side of the DSET statement. Toset a variable to the result of the predefined function, use the following format:

// DSET variable=function(parameter1,parameter2,...)

For example,

// DSET VAR1=DTADD(1,&C_JDATE)

The above statement adds one to the current system date and stores the resultin variable VAR1. (All month-end and leap-year adjustment is automaticallyhandled by the DTADD function.)

The primary value of these functions is that they can be used to automate yourJCL setup. By encoding the functions in your CA Driver procedures, youeliminate the need for JCL staging and manual manipulation. Because all of thefunctions have parameters that accept or default to CA Driver variableparameters, the power of the functions and the variable parameters can becombined.

The functions perform more than simple arithmetic operations because theytake into account transitions between months, years, and periods so that theyreturn the expected values.


Functions

CA Driver Functions

Arithmetic Date Functions

CA Driver offers the following arithmetic date functions. CA Driver automaticallyhandles all leap-year, month-end, and year-end adjustments.

Function and Parameters Explanation

DTADD(n,&var) Adds "n" to variable "&var." The variable &var must contain a validJulian date in the yyddd format. n represents a number of days to beadded to &var and can be a positive numeric constant or a variablecontaining a positive numeric value.

Example: If &C_JDATE=06366, DTADD(4,&C_JDATE)=07004

DTSUB(n,&var) Subtracts "n" from variable "&var." The variable &var must contain avalid Julian date in the yyddd format. n represents a number of days tobe subtracted from &var and can be a positive numeric constant or avariable containing a positive numeric value.

Example: If &C_JDATE=07005, DTSUB(8,&C_JDATE)=06363

DTDIF(&var1,&var2) Subtracts variable "&var2" from variable "&var1." The variables &var1and &var2 must contain valid Julian dates in the yyddd format.

Example: If &C_JDATE=07040, DTDIF(07045,&C_JDATE)=5

MNADD(n,&var) Adds "n" to variable "&var." The variable &var must contain a validJulian date in the yyddd format. n represents a number of months to beadded to &var and can be a positive numeric constant or a variablecontaining a positive numeric value.

Example: If &C_JDATE=07023, MNADD(2,&C_JDATE)=07082

MNSUB(n,&var) Subtracts "n" from variable "&var." The variable &var must contain avalid Julian date in the yyddd format. n represents a number of monthsto be subtracted from &var and can be a positive numeric constant or avariable containing a positive numeric value.

Example: If &C_JDATE=07039, MNSUB(1,&C_JDATE)=07008


Functions

Date Conversion Functions

The following date conversion functions are offered by CA Driver. All leap-year,month end, and year end adjustments are automatically handled by CA Driver.


DMY(&var) Converts variable "&var" into ddmmyy format. The variable &var mustcontain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, DMY(&C_JDATE)=010207

MDY(&var) Converts variable "&var" into mmddyy format. The variable &var mustcontain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, MDY(&C_JDATE)=020107

YMD(&var) Converts variable "&var" into yymmdd format. The variable &var mustcontain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, YMD(&C_JDATE)=070201

DMYR(&var) Converts variable "&var" into ddmmccyy format. The variable &varmust contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, DMYR(&C_JDATE)=01022007

MDYR(&var) Converts variable "&var" into mmddccyy format. The variable &varmust contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, MDYR(&C_JDATE)=02012007

YRMD(&var) Converts variable "&var" into ccyymmdd format. The variable &varmust contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, YRMD(&C_JDATE)=20070201

DM3Y(&var) Converts variable "&var" into ddmonyy format. The variable &var mustcontain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, DM3Y(&C_JDATE)=01FEB07

M3DY(&var) Converts variable "&var" into monddyy format. The variable &var mustcontain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, M3DY(&C_JDATE)=FEB0107

YM3D(&var) Converts variable "&var" into yymondd format. The variable &var mustcontain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, YM3D(&C_JDATE)=07FEB01


Functions


DM3YR(&var) Converts variable "&var" into ddmonccyy format. The variable &varmust contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, DM3YR(&C_JDATE)=01FEB2007

M3DYR(&var) Converts variable "&var" into monddccyy format. The variable &varmust contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, M3DYR(&C_JDATE)=FEB012007

YRM3D(&var) Converts variable "&var" into ccyymondd format. The variable &varmust contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, YRM3D(&C_JDATE)=2007FEB01

DAY(&var) Converts variable "&var" into the day of the week (MONDAY,TUESDAY, and so on). The variable &var must contain a valid Juliandate in the yyddd format.

Example: If &C_JDATE=07032, DAY(&C_JDATE)=MONDAY

MONTH(&var) Converts variable "&var" into the month name (JANUARY,FEBRUARY, and so on). The variable &var must contain a valid Juliandate in the yyddd format.

Example: If &C_JDATE=07032, MONTH(&C_JDATE)=FEBRUARY

MON(&var) Converts variable "&var" into a three character abbreviation of themonth name (JAN, FEB, and so on). The variable &var must contain avalid Julian date in the yyddd format.

Example: If &C_JDATE=07032, MON(&C_JDATE)=FEB

MON#(&var) Converts variable "&var" into the month number (01,02,03, and so on).The variable &var must contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, MON#(&C_JDATE)=02

DOW(&var) Converts variable "&var" into a three-character abbreviation of the dayof the week name (SUN, MON, and so on). The variable &var mustcontain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, DOW(&C_JDATE)=MON

DOW#(&var) Converts variable "&var" into a two-digit day of the week (01, 02, 03,and so on). The two-digit numbering begins with Sunday (01). Thevariable &var must contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=07032, DOW#(&C_JDATE)=02


Functions


WOM(&var) Converts variable "&var" into a two-digit week of the month (01, 02, 03,and so on). The variable &var must contain a valid Julian date in theyyddd format. This refers to full weeks (not partial).

Example: If &C_JDATE=08096, WOM(&C_JDATE)=01

WOY(&var) Converts variable "&var" into a two-digit week of the year (01, 02, 03,and so on). The variable &var must contain a valid Julian date in theyyddd format. This refers to full weeks (not partial).

Example: If &C_JDATE=08096, WOY(&C_JDATE)=14

WOM#(&var) Converts variable "&var" into a two-digit week of the month (01, 02, 03,and so on). The variable &var must contain a valid Julian date in theyyddd format. Since the weeks are defined from Sunday to Saturday,the first week may only contain a couple of days.

Example: If &C_JDATE=08096, WOM#(&C_JDATE)=02

WOY#(&var) Converts variable "&var" into a two-digit week of the year (01, 02, 03,and so on). The variable &var must contain a valid Julian date in theyyddd format. Since the weeks are defined from Sunday to Saturday,the first week may only contain a couple of days.

Example: If &C_JDATE=08096, WOY#(&C_JDATE)=15


Functions

Day-Of-Month Functions

The following day-of-month functions are offered by CA Driver. These functionsreturn dates or portions of dates by counting a specified number of daysforward from the beginning of months or backwards from the end of months. Allleap-year, month end, and year end adjustments are automatically handled byCA Driver. The functions are useful for coding procedures that require a datethat is always a certain number of days from the beginning or end of the monthsuch as a billing date that is constantly on the 10th day of the month.


LDOM(n,yyddd) Returns the day-of-month number by counting n days backwards fromthe end of the month of the Julian date (yyddd) specified. Countingbegins at 1 on the last day of the month. (n=1 returns the last day ofthe month.) If yyddd is not specified, the default is the current&C_JDATE value. n should be in the range of 1-31.

Example 1: LDOM(2,07025)=30Example 2: LDOM(2,07045)=27

JDOM(n,yyddd) Returns a Julian date by counting n days from the beginning of themonth of the the Julian date (yyddd) specified. Counting begins at 1 onthe first day of the month. (n=1 returns a Julian date representing thefirst day of a month.) If yyddd is not specified, the default is the current&C_JDATE value. n should be in the range of 1-31.

Example 1: JDOM(2,07025)=07002Example 2: JDOM(2,07045)=07033

LJDOM(n,yyddd) Returns a Julian date by counting n days backward from the end of themonth of the Julian date (yyddd) specified. Counting begins at 1 on thelast day of the month. (n=1 returns a Julian date representing the lastday of a month.) If yyddd is not specified, the default is the current&C_JDATE value. n should be in the range of 1-31.

Example 1: LJDOM(2,07025)=07030Example 2: LJDOM(2,07045)=07058


Conditional Procedure Expansion


You can use CA Driver's conditional procedure expansion to:

■ Control which parts of a procedure are expanded, based on logic in theprocedure.

■ Branch forward or backward within a procedure, based on variableparameter values supplied on the EXEC statement.

These commands are available to program conditional procedure expansion.

Code the commands in control statements like the following:

To Use thiscommand

Assign a name to a control statement DSTEP

Branch to a step DGOTO

Define conditions for branching DIF

Set variable parameters DSET

Control looping DLCTR

Flush all calling procedures DFLUSH

Abort current procedure DABORT

//name command operands

Where name is an optional user-defined value given to a control statement sothat it can be referenced in DGOTO and DIF statements.

Each of the commands is described on the following pages.



Define Step Names (DSTEP)

Use the DSTEP command to assign a name to a control statement. Naming acontrol statement allows you to branch to that statement from a DIF or DGOTOstatement.

//name DSTEP

Names can be one to eight alphanumeric characters. A maximum of 256names can be defined in each procedure.

Examples

//ONE DSTEP//DAILYRUN DSTEP//STEP1 DSTEP//1 DSTEP

Branch (DGOTO)

Use the DGOTO command to stop procedure expansion, branch forward orbackward to another control statement, and continue expansion at that point.

//name1 DGOTO name2

Examples

//name DGOTO ONE//name DGOTO DAILYRUN//name DGOTO STEP1//name DGOTO 1



The following example demonstrates how to use DSTEP and DGOTOstatements to restart an abended job stream at step three instead of step one.To do this, the procedure is defined with a variable parameter called RESTARTthat has a default value of STEP01.

//PAYROLL DPROC RESTART=STEP�1// THIS JOB IS BEGINNING AT STEP &RESTART// DGOTO &RESTART//STEP�1 DSTEP// STEP STEP�1 ...//STEP1 EXEC PGM=PAY�1// DD ...//SYSIN DD // DATA/ //STEP�2 DSTEP// STEP STEP�2//STEP2 EXEC PGM=PAY�2// DD ...// DD ...//STEP�3 DSTEP// STEP STEP�3//STEP3 EXEC PGM=PAY�3// DD ...

If a restart is necessary, an overriding value is supplied for the RESTARTparameter specifying the step name at which restart is to begin. In this case,this is step three:

//CALL EXEC PROC=PAYROLL,RESTART=STEP�3

This procedure could easily be expanded to include logic that would make stepselection stop at any specified step name as well as start at any specified stepname.



Define Conditions (DIF)

Use the DIF command for conditional forward and backward branching. Codethe DIF control statement in this format, supplying the values shown in the chartbelow.

//name1 DIF parmname operator value GOTO name2

Note: Do not confuse the DGOTO statement with the GOTO clause of the DIFstatement.

At this point Specify this value

name1 An optional name for this control statement that allows itto be referenced in other DIF or DGOTO statements.

parmname A variable parameter that was defined on the DPROCstatement when the procedure was cataloged.

operator The relationship between the parameter and the valueas one of these operators: LT, GT, EQ, NE, GE, or LE.The symbols =, <, > can be used instead of EQ, LT,and GT.

value A character string against which to test the variableparameter. It can be from 1-64 characters in length andmust be delimited by quotes or some other specialcharacter if it contains other than all alphanumericcharacters. (If this character string is a different lengththan the value of the parameter, the length of theparameter value is used.) This can also be a variable.

name2 The name of another control statement that is to bebranched to if these conditions are met.

Examples

// DIF VAR1 EQ YES GOTO STEP1// DIF VAR2 NE 'DAILY RUN' GOTO MONTHLY// DIF VAR3 LE 99 GOTO TESTOK// DIF SIZE GT 12� GOTO TOOLARGE



The following example demonstrates how conditional procedure expansionselects different job steps from a large procedure, depending on the day of theweek. The reserved variable C_DAY is used to inform the procedure of the dayof the week. The procedure is stored in the CA Driver library as follows:

//PAYROLL DPROC// THIS PAYROLL REPORTING RUN IS FOR &C_DAY//STEP1 EXEC PGM=PAYRUN// DD ...// DD ...// DIF C_DAY NE FRIDAY GOTO NOTFRI// THIS STEP IS PROCESSED ONLY ON FRIDAYS//STEP2 EXEC PGM=RECAP// DD ...// DD ...//NOTFRI DSTEP// END OF PAYROLL

When this procedure is called on Monday, this expanded job stream issubmitted.

// THIS PAYROLL REPORTING RUN IS FOR MONDAY//STEP1 EXEC PGM=PAYRUN// DD ...// DD ...// END OF PAYROLL

When this procedure is called on Friday, this expanded job stream is submitted.

// THIS PAYROLL REPORTING RUN IS FOR FRIDAY//STEP1 EXEC PGM=PAYRUN// DD ...// DD ...// THIS STEP IS PROCESSED ONLY ON FRIDAYS//STEP2 EXEC PGM=RECAP// DD ...// DD ...// END OF PAYROLL



Set Variable Parameters (DSET)

Use the SET command to change the value of a variable parameter duringconditional expansion. Code the name of the parameter and the new value inthis format with no spaces after the parameter name.

//name DSET parmname=value

The value can be one of these:

■ An integer, either positive or negative.

// DSET VAR1=4 (positive value is assumed)// DSET VAR=+22 (positive value can be explicit)// DSET VAR=-3 (negative value must be explicit)

■ The result of an arithmetic expression using integer values and arithmeticoperators (+, -, *, /).

// DSET VAR1=4-2// DSET VAR1=8+7// DSET VAR1=4 3// DSET VAR1=8/4

■ A character string.

// DSET VAR1=NO// DSET VAR1='A CHARACTER STRING'

■ The value of another variable parameter.

// DSET VAR1=&VAR2



■ The result of an arithmetic expression using two variable parameters or onevariable parameter and an integer. (Variable parameters used in arithmeticexpressions must have numeric values associated with them, rather thancharacter values. The results of all arithmetic operations are truncated toprovide only integer results.)

// DSET VAR1=&VAR1+1// DSET VAR1=&VAR1+&VAR2// DSET VAR1=&VAR2-&VAR3// DSET VAR1=&VAR2 &VAR3// DSET VAR1=&VAR2/2

Control Loops (DLCTR)

As a result of backward step branching during procedure expansion, procedureexpansion can enter a loop. CA Driver automatically terminates procedureexpansion when any step name is referenced more than 16 times. To overridethe default value of 16 step references, use the DLCTR command and specifya number.

//name DLCTR n

The number you specify (n) is the maximum number of times any one step canbe branched to. If any step is referenced n+1 times, an error message isproduced and procedure expansion is terminated.

Examples

// DLCTR 4// DLCTR 9�// DLCTR 999



Abort Expansion (DFLUSH)

Use the DFLUSH command to completely terminate procedure expansion.

//name DFLUSH

The DFLUSH statement flushes not only the remainder of the currentprocedure, but the remainder of any and all calling procedures as well.

Abort Expansion of the Current Procedure (DABORT)

Use the DABORT command to terminate expansion of the current procedure.Calling procedures continue to expand normally.

//name DABORT


Comments Inside CA Driver Procedures

Comments Inside CA Driver Procedures

The following applies to CPU jobs only. For information about comments insidean XPJOB job's CA Driver procedure, see “Comments for XPJOB Jobs.”

Comments for CPU Jobs

By default, each statement in a CA Driver procedure is considered a part of theprocedure and is subject to modification by CA Driver. Even those statementsthat begin with '//*' and are considered comments in JCL are eligible for CADriver variable substitution.

This can be useful in certain situations, but the need may arise for commentsinside CA Driver procedures that do not appear in expansions.

CA Driver can be instructed to ignore comment statements altogether. In thisway, comment statements can be used for documentation inside the procedurebut will not appear in any displays where the procedure is expanded.

The DPROCCOM keyword on the OPTIONS statement in the CA 7 initializationfile controls the use of comments inside CA Driver procedures. The default isDPROCCOM=NO. All CA Driver procedure statements beginning with '//*' aresubject to variable substitution and will be included in procedure expansions.

If DPROCCOM=YES is specified, any CA Driver procedure statement beginningwith '//*' will be ignored by CA Driver and will not appear in procedureexpansions.

Should there be a need for comment statements inside CA Driver proceduresthat begin with a character string other than '//*' then that string can be codedas a value on the DPROCCOM keyword. The value must not exceed eightbytes and should not include blanks or commas. The value also cannot be oneof the following: Y, YES, N, or NO.

Comments for XPJOB Jobs

For XPJOB jobs, comments are denoted by an asterisk (*) in column one,provided that the previous statement is not a continued statement. You canembed comments into the CA Driver procedure, but these are not used norshown in the data sent to the destination agent. If the procedure uses variableson the line, these variables are not reflected anywhere but in the returnedcomment statement, which is not used.


Use CA Driver in the CA 7 Environment -- Some Examples

Use CA Driver in the CA 7 Environment -- Some Examples

The following topics provide examples of conditional execution based onschedule ID and XPJOB driver procedures.

Conditional Execution Based on Schedule ID

You can use the &C_L2SID reserved name variable parameter to modify aparameter for a job. For example, by convention, schedule ID 001 indicates thatthe job should run with a parameter of MONTHLY, schedule ID 002 isassociated with a parameter of WEEKLY. Schedule ID 003 is considered aDAILY run by the job.

You can use CA Driver to generate a parameter to the job based on scheduleID.

//procname DPROC RUNTYPE=,VAR(4)=(MONTHLY,WEEKLY,DAILY,OTHER),HOLDSEL=// DSET HOLDSEL=&C_L2SID// DIF HOLDSEL LE 3 GOTO DOIT// DSET HOLDSEL=4//DOIT DSTEP// DSET RUNTYPE=&VAR(&HOLDSEL)//STEPNAME EXEC PGM=USERPGM,PARM=&RUNTYPE

XPJOB Driver Procedures

For an XPJOB, the CA Driver Procedure XPJDPROC is stored in the DPROClibrary (either CARPROC DD statement or the DPROC library associated withthe JCL or PARM library as defined through initialization parameters). Noticethe format of the first statement, which identifies the procedure name.

//XPJDPROC DPROC TIME=6�PARM�1='T=&TIME'

The XPJOB PARM member that invokes this procedure is coded as follows:

DPROC=XPJDPROC,TIME=3�PARM�2=F=��12

The parameters sent to the destination platform are as follows (not all data sentto the platform is represented here):

PARM�1 T=3�PARM�2 F=��12


Chapter 5. NCF


Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165CA 7 NCF Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Planning and System Requirements . . . . . . . . . . . . . . . . . . . . . . 172Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 177System Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Operator Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

This section defines the purpose and basic requirements for CA 7 NCF(Network Communications Facility) and describes the primary components ofthe system. Functional descriptions of the operator commands are alsoincluded.

Chapter 5. NCF 163

Purpose

Purpose

It is often desirable, for maximizing use and effectiveness of computerresources, to route CPU jobs (and their products) to some other data centersfor processing, printing, and so forth. Generally these data centers are widelydispersed geographically. They may be located very close to each other,however. In any case, routing of jobs is performed by JES over acommunications link between the data centers. This is accomplished with JEScontrol statements included within the JCL for the job.

IBM provides a Network Job Entry (NJE) facility within JES to handle therouting of jobs to be processed at another data center. NJE also routes anyprint or punch output to whatever location the user wishes to perform thatfunction. Printing and punching of job output does not have to be done at thelocation where job execution occurs.

CA 7, in its native form, performs dynamic workload management functionssuch as scheduling, prerequisite verification, job submission, and so forth,based on SMF data. In an NJE environment, as in all environments, SMF datais only produced at the location where job execution occurs. CA 7 may or maynot be installed at that location. SMF data must, however, be returned to theCA 7 that originally submitted the job if CA 7 is to be able to track the job.

CA 7 NCF, an optional component of CA 7, provides the software required toallow the user to fully use all workload management facilities of CA 7, whethersome jobs are processed on an NJE basis.

With NCF, jobs submitted by CA 7 can execute at any site within a network ofsites just as if the site were a local CPU. NCF ensures that the CA 7 thatsubmitted a job receives the necessary SMF data for the job regardless ofwhich site processed the job.

No changes are required to the CA 7 database for a job to be run on an NJEbasis. The JCL for any such job must, however, contain the JES statementsnecessary to cause JES to route the job to the desired location after it hasbeen submitted by CA 7. When execution does occur, CA 7 performs itsfunctions related to the job just as if the job executed in an initiator on a localCPU. This transparency to both CA 7 and the production user would not bepossible without the NCF component.


Requirements

Requirements

CA 7 must exist at each node from which CA 7 controlled jobs are to besubmitted. ICOM (the CA 7 Independent Communications Manager) must beinstalled on each CPU where these jobs are to execute. CAIRIM plus the CA 7SMF interface exits and SVC interface must also be installed on each CPU.

The minimum requirements for CA 7 NCF are:

■ Support for CA 7, under z/OS with JES2 or JES3, at a minimum of onesite.

■ Support for ICOM, under z/OS, at all sites.

■ Generation of SMF record types 14 (optional), 15, 26 (optional), 30, and 64(optional) at all sites.

■ A VTAM environment that supports the Multisystem Networking Facility(MSNF) at all sites.

NJE jobs do not necessarily require special CA 7 database definitions.

Chapter 5. NCF 165

CA 7 NCF Components

CA 7 NCF Components

The primary components of this system are:

■ CAIRIM, the Resource Initialization Manager

■ CA 7 SVC interface and SMF interface exits

■ ICOM

■ Node table

■ Unknown node table

■ NCF communications data set

■ NCF undeliverable queue (UDQ)

■ NCF VTAM application program

■ CA 7 NCF test data generator

The following figures illustrate the data flow between these components within asingle CPU and a typical NCF environment (however, many variations areavailable to the user).

The following illustrates data flow within one CPU:


CA 7 NCF Components

The following illustrates one typical NCF environment:

Chapter 5. NCF 167

CA 7 NCF Components

CAIRIM (Resource Initialization Manager)

CA 7 NCF uses the CA Resource Initialization Manager, CAIRIM. CAIRIM isthe common driver for a collection of dynamic initialization routines thateliminate the need for preinstalled user SVCs, SMF interface exits, subsystems,and other installation requirements commonly encountered when installingsystems software. These routines are grouped under the service code S910,which is one of the CA Common Services.

CA 7 uses the CAISMFI Dynamic SMF Event Interceptor (which is asubcomponent of CAIRIM), so SMF recording must be active in the system forany SMF event or data handling product routines. The CAIRIM SMF Interceptorcomponent does not require any particular SMF records.

SVC Interface

When each job is submitted to JES by CA 7, the JOB statement is flagged withthe originating node ID. The CA 7 UJV SMF interface exit preserves this ID ineither the SMF Reader Time or SMF User ID fields depending on whichlocation the user designates, in ICMDSECT, for this purpose.

The CA 7 SVC, when called by the CA 7 SMF interface exits, uses this nodeID to identify the CA 7 location that submitted the job and to which all SMFdata for the job should be returned. The originating CA 7 node ID is used todistinguish between data that should be retained locally and that data thatshould be routed back to CA 7 at some other node.

The CA 7 SVC interface obtains data from the CA 7 SMF interface exits andthe CA 7 trailer or U7SVC programs and transfers this data across addressspaces for subsequent processing by ICOM. The SVC interface and SMFinterface exits must be installed at all sites for NCF processing to occur.

Although the execution location must generate the necessary SMF record typesto satisfy CA 7 requirements, the data need not be also written to the SMFMANX/Y data sets unless the user so desires. This data that occurs at theexecution site is available at the originating CA 7 site for logging into the CA 7log data set in standard CA 7 log record format.


CA 7 NCF Components

ICOM

All ICOMs that run in an NCF environment must have the NCF modulesavailable (for example, STEPLIB) and an extra DD statement pointing to theNCF communications data set. This is an extension of the standard CA 7ICOM program. It must be installed at each node. It processes data for localand remote records by extracting data from the SVC interface and writing localrecords to the CA 7 communications data set and remote records to the NCFcommunications data set.

Data received through VTAM at an originating node is routed through the SVCinterface and processed by ICOM as if it were generated locally.

Node Table

This table defines nodes in the network for the NCF VTAM task. Up to 222nodes can exist in any one network. Each NCF node corresponds to a JESNJE node on a one-to-one basis. UCC7NODE is the required name for thenode table. Generation of the node table is accomplished with the UNCNODmacro as discussed in the appendix "VTAM and NCF Node Table Definitions"in the Installation Guide.

Each node in the node table must have both a unique CA 7 identifier and aunique VTAM identifier (ACBNAME) as specified in a VTAM APPL definition.Each site must have its own table.

For a successful communications link to be established between the NCFVTAM tasks at any two nodes in the network, a validation of the two nodetables is automatically performed at "bind" time. A discussion of this validationprocedure is included in the appendix "VTAM and NCF Node Table Definitions"in the Installation Guide.

Unknown Node Table

If, during processing, any data is encountered for a node not defined in thenode table, an entry is created in the unknown node table dynamically by theNCF VTAM task. Any SMF or trailer data for such nodes are written to theundeliverable queue besides creating an entry to this table.

Unless the user changes the node table while jobs are executing at a remotenode in the network, no unknown nodes should ever occur.

If the unknown node table becomes full, a warning message is issued and anynew undeliverable data is dropped.

Data in the undeliverable queue for an unknown node can be purged with thePURGE command. Any reoccurrence of data for this unknown node is alsowritten to the undeliverable queue, and the existing entry in the unknown nodetable is reused.

Chapter 5. NCF 169

CA 7 NCF Components

NCF Communications Data Set

The NCF communications data set acts as intermediate storage for remote datacollection at each node in the network. It contains SMF and CA 7 trailer datafor jobs submitted from a remote node. This file must exist for NCF processingto occur. This data set has a one-to-one relationship with a JES NJE SPOOL orjob queue. In a multi-access spool (MAS) complex or a single CPU site, onlyone data set is defined.

NCF Undeliverable Queue (UDQ)

The UDQ contains data for nodes that do not have an active link, or that arenot defined in the node table. Any data that cannot be transmitted due tocommunication interruptions are saved in this data set. This file must exist forNCF processing to occur.

If the UDQ becomes full, data contained in the file must be purged ortransmitted or new data is lost. A progressive series of warning messages areissued beginning when the file threshold (80 percent) is reached and continuinguntil the percentage used drops below the threshold value.

NCF VTAM Application Program

The NCF VTAM application program receives and transmits CA 7 NCF databetween nodes in the network. This program receives control once VTAM andthe NCF VTAM application program are started.

Functions

The NCF VTAM application program performs the following functions:

■ Loads the node table

■ Builds the unknown node table

■ Establishes VTAM sessions with all other nodes

■ Packages outbound SMF and trailer data and transmits it through VTAMfacilities to NCF at another node for host CA 7 processing

■ Processes NCF operator commands

■ Writes/reads undeliverable data to/from the UDQ

■ Receives data from the sending node and passes it to the SVC forprocessing by ICOM and subsequently by CA 7

■ Transmits a positive response to the sending node


CA 7 NCF Components

CA 7 NCF Test Data Generator

A test program is supplied that generates sample data to be used by CA 7NCF. For testing purposes, the EXEC statement for the NCF VTAM task shouldbe changed to include two additional PARM values. The PARM value TESTindicates that the installation test is being performed. Another PARM value,TABLE=member can be used to identify a node table to be used for this test.This node table name does not have to be UCC7NODE, but can be if desired.The coded PARM value for this test would be similar to the following example:

PARM=('TIME=3��',TEST,'TABLE=UCC7NODB')

Note: The installation test parameters TEST and TABLE are not valid for usein a normal production environment.

To test the establishment of a session between two or more NCF nodes, TheTEST and TABLE parameters can be used to execute two or more nodes on asingle machine. The VTAM APPL definitions must be correctly coded to allow alocal-LU to local-LU session.

To test data transmission between two nodes, a data generator program issupplied that can be executed with the following JCL:

// EXEC PGM=SASSNCDG,PARM='TABLE=xxxxxxxx'//STEPLIB DD DISP=SHR,DSN=user load library//UCC7NCFD DD DISP=SHR,DSN=user defined NCF communications data set//SYSIN DD DUMMY,BLKSIZE=8�

The TABLE parameter should specify the same table used by the NCF VTAMapplication program that is to transmit the data. Sample data is generated,according to this table, for transmission to all remote nodes. The SYSIN DDstatement is required and should always be coded as shown in the JCL aboveunless otherwise directed by Technical Support.

Note: The CA 7 SVC is never invoked by CA 7 NCF when PARM=TEST isspecified.

When you have completed testing with the NCF Test Data Generator, youshould reinitialize the ICOM communications data set (COMMDS), the NCFcommunications data set (COMNCF), and the NCF undeliverable queue(UNDQUE). This will remove the test data placed in these files.

Chapter 5. NCF 171

Planning and System Requirements


At least one site in the network must have CA 7 installed. The installation ofCA 7 NCF is incorporated in the Installation Guide. The information in thistopic is provided to allow you to effectively plan the installation of CA 7 NCF.Installation requirements for sites that are not running CA 7 are slightly differentfrom those for sites that are running CA 7.

General Notes

This topic discusses both terminology and installation.

Terminology

The following terminology is used throughout this chapter and the InstallationGuide and helps distinguish between environments.

NCFNetwork Communication Facility, a component of CA 7. Also refers to theVTAM application program used to pass certain CA 7 data from site to site.

NCF ComplexUsed to refer to all the sites connected by NCF.

NCF1A site that runs CA 7 and NCF.

NCF2A site that runs NCF but not CA 7.

siteA node in an NJE network. Consists of one or more CPUs running with orwithout shared spool.



Installation

The following general considerations apply to installation:

■ CA 7 must be installed in at least one of the sites in the NCF complex.

■ If both CA 7 and NCF are to be installed at a site, first install CA 7 andNCF at the NCF1 site, then proceed installing NCF at the NCF2 sites.

■ Beginning with CA 7 r11, NCF can only be used by the CA71 instance.

■ All of the CPUs in the NCF Complex must have the CA 7 SVC and CA 7SMF interface exits installed. ICOM must be run on each CPU in thecomplex. However, NCF itself only runs on one CPU per site.

■ The JOB statements for all jobs submitted by CA 7 must have blanks incolumns 69, 70, and 71. (If external security is used with USERID insertion,column 68 must also be blank.)

■ Sites that run in different time zones can cause apparent date/timeproblems. The time values in the CA 7 database that are established by theuser (for example, DOTM) must be set according to the time zone wherethe CA 7 database is located and not where the job is to be run.

■ WLB values have less meaning because CA 7 groups all the resourcestogether.

■ CA 11 controlled jobs require the CA 11 database and programs be at thesite where the jobs are run. Also, all sites to which CA 7 submits CA 11controlled jobs must use the same procedure name for RMS. The RMSprocedure name must be in the CA 11 Option Table or in the CA 7initialization file (RESTART statement).

■ The LOAD procedure inserted into jobs submitted by CA 7 must exist at allsites and the procedure name must be the same at all sites.

■ A CA 7 site that does not use NCF cannot send a CA 7 submitted job to aCA 7 site that does run NCF (NCF1 or NCF2) if a LOAD step is included inthe JCL. This results in a U0110 abend in the LOAD step. If there is noLOAD step, the job runs but does not track.

Chapter 5. NCF 173


Resource Requirements

For the CA 7 NCF system to function, specific requirements must be met forthe operating system, memory size, and NCF data sets.

Operating System Environment

CA 7 NCF operates under all levels of the z/OS operating system that aresupported by IBM.

Although CA 7 does not have to be installed at each site for NCF to function,ICOM must exist for each site and in each CPU where CA 7 controlled jobs areto execute. CA 7 must exist at each site from which CA 7 controlled jobs are tobe submitted.

The CA 7 SVC interface and SMF interface exits must be installed at all sitesand on all CPUs that can execute CA 7 controlled jobs. CAIRIM, CA ResourceInitialization Manager, must be on each CPU as well.

Memory Requirements

The virtual memory requirements of the VTAM task are variable, based on thenumber of nodes in the node table. The following formula should be used tocalculate the virtual region size.

Region size = 180KB + (4KB * (# of nodes))

Memory requirements of ICOM remain about the same, approximately 256 KB.

DASD Devices

CA 7 NCF supports the following disk drives:

3375

3380

3390

9345



DASD Requirements

The permanent files for CA 7 NCF consist of two data sets used by NCF itselfand one data set used by ICOM. Following is a description of the permanentfiles.

NCF Communications Data Set: The NCF communications data set containsCA 7 formatted SMF and trailer data to be transmitted to remote nodes. In amulti-CPU site, this data set must reside on a shared DASD device. Each CPUin the complex must execute a copy of ICOM, each of which shares this dataset.

The NCF communications data set is a formatted physical sequential data setwith the following characteristics:

DCB=(RECFM=F,BLKSIZE=1�24,LRECL=1�24)

The space required by the NCF communications data set depends on theamount of NCF activity. A minimum allocation of 900 blocks is recommended.

This data set must be formatted using the SASSNC12 program. See the CA 7install job N030 for sample JCL.

Undeliverable Queue (UDQ): The UDQ contains CA 7 formatted SMF andtrailer data that could not be transmitted because communication with a nodewas interrupted or could not be established. It also contains data for any nodesencountered during processing that have not been defined in the node table.Unless the user changes the node table while NJE jobs are in the JES queue,either locally or remote, no unknown node IDs should occur.

The undeliverable queue is a formatted physical sequential data set with thefollowing characteristics:


The space required by the UDQ depends on the amount of NCF activity. Noless than one cylinder is recommended. At least 600 blocks of space should beallocated for each node to which data can be transmitted. Experience mayshow that more space is required for a particular site.

This data set must be formatted using the SASSNC15. See the CA 7 installjob N030 for sample JCL.

Chapter 5. NCF 175


ICOM Communications Data Set: The ICOM communications data setcontains CA 7 formatted SMF and trailer data to be processed by the localCA 7. This data set must reside on a shared DASD device for multi-CPU sites.For NCF1 sites, this data set is allocated and initialized during CA 7installation.

The ICOM communications data set is a formatted physical sequential data setwith the following characteristics:


Space required for the ICOM communications data set at NCF2 sites should beabout 100-150 blocks (about five tracks on 3390 devices). At NCF1 sites, spaceis determined during CA 7 installation.

For NCF2 sites, the *CPU* statement used to format the file should specifyUCC7NCF2 (not UCC7IRDR or UCC7SUB1). Failure to do this could possiblyresult in ICOM looping. For more information about formatting thecommunications data set, see the installation requirements in the SystemsProgrammer Guide.

CAIRIM System Requirements

The installation of CA 7 NCF requires that CAIRIM be installed at each sitewhere CA 7 NCF will execute. This service may have already been installedwith another CA product.

For detailed system requirements for CAIRIM, see the Installation Guide guide.


Implementation Considerations


The use of JES NJE capabilities to address requirements for productionprocessing in a CA 7 environment not only requires the installation of thenecessary software at the processing sites, but also requires some productionconsiderations for implementing jobs under CA 7.

CA 7 NCF provides the user with software that allows CA 7 to submit jobs that,through JES NJE routing, can execute at a remote site, yet allowing CA 7 tocontrol and monitor the jobs as if they were executing locally. Even without thesupport of CA 7 NCF, jobs routed to a remote site or node through JES canexecute at the desired destination node. CA 7 at the local site or node would,however, be unable to track the jobs automatically through SMF feedback sinceall SMF data for the job would occur only at the remote node at whichexecution occurred. Using the NCF component software, production processingcan occur at any remote node as if the remote processor and initiator were alocal initiator.

However, there are implementation considerations for the production user thatare critical to the success of this processing. These considerations arediscussed in this topic.

Chapter 5. NCF 177


Execution Options

An option can be used to specify the time allowed for asynchronous processing.This option is specified in the JCL PARM field of the EXEC statement for theNCF VTAM application program. The option is specified as follows:

��─ ──PARM= ──┬ ┬─────────────────────── ─────────────────────────────────�� │ │┌ ┐─��3��─

└ ┘──'TIME= ──┴ ┴─tttttttt─ '

TIMEIs the duration of the WAIT that is issued by the NCF VTAM applicationprogram when an attempt to enqueue the NCF communications data setfails. You may need to adjust this parameter to minimize data setcontention, especially in an MAS environment.

This time limit is also used to synchronize the initial LOGON processingduring NCF startup. If all remote nodes have not attempted to LOGONwhen the limit is reached, a warning message (CA7.NC203) is issued andthe remaining LOGONs are allowed to complete asynchronously whilenormal processing commences. This parameter is optional.

00003000Is the default time limit (30 seconds) in one hundredths of a second.Leading zeros can be omitted.

ttttttttIs the user-specified time limit in one hundredths of a second. Leadingzeros can be omitted.



Sample NCF VTAM PARM

The following is a coded example of the PARM for the NCF VTAM applicationprogram:

//NCF EXEC PGM=NCF,PARM='TIME=��25��'

Sample NCF VTAM JCL

Following is an example of the JCL for the NCF VTAM task:

//jobname JOB user job statement specifications / JOBPARM user specifications // //NODE1 EXEC PGM=NCF,PARM='TIME=3��' //STEPLIB DD DISP=SHR,DSN=cai.ca7.caiload //SYSPRINT DD SYSOUT= //UCC7SNAP DD SYSOUT= //SYSABEND DD SYSOUT= //SYMDUMP DD DUMMY //UCC7NCFD DD DISP=SHR,DSN=user defined communications data set //UCC7NCFU DD DISP=OLD,DSN=user defined NCF undeliverable queue //

The UCC7SNAP DD statement cannot have FREE=CLOSE specified.

Chapter 5. NCF 179


CA 7 Database

CA 7 NCF provides support for CA 7 jobs that execute at a remote NJE node.Actual execution can occur at any location within the network of CPUs. Theexecution location is essentially transparent to the production control person.However, CA 7 database considerations for scheduling and the DB.1 panel areimportant for NJE jobs.

Scheduling

All CA 7 scheduling considerations are the same for NJE jobs as for jobs thatexecute locally. Triggers, calendar schedules, job dependencies, use ofnetworks, and so forth, are fully supported for NJE jobs. The only difference isthat NJE jobs execute at a remote site. It is a user's responsibility to ensurethat the remote node is prepared to process the job when it arrives.

Note: The day and time values specified in defining the schedules for the jobsare the values used by the CA 7 into which they are defined. For example,consider a situation where site A is in New York and site B is in Los Angeles.Job X is to be run at site A and is due out at 10:00 AM, New York time. If thejob is defined in the CA 7 database at site B, then the due-out time for the jobshould be marked as 7:00 AM.

DB.1 Panel

Fields on the DB.1 panel are used for NJE jobs with only a few specialconsiderations. The GENERAL, JCL, REQUIREMENTS, and MESSAGESsegments of the DB.1 panel are used as they would be without NCF.

All of the fields in the EXECUTION segment have the same meaning exceptthat the MAINID field for an NJE job should, when used, specify a CPU fromwhich JES can transmit the job to the proper remote node (after CA 7 submitsthe job to JES). It is still the user's responsibility to ensure that the job containsthe JCL necessary to cause JES to do the routing once JES receives an NJEjob submitted by CA 7.

If the INSERT-RMS field in the EXECUTION segment has a value of Y, CA 7inserts the step that executes CA 11. In these cases, CA 11 must be installedat the location where the job executes.

Fields in the RESOURCES segment of the DB.1 panel apply to resources thatmust be available at the remote node.



User Execution JCL

User execution JCL for the NJE jobs must be located at the CPU site fromwhich CA 7 initially submits the job to JES. The JCL segment of the DB.1panel must define where the JCL can be found.

Care must be taken also to ensure that any LTERM value specified in theMESSAGES segment of the DB.1 panel (or in the JCL statement in theinitialization file) causes messages to go to a terminal where problems can beproperly addressed if they arise.

JOB Statement

Since the job executes at a remote site with its own version of the operatingsystem, fields in the JOB statement must meet the requirements of the remotesite. This includes the following JOB statement fields:

■ Job name

■ Accounting data

■ Job class

To control the job, positions 69 through 71 of the JOB statement are reservedfor indicators that CA 7 manages. Position 69 must always contain a blank (toprevent JCL errors) and positions 70 and 71 contain indicator bytes set byCA 7 for execution control purposes. These reserved positions in the JOBstatement must be reserved in all CA 7 controlled jobs whenever NCF supportis used for any jobs.

In a CA 7 environment without NCF support, only positions 70 and 71 of theJOB statements were reserved. To avoid problems when NCF is installed, theuser must ensure that all JOB statements to be handled by CA 7 do not violatethis convention.

Note: Use of external security can require an additional column of the JOBstatement. For more information, see the chapter "Installation Requirements" inthe Systems Programmer Guide.

Chapter 5. NCF 181


JES2 Statements

Jobs can be routed to a remote node for execution, through JES2, through oneof the following control statements:

/*ROUTE/*XEQ

See the IBM publications for a discussion of these statements. When used,these statements are located in the local execution JCL library immediatelyafter the JOB statement. Once the job is submitted to JES by CA 7, thesestatements direct JES2 to route the job to the proper NJE node.

JES2/NJE also supports the /*XMIT control statement. This statement is onlydocumented in the JES2 manual. When used, the name of the job transmittedto the remote node must be the same as the name of the job that caused thejob to be transmitted.

Use of the /*ROUTE statement to direct printed or punched output to the properlocation, should be carefully considered since its function varies depending onwhere it is positioned in the JCL relative to the position of a /*ROUTE XEQstatement.

JES3 Statements

In a JES3 environment, the following JES3 statements are used to control therouting of jobs and their output to the proper JES3 locations:

//*MAIN//*FORMAT

Discussion of these statements is included in the IBM publications.



EXEC Statements

All programs, including all utility type programs, executed in NJE jobs mustexist at the execution node as opposed to the submission node. Existence ofthe programs at the execution node is a user's responsibility.

Cataloged procedures used in NJE jobs must also be located at the site whereconversion and interpretation of the cataloged procedures occur.

DD Statements

Data definition (DD) statements, besides referencing a data set located at theexecution site, must also meet the requirements of the execution node for:

■ Catalog conventions including data set name index levels

■ Unit names for devices needed

■ Model DSCBs

■ SYSOUT classes

■ SYSOUT DEST values

■ MVS subsystem names

Data Sets

Besides JCL, program, and other module library requirements, the user mustalso ensure that production data sets are located at the execution node and, ifapplicable, are cataloged correctly. Some production data sets can always bemaintained at one site while others may be required at more than one site. Theuser must ensure that the correct version of each data set is available at theexecution node prior to job execution.

References to data sets in all DD statements must meet the requirements ofthe execution node.

Chapter 5. NCF 183


General Usage

Several CA 7 facilities routinely used at local nodes can also be used at remoteNJE nodes as long as the load modules have been installed at the remote site.These facilities include:

■ Trailer step (SASSTRLR)

■ Batch card load program (SASSBCLP)

■ U7SVC utility

■ LOAD process (SASSJJCL)

All features of these facilities function the same for both local and remotenodes. Jobs can be demanded, requirements can be posted, and so forth, byexecuting these programs at the execution node. Activities that are to beperformed by CA 7 as a result of the execution of these programs arecontrolled by CA 7, wherever it resides, based on the feedback provided byNCF support. Jobs demanded or released by these facilities can execute at anynode in the network based on the routing that is specified in JES controlstatements within the JCL for the jobs.

NCFNODE Parameter

When executing SASSTRLR, the EXEC statement can be coded with a nodename in the PARM parameter. This causes the event posting data to be routedto CA 7 residing at the node name specified. If this parameter is not coded, thefeedback data is sent to the CA 7 location that submitted the job.

If used, the parameter must be first and would be coded in the format:

PARM='NCFNODE=nodename,...'

where nodename identifies the node to which posting data should be sent. Thenode name must exist in the NCF node table as defined with the NODNAMEparameter of the UNCNOD macro. (For further details on node names, see thenode table assembly discussion in the appendix "VTAM and NCF Node TableDefinitions" in the Installation Guide.)



CA 7 LOAD Process

The LOAD process is performed at the execution site. Data from this process isautomatically returned to the originating CA 7 site for updating of the CA 7database. Job characteristics in the database reflect the resource and data setinformation from the execution environment. This includes the RESOURCE dataon the DB.1 panel, information on the CA 7 cross-reference reports, and allother references to data sets and resources within CA 7.

Data set requirements and triggers are supported no matter where the jobexecutes. The data sets must physically reside at the execution node for properexecution to occur.

Chapter 5. NCF 185

System Operations

System Operations

The following topics discuss system operations.

Initialization

The only recurring initialization task required of the user once the system hasbeen installed is to ensure that VTAM is active before starting.

All other initialization is performed automatically to include:

■ Loading the node table (UCC7NODE)

■ Creation of control blocks

■ Scanning files

If NCF data sets need to be scratched and reallocated for any reason, theymust be reinitialized prior to execution of NCF. For a discussion of theprograms provided to satisfy this requirement, see the appendix "VTAM andNCF Node Table Definitions" in the Installation Guide.

Establish Communications

When the system is started, it automatically establishes communications withVTAM and then attempts to log on to all nodes in its table.

If any nodes are not active, they cannot log on. However, when those nodes dobecome active, they automatically attempt to log on.

For more information. see “LOGON Command” on page 192.


System Operations

Standard Operations

The following topics discuss standard operations.

Status Information

The STATUS command provides information on the nodes in the system,including nodes specified in the node table and any unknown nodesencountered during processing. It indicates whether they are active or inactiveand displays activity counts. Status can be displayed for one node or all of thenodes.

See “STATUS Command” on page 195 for more information.

Error Recovery

Data for nodes with which NCF cannot communicate, or which are not in theUCC7NODE table, is put in the undeliverable queue (UDQ). Data for theseunknown nodes remains on the UDQ until communication can be established oruntil the data is purged using the PURGE command. If communication is notestablished with that node in the near future, you may want to purge its data toprevent the UDQ from being filled.

See “PURGE Command” on page 194 for more information.

Termination

The normal method of terminating CA 7 NCF is to issue the SHUTDOWNcommand followed by the STOP command. This allows all pending processesto complete and provide an orderly termination.

By using only the STOP command, pending processes are cut off and the jobterminates. Data cannot be lost using this method because the data setpointers are not updated until a positive response has been received. However,duplicate data can be sent because the data may have been successfullyreceived before the positive response was issued.

See “STOP Command” on page 189 and “SHUTDOWN Command” onpage 190 for more information.

Chapter 5. NCF 187

Operator Commands

Operator Commands

The NCF operator commands give the user the ability to:

■ Initiate and terminate communication with another node

■ Reestablish communication after a shutdown

■ Display node status information

■ Purge data from the undeliverable queue

■ Terminate the NCF VTAM application

All commands to the CA 7 NCF application are done using the MVS MODIFYcommand with the exception of the MVS STOP command. The othercommands discussed in this topic require that a MODIFY taskname precedethe command text in the following format:

��─ ──MODIFY taskname ──,command ──┬ ┬───────── ───────────────────────────�� └ ┘ ─operand─

The short form of the MODIFY command, F, can be used interchangeably withMODIFY.

The maximum acceptable length for the command [operand] is 36 characters.

Any command that is not syntactically and logically correct will be rejected withthe message:

CA-7.NC1�1 UNKNOWN COMMAND IGNORED


Operator Commands

STOP Command

The STOP command immediately detaches the subtask and terminates theNCF job. You should issue a SHUTDOWN command prior to a STOPcommand to complete all pending processes.


��─ ──STOP jobname ─────────────────────────────────────────────────────��

jobnameDefines the OS job or task name of the NCF VTAM application to beterminated.

Response

Upon successful completion of the command, the following message is issued:

IEF4�4I jobname - ENDED - TIME = hh.mm.ss

Chapter 5. NCF 189

Operator Commands

SHUTDOWN Command

The SHUTDOWN command posts all node processors to complete theirpending processes and logs off. The command terminates communication withVTAM by closing the ACB and freeing all control blocks. The only validcommands after a SHUTDOWN are STARTUP or STOP. The SHUTDOWNcommand also issues a STATUS command.


��─ ──MODIFY jobname,SHUTDOWN ──────────────────────────────────────────��

jobnameDefines the OS job or task name of the NCF VTAM application to beterminated.

Response

Upon successful completion of the command, the following message is issued:

CA-7.NC1�5 SHUTDOWN COMPLETE

A STATUS command, issued by the SHUTDOWN command, will display thestatus of the nodes. See “STATUS Command” on page 195 for details.


Operator Commands

STARTUP Command

The STARTUP command, after a SHUTDOWN command, reestablishescommunications. The command rebuilds all control blocks, opens the ACB, andlogs on all nodes.


��─ ──MODIFY jobname,STARTUP ───────────────────────────────────────────��

jobnameDefines the OS job or task name of the NCF VTAM application to beattached.

Response

The following message will appear for each node (xxxxxxxx) that was logged onsuccessfully:

CA-7.NC3�2 SESSION ESTABLISHED WITH NODE (xxxxxxxx)

Chapter 5. NCF 191

Operator Commands

LOGON Command

The LOGON command attempts to establish communications with the nodespecified. This is usually done after that node has been logged off. Once thelink has been established, any undeliverable data in the UDQ will be sent.


��─ ──MODIFY jobname,LOGON nodename ────────────────────────────────────��

jobnameDefines the OS job or task name of the NCF VTAM application.

nodenameDefines the node with which communication is being established.

Response

Upon successful completion of this command, the following message is issued:

CA-7.NC3�2 SESSION ESTABLISHED WITH NODE (xxxxxxxx)


Operator Commands

LOGOFF Command

The LOGOFF command marks the node specified to be logged off. Once thatnode has completed any pending processes, the LOGOFF command will beexecuted, communications will be terminated and all future data will go to theundeliverable queue until the node is again logged on. This command can beissued at any node.


��─ ──MODIFY jobname,LOGOFF nodename ───────────────────────────────────��


nodenameDefines the node specified to log off.

Response

Upon successful completion of this command, the following message is issued:

CA-7.N3�3 LOGOFF REQUEST COMPLETE FOR NODE=xxxxxxxx

Chapter 5. NCF 193

Operator Commands

PURGE Command

The PURGE command deletes all the records from the undeliverable queue forthe node specified in the command. The entire undeliverable queue must beread and processing of the communications data set is suspended until this iscompleted. Multiple nodes can be purged only by entering multiple commands.


��─ ──MODIFY jobname,PURGE nodename ────────────────────────────────────��


nodenameDefines the node to be purged.

Response

A message is not issued when the purge is complete. To verify that the purgecompleted, a STATUS command must be issued.

Note: Since UDQ processing must be serialized to ensure chronologicalintegrity of the SMF data, a PURGE command can require several minutes tocomplete depending on the volume of records.

This command deletes records that CA 7 uses for tracking jobs. This can resultin some jobs staying in the ready or active queues.


Operator Commands

STATUS Command

The STATUS command displays the status of a single node or all nodes. Thenodes displayed will be those in the UCC7NODE table plus any unknownnodes that were encountered during processing. The percentage of blocks usedin both the NCF communications data set and undeliverable queue is alsodisplayed. Record counts reflect the volume of data since the last STARTUP.


All Nodes: To display the status of all nodes:

��─ ──MODIFY jobname,STATUS ────────────────────────────────────────────��


Single Node: To display the status of a single node:

��─ ──MODIFY jobname,STATUS nodename ───────────────────────────────────��

nodenameDefines the single node for which status is to be displayed.

Chapter 5. NCF 195

Operator Commands

Response

Following is an example of a display for the STATUS command.

� �--------------------- CA-7 NCF VTAM STATUS ----------------------

__NODE__ (ID) _STATUS_ _LUTYP_ _RECV_ _SENT_ _UNDL_ _PURG_ ADL�1�1 (�2) INACTIVE ��57 ��57 �� ACH�2�1 (�3) ACTIVE PLU ��485 ��485 ��

nodename (�4) UNKNOWN �� 146 ��

NCF QUEUE ..41% USED UND QUEUE ..23% USED� �

This panel contains the following fields:

NODEThe VTAM APPL ACBNAME of the node whose status information isdisplayed. Each unknown node name will be printed on a separate line.

IDThe node ID in hexadecimal.

STATUSThe status of each node:

ACTIVECommunication is established with this node.

INACTIVECommunication is not established with this node.

UNKNOWNThis node is not in the UCC7NODE table but data was received and iseither being held on the undeliverable queue or was purged.

LUTYPEIf a node is active, it is either a primary logical unit (PLU) or secondarylogical unit (SLU). The node that initiated the communications link is thePLU.

RECVThe number of blocks received from the node specified.

SENTThe number of blocks sent to the specified node.

UNDLThe number of blocks on the undeliverable queue (UDQ) that contain datafor this node. The physical blocks on the UDQ can contain data for multiplenodes. Therefore, the total of the UNDL counts on the STATUS commanddoes not necessarily correlate to the physical blocks used on the UDQ.

PURGThe number of blocks on the UDQ that contained data for the node thatwas purged.


Operator Commands

NCF QUEUEThe percentage of blocks used in the NCF communications data setcompared to total blocks available.

UND QUEUEThe percentage of blocks used in the UDQ compared to total blocksavailable. When the UND QUEUE % USED first exceeds 80 percent, 85percent, and 90 percent, a warning message will be issued. The warningmessage will be issued every time a block is added while it exceeds 95percent.

Chapter 5. NCF 197

Operator Commands

TRACE Command

As a debugging aid, the TRACE command is used to activate or deactivate theNCF tracing facility. This facility can provide SNAP dumps or WTOs to assist inisolating problems.

Note: Due to the extreme volumes of WTO and SNAP output produced, thisfacility should only be used when requested by Technical Support for problemresolution.


��─ ──MODIFY jobname,TRACE= ──┬ ┬─SNAP───────────── ──────────────────────�� ├ ┤─n────────────────

└ ┘──(n,mm,mm,...,mm)

jobnameDefines the OS job or task name of the VTAM subtask.

TRACE= SNAP|n|(n,mm,mm,...,mm)Activates the trace facility.

SNAPIndicates that SNAP dumps are to be taken.

nIndicates the level number of WTOs desired. When coded by itself,WTOs will be produced by all modules.

Level numbers (n) for WTOs are 1, 4 and 7 and are the only validvalues for WTOs. Level 1 provides the most general WTOs. Levels 4and 7 provide progressively more detailed WTOs. Level 7 provides themost detailed WTOs. A special level number of 127 can be used torequest PCB SNAP dumps each time a PCB is dispatched. A PCB(Program Control Block) is an NCF internal data area used incontrolling all processing.

(n,mm,mm,...,mm)Indicates that the specified level of WTOs (n) is desired only from themodules specified as mm in the list. The parentheses must be coded asshown. The specification for n is the same as previously indicated. Asan example, (7,01,03,04) indicates that the most detailed WTOs aredesired from modules SASSNC01, SASSNC03, and SASSNC04.Leading zeros are not required.


Operator Commands

Deactivate the Trace Facility

To deactivate the previously activated trace facility, the following command isused:

��─ ──MODIFY jobname,TRACE=OFF ─────────────────────────────────────────��

jobnameSpecifies the same meaning as in the previous TRACE command enteredto activate the tracing facility.

Chapter 5. NCF 199

Chapter 6. Cross-Platform Scheduling


CAICCI Cross-Platform Connections . . . . . . . . . . . . . . . . . . . . . . 203The XPS CLIENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207The XPS SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

A CA scheduling solution can request work to be run on its behalf by anotherCA scheduling solution on a different platform. For example, CA AutoSys on aUNIX platform can request that CA 7 schedule MVS jobs on its behalf. Thefollowing CA scheduling solutions can participate in cross-platform scheduling:

■ CA 7

■ CA Scheduler

■ CA Jobtrac

■ CA AutoSys

■ CA NSM Job Management Option

■ Unicenter CA-7 Agent

■ Unicenter Universal Job Management Agent

This discussion refers to the CA scheduling solution requesting work (such asan MVS job or UNIX script, and so on) as the XPS CLIENT. The XPS SERVERis the CA scheduling solution controlling execution of the work requested by theXPS CLIENT. In the previous example, CA AutoSys is the XPS CLIENT andCA 7 is the XPS SERVER.

The workload can be thought of as primarily under the control of the XPSCLIENT. The XPS CLIENT requests work and monitors status for purposes ofworkload control (evaluating requirements, triggering other work). The XPSSERVER only acts to initiate work and to communicate status information aboutthe work to the XPS CLIENT.

CA 7 can act as the XPS CLIENT by requesting work on other platforms andcan also act as the XPS SERVER by submitting and tracking work in responseto requests from XPS CLIENTs.

Chapter 6. Cross-Platform Scheduling 201

This section discusses the requirements that allow CA 7 to participate in thecross-platform scheduling environment. All forms of cross-platform schedulingrequire communications between systems using CA Common CommunicationInterface (CAICCI). The other requirements necessary for CA 7 to run as anXPS CLIENT are distinct from those that are needed for CA 7 to act as an XPSSERVER. For this reason, the discussion of CA 7 and cross-platformscheduling follows in two sections: “The XPS CLIENT” on page 207 and “TheXPS SERVER” on page 223.


CAICCI Cross-Platform Connections


The MVS system and the system running the other scheduler or agent must beconnected by CAICCI (CA Common Communications Interface). Specifically,Cross-Platform Scheduling uses the TCP/IP Gateway protocol of CAICCI. Theconnection can be defined on the MVS side, the non-MVS side, or on both.

Ideally, the connection definitions are made on the system with the fewestnumber of connections, and/or the system that is recycled most often. A typicalsite probably has a small number of MVS systems that are active the majorityof the time and many non-MVS systems, some of which may be shut downfrequently. In this case, it makes sense to make the CAICCI connectiondefinitions on the non-MVS system.



Non-MVS CAICCI Connections

CAICCI connections are defined in the following files, depending on theplatform:

Platform Product File

UNIX CA NSM JobManagementOption orAgent

$caiglbl0000/cci/config/<machine-name>/ccirmtd.prfwhere <machine-name> is the CCI name of the machine.

Windows CA NSM JobManagementOption

\TNG\CAIUSER\CCIRMTD.RC

Windows Agent \CA\CAIUSER\CCIRMTD.RC

The format of the CCIRMTD file is the same on all non-MVS platforms. The firstline must be a LOCAL statement and can be followed by any number ofREMOTE statements.

LOCAL = ip-address cciname blocksize [STARTUP] [PORT=nnnn] [ALIAS=xxxxxxxx]REMOTE = ip-address cciname blocksize [STARTUP] [PORT=nnnn] [RETRY=n]

"ip-address" is either the numerical TCP/IP address of the node, or a name thatcan be resolved into a TCP/IP address. A TCP/IP PING command on this valueshould be successful.

"cciname" is the name that CAICCI will use for this node. This value may ormay not be the same as the IP address. The name must match the CAICCIname defined at the remote node. For MVS, the CAICCI name is defined by theSYSID parameter in the CAICCI parameters.

If STARTUP is specified, the connection is attempted as soon as CAICCI starts.We recommend this.

PORT specifies the TCP/IP port number to use. The default is 1721, which isthe default port for CA NSM Job Management Option and agent. The defaultport on MVS is 7000 and can be changed on the PROTOCOL(TCPIPGW....)statement.

ALIAS is only valid on the LOCAL statement. If the "cciname" is longer thaneight characters, a one- to eight-character alias must be used to accommodateCAICCI on MVS systems. Other CAICCI systems see the local system by thisalias name.

RETRY is only valid on the REMOTE statement. If the connection cannot bemade or is broken, CAICCI will retry the connection every n minutes.



CAICCI must be restarted to pick up changes to the CCIRMTD file.



MVS CAICCI Connections

CAICCI protocol and connection definitions on MVS reside in the CAICCIparameters, which are pointed to by the CAIENF started task.

A TCP/IP Gateway PROTOCOL statement is required for any CAICCIcross-platform scheduling communication. This is necessary even if theindividual node connnections are defined on the non-MVS platforms. The typesof TCP/IP Gateway protocols are TCPIPGW, TCPIP3GW, and TCPIPSGW.For specific information about these protocols, see the CAICCI User Guide.

Each remote connection definition requires both a NODE and CONNECTstatement.

NODE(TCPIPGW,ip-address:port,retry,cciname)CONNECT(cciname)

"TCPIPGW" should match the type of gateway specified on your PROTOCOLstatement (TCPIPGW, TCPIP3GW, or TCPIPSGW).

"ip-address" is either the numerical TCP/IP address of the node or a name thatcan be resolved into a TCP/IP address. A TSO PING command on this valueshould be successful.

"port" specifies the TCP/IP port number in use at the specified node.

"retry" specifies the number of minutes between attempts to establish orreestablish the connection.

"cciname" is the name that CAICCI will use for this node. This value may ormay not be the same as the IP address. The name must match the CAICCIname defined at the remote node (or the ALIAS= if specified). On MVS, thenode name is not case sensitive.

The NODE and CONNECT statements can also be issued from a console byprefixing the command with "ENF'. For example:

ENF CONNECT(NODEX)


The XPS CLIENT

The XPS CLIENT

The XPS CLIENT for CA 7 sends scheduling requests to a CA schedulingsolution (XPS SERVER) that can be running on a remote platform and receivesstatus feedback (job initiation and job termination information) from the XPSSERVER.

The XPS CLIENT for CA 7 performs two functions: submission and tracking.Jobs can be submitted to a remote platform directly (XPJOB definitions) or byusing the batch program CA7TOUNI. The tracking function is provided by theCA 7 Cross-Platform Tracking System (XTRK).

Direct Submit Function

When CA 7 detects a job should be submitted for execution, CA 7 reads thedatabase and determines the type of job. If the job is an internal cross-platformjob (XPJOB), CA 7 builds a request containing the information required to runthe job on the remote platform. The remote platform location, or node, isextracted from the XPJOB definition. After all requirements are met, CA 7sends this information to the remote platform using CA Common ServicesCAICCI.

Note: For more information about the XPJOB definition and the DB.10 panel,see the Database Maintenance Guide.

No JCL is associated with XPJOB definitions, and no separate batch job buildsand sends the scheduling request to the remote platform. The job is validatedagainst rules relevant for XPJOBs as opposed to regular CPU jobs (forexample, a JOB statement is not required). All the CA 7 features that areapplicable to regular jobs (triggering, scheduling, prose, and so on) areapplicable for XPJOBs. XPJOBs flow through the CA 7 queues the same asregular CPU jobs. A CPU indication of XPJ distinguishes it from a regular CPUjob.


The XPS CLIENT

XPJOB definitions provide many benefits when compared to using the batchprogram CA7TOUNI.

■ The XPJOB function makes it simpler for users not familiar with z/OS JCLto schedule cross-platform jobs.

■ XPJOB definitions provide a method to secure sensitive data. Normally,CA7TOUNI parameters are coded in-stream with the job's JCL, making userIDs, passwords, or both visible in JES displays. Optionally, this informationcan be placed in yet another data set that the JCL must reference. WithXPJOB definitions, the sensitive data does not appear in JES displays andmay be stored in the CA 7 data base, an indirect location, or in the jobdefinition's parameter library. Access to this data can be protected usingCA 7's external security interface.

■ XPJOB definitions improve system resource utilization by eliminating theneed to run a z/OS job for every cross-platform job. This reduces oreliminates the overhead and runtime problems that users often face whendealing with batch jobs. Additional batch initiators are not required. XPJOBsjobs are not subject to JCL errors, extraneous resource conflicts, orprocessor delays often found with batch jobs.

■ Because transmission of the XPJOB request is handled entirely within theCA 7 address space, more effective control of the job submission processoccurs at program level. If an alternative remote node is defined for theprimary remote platform node, and the primary remote platform node is notcurrently active, CA 7 can reroute the XPJOB information to the alternatenode. Also, with direct connections to the remote nodes, a user can requesta job cancellation, assuming the cross-platform agent supports such arequest.

■ CA 7 relies on SMF data for posting batch job information. Using aninternal interface to communicate to the cross-platform agent eliminates theSMF tracking overhead, delays, and ambiguities. Because thecross-platform jobs are submitted for execution through a separate subtaskdirectly to CA Common Services CAICCI, the normal batch job throughputthrough a JES internal reader is reduced.

Sites can convert their CA7TOUNI jobs to XPJOB definitions using theCA7TOUNI-to-XPJOB Conversion Utility.

Note: For more information about the CA7TOUNI-to-XPJOB Conversion Utility,see Appendix A, “CA7TOUNI Conversion Utility” on page 321.


The XPS CLIENT

Batch Submit Function

The batch submission program CA7TOUNI can also send jobs to a remoteplatform. This was the initial method CA 7 used to schedule jobs on a remoteplatform and is still supported. Sites wanting to use variable substitution for theNODE name or wanting a protected data set for password information shouldcontinue to use the batch CA7TOUNI program. Sites that do not have a CAICCIconnection on the operating system where CA 7 runs should also useCA7TOUNI because it lets them route the job for execution on an operatingsystem with a CAICCI connection.

Note: For more information about using batch program CA7TOUNI, seeAppendix B, “Batch Program CA7TOUNI” on page 351.

Direct Submit Function Parameters

| Parameter data, previously contained in z/OS JCL (when using batch program| CA7TOUNI), is now located in a parameter library that is identified in the| XPJOB definition. Two of the CA7TOUNI required parameters, XPNODE and

XPEXEC, are now part of the XPJOB definition.

Note: For more information about the XPNODE and XPEXEC parameters, seethe Database Maintenance Guide.

The following describes all the parameters that are valid for XPJOB definitions:

DOMAIN(Optional) Defines a domain name and can be required for some requestssent to Windows platforms.


Source: Optional parameter library or associated to a node/owner accessdefinition (for more information, see XPSWD in the Database MaintenanceGuide).


The XPS CLIENT

LINELEN(Optional) Controls the line length of the SYSIN input for the SUBFILE andPARMxx keyword parameters. Normal XPJOB submission processingautomatically determines whether columns 73 to 80 contain line sequencenumbers (LINELEN=AUTO). If column 72 contains a blank, null, or plussign, and columns 73 to 80 are numeric, columns 73 to 80 are consideredto be line sequence numbers. Line sequence numbers are not consideredpart of the PARMxx keyword value.

The LINELEN keyword can override this automatic determination and forceXPJOB submission processing to consider the full 80-byte record as part ofthe data area (LINELEN=80). Or it can force XPJOB submission processingto ignore columns 73 to 80 (LINELEN=72) regardless of the contents ofthose columns.

Default: LINELEN=AUTO

Limits: AUTO, 72, and 80 are the only allowed values

Source: Optional parameter library

Note: This keyword can be specified multiple times. Processing forPARMxx keywords is controlled by the last valid LINELEN specificationprocessed before the current line.

PARM1 thru PARM64(Optional) Supply values to be used on the target platform. Values can be1 to 256 characters. Avoid special characters because they may nottranslate correctly on the target platform. Embedded blanks cause the valueto be enclosed in double quotes by the XPS SERVER on the targetplatform. Because the parameter library is limited to 80 characters,continuation may be required. To continue a record, end it with a plus sign(+) and continue in column 1 of the next statement. The ending plus signdoes not appear in the resulting value. Keyword checking is suspendedduring a continuation operation.


Source: Optional parameter library. If only one parameter is needed (and itis 128 characters or less), it can be specified in the XP PARM field on theXPJOB definition, described in the Database Maintenance Guide.

Note: The contents of columns 73 to 80 can be included or excludedbased on the processing controls currently in effect. Normally, linesequence numbers in columns 73 to 80 are ignored. For more information,see the preceding LINELEN parameter.


The XPS CLIENT

SUBPASS(Optional) Identifies the password to be passed with SUBUSER to thetarget platform. The password is sent to the target system in an encryptedformat. Some target systems may require that a password accompany theSUBUSER on cross-platform requests.



Note: XPJOB definitions provide a number of more secure alternatives tousing SUBPASS and SUBUSER. Review the OWNER parameter in theXPJOB definition and the XPSWD command. For more information aboutXPJOB and XPSWD, see the Database Maintenance Guide. For moreinformation about the XPDEF initialization file statement, which discussesthe hierarchy of cross-platform job submission user ID and passwordprocessing, see the Systems Programmer Guide.

SUBUSER(Optional) Identifies the user ID for security purposes on the target platform.



Note: XPJOB definitions provide a number of more secure alternatives tousing SUBPASS and SUBUSER. Review the OWNER parameter in theXPJOB definition and the XPSWD command. For more information aboutXPJOB and XPSWD, see the Database Maintenance Guide. For moreinformation about the XPDEF initialization file statement, which discussesthe hierarchy of cross-platform job submission user ID and passwordprocessing, see the Systems Programmer Guide.

Additional parameters that are valid for CA7TOUNI jobs are either notapplicable for XPJOBs (for example, JOBNO, JOBSET, SUBCHECK, 7TRACE),or handled differently. MONITOR information is now extracted from theXMONITOR keyword of the XPDEF file initialization statement. Sites wanting touse the equivalent of SUBROOT must set the SUBROOT keyword of theXPDEF file initialization statement to Y and associate the ROOT user ID to anOwner or Node using the XPSWD command. Lastly, SUTYPE is now a field inthe XPJOB definition.


The XPS CLIENT

Cross-Platform Tracking

Tracking consists of the XPS SERVER returning feedback records for CA 7submitted jobs to the system that sent the request. These records aretransmitted using CA Common Services CAICCI and represent job initiation, jobtermination, and job failure events.

The CA 7 Cross Platform Tracking System (XTRK), running on the MVSsystem where the CA 7 cross-platform job submission occurred, receives theseevents and converts them to SMF-like feedback recognized by CA 7. CA 7then processes this information like any other job to determine when it becomesactive, completes, or fails. There should be one copy of CA 7 XTRK per CA 7instance executing on each system where CA 7 cross-platform jobs can besubmitted.

CA 7 XTRK can be run as any of the following:

■ Started task/batch job

■ Subtask under ICOM

■ Subtask under CA 7 (preferred method)

Running CA 7 XTRK as a subtask under CA 7 is the recommended executionmethod. This method is required for tracking XPJOB defined jobs submitteddirectly from CA 7. It also tracks jobs submitted using CA7TOUNI. Sites notplanning to allow XPJOB definitions can run CA 7 XTRK as a started task,batch job, or subtask under ICOM.

Note: For more information about running CA 7 XTRK as a started task orbatch job, see Appendix C, “XTRK as a STC or Job” on page 361. For moreinformation about running CA 7 XTRK as a subtask under ICOM, seeAppendix D, “XTRK Under ICOM” on page 367.

Sites wanting to take advantage of the CA 7 XTRK High Availability Option(HAO) must run CA 7 XTRK as a subtask under CA 7. HAO allows a backup(or failover) system of CA 7 to continue tracking cross-platform jobs (XPJOBjob type) submitted by the downed CA 7 system. If a site has a dormant copyof CA 7, or starts CA 7 on another system, with the same primary name as theoriginal CA 7 system, CA Common Services CAICCI reroutes the trackinginformation to that CA 7 system so that XPJOB posting continues to occur.

Also, events such as job execution and file creation/update that occur onnon-MVS platforms can be tracked even though CA 7 did not request that work(Cross-Platform External Tracking). A CA scheduler or agent must be executingat the remote node for this tracking to occur.


The XPS CLIENT

Cross-Platform Tracking Under the CA 7 Started Task

To execute CA 7 XTRK as a subtask under CA 7, do the following:

1. Define CAICCI connections among systems. For more information, see“CAICCI Cross-Platform Connections” on page 203.

These CAICCI connections are the same regardless of which side is actingas the XPS CLIENT or XPS SERVER.

Note: This interface requires CA Common Services for z/OS.

2. Update the CA 7 started task JCL to include the following JCL DDstatement:

//XCKPT DD DISP=OLD,DSN=xtrkcheckpoint

The XCKPT DD points to the CA 7 Cross-Platform Checkpoint file. Eachcopy of CA 7 XTRK must have its own Checkpoint file. The DCBparameters for the Checkpoint files are:

DSORG=PS,RECFM=FB,LRECL=4�96,BLKSIZE=4�96

CA 7 JCLLIB member CA07N010 (prefix may have changed based on theSYSGEN) allocates a checkpoint file that can be used for the XCKPT DDstatement. Optionally, sites can use an existing CA 7 XTRK checkpointdata set that is currently used in a XTRK started task, batch job, or ICOMJCL stream. This assumes sites are converting to run CA 7 XTRK as asubtask under CA 7.

//XPRINT DD SYSOUT=

The XPRINT DD specifies the SYSOUT class for CA 7 XTRK tracemessages. The type and volume of messages produced is controlled by thefirst value of the XTRKTRC keyword of the XPDEF initialization filestatement.

//XSNAP DD SYSOUT=

The XSNAP DD specifies the SYSOUT class for CA 7 XTRK storage snapoutput. The type and volume of output produced is controlled by the secondvalue of the XTRKTRC keyword of the XPDEF initialization file statement.

//XEVENTS DD DISP=SHR,DSN=xtrk..xtracking(rules) optional

The XEVENTS DD is optional.

Note: For more information about the XEVENTS DD statement, see “CA 7Cross-Platform External Tracking” on page 218.

3. Update the CA 7 started task initialization file tracking tracing statement ifneeded.

XTRKTRC=21

CA 7 XTRK is automatically enabled when an XCKPT DD statement isfound in the CA 7 online started task.


The XPS CLIENT

Note: For more information about the XPDEF initialization file statementkeywords, see the Systems Programmer Guide.

4. Recycle the CA 7 started task. Check for the CAL2X101I - CAL2X103Imessages (in the CA 7 JOBLOG) showing the status of the cross-platformtracking subtask under CA 7.

5. Define CA 7 cross platform-jobs using the XPJOB definition function.

Note: For more information about the XPJOB function, see the DatabaseMaintenance Guide.

6. Schedule/Demand the XPJOB definition on CA 7.

Note: For more information about scheduling and demanding CA 7 jobs,see the Database Maintenance Guide.

Set up the High Availability Option (HAO) of CA 7 XTRK

Sites can take advantage of HAO by assigning a value to the XPDEF fileinitialization statement XPHAO keyword. The XPHAO value must be uniqueacross the enterprise. If two or more copies of CA 7 have the same XPHAOvalue, it cannot be determined which copy should receive the cross-platform jobfeedback.

If the XPHAO value is set, and a secondary dormant copy of CA 7 is active,cross-platform failover is automatically handled should the primary copy ofCA 7 fail.

Note: For more information about setting up a dormant copy of CA 7, see theSystems Programmer Guide.

Sites can also shut down CA 7 and resubmit the same CA 7 started task on adifferent LPAR. As long as the XPDEF file initialization statement XPHAOkeyword has not changed, cross-platform tracking information will be routed tothe new copy of CA 7 as soon as it is active.

Important! If you chose to activate HAO, you should do so when no XPJOBcross-platform jobs are active. Failure to do so could result in cross-platformtracking information not being returned to the originating copy of CA 7.


The XPS CLIENT

CA 7 Cross-Platform Tracking Commands

Sites running CA 7 XTRK as a subtask under CA 7 can use the /XTASKcommand to display its status or add/update information. CA 7 XTRK runningas a batch job, started task, or subtask under ICOM accepts MODIFY or STOPoperator commands. The following explains the parameters that are available:

ADDNODE(nnnnnnn)Adds a CAICCI node (nnnnnnnn) to the XTRK Node Table. XTRK willattempt to establish communications with that node.

BLDXEVTRebuilds the Cross-Platform External Tracking table from the rules definedin the XEVENTS DD. If the rebuild is successful XTRK will attempt toresynchronize with each remote node to pass the new set of externaltracking rules.

DELNODE(nnnnnnn)Deletes a CAICCI node (nnnnnnnn) from the XTRK Node Table. XTRK willno longer attempt to communicate with that node.

NODE[(nnnnnnnn),status]Lists nodes from the XTRK Node Table indicating the current status, lastactivity and checkpoint dates and times. The default is to list all nodes. Afull or partially qualified argument can be specified to limit the display. Forexample: NODE(AIX*). See messages CAL2X155I and CAL2X156I. Inaddition to a node argument, a status argument can be specified to limitthe display to nodes that have a particular connection status. The statuskeywords match the status displayed in the CAL2X156I message (ACTIVE,LOSTCONN, SYNCH, NO CONTACT, DELETED), plus a special keyword,INACT, which will select nodes that are not active (for any reason). Forexample, NODE(AIX*),INACT. Or, NODE,ACTIVE.

NODEN[(nnnnnnnn),status]Lists nodes from the XTRK Node Table indicating the CAICCI node nameand the remote node name. This display can be useful if you are usingCAICCI Alias names. The default is to list all nodes. A full or partiallyqualified argument of the CAICCI node name can be specified to limit thedisplay. For example: NODEN(AIX*). See message CAL2X154I. Inaddition to a node argument, a status argument can be specified to limitthe display to nodes that have a particular connection status (see theprevious NODE command).

NODEX[(nnnnnnnn),status]Lists nodes from the XTRK Node Table indicating the current status, lastactivity and checkpoint dates and times, and the internal status flags. Thedefault is to list all nodes. A full or partially qualified argument can bespecified to limit the display. For example: NODEX(AIX*). See messagesCAL2X155I and CAL2X156I. In addition to a node argument, a statusargument can be specified to limit the display to nodes that have aparticular connection status (see the previous NODE command).


The XPS CLIENT

PINGForces the XTRK Tracking Manager to send a CAICCI record to each nodein the XTRK Node Table to confirm a connection, or attempt to initiate aconnection. Normally this process is done on a timer basis.

SNAP(..option..)Forces a storage snap to be written to the XSNAP DD (if available andopen). The options are:

SVTXTRK System Vector Table

TABXTRK Node Table Blocks

XEVTXTRK External Event Table entries

ALLAll of the above

STOPCauses XTRK to perform normal shutdown processing. This can also bedone using the operator STOP command (P CA7XTRK).

TRC(pc)Without any operands it causes a display of current XTRK trace settings(see message CAL2X159I). With operands:

TRC(pc)Resets the current trace code settings. For example: TRC(21) sets theprint trace code to 2 and the console trace code to 1. Both codes mustbe specified.

TRC(OPEN,...)Causes the PRINT or SNAP file to be opened.

TRC(CLOSE,...)Causes the PRINT or SNAP file to be closed.

TRC(RESET,...)Causes the PRINT or SNAP file to be closed and then opened.

XEVTLists rules from the XTRK External Tracking Event table. See messagesCAL2X185I and CAL2X186I. The default is to list all event rules. A full orpartially qualified CAICCI node argument can be specified to limit thedisplay to only those rules that apply to that node argument. For example:XEVT(AIX*).


The XPS CLIENT

The following are some examples that display the command syntax for CA 7XTRK running as a subtask under CA 7, CA7 XTRK running as a batch job,and CA7XTRK running under ICOM. Command output is written to the CA 7 orbatch job JOBLOG.

Add a Node

CA 7 Subtask - /XTASK,M=(CMD,TRACKER,ADDNODE(TESTNODE))Batch Job - F jobname,ADDNODE(TESTNODE)ICOM - F CA7ICOM,XTRK=ADDNODE(TESTNODE)

Display Nodes

CA 7 Subtask - /XTASK,M=(CMD,TRACKER,NODE(TEST ),ACTIVE)Batch Job - F jobname,NODE(TEST ),ACTIVEICOM - F CA7ICOM,XTRK=NODE(TEST ),ACTIVE

Display Nodes

CA 7 Subtask - /XTASK,M=(CMD,TRACKER,NODEX)Batch Job - F jobname,NODEXICOM - F CA7ICOM,XTRK=NODEX

Ping Nodes

CA 7 Subtask - /XTASK,M=(CMD,TRACKER,PING)Batch Job - F jobname,PINGICOM - F CA7ICOM,XTRK=PING

Delete Nodes

CA 7 Subtask - /TASK,M=(CMD,TRACKER,DELNODE(TESTPLN))Batch Job - F jobname,DELNODE(TESTPLN)ICOM - F CA7ICOM,XTRK=DELNODE(TESTPLN)

Change Trace Settings

CA 7 Subtask - /TASK,M=(CMD,TRACKER,TRC(22))Batch Job - F jobname,TRC(22)ICOM - F CA7ICOM,XTRK=TRC(22)


The XPS CLIENT

CA 7 Cross-Platform External Tracking

The CA 7 Cross-Platform Tracker (XTRK) can request notification of job eventsand file create/updates from a CA scheduler or agent. For jobs to be tracked,they must be under the control of the CA scheduler or agent. However, thecreation or update of files can be detected by the CA scheduler or agent even ifit is done by a task outside of their control.

When XTRK starts, it checks for an XEVENTS DD statement. If present, itshould point to a 80-byte statement-image data set or PDS member thatcontains the event rules for CA 7 Cross-Platform External Tracking. WhenXTRK establishes communication with a remote system, it passes to thatsystem the rules that apply to it. When a matching job initiation, termination, orfile create/close occurs on that system, the feedback record for that event issent to XTRK using the same format as normal cross-platform work.

When XTRK receives this external feedback it will generate pseudo-SMFrecords for CA 7 that match the format of CA 7 External Tracking. The CA 7address space treats these pseudo-SMF records in the same manner as otherexternal tracking records. For information about setting up CA 7 to processexternal tracking, see the Systems Programmer Guide.

For cross-platform external file creates/updates, SASSXDSN is not required.


The XPS CLIENT

The general syntax of an event definition in XEVENTS is:

EVENT( - NODE(cciname) - TYPE(JOB|DSN|CONNECT) -

NAME(external job name or file name) - JNO(nnnn) -

JOBSET(external jobset name) -MVSNAME(mvs job or data set name) -

STAT(N|Y) - )

The keywords within the EVENT( can be in any order. Not all keywords aremeaningful for all types of events. Unless otherwise specified, case does notmatter. All data must be between columns 1 and 72. To continue lines at anypoint (inside or outside a keyword), end the line with " -" (a blank followed by adash). The line is continued with the first non-blank character on the next line.To code comments, place an asterisk (*) in column 1.

TYPE(Indicates the type of event. Valid values are JOB, DSN or CONNECT.TYPE( is required for all events.

TYPE(JOB)Indicates that matching job initiation and termination events should betracked.

TYPE(DSN)Indicates that matching file creation/update events should be tracked.

TYPE(CONNECT)Indicates that XTRK should always attempt to establish contact withthe CAICCI node specified in the NODE( parameter.

JNO(For event TYPE(JOB), the four-digit job number of the job to be tracked asdefined to CA NSM Job Management Option.JNO( is REQUIRED for TYPE(JOB) events. It is ignored for other types.

For CA AutoSys, use a fixed value of 0001.

JOBSET(For event TYPE(JOB), the jobset name of the job to be tracked as definedto CA NSM Job Management Option.JOBSET( is REQUIRED for TYPE(JOB) events. It is ignored for othertypes.

For CA AutoSys, use a fixed value of XXXX.

MVSNAME(For event TYPE(JOB), the job name that conforms to MVS standards to beused by CA 7 to track this job.For event TYPE(DSN), the fully qualified data set name that conforms toMVS standards to be used by CA 7 to track this file.MVSNAME( is REQUIRED for TYPE(JOB) and TYPE(DSN) events.


The XPS CLIENT

NAME(For event TYPE(JOB), the name of the job to be tracked as defined to theother CA scheduling system.For event TYPE(DSN), the fully qualified name of the file to be tracked, orin certain configurations masking is allowed. For more information aboutmasking, see the Command Reference Guide. The value of NAME( iscase-sensitive when used for a job name, and it may be case-sensitivewhen used as a file name, depending on the target platform.NAME( is REQUIRED for TYPE(JOB) and TYPE(DSN) events.

NODE(The CAICCI node name at which the other CA scheduler or agent shouldwatch for this event. For TYPE(CONNECT) it is the node name that XTRKshould always establish contact with.NODE( is REQUIRED for all events.NODE( must be fully qualified for TYPE(CONNECT) events.NODE( can be fully qualified, partially qualified or fully generic forTYPE(JOB) or TYPE(DSN) events.

STAT(For EVENT(DSN), STAT( indicates which method should be used on UNIXmachines to determine when the file has been updated. STAT(N), thedefault, uses hooks in the UNIX kernel and is the fastest and most reliablemethod. STAT(Y) uses a UNIX statistics utility to determine when the filehas been updated. For more information about these methods, see thedocumentation for the other CA scheduler or agent.STAT( is optional for EVENT(DSN) events and ignored for all other events.

To display the current external events, use the XTRK command XEVT.

To rebuild the table of external events, use the XTRK command BLDXEVT.

Note: For more information about these commands, see “CA 7 Cross-PlatformTracking Commands” on page 215.


The XPS CLIENT

XEVENTS Example 1

EVENT( TYPE(DSN) - NODE(NTBOX1) - NAME(c:\dir\myfile.txt) - MVSNAME(NTBOX1.MYFILE.TXT) )

When file c:\dir\myfile.txt is created or updated on node NTBOX1, XTRK willtrack the creation/update of data set name NTBOX1.MYFILE.TXT as a CA 7external data set.

XEVENTS Example 2

EVENT( TYPE(JOB) - NODE(UNIX�1) - NAME(payjob-on-unix) - JNO(��1) - JOBSET(payroll-jobset-on-unix) - MVSNAME(UNIXPAY1) )

The other CA scheduler or agent will send XTRK feedback when job'payjob-on-unix', job number '0001' in jobset 'payroll-jobset-on-unix' initiates andterminates at node UNIX01. XTRK will track it as a CA 7 external job with thename UNIXPAY1.

XEVENTS Example 3

EVENT( TYPE(JOB) - NODE(AIX ) - NAME(aix-job1) - JNO(��1) - JOBSET(aix-jobset) - MVSNAME(AIXJOB1) )

Each CA scheduler or agent that XTRK connects with, whose CAICCI Nodename begins with the characters 'AIX', will be asked to send XTRK feedbackwhen job 'aix-job1', job number '0001' in jobset 'aix-jobset' initiates andterminates. XTRK will track it as a CA 7 external job with the name AIXJOB1.This definition allows you to set up one rule that will capture tracking for this jobregardless of which AIX machine it runs on.


The XPS CLIENT

XEVENTS Example 4

EVENT( TYPE(CONNECT) NODE(AIX��1) )EVENT( TYPE(CONNECT) NODE(AIX��2) )EVENT( TYPE(CONNECT) NODE(AIX��3) )

These rules ensure that XTRK will attempt to communicate with each of thesesystems (AIX001, AIX002, AIX003). Normally, XTRK communication will onlytake place if CA 7 submits a cross-platform job to that remote system. If yousimply want to listen for cross-platform external tracking events at a node, theTYPE(CONNECT) rule ensures that XTRK will attempt to establishcommunication with that system.

Usage Notes

Duplicate External Events: If you are running CA 7 Cross-Platform TrackingSystem (XTRK) on more than one MVS image, you should not use the sameXEVENTS rules for both copies. If you do, each XTRK could receive feedbackfor the same remote job or file event. Depending on the timing of XTRK, ICOM,and CA 7 processing, this could result in duplicate triggers (at worst), orunnecessary overhead in the CA 7 address space (at best). We recommendhaving one copy of XTRK handle the Cross-Platform External Tracking forCA 7.

Using TYPE(CONNECT) Event Rules: Normally the CA 7 Cross-PlatformTracking System (XTRK) only communicates with those remote systems whereCA 7 Cross-Platform jobs are submitted to. If you want to use CA 7Cross-Platform External Tracking for remote systems that do not receive anyCA 7 cross-platform work, you need to define at least one XEVENTS rule thatexplicitly references that node. If the only rules that apply to that node havegeneric NODE( parameters, use a TYPE(CONNECT) rule to explicitly identifythe node to XTRK.

SASSEXTT Model Queue Record Table Module: For CA 7 to track externaltasks (local or cross-platform), the Model Queue Record Table module,SASSEXTT, must be available to the CA 7 address space. The ExternalJob/STC Filter Table module, SASSEXTL, is NOT required for cross-platformexternal tracking. For information about enabling CA 7 external tracking, seeTracking External Tasks in the Systems Programmer Guide.


The XPS SERVER

The XPS SERVER

The CA 7 XPS SERVER receives scheduling requests from a CA schedulingsolution that can be running on a remote platform. It responds by servicing therequests (job submission), and returning appropriate feedback to the XPSCLIENT. In this way, the XPS CLIENT is notified of job initiation andtermination.

The CA 7 XPS SERVER comprises two distinct functions: the XPS SUBMITMONITOR and the XPS Router. The programs that make up the XPS Routerfunction normally run as subtasks in the CA 7 address space. The XPSSUBMIT MONITOR function is accomplished by main task and subtaskprograms.

The XPS Submit Monitor

The XPS SUBMIT MONITOR is the function that interprets the schedulingrequest from the XPS CLIENT, schedules the job in CA 7 and sends statusfeedback to the XPS CLIENT through the XPS Router.

The XPS SUBMIT MONITOR is responsible for two activities: submission ofCA 7 jobs and creating status information for the XPS CLIENT.


The XPS SERVER

Submission

The XPS Router forwards a scheduling request from an XPS CLIENT to theXPS SUBMIT MONITOR using CAICCI. The SUBMIT MONITOR builds aterminal command based on parameters provided in the scheduling request orfrom options coded in the CA 7 initialization file. The submit MONITOR thenuses an internal terminal to issue a command that causes the job to bescheduled. The definition of an internal terminal is marked by the specificationof DEVICE=TRXDV. If CA 7 is to be an XPS SERVER, at least one internalterminal must be defined.

The value of the XPSSCHD keyword on the SVCNO and XPDEF statements inthe CA 7 initialization file determines the scheduling command that is issuedwhen a cross-platform scheduling request is received.

For more information about this important parameter, see “Manage theCross-Platform Workload” on page 232 and the discussion of the XPSSCHDkeyword of the SVCNO and XPDEF initialization file statements in the SystemsProgrammer Guide.

The XPS SUBMIT MONITOR respects CA 7 terminal security. A USERID isrequired for the logon to the internal terminal used for the scheduling request.This USERID will determine the security in effect for the request. If no USERIDis supplied on the scheduling request from the XPS CLIENT then the value ofthe XPSSID keyword on the SECURITY statement will be used for the logon tothe internal terminal. If no USERID is supplied and if no value is coded for theXPSSID keyword then the scheduling requests will fail. For more information,see the Security Reference Guide.

If the default value for the XPSSCHD keyword is used, then jobs that arerequested by an XPS CLIENT will report an entry mode of 'XPS' in the outputof queue displays.

Jobs that are requested by another CA scheduling system must be defined onthe CA 7 database PRIOR to scheduling. If the job is not defined to CA 7, thescheduling request from the XPS CLIENT will fail.

The command that is used by the XPS SERVER to schedule the job isrecorded in the CA 7 Log. If an XPS CLIENT scheduling request fails, theterminal command as well as the CA 7 error message that is produced mayprove useful in problem determination.


The XPS SERVER

Status Update

The XPS SUBMIT MONITOR function will send status information to the XPSCLIENT in the form of CAIENF events. The CAIENF event that is used for thispurpose is named 'CAXPSFBK'. CA 7 will create CAXPSFBK records to signalstatus changes such as job initiation, job termination and job failure. TheseCAIENF events will be captured by the XPS Router and forwarded to the XPSCLIENT.

If the command used to schedule the job fails for any reason (for example,/LOGON failure, job not defined, and so on), CA 7 creates a CAIENF recordreporting the failure to be sent to the XPS CLIENT.

A CAIENF record reporting job initiation is created when CA 7 receives the jobinitiation record from SMF.

The value of the XPSSCHD keyword on the SVCNO and XPDEF initializationfile statements affect the way job completion status updates are reported to theXPS CLIENT. If the default of XPSSCHD=RUNREF is used, a CAIENF recordfor job completion is created immediately when the job terminates. IfXPSSCHD=DEMAND or XPSSCHD=RUN is coded, the job completion statusupdate is not reported until the job exits the request queue.

If a job requested by an XPS CLIENT is canceled in CA 7 prior to jobsubmission, then CA 7 will create a CAIENF record indicating that the jobfailed. If, however, the job has already run at least once, then a CAIENF recordindicating job termination will be created.

Note: Exercise care with jobs using XPSSCHD=RUNREF and CA 7 stepcondition code checking (#SSC statements). If #SSC processing detects anerror situation, then the code returned to the requesting system is the returncode detected by #SSC processing. This may or may not be the highestcondition code actually produced by the job.


The XPS SERVER

The Cross-Platform Scheduling Router (XPS Router)

To communicate with other CA scheduling solutions each system must presenta single point of communication. The cross-platform scheduling router (XPSRouter) is this single point of communication on MVS systems. On a given MVSsystem there can be more than one CA scheduling solution executing. Forexample, there can be multiple instances of CA 7 executing on the same MVSimage. The cross-platform scheduling router enables all instances of CA 7 toparticipate in cross-platform scheduling.

On MVS systems, the cross-platform scheduling router receives all requests forwork from other systems. It then routes each request to the appropriate CAscheduling solution on that system. The feedback information (job initiation,termination, failure) generated by the CA scheduling solution is used to createCAIENF cross-platform feedback events (CAXPSFBK). The cross-platformscheduling router intercepts these events and sends the feedback to theoriginal requester. Logging this information in CAIENF also prevents the loss offeedback data if communications problems interrupt the links among platforms.When the link is reestablished, the cross-platform scheduling router can retrievethe logged feedback events from CAIENF and send them to the system thatoriginated the request.

Cross-platform scheduling communication is performed by using the CACommon Communications Facility (CAICCI). A copy of CAICCI runs on eachsystem where CA solutions require it. The copies of CAICCI on each systemcommunicate with each other using various protocols based on CAICCI controlparameters. The gateway communication protocol is used for cross-platformscheduling (host-to-host connection).

Each copy of CAICCI has a unique identifier known as the node name. Oneach system, CA solutions register with the local copy of CAICCI as a CAICCIapplication. The local CAICCI then makes those applications known to thecopies of CAICCI on other systems that it is connected to. There are severalunique CAICCI application names that are used only for cross-platformscheduling. The combination of the node name and the unique CAICCIapplication names enable CA scheduling solutions to route requests for workand the feedback from that work.

Besides the unique node and CAICCI application names, each CA schedulingsolution that participates in cross-platform scheduling has a seven-characteridentifier known as a monitor name. In an MVS environment, each CAscheduling solution must have a monitor name that is unique in the local MVSenvironment. Thus, on a system where there are multiple instances of CA 7 atthe same node, each instance must have a different monitor name forcross-platform scheduling to work properly for all defined instances.


The XPS SERVER

The CAICCI application names used by cross-platform scheduling are based onthe functions they perform. The CAICCI application that receives requests forwork has a fixed name that is common to all systems, and there can only beone copy at a CAICCI node. Other CAICCI applications that participate incross-platform scheduling have a common format where the monitor namemakes them unique in the local CAICCI environment.

The CAICCI application names used in cross-platform scheduling are:

■ SUBMITC Server

This CAICCI application name receives requests for work from CAScheduling solutions on other systems. The SUBMITC Server routes therequest to the appropriate CA scheduling solution at that node(monitor-name Server).

There can only be one copy of the SUBMITC Server on a given noderegardless of how many CA Scheduling solutions are executing at thatnode. On MVS, this application is controlled by the cross-platformscheduling router. On non-MVS platforms there can only be one CAScheduling solution so the SUBMITC Server is controlled directly by thatsolution.

■ CAU9SET Setup Manager

This CAICCI application name controls the Checkpoint Synchronizationprocess with other systems. The Setup Manager initiates theSynchronization process and sends feedback (job initiation, termination,failure information) that was previously logged but not yet sent to the othersystem participating in the synchronization.

There can only be one copy of the Setup Manager on a given noderegardless of how many CA Scheduling solutions are executing at thatnode. On MVS, this application is controlled by the cross-platformscheduling router.

■ CAU9CTK Track Task

This CAICCI application name sends the real-time feedback (job initiation,termination, and failure information) to the remote system that requested apiece of work.

There can only be one copy of the Track Task on a given node regardlessof how many CA Scheduling solutions are executing at that node. On MVS,this application is controlled by the cross-platform scheduling router.


The XPS SERVER

■ monitor-name Job Submit or monitor-name Job Submit2

This CAICCI application sends a request for a job to be run on a differentsystem. The request for work is sent to the SUBMITC Server at the targetnode where the work is to be executed. The CAICCI application nameconsists of the seven character monitor name followed by the fixed text 'JobSubmit' or 'Job Submit2'.

There can be as many copies of Job Submit applications on a given nodeas there are CA Scheduling solutions executing at that node. On MVS,these applications are controlled by each CA scheduling solutionparticipating in cross-platform scheduling.

■ monitor-name Job track

This CAICCI application name receives the cross-platform feedback (jobinitiation, termination, and failure information) for jobs it requested to be runon a remote system. The feedback is sent either by the SetUp Manager orTrack Task at the system where the job was actually run. The CAICCIapplication name consists of the seven-character monitor name followed bythe fixed text 'Job track'.

There can be as many copies of Job track applications on a given node asthere are CA Scheduling solutions executing at that node. On MVS, theseapplications are controlled by each CA scheduling solution participating incross-platform scheduling.

■ monitor-name Server

There can be multiple CA scheduling solutions on a single MVS image.These CAICCI applications receive requests for work from the SUBMITCServer application running at the local node. The CAICCI application nameconsists of the seven-character monitor name followed by the fixed text'Server'.

There can be as many copies of Server applications on a given node asthere are CA Scheduling solutions executing at that node. Theseapplications appear only on MVS and are controlled by each CA schedulingsolution participating in cross-platform scheduling.


The XPS SERVER

Cross-Platform Server Password Requirements

The password requirement rules for the cross-platform server on MVS definewhen a password must accompany an explicit user ID in a cross-platformrequest. Using these rules you can discriminate between trusted andnon-trusted systems when receiving requests. That is, if you are confident thatrequests from a given system have already gone through security checks toensure that the user ID passed with the request should be honored, you canspecify a rule so that the cross-platform router will accept the user ID without apassword. For other systems that are not 'trusted' you can write rules so thatany request from them that contains a user ID must also carry a password thatcan be validated by the cross-platform server. Requests received from thesesystems that have a user ID but no password will be automatically rejected bythe XPS Router.

The Password Requirement process in the XPS Router will not validate theuser ID/password combination itself. That process will be done by the XPSServer scheduling system based upon it's own security processing (internal orexternal).

Password Requirement Rules are defined in a data set pointed to by theXPSPSWD DD statement in the Cross-Platform Scheduling Router (XPS)environment. This data set is a sequential file consisting of fixed 80 byterecords (physical sequential or a member of a PDS). The records can beblocked or unblocked. If the XPSPSWD DD statement is not present, orcontains no valid rules, the default processing is to accept all requests withoutchecking for the presence of passwords.

When the Cross-Platform Scheduling Router (XPS) goes through initializationprocessing it will attempt to locate and parse the Password Requirement Rules.If found, these rules will be stored in an in-storage table that will be accessedduring normal processing. Changes made to the rules will not take effect untilXPS is reinitialized.

Syntax Rules

■ Lines beginning with a blank or an asterisk (*) are considered commentlines.

■ Each individual rule must be contained on a single line between columns 1through 71. Continuation lines are not supported.

■ The rule definition consists of a series of keywords/values beginning incolumn 1, separated by commas with no embedded blanks.


The XPS SERVER

Keywords

NODE=caicci-node-nameIdentifies the one- to eight-character CAICCI node name that aCross-Platform request can be received from. It must be specified as aspecific name or an asterisk (*) that indicates all nodes. If not specified, thedefault is NODE=* indicating all nodes.

MONITOR=monitor-nameIdentifies the seven-character scheduling system monitor name that aCross-Platform request can be received from. It must be specified as aspecific name or an asterisk (*) that indicates all monitor names. In caseswhere a given node may have multiple scheduling systems (such asmultiple instances of CA 7), the NODE and MONITOR combination willuniquely identify a specific scheduling system. If not specified, the default isMONITOR=* indicating all monitor names.

ID=user-idIdentifies the one- to eight-character user ID that can be passed with across-platform request. It must be specified as a specific name or anasterisk (*) that indicates all user IDs. If not specified, the default is ID=*indicating all user IDs.

PSWD=YES/NOIndicates whether a cross-platform request that matches theNODE/MONITOR/ID parameters of the rule must have a password toaccompany the user ID in the request. A value of YES (or Y) indicates thatsuch requests must have a password. A value of NO (or N) indicates thatpasswords are optional for such requests. If not specified, the default isPSWD=YES.

Processing

When a cross-platform request is received by the XPS Router a check will bemade to determine if there is an explicit user ID contained in the request.

1. If the request does not contain a user ID, a password requirement checkwill not be made.

2. If the request contains both a user ID and a password, a passwordrequirement check will not be made.

3. If the request contains a user ID but no password, a password requirementcheck will be made.

The XPS Router will attempt to find the 'best match' between the currentrequest and the Password Requirement Rule Table based upon the NODE,MONITOR and user ID. A match with a rule that specifies a specific NODE,MONITOR and/or ID will take precedence over a generic rule. If multiple rulesequally match a request then the rules that require a password will takeprecedence over those that do not. If no match is found in the table then therequest will be allowed to proceed without a password.


The XPS SERVER

Examples

NODE=A�4IENF,MONITOR=CA7CA71,ID= ,PSWD=YES

The preceding rule indicates that any request from CAICCI node A04IENF,scheduling system CA7CA71 must have a password if it contains an explicituser ID.

NODE= ,ID=MASTER,PSWD=YES

The preceding rule indicates that any request that contains a user ID ofMASTER must have a password, regardless of what CAICCI node orscheduling system sent the request. Note that the default for MONITOR= is '*' ifit is not specified.

NODE=A�4IENF,ID=TESTUSER,PSWD=NO

The preceding rule indicates that a request from CAICCI node A04IENF with auser ID of TESTUSER is not required to have a password associated with it.

NODE=A�4IENF,ID= ,PSWD=YESNODE= ,ID=TESTUSER,PSWD=NO

If a request is received from CAICCI node A04IENF with a user ID ofTESTUSER it will partially match on both of the preceding rules. The secondrule will take precedence because a specific ID match will take precedenceover a specific NODE match. A password is not be required.

NODE=A�4IENF,MONITOR= ,ID= ,PSWD=YESNODE= ,MONITOR=CA7CA71,ID= ,PSWD=NO

If a request is received from CAICCI node A04IENF, scheduling systemCA7CA71 with any user ID it will partially match on both of the preceding rules.In this case the matches have equal weight (NODE or MONITOR specific, IDgeneric). In the case of a tie, the rule that requires a password will takeprecedence over one that does not. A password WILL be required.


The XPS SERVER

Manage the Cross-Platform Workload

The distributed nature of cross-platform scheduling emphasizes the need toconsider the question of managing the cross-platform workload.

There are two approaches to scheduling that can be distinguished in terms ofthe degree of control granted the XPS CLIENT versus the degree of controlgranted the XPS SERVER.

The manager-agent model may be useful in making this distinction. Thescheduling manager is the focal point of control for the workload. Thescheduling manager requests work and monitors status for purposes ofworkload control (evaluating requirements, triggering other work). Thescheduling agent initiates work at the request of the manager andcommunicates status information to the manager. Scheduling definitions(triggers, requirements) are primarily the responsibility of the schedulingmanager.

The question then arises: should scheduling manager functions be handled bythe XPS CLIENT or the XPS SERVER?

These roles are largely determined by the way in which cross-platform jobsenter CA 7. Cross-platform jobs can enter CA 7 in one of three ways:

■ Using a special variant of the RUN command referred to as RUNREF

■ The DEMAND command.

■ The RUN command.

CA 7 determines how the job will enter the request queue based on the valueof the XPSSCHD keyword on the XPDEF initialization file statement. Valuesinclude RUNREF, DEMAND and RUN.

By default, cross-platform jobs enter CA 7 using the RUNREF option. Thisassigns the role of scheduling manager to the XPS CLIENT, the requester ofthe job on another platform (for example, CA AutoSys). The primaryresponsibility for workload control belongs to the XPS CLIENT. Jobs scheduledusing this option do not honor requirements defined in CA 7, they are notconsidered requirements for other CA 7 jobs and they will not trigger otherCA 7 jobs at completion. This variant of the RUN command differs from thestandard RUN command in that it will not allow a CA 7 restart. A job scheduledusing this command is considered "complete" at either normal or abnormaltermination. An entry for the job will appear in the CA 7 RUNLOG, however noentry is created for the job in the prior-run queue.


The XPS SERVER

A greater degree of workload control over cross-platform jobs can be assignedto CA 7 using the XPSSCHD=DEMAND or XPSSCHD=RUN options. If eitherof these options is used, then additional management functions become theresponsibility of CA 7.

XPSSCHD=RUN confers additional responsibility on CA 7 for monitoring andcontrol of restart and rerun conditions. However, because the RUN command isused to schedule the job, CA 7 requirement and trigger definitions will beignored.

XPSSCHD=DEMAND confers even more management responsibility on CA 7.Because the DEMAND command is used to schedule the job, CA 7requirement and trigger definitions will be honored, and CA 7 must be used tomonitor restart and rerun conditions.

Note: The XPSSCHD keyword on the XPDEF initialization file statement isused to declare a global option that applies to all jobs requested from XPSCLIENTs. This parameter can be overridden for selected jobs by coding thiskeyword in the 'Filename' field (Job Detail - Submission - Filename) in CA NSMJob Management Option. See Step 6 in “CA 7 XPS Server ImplementationChecklist” on page 234.

Exercise care with jobs using XPSSCHD=RUNREF and CA 7 step conditioncode checking (#SSC statements). If #SSC processing detects an errorsituation, then the code returned to the requesting system is the return codedetected by #SSC processing. This may or may not be the highest conditioncode actually produced by the job.

The default schedule ID for cross-platform jobs is 1. This value can beoverridden for selected jobs by coding a SCHID keyword in the Filename field(Job Detail - Submission - Filename) in the requesting system definition. Formore information about SCHID, see “CA 7 XPS Server ImplementationChecklist” on page 234.


The XPS SERVER

CA 7 XPS Server Implementation Checklist

1. Define CAICCI connections among systems. See “CAICCI Cross-PlatformConnections” on page 203.


This interface requires CA Common Services for z/OS.

2. Define CAIENF Cross-Platform Scheduling Feedback Event (CAXPSFBK).

To define the CAXPSFBK CAIENF event and data elements, see themember JE10DCM in the CA Common Services Sample JCL library.

3. Add cross-platform scheduling keywords to the CA 7 initialization file.

Select the appropriate values for cross-platform scheduling on the XPDEFinitialization file statement:

a. Specify XSERVER=YES. This indicates to activate CA 7 XPS SERVERfunctions.

b. The XPS Router executes on only one copy of CA 7 at any givenCAICCI node. The XPS Router starts on the primary copy of CA 7 bydefault if XSERVER=YES is coded. If cross-platform scheduling is to beused only with a non-primary instance of CA 7, code XROUTER=YESon the XPDEF statement for that instance of CA 7 to start the XPSRouter.

c. Determine the appropriate value for the XPSSCHD parameter (on theXPDEF statement) based on the needs of your environment. Rememberthat the default value gives the greatest degree of workload control tothe XPS CLIENT and limited control to CA 7. If a greater degree ofcontrol over cross-platform jobs should be given to CA 7 consider eitherDEMAND or RUN values for XPSSCHD.

d. If you have more than one instance of CA 7 on the target MVS systemand you want to route jobs to all of them, determine the appropriatevalue for the XPDEF file initialization statement XMONITOR keyword. Ifthis keyword is enabled, the MONITOR name for a given instance ofCA 7 is displayed at startup in message 'CA-7.ISVC - XPS SERVERINITIALIZED. MONITOR VALUE: xxxxxxx. Refer to Step 6 in thischecklist for information on how this value is used.

At least one internal terminal must be defined for use by cross-platformscheduling. For more information about terminals with DEVICE=TRXDV,see the Systems Programmer Guide.

For information about the initialization options for CA 7 XPS SERVERfunctions, see the Systems Programmer Guide. You need to shut down andrestart CA 7 for these options to take effect.


The XPS SERVER

4. Define cross-platform scheduling password requirement rules.

If you want to define cross-platform scheduling password requirement rulescreate a data set or PDS member to hold the rules. Add an XPSPSWD DDstatement to the CA 7 JCL where the XPS Router will execute (see step 3b above). For information about coding the password requirement rules,see “Cross-Platform Server Password Requirements” on page 229.

5. In CA NSM Job Management Option, define a Station for the system whereCA 7 executes.

For the specific procedures to define a Station, see the CA NSM JobManagement Option documentation. The Station should represent the MVSsystem where CA 7 executes. The 'Station Type' should be CPU, and the'Node Type' should be MVS.

6. Define cross-platform jobsets and jobs on CA NSM Job ManagementOption.

For the specific procedures to define Jobsets and Jobs, see the CA NSMJob Management Option documentation.

a. Use the 'Station' defined above in the Job definition (Job Detail - MainPanel).

b. Specify the MVS job name that is defined to CA 7 in the 'Filename' field(Job Detail - Submission - Filename).

c. If you have more than one instance of CA 7 at the target MVS systemand you want to route this job to a specific instance of CA 7, add thekeyword ',MONITOR=monitor-name' after the MVS job name in the'Filename' field. For example, if you want to execute job TESTJOB1 onthe third instance of CA 7 whose monitor name is CA7CA73, specifythe following in Filename:

TESTJOB1,MONITOR=CA7CA73

d. The value of the XPSSCHD keyword on the XPDEF initialization filestatement specifies how a job requested by an XPS CLIENT is to bescheduled. This is a global value and applies to all jobs requested byXPS CLIENTs. To override this value for a specific job add the keyword',XPSSCHD=xpsschd-value' after the MVS job name in the 'Filename'field. For example, if job TESTJOB1 is to be DEMANDed on the thirdinstance of CA 7 but the XPSSCHD value in CA 7 is RUNREF, thenspecify the following in Filename:

TESTJOB1,MONITOR=CA7CA73,XPSSCHD=DEMAND


The XPS SERVER

e. If you want the requested CA 7 job to run with a schedule ID other than1, add the keyword ',SCHID=nnn' after the MVS job name in the'Filename' field. The value for SCHID must be 1 to 3 digits between 1and 255. For example, if job TESTJOB1 is to be DEMANDed withschedule ID 19, specify the following in Filename:

TESTJOB1,XPSSCHD=DEMAND,SCHID=19

f. If you want to specify a CA 7 user ID that will be used to bring the MVSjob into the CA 7 system, specify it in the 'Run as User', 'User' field(Job Detail-Submission-Run as User). Otherwise, the CA 7 user ID willdefault according to the XPSSID= option on the SECURITY statement inthe CA 7 initialization file. A password may or may not be requireddepending on the MVS Password Requirement Table described in Step4, above. If no Password Requirement Table has been set up, apassword is not required.

7. Define the MVS jobs to CA 7.

The jobs that will be initiated by cross-platform requests must be defined inthe CA 7 database. These are the MVS jobs identified in the 'Filename'field of the CA NSM Job Management Option jobs. For information aboutdefining a job in CA 7, see the CA 7 documentation.

The Automated Recovery Facility (ARF) CANNOT be used withcross-platform jobs.

8. Schedule/Demand the CA NSM Job Management Option Jobset.

For more information about procedures to schedule Jobsets/Jobs, see theCA NSM Job Management Option documentation.

When the cross-platform jobs are submitted the request will be routed toCA 7 on the specified MVS system (XPS SERVER), and the feedback fromCA 7 will be returned to the requesting system (XPS CLIENT).


Chapter 7. Email


Email Address Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Email Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Email Test Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Data Set for TCP/IP Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

CA 7 can generate and send email messages. The content of the emailmessages can be generic or contain information about a specific job in theCA 7 queues.

The EMAIL initialization file statement must be successfully processed beforethe CA 7 email interface is initialized. Sites can use the /DISPLAY,ST=EMAILcommand to determine whether the email interface has been initialized. Forinformation about the EMAIL initialization file statement, see the SystemsProgrammer Guide.

The email interface uses an email template (read from the EMAILLIB PDS) tobuild the body of the email. The template can have variables (such as&JOBNAME) that are resolved by CA 7 before the email is sent.

An email is sent to the list of email addresses in an email address member(read from the EADDRLIB PDS). One email can have 1 to 100 recipients. Ifadditional email recipients are needed, the email must be sent again using asecond email address member.

Emails are generated and sent when the /EMAIL command is issued. The/EMAIL command specifies an email template to use (using the TXT keyword)and an email address member to use (using the TO keyword). The /EMAILcommand can optionally specify a job in the CA 7 queues (using the JOBkeyword). For information about the /EMAIL command, see the CommandReference Guide.

The /EMAIL command can be issued anywhere a CA 7 top-line command canbe issued, including from an ARFSET.

Depending on your local implementation of TCP/IP, it may be necessary to adda //SYSTCPD DD statement to your CA 7 online JCL and your email test utility.

Note: CA 7 has no control over the delivery of emails. Therefore, CA cautionsagainst using email as the sole notification of a problem, such as an abendedor failed job.

Chapter 7. Email 237

Note for JES3 Sites: Regardless of whether you run IPv4 or IPv6, be sure thename of your global is in the HOSTS.LOCAL file for the system on which CA 7is running.


Email Address Members


Members of the EADDRLIB PDS are used to build the list of email addresses towhich an email is sent. The member name is specified by the TO=xxxxxxxxkeyword on the /EMAIL command.

Each member can have 1 to 100 email addresses. Each address must start incolumn one and can be up 70 characters long. The addresses can contain bothuppercase and lowercase letters, as well as any special characters needed inthe email address.

CA 7 does not verify the email address in any way. Email addresses are usedas is.

Email addresses can be internal or external to your company. Note that yourSMTP (email) servers may need to be configured to deliver mail outside of yourcompany.

Comments can be included in the email address member by starting eachcomment line with an asterisk in column one.

The default reply email address (specified by the EMAIL initialization filestatement on the EREPLY keyword) can be overridden by starting the firstemail address with the word "reply:" followed by the reply address. The newreply address starts immediately after the colon. The word "reply:" can be inuppercase or lowercase.



Example 1: The simplest address member is a single line with an emailaddress:

Top of Data =COLS> ----+----1----+----2----+----3----+----4----+----5----+--��1 [email protected] Bottom of Data

Example 2: An example of multiple email addresses with comments included:

Top of Data =COLS> ----+----1----+----2----+----3----+----4----+----5----+--��1 Payroll application group��2 [email protected]��3 [email protected]��4 Upper_And_Lower_Case@a_really_long_company_name.com Bottom of Data

Example 3: An example of overriding the reply address:

Top of Data =COLS> ----+----1----+----2----+----3----+----4----+----5----+--��1 reply:[email protected]��2 [email protected] Bottom of Data

If the application programmer receiving this email replies to it, then the reply willgo to the operations group. A site may choose to use this method to allowemail recipients to respond to a problem directly to the person or groupresponsible for correcting the problem. For example, the applicationprogrammer might instruct the operations group to restart the abended job in acertain step.


Email Templates

Email Templates

The subject line and body of the email are controlled by the email template.Email templates are stored in the EMAILLIB PDS. The email template membername is specified on the TXT=xxxxxxxx keyword on the /EMAIL command.

The first line of the template can specify the email subject. The line starts withthe word "subject:" starting in column one. The remainder of that line is used asthe subject of the email.

The rest of the email template is used for the body of the email. The body canbe in any valid email format, such as simple (ASCII) text or HTML.

Note: Emails are translated from EBCDIC to ASCII using the IBM XLATEservice or the CA 7 CAL2XLAT translation module. The XLATE service doesnot translate all characters correctly. For more information, see “SpecialCharacters” on page 244. The CA 7 CAL2XLAT module is described in theSystems Programmer Guide.

Trailing blanks on each line are discarded.

Any line can have one or more variables that CA 7 resolves before sending theemail. Variable names must start with an ampersand (&) and be in uppercase.Trailing blanks are removed from the values of all variables. Note that somevariables do not always have a value.

The following variables are always available in an email template:

Variable Name Variable Contents

&AMPER The ampersand (&).

&CA7 The instance name (PROD, TEST, CA71, etc.) of CA 7that is generating and sending the email.

&CA7CCI The 8-byte CAICCI node name of the system on whichCA 7 is executing.

&CA7CUST The 44-character heading value specified on theCUST,ID=xxxxx initialization file statement.

&CA7HOST The SMFID of the system on which CA 7 is executing.

&CA7LVL The service pack level of CA 7, such as "SP1".

&CA7NAME The name of the product, "CA 7".

&CA7RLSE The release of CA 7, such as "r11.1".

&CRLF The carriage return/line feed.


Email Templates

The following variables are available when the JOB= keyword is specified onthe /EMAIL command:

Variable Name Variable Contents

&EFROM The value that will be displayed in the "from" field of theemail. The value is specified on the EMAIL,EFROM=xxxxinitialization file statement, and can be changed by the/EADMIN,EFROM=xxxx command. The default is "CA-7".

&EREPLY The reply email address for this email. The value isspecified on the EMAIL,EREPLY=xxxx initialization filestatement and can be changed by the/EADMIN,EREPLY=xxxx command. The reply addresscan also be overridden in the email address member.The default is "[email protected]".

&VAR1 to &VAR8 Contents of the VAR=(xx,xx,) keyword on the /EMAILcommand. If the VAR= keyword is not specified thenthese variables are blank.

Variable Name Variable Contents Notes

&DEADDATE The deadline date for the job 1

&DEADTIME The deadline time for the job 2

&DUEDATE The due out date for the job 1

&DUETIME The due out time for the job 2

&EDATE The date the job ended 1,3

&EMODE The entry mode for the job, such as"DEMANDED."

&ETIME The time the job ended 2,3

&JES# The JES number for the job 3

&JOB# The CA 7 job number

&JOBNAME The name of the job

&JQUSER The 20-byte contents of the JQUSER field 4

&MAINID The MAINID for the job 6

&MCNT The current master requirement count forthe job

&QUEUE The current queue — REQ, RDY, or ACT

&RC The return code for the job 3

&SCHDID The job's schedule ID


Email Templates

Notes

1. Dates are formatted as "Tue, 14 Sep 20xx"

2. Times are formatted as "hh:mm:ss". If the specified time does not haveseconds, then "00" is used for the seconds.

3. If the job has not yet started, the start date and time are "*Unknown"and the JES number and SMFID will be blank. If the job has not yetended, the end date and time are "*Unknown" and the return code(RC) will be blank. For cross-platform jobs, the possible SMFID valuesare 7XPJ, 7UNI, 7UWT, or blank. The value depends on how the jobcompleted (job status) and the timing of when the email is generated.

4. No conversion is done on the JQUSER contents. If the contents arenot EBCDIC characters, the ASCII translation necessary for sendingthe email may generate garbage characters.

5. The job status variable will contain the same string that would appearin the column of an LQ command display.

6. For XPJOBs, the MAINID is XPJ.

The CAI.CAIEMAIL data set provides some sample email templates. You canuse these as is or tailor them to your needs. The samples are formatted forHTML. The following sample templates are provided:

Variable Name Variable Contents Notes

&SDATE The date the job started 1,3

&SMFID The SMFID of the system where the job isexecuting (or did execute).

3

&STATUS The job's current status 5

&STIME The time the job started 2,3

&SYSTEM The job's SYSTEM (from the job definition)

&UID The CA 7 UID (userid) value for this job

Template Suggested Use

@JOBABND Job abends

@JOBEND Job successful completions

@JOBFAIL Job failures (bad return codes)

@JOBLATE Jobs being marked late


Email Templates

Special Characters

Emails must be sent in ASCII. CA 7 uses the translate table defined by moduleCAL2XLAT, if available. You can modify this table to translate certain specialcharacters such as the exclamation mark (!), the square brackets ([ ]), the caret(^), and the vertical bar (|). For more information about EBCDIC/ASCIITranslation Tables, see the Systems Programmer Guide.

If you are using HTML format for your email template, you can use JavaScriptcodes for these special characters. The following is a partial table of JavaScriptcodes that you can use instead of these special characters:

Character Code

! !

[ [

] ]

| |

Many other JavaScript codes are available.

Notice that each code starts with an ampersand followed by a hash mark andends with a semicolon.

If your site has implemented the CA 7 CAL2XLAT module, characters aretranslated based on the definitions assigned in the program. If you have notremapped the special characters described previously, you will have the sameissues as the XLATE service.


Email Test Utility

Email Test Utility

A batch utility, CAL2EMLT, is available to test the email interface in an isolatedenvironment. The utility can be used to test different SMTP (email) servers, newtemplates, and/or new email address members.

CAL2EMLT provides information about a "dummy" job so that email templateswith variables referencing job information will be displayed with realistic data.Program CAL2EMLT should complete with RC=0. However, it generates avariable that simulates that the program abended with code S0C4.

The JCL for CAL2EMLT is as follows:

//stepname EXEC PGM=CAL2EMLT//STEPLIB DD DISP=SHR,DSN=cai.CAILOAD (CA 7 LOAD LIBRARY)//SYSPRINT DD SYSOUT= //EMAILLIB DD DISP=SHR,DSN=cai.CAIEMAIL (EMAIL TEMPLATES)//EADDRLIB DD DISP=SHR,DSN=address.lib (EMAIL ADDRESSES)//SYSIN DD control statements//

For more information, see the L2EMAIL SAMPJCL member.

Control Statements

The control statements must begin in column one. The keywords (such asESERVER) should be entered in uppercase. Some keywords (again, such asESERVER) accept mixed case values.

Comments can be included by starting the line with an asterisk in column one.

ESERVER=valueIdentifies the primary SMTP (email) server that should be used. If theprimary SMTP server is not available or if the ESERVER keyword is notspecified, then the SMTP server on the z/OS image where CAL2EMLTexecutes is used. The ESERVER value can be a one to 70 character nameto be resolved by a Domain Name Server (DNS) or an IP statement in theformat n.n.n.n or x:x:x:x:x:x:x:x, where n is a decimal number from 0through 255 and x is a hexadecimal number from 0 through FFFF. Leadingzeros can be specified for both. The short form of an IPv6 address using adouble colon (::) can be used.

EPORT=valueSpecifies the TCP/IP port number to use when communicating with theSMTP (email) server. The value defaults to 25, which is the well-known portnumber for SMTP and should rarely, if ever, need to be changed. Validvalues are 1 to 99999.


Email Test Utility

EFROM=valueSpecifies the value to appear in the "From" field of the email. The value canbe one to 70 characters and defaults to "CA-7."

EREPLY=valueSpecifies the email reply address to be used if the recipient replies to theemail. The value can be 1 to 70 characters and defaults [email protected].

ETIMEOUT=valueSpecifies the maximum number of seconds CAL2EMLT should wait forresponses from TCP/IP and the SMTP (email) server. The default is 10seconds. Valid values are 5 to 20 seconds.

TO=valueIdentifies the member in the EADDRLIB PDS to read for the emailaddresses. The TO keyword is required and has no default.

TXT=valueIdentifies the member in the EMAILLIB PDS to read for the email template.The TXT keyword is required and has no default.

VARn=valueThe VAR1 to VAR8 keywords allow the user to specify one to eightcharacter values. The values are substituted for the &VAR1 to &VAR8variables in the email template.


Data Set for TCP/IP Data

Data Set for TCP/IP Data

Email uses TCP/IP as a transport mechanism. Each system must run at leastone TCP started task. TCP/IP configuration data is contained in a data setpointed to by a //SYSTCPD DD statement in the TCP started task. Dependingon your implementation of TCP/IP, that data set may be dynamically allocated.

Your site may run more than one TCP started task. If so, CA 7 corresponds toone of these TCP "stacks." If the data set is not dynamically allocated, or if yoursite runs multiple TCP stacks, it may be necessary to add a //SYSTCPD DDstatement to your CA 7 online JCL. Check with your TCP/IP support person tosee if this DD statement is necessary at your site.

If needed, this DD statement should be the same as the //SYSTCPD DDstatement in the JCL of the TCP started task that corresponds to CA 7.

//SYSTCPD DD DISP=SHR,DSN=TCPIP.VTAM.DATA

In addition, an identical //SYSTCPD DD statement should be added to the JCLof the email test utility.


Chapter 8. Global Variables


The Substitution Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Substitution Rules and Restrictions . . . . . . . . . . . . . . . . . . . . . . 251General Reserved Variable Names . . . . . . . . . . . . . . . . . . . . . . 253Job-Specific Reserved Variable Names . . . . . . . . . . . . . . . . . . . . 254Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

The CA 7 global variables feature permits users to perform variable substitutionwithout requiring the use of CA Driver procedures. It also provides functionalityfor customers who want to use the feature instead of, or in addition to, CADriver.

The feature allows users to define global variables and assign values to thosevariables. There are also a fixed set of reserved global variables that arealways available (for example, current date, job name, and more). Reservedglobal variables are identified by a one-character prefix (7 is the default) thatcan be set by the site.

Note: To add, update, and delete global variables, see the /GVAR commandin the Command Reference Guide.

Variable substitution takes place if the GVARSUB=YES option was specifiedwhen the instance of CA 7 was started.

Note: For more information, see the Systems Programmer Guide.

A CA 7 command can be used to simulate JOB statement expansion to testsubstitution without actually submitting the job.

Note: For more information about the LJCK,JOB=jobname,LIST=ONLYcommand, see the Command Reference Guide.

Chapter 8. Global Variables 249

The Substitution Process

The Substitution Process

How global variable substitution behaves depends on where it is encountered. Itis designed for CA 7 JOB statements. Global variable substitution behavesdifferently in CA Driver procedures and standard JCL procedures.

CA 7 JOB Statements

As CA 7 processes the job, each statement is parsed for variables based on acharacter string prefix that can be specified by the site. The default prefix is anampersand followed by a colon (&:). When a valid variable is found, the valuefor that variable is substituted in place of the variable. After the entire statementhas been parsed, it is submitted.

CA Driver Procedures

When CA Driver is active, the CA Driver process takes place before globalvariable substitution. In effect, two variable substitution processes take place. Ina statement of a CA Driver procedure, the CA Driver variables are first replacedwith their values. Next, any global variables are replaced with their own valuesbefore being submitted.

Note: The value of a CA Driver variable can be a global variable, which isthen replaced by its own value.

Standard Procedures

CA 7 does not expand non-Driver JCL procedures. JES performs that function.Therefore, if a global variable is found in a standard, non-Driver JCL procedure,global variable substitution does not take place.

Note: If JES encounters an unsubstituted global variable, a JCL error mayoccur.


Substitution Rules and Restrictions


The following rules and restrictions apply to global variable substitution:

■ Global variable substitution applies only to jobs submitted by CA 7.

■ For CPU jobs, a JCL error occurs if the replacement data would cause theJCL line to expand:

– into column 72 if the line is numbered and column 72 is blank

– into column 67 on the job card

– into column 80 in all other cases

The error will be described in the CA 7 browse data set.

■ If the global variable is followed by a blank, the replacement data is alsofollowed by at least one blank.

■ If the global variable is followed by a comma, the replacement data is alsofollowed by a comma.

■ If the global variable is followed by a right parenthesis, the replacementdata is also followed by a right parenthesis.

■ If the global variable is followed by a single period, the replacement data isnot followed by a period. The period is omitted, and the replacement data isconcatenated with the text immediately following the variable.

■ If the replacement character string is shorter than the global variable(including the prefix), the character string is shifted left the number of bytesthe replacement character string is shorter than the global variable. Theshift continues until a space is encountered, at which point the shiftterminates. At that point, the number of spaces is increased by the numberof bytes that the global variable exceeds the replacement character string.

■ If the replacement character string is longer than the global variable, allfollowing bytes are shifted right by the number of bytes that the replacementcharacter string is longer than the global variable. This shift continues until astring of spaces long enough to contain the number of characters shifted,plus one blank is encountered at the end of the statement. If such a stringof spaces is not available, an error message is issued and the processterminates. Two or more character strings can be shifted right if the numberof spaces at the end of the statement is sufficient to contain the number ofcharacters shifted and still leave one space.



In the following examples, global variable &:F has a replacement value ofFILEAB and &:DATASET has a replacement value of DSN:

Original stmt: //&:F DD DSN=PAYROLL.MASTER COMMENTExpanded stmt: //FILEAB DD DSN=PAYROLL.MASTER COMMENTOriginal stmt: //INP DD DSN=&:DATASET..XYZ COMMENTExpanded stmt: //INP DD DSN=DSN.XYZ COMMENTOriginal stmt: //INP DD DSN=MASTER.&:F..INPUT COMMENTExpanded stmt: //INP DD DSN=MASTER.FILEAB.INPUT COMMENT

■ The value for a global variable can contain one or more other globalvariables. For example, the following value is legal: AB&:CD.EF&:WX.YZ. Ifthe value for global variable &:CD is 7 and the value for &:WX is 5, the finalsubstituted value will be AB7EF5YZ

■ Recursion is allowed and means that a global variable can return anothervariable in the first position. Examples: global variable &:ABC returning thestring &:XYZ is recursive. &:ABC returning XY&:ZW is not recursivebecause the &: prefix is not in the first position.

In the following example, global variable &:RC1 has a replacement value of&:RC2. (note the period at the end) and &:RC2 has a replacement value ofMASTER:

Original stmt: //DD1 DD DSN=PAYROLL.&:RC1 COMMENTExpanded stmt: //DD1 DD DSN=PAYROLL.MASTER COMMENT

■ If the number of recursions for a global variable exceeds the limit specifiedby the GVARLVL parameter on the initialization OPTIONS statement, a JCLerror occurs. The error is described in the CA 7 browse data set.

Note: For more information about the GVARLVL parameter, see theSystems Programmer Guide.

■ When right-shifting, the number of characters moved is the largest numbermoved during any of the intermediate or final substitutions. In the followingexample, the value for the variable &:MODEL is &:X. and the value for thevariable &:X is the reserved variable &:7CA7. The instance of CA7 is CA74.The numbers 15 and 30 show the positions of columns 15 and 30 duringand after substitution.

Original stmt: // &:MODEL 15 &:MODEL.XX 3�Intermediate (unseen) stmt: // &:X. 15 &:X.XX 3�Intermediate (unseen) stmt: // &:7CA7. 15 &:7CA7.XX 3�Final stmt: // CA74 15 CA74XX 3�


General Reserved Variable Names

General Reserved Variable Names

The following table contains the general reserved variable names.

Note: The length of returned text varies. Trailing blanks are omitted to avoidembedded blanks in case of concatenation.

Variable Name Variable Contents VariableLength

Notes

7CA7 Instance/alias name of CA 7 =<4 See note.

7CA7CCI CAICCI node name of thesystem on which CA 7 isexecuting

=<8 See note.

7CA7HOST SMFID of the system on whichCA 7 is executing

=<4 See note.

7CA7LVL Service pack level of CA 7,such as "SP1"

=<4 See note.

7CA7RLSE Release of CA 7, such as"r11" or "r11.5"

=<5 See note.

7CDATE Current system date inGregorian format (mm/dd/yy)

8

7CDATEJ Current system date in Julianformat (yyjjj)

5

7CDAYW Current day of the week(SUNDAY,...)

=<9 See note.

7CMONTH Current month (JANUARY,...) =<9 See note.

7CTIME Current system time(hh:mm:ss)

8

7DD Current day of the month 2

7HH Current hour 2

7MM Current month 2

7MN Current minute 2

7NULL Null 0

7SS Current second 2

7YY Current year (yy) 2

7YYYY Current year (yyyy) 4


Job-Specific Reserved Variable Names


The following table lists the job-specific reserved variable names.

Variable Name Variable Contents VariableLength

Notes

7CA7JOB# CA 7 job number 5 2

7CC Value for condition code test injob definition

5

7CLASS Job workload balancing (WLB)class value

1

7DLDATE Job deadline date (mm/dd/yy) 8

7DLTIME Job deadline time (hh:mm:ss) 8 3

7DODATE Job due out date 8

7DOTIME Job due out time 8 3

7EMODE Job entry mode =<8 1,4

7JOBNAME Job name =<8 1

7LTERM Job LTERM value =<8 1,5

7MAINID Job MAINID =<4 1

7PRY Job WLB priority value 3

7QUEUE Job current queue =<8 1

7RO Relational operator value forcondition code test in jobdefinition

2 6

7SCHDID Job schedule ID 3 7

7SYSTEM Job system in job definition =<8 1

7TAPE1 Number of WLB TAPE1 tapedrives for job

3

7TAPE2 Number of WLB TAPE2 tapedrives for job

3

7UID Job UID 3



Notes

1. The length of returned text varies. Trailing blanks are omitted to avoidembedded blanks in case of concatenation.

2. Value is 00001 on LJCK displays.

3. The specified time does not have seconds. Uses 00 value for the seconds.

4. Value is SSCAN on LJCK displays.

5. Value is job name on LJCK displays.

6. If character is a blank, it is translated to a period to avoid embedded blanksin case of concatenation.

7. Value supplied from SCHID is used.


Examples

Examples

Assume the current date is November 25, 2007. The reserved global variable&:7CDATE produces the value 11/25/07.

European Date Format: The following sequence can be used to produce thevalue 25/11/07:

&:7DD./&:7MM./&:7YY

Alternate Date Format: The following sequence can be used to produce thevalue 2007.11.25:

&:7YYYY..&:7MM..&:7DD


Chapter 9. Jobflow Illustrator


Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258The Workflow Building Process . . . . . . . . . . . . . . . . . . . . . . . . . 260Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Initialization Parameters (INITDEF DD Statement) . . . . . . . . . . . . . . 264Building Parameters (PARMDEF DD Statement) . . . . . . . . . . . . . . 272Commands (SYSIN DD Statement) . . . . . . . . . . . . . . . . . . . . . . 285JCL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303CSV Flowchart File Description . . . . . . . . . . . . . . . . . . . . . . . . . 307FLOWCHART TYPE=PRINT Description . . . . . . . . . . . . . . . . . . . 314Sample FLOWCHART TYPE=CSV File (Partial) . . . . . . . . . . . . . . . 319

This chapter defines the purpose and basic requirements for Jobflow Illustratorand describes how to generate, save, restore, modify, print, and report onworkflows.

Chapter 9. Jobflow Illustrator 257

Purpose

Purpose

A workflow is a comprehensive view of the CA 7 workload for a specific periodof time, which is known as the span. The workload comprises objects (jobs anddata sets) and the direct relationships, or connections, between them.

For an object or connection to be included in a workflow, the object orconnection must first be defined in the CA 7 database.

Connections

Jobflow Illustrator reports the following connections:

CONDIdentifes a conditional dependency.

DRJIdentifes a data set is a requirement (prerequisite) for a job.

DTJIdentifes a data set triggers job.

INDJRJIdentifes a job is indirectly a requirement for a job. (See Note)

INDJTJIdentifes a job indirectly triggers a job. (See Note)

JCDIdentifes a job creates a data set.

JRJIdentifes a job is a requirement for a job.

JTJIdentifes a job triggers a job.

NEGDEPIdentifes a negative dependency.

REPEATIdentifes a job that repeats.

Note: Indirect relationships are reported when the user selects the option notto display data sets in the workflow. For example:

JOBA creates DSN1, which triggers JOBB. If data sets are not displayed in theworkflow, JOBA shows as indirectly triggering JOBB.


Purpose

Simulation Mode

Simulation Mode is a manner of operation in which all workflow data comesfrom the CA 7 database. No information comes from the queues.

The workflow is built in internal tables depending on building parameterssupplied at startup. Because no data comes from the queues, the workflow isstatic, that is, jobs running in the system have no effect on the workflow.However, if someone is modifying the CA 7 database while CA 7 JobflowIllustrator is starting, the tables may be affected.

Ad Hoc Adds and Deletes

After the original workflow is built, you can simulate what if situations by addingjobs, data sets, or both, and by deleting jobs to or from the workflow to see howthe outcome would change.

Checkpoint Save and Start

You can create a baseline workflow by saving the workflow to a data set. Thisdata set can be used as input on a TYPE=CKPT start to create a workflow thatcan be used as the baseline starting point for a new simulation.

Flowchart Output

Jobflow Illustrator produces two kinds of flowchart output: print andcomma-separated value (CSV).

In print output, boxes contain data about job and data set objects. An optionallows users to omit the data set boxes and print only job boxes. The boxes areconnected and information about the types of connections is displayed. Themaximum size print flowchart is 999 pages horizontally by 999 pages vertically.A sample print flowchart can be found in the “FLOWCHART TYPE=PRINTDescription” on page 314.

In CSV output, data is sent to a file. Commas separate fields in each record.The first record in the file contains the names of the fields, similar to columnheadings. This data set is suitable for importing into a program such asMicrosoft Excel. An extract of a CSV file is shown in the “Sample FLOWCHARTTYPE=CSV File (Partial)” on page 319.

The CSV output can also be used by an online application such as CAWorkload Control Center.


The Workflow Building Process

The Workflow Building Process

The workflow building process consists of two phases: search and filter. WhenCA 7 Jobflow Illustrator builds its tables, it uses search parameters to query theCA 7 database to see what scheduled jobs meet all the specified criteria. Eachmatching job becomes head of a workflow chain.

After heads of chain are identified, each chain is run to add triggered jobs anddata sets and required (prerequisite) jobs and data sets. The filter parametersspecify the criteria for selecting the non-head of chain job and data sets.

Note: For more information about the parameters used by the search and filterphases, see “Building Parameters (PARMDEF DD Statement)” on page 272.

Once the workflow build completes, commands from the SYSIN file process theselected information.


Implementation

Implementation

This section describes how to start CA 7 Jobflow Illustrator as a batch job.

CA 7

CA 7 Jobflow Illustrator uses CAICCI to communicate with CA 7. To workcorrectly, the instance of CA 7 to which the workflow will relate must be up andrunning.

The CA 7 Jobflow Illustrator job must run on an LPAR that can communicatewith the appropriate CA 7 instance.

For information about implementing CAICCI, see the “Interface with CAICCI” onpage 90.

Note: For more information about running CA 7, see the SystemsProgrammer Guide.

Sample User JCL

The following is an example of the JCL for CA 7 Jobflow Illustrator with allrequired and optional DD statements. The DD statements you use depends onthe functions you perform.

//jobname JOB (accounting)//JS�1� EXEC PGM=CAL2FSIM,PARM='overrides'//STEPLIB DD DSN=cai.ca7.loadlib,DISP=SHR//CHKPOINT DD DSN=ckptin.data.set.name,DISP=SHR//SAVE DD DSN=ckptout.data.set.name,// DISP=(NEW,CATLG,DELETE),// SPACE=(CYL,(1,1)),UNIT=SYSALLDA,// DCB=(RECFM=VB,LRECL=724,BLKSIZE=�)//FLOWCSV DD DSN=csv.data.set.name,// DISP=(NEW,CATLG,DELETE),// SPACE=(TRK,(1,1)),UNIT=SYSALLDA,// DCB=(RECFM=VB,LRECL=1��,BLKSIZE=�)//FLOWPRT DD SYSOUT= //SYSMSGS DD SYSOUT= //SYSUSNAP DD SYSOUT= //SYSUDUMP DD SYSOUT= //INITDEF DD initialization parameters/ //PARMDEF DD building parameters/ //SYSIN DD commands//

The DD statements are described in the next section. Examples are providedlater.


Implementation

Input DD Statements

The following are the CA 7 Jobflow Illustrator input DD statements:

STEPLIBSpecifies the CA 7 load library.

CHKPOINTSpecifies the CA 7 Jobflow Illustrator checkpoint data set to read. Requiredonly if a TYPE=CKPT start is being done. Can be a different ddname if theCKPTDDN initialization parameter is specified.

INITDEFIdentifies the source of initialization parameters or identifies the data setcontaining the initialization parameters. Required.

PARMDEFIdentifies the source of building parameters or identifies the data setcontaining the building parameters. Required for TYPE=COLD start.Ignored for TYPE=CKPT start.

SYSINIdentifies the source of control statements or identifies the data setcontaining the control statements. Required.

Output DD Statements

The following are the CA 7 Jobflow Illustrator output DD statements:

SAVESpecifies the data set to which a checkpoint file will be saved. Required ifthe SAVE command statement is specified. Can be a different ddname ifthe DDNAME option is specified on the SAVE command statement.

FLOWCSVSpecifies the data set to which to which a comma-separated value file willbe written. Required if the FLOWCHART TYPE=CSV command statementis specified. Can be a different ddname if the DDNAME option is specifiedon the FLOWCHART command statement.

FLOWPRTSpecifies SYSOUT or the file to which a flowchart will be printed. Requiredif the FLOWCHART TYPE=PRINT command statement is specified. Can bea different DD name if the DDNAME option is specified on theFLOWCHART command statement.


Implementation

SYSMSGSSpecifies SYSOUT or the file to which CA 7 Jobflow Illustrator messagesare written. Required if Jobflow Illustrator is being run as a batch job.Recommended if Jobflow Illustrator is being executed by a calling program,but in this case, SYSMSGS may be omitted. If omitted, SYSMSGS isdynamically allocated, and the default sysout class is used.

SYSUSNAP(Optional) Specifies SYSOUT or the file to which SNAPs will be written inthe case of some error conditions that generate return code 8 or higher.

SYSUDUMP(Optional) Specifies SYSOUT or the file to which a dump will be written inthe case of an abend.

Dynamically Allocated DD Statements

The following are the CA 7 Jobflow Illustrator dynamically allocated DDstatements:

DBPARMSDefines parameters in the database. The same DBPARMS data set as theassociated CA 7 online instance is allocated dynamically by CA 7 JobflowIllustrator.

In the DBPARMS file, several data sets are defined using the UCC7DBASEparameter. The ddnames for these data sets can be found by looking forthe DDNAME keyword after the UCC7DBASE parameter. Look forDDNAMES UCC7JLIB, UCC7DLIB, and UCC7IDS. They should beaccompanied by a keyword in the form ALLOCxxx, where xxx is either JCLor DYN.

For the DBPARMS data set to be allocated dynamically, it must be apermanent data set, residing on DASD. DD DUMMY must not be specifiedin the CA 7 JCL.

Note: For more information about the DBPARMS file, see the SystemsProgrammer Guide.

UCC7JLIB, UCC7DLIB, UCC7IDSSpecify the job data set, the dataset data set, and the index data set, whichare collectively known as the CA 7 database.

If coded as ALLOCDYN in the DBPARMS data set, they are allocateddynamically.

If coded as ALLOCJCL in the DBPARMS data set, they are allocateddynamically if they are not present in the Jobflow Illustrator JCL, either inthe batch job or schedule server task. If they are present in the JCL anddummied out, Jobflow Illustrator generates an error message andterminates.

Note: DD statements DBPARMS, UCC7JLIB, UCC7DLIB, and UCC7IDSare not shown in any example JCL in this chapter.


Initialization Parameters (INITDEF DD Statement)


You can code parameters in columns 1 through 71. Separate parameters withspaces or commas. There is no space between the parameter keyword andvalue.

Note: All of the parameters in this section can be overridden by coding themin the PARM field on the EXEC statement.

The initialization parameters used by CA 7 Jobflow Illustrator have norelationship to those used by CA 7. Any names or options that match arecoincidental and have no effect on CA 7.

TYPE Parameter

The TYPE parameter has the following format:

��─ ──┬ ┬───────────────── ──────────────────────────────────────────────�� │ │┌ ┐─COLD─

└ ┘──TYPE= ──┴ ┴─CKPT─

TYPE=COLD|CKPT(Optional) Specifies the method of starting CA 7 Jobflow Illustrator.

COLDSpecifies that CA 7 Jobflow Illustrator should use the buildingparameters specified in the PARMDEF file and information from a CA 7database to build a workflow. This is the default.

CKPTSpecifies that CA 7 Jobflow Illustrator should ignore the PARMDEF fileand read the data set pointed to by the CHKPOINT DD. The checkpointdata is used as input to build a workflow. The CA 7 database is notread when building the workflow.



CA7 Parameter

The CA7 parameter has the following format:

��─ ──┬ ┬───────────────── ──────────────────────────────────────────────�� │ │┌ ┐─CA71──

└ ┘──CA7= ──┼ ┼──CA7n ─ └ ┘─alias─

CA7=CA71|CA7n|alias(Optional) Specifies the instance of CA 7 that the workflow will model.

CA71Maps to what used to be known as the production copy of CA 7. Thisis the default.

CA7nCA7n specifies the instance of CA 7 with which to connect. n can bean integer from 1 through 8.

aliasDefines a one- to four-character alias. This alias must correspond to analias assigned to a CA 7 instance during CA 7 initialization by CAIRIM.



LOGON Parameter

The LOGON parameter has the following format:

��─ ──┬ ┬────────────────────────── ─────────────────────────────────────�� │ │┌ ┐─submitter ID─

└ ┘──LOGON= ──┴ ┴─operatorid───

LOGON=submitter ID|operatorid(Optional) Specifies the operator identification required to log on to theinstance of CA 7 that the workflow will model. This parameter will usuallyhave to be coded for a TYPE=COLD start.

Note: This information is not saved to the checkpoint data set during aSAVE operation. During a TYPE=CKPT start, it is not necessary to code aLOGON parameter unless accessing the CA 7 database with an ad hoc(ADDJOB, ADDDS, or DELJOB) command.

Default: The submitter ID of the person who is running CA 7 JobflowIllustrator. If a batch job was run, this ID will normally be the TSO ID of thesubmitter. If CA 7 Jobflow Illustrator was called by a program, this field isdetermined by the ACEE of the address space returned by SAF.

operatoridDefines a one- to eight-character field.



CA7PASS Parameter

The CA7PASS parameter has the following format:

��─ ──┬ ┬────────────────── ─────────────────────────────────────────────��└ ┘──CA7PASS=password

CA7PASS=password(Optional) Specifies the one- to eight-character password required to log onto the instance of CA 7 that the workflow will model. This field may not benecessary depending on your site requirements. There is no default. Thepassword is encrypted internally.

The following is applicable only if your site requires a password to log on toCA 7: This information is not saved to the checkpoint data set during aSAVE operation. During a TYPE=CKPT start, it is not necessary to code aCA7PASS parameter unless accessing the CA 7 database with an ad hoc(ADDJOB, ADDDS, or DELJOB) command.



SIZE Parameter

The SIZE parameter has the following format:

��─ ──┬ ┬─────────────────── ────────────────────────────────────────────�� │ │┌ ┐─SMALL──

└ ┘──SIZE= ──┼ ┼─MEDIUM─ └ ┘─LARGE──

SIZE=SMALL|MEDIUM|LARGE(Optional) Provides CA 7 Jobflow Illustrator an estimate of the size of theflow so that the internal tables can be built with an appropriate size tofacilitate processing.

SMALLEstimates that the flow contains less than 10,000 jobs. If the flow sizeis unknown, this default size should be used. This is the default.

MEDIUMEstimates that the flow contains from 10,000 to 100,000 jobs.

LARGEEstimates that the flow contains over 100,000 jobs.



NODE Parameter

The NODE parameter has the following format:

��─ ──┬ ┬────────────────────── ─────────────────────────────────────────�� │ │┌ ┐─localnode─

└ ┘──NODE= ──┼ ┼─crossnode─ └ ┘─ AUTO ────

NODE=localnode|crossnode|*AUTO*(Optional) Specifies the CAICCI node where the copy of CA 7 that is beingmodeled is executing. If that copy executes on the local node, theparameter is not needed.

Default: The local CAICCI node.

crossnodeDefines a one-to eight-character field.

*AUTO*Specifies that the CAICCI interface should attempt to dynamically locatethe CAICCI node where a CA 7 with a matching instance nameresides.

Note: For more information, see “RECEIVER Parameter” onpage 270.



RECEIVER Parameter

The RECEIVER parameter has the following format:

��─ ──┬ ┬───────────────────────── ──────────────────────────────────────�� │ │┌ ┐─instance─

└ ┘──RECEIVER= ──┴ ┴─suffix───

RECIEVER=instance|suffix(Optional) Specifies the one- to four-character CAICCI suffix if it is not thesame as on the local node.

Default: The name of the CA 7 instance that is being modeled.

Note: The name used to identify the CAICCI receiver for a given copy ofCA 7 can be explicitly set with the XTMNAME keyword of the SVCNOstatement in the CA 7 initialization file (or implicitly by the RNAMEkeyword). This allows each copy of CA 7 to be unique across a CAICCInetwork even though more than one copy can have the same instancename. Assignment of unique CAICCI receiver names allows theNODE=*AUTO* parameter to be used to dynamically target a specific copyof CA 7.



CKPTDDN Parameter

The CKPTDDN parameter has the following format:

��─ ──┬ ┬──────────────────────── ───────────────────────────────────────�� │ │┌ ┐─CHKPOINT─

└ ┘──CKPTDDN= ──┴ ┴─ddname───

CKPTDDN=CHKPOINT|ddname(Optional) Specifies the one- to eight-character ddname of the checkpointdata set to read during a TYPE=CKPT start.

Default: CHKPOINT


Building Parameters (PARMDEF DD Statement)


Building parameters are used to specify to CA 7 Jobflow Illustrator how to buildthe workflow tables. Some of the parameters (MAXJOBS, FROM, TO, SPAN,EXTRACT, QTIME) are global in nature and relate to all jobs in the workflow.Other parameters (JOB, SCHID, and SYS) are used to select the head of chainjobs for the workflow. The remaining parameters (JOBFILTER, SCHFILTER,and SYSFILTER) are used to determine the jobs and data sets that are eithertriggered or requirements (prerequisites).

You can code parameters in columns 1 through 71. Separate parameters withspaces or commas. There is no space between the parameter keyword andvalue. Values containing spaces or commas must be contained withinparentheses.

On a TYPE=CKPT start, the PARMDEF DD is ignored.

Note: All of the parameters in this section can be overridden by coding themin the PARM field on the EXEC statement.



Global Building Parameters

Global building parameters pertain to all jobs and data sets in the workflow.

MAXJOBS Parameter

The MAXJOBS parameter has the following format:

��─ ──┬ ┬────────────────────── ─────────────────────────────────────────�� │ │┌ ┐─�──────

└ ┘──MAXJOBS= ──┴ ┴─number─

MAXJOBS=0|number(Optional) Limits workflow processing to a maximum number of jobs. Thiscan be useful when it is unclear how large the workflow would be, and theuser is expecting a limited number of jobs in the output. MAXJOBS is highlyuseful when testing.

Default: 0 (no limit on the number of jobs)

Limits: 1 - 9999999 (When CA 7 Jobflow Illustrator exceeds this number ofjobs, it stops processing and sets return code 8.)

Example: Set MAXJOB Limit to 40 Jobs

If you know that your weekend payroll cycle has only 20 jobs, specifying thefollowing would avoid runaway processing in case the building parameters werecoded incorrectly.

MAXJOBS=40



FROM Parameter

The FROM parameter has the following format:

��─ ──┬ ┬──────────────────────────────────────── ───────────────────────��│ │┌ ┐─(current date,current time)─└ ┘──FROM= ──┼ ┼─(mmddyy,hhmm)───────────────

└ ┘─hhmm────────────────────────

FROM=(mmddyy,hhmm)|hhmm(Optional) Specifies the beginning date and time of the workflow.

Default: Current date and time

(mmddyy,hhmm)Defines the date and time.

mmddyyDefines the calendar date of the beginning date of the workflow.

mmDefines the month. Leading zeros are required.

Limits: 01 - 12

ddDefines the day. A leading zero is required if less than 10.

Limits: 01 - 31

yyDefines the year.

hhmmDefines the beginning time.

hhDefines the hour.

Limits: 00 - 23

mmDefines the minute.

Limits: 00 - 59



hhmmDefines the beginning time. With this parameter, the current date isused.

hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59



TO Parameter

The TO parameter has the following format:

��─ ──┬ ┬──────────────────────── ───────────────────────────────────────��└ ┘──TO= ──┬ ┬─(mmddyy,hhmm)─

└ ┘─hhmm──────────

TO=(mmddyy,hhmm)|hhmm(Optional) Specifies the ending date and time of the workflow.

Limits: TO is mutually exclusive with SPAN.


mmddyyDefines the calendar date of the ending date of the workflow.


Limits: 01 - 12


Limits: 01 - 31

yyDefines the year.

hhmmDefines the ending time.

hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59

hhmmDefines the ending time. With this parameter, the current date is used.

hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59



SPAN Parameter

The SPAN parameter has the following format:

��─ ──┬ ┬────────────────── ─────────────────────────────────────────────�� │ │┌ ┐─��8��─

└ ┘──SPAN= ──┴ ┴─hhhmm─

SPAN=00800|hhhmm(Optional) Specifies the length of the time interval (that is, the duration) ofthe workflow. This value is added to the FROM date and time to determinethe ending date and time of the workflow.

Default: 00800 (8 hours and no minutes)

Limits: SPAN is mutually exclusive with TO.

hhhmmDefines a time interval. hhh is a three-digit field, with leading zeros, ifnecessary. mm must be two digits. The maximum duration of the spanis 16800, which is one week.



EXTRACT Parameter

The EXTRACT parameter has the following format:

��─ ──┬ ┬─────────────────── ────────────────────────────────────────────�� │ │┌ ┐─YES─

└ ┘──EXTRACT= ──┴ ┴─NO──

EXTRACT=YES|NO(Optional) Specifies whether Jobflow Illustrator should perform an initialextract of data from the CA 7 database or start with null tables so thatflows are built entirely from ADDJOB and ADDDS commands.

YESSpecifies to build internal tables by extracting data from the CA 7database. This is the default.

NOSpecifies to start with null tables. JOB building parameters are notallowed with this option.

QTIME Parameter

This parameter has the following format:

��─ ──┬ ┬──────────────────── ───────────────────────────────────────────�� │ │┌ ┐─HONOR──

└ ┘──QTIME= ──┴ ┴─IGNORE─

QTIME=HONOR|IGNORE(Optional) Specifies whether to use elapsed queue time (QTM) indetermining a triggered job's start time.

HONORDelays a triggered job's start time by the amount of the queue time.This is the default.

IGNOREIgnores queue time when calculating start time.



Search Building Parameters

Search building parameters specify the criteria for CA 7 Jobflow Illustrator touse when searching the CA 7 database for scheduled jobs to become heads ofchains in the workflow.

JOB Parameter

The JOB parameter has the following format:

��─ ──┬ ┬───────────────────────── ──────────────────────────────────────�� │ │┌ ┐─ ─────────────

└ ┘──JOB= ──┼ ┼─jobname─────── ├ ┤─jobname�────── ├ ┤─job?ame─────── ├ ┤─jo?name�────── └ ┘─(jobname,nnn)─

JOB=*|jobname|jobname*|job?ame|jo?name*|(jobname,nnn)(Optional) Specifies search criteria for the names of scheduled jobs tobecome heads of chains in the workflow.

Default: * (All jobs)

Limits: This parameter not allowed with EXTRACT=NO.

jobnameSpecifies a specific job name.

jobname*Specifies a generic job name terminated with an asterisk.

job?ameSpecifies a generic job name masked in a single position.

jo?name*Specifies a combination job name masked in a single position andterminated with an asterisk.

(jobname,nnn)Specifies a specific job name with a specific one- to three-digit SCHID.If specified here, the SCHID overrides the SCHID parameter for thisjob.



SCHID Parameter

The SCHID parameter has the following format:

��─ ──┬ ┬─────────────────────── ────────────────────────────────────────�� │ │┌ ┐─�─────────

└ ┘──SCHID= ──┼ ┼─nnn─────── │ │┌ ┐─,─ └ ┘──( ───� ┴nnn )

SCHID=0|nnn|(nnn list)(Optional) Defines the schedule ID value as the selection criteria for thejobs to be heads of chains in the workflow. This parameter can beoverridden by coding the (jobname,nnn) format of the JOB parameter.

Default: 0 (all schedule IDs)

nnnDefines a one- to three-digit number.

Limits: 0 - 255

(nnn list)Specifies a list of up to 10 schedule ID numbers, enclosed inparentheses and separated by commas.



SYS Parameter

The SYS parameter has the following format:

��─ ──┬ ┬────────────────────────── ─────────────────────────────────────�� │ │┌ ┐─ ──────────────

└ ┘──SYS= ──┼ ┼─systemid─────── ├ ┤─system�──────── │ │┌ ┐─,────── └ ┘──( ───� ┴systemid )

SYS(Optional) Specifies system name selection criteria for the jobs to be headsof chains in the workflow.

Default: * (All system names)

systemidDefines a specific system name. This is a one- to eight-characteralphanumeric field.

system*Defines a generic system name terminated with an asterisk.

(systemid list)Defines a list of up to 10 system names, enclosed in parentheses andseparated by commas.



Filter Building Parameters

Filter building parameters specify the criteria for CA 7 Jobflow Illustrator to usewhen running trigger and requirement chains to determine whether to includejobs and data sets in the workflow.

JOBFILTER Parameter

The JOBFILTER parameter has the following format:

��─ ──┬ ┬─────────────────────────────────── ────────────────────────────�� │ │┌ ┐─ ─────────────────

└ ┘──JOBFILTER= ──┼ ┼─jobname─────────── ├ ┤─jobname�────────── ├ ┤─job?ame─────────── ├ ┤─jo?name�────────── │ │┌ ┐─,───────── └ ┘──( ───� ┴jobname,nnn )

JOBFILTER=*|jobname|jobname*|job?ame|jo?name*|(jobname,nnn)(Optional) Defines the criteria for selecting the non-head of chain job namesin the workflow.

Default: * (All job names)

jobnameDefines a specific job name.

jobname*Defines a generic job name terminated with an asterisk.



(jobname,nnn)Defines a specific job name with a specific one- to three-digit SCHID. Ifspecified here, the SCHID overrides the SCHID parameter for this job.



SCHFILTER Parameter

The SCHFILTER parameter has the following format:

��─ ──┬ ┬─────────────────────────── ────────────────────────────────────�� │ │┌ ┐─�─────────

└ ┘──SCHFILTER= ──┼ ┼─nnn─────── │ │┌ ┐─,─ └ ┘──( ───� ┴nnn )

SCHFILTER=0|nnn|(nnn list)(Optional) Defines the criteria for selecting the non-head of chain scheduleID values in the workflow.

Default: 0 (All schedule IDs)

nnnDefines a one- to three-digit number.

Limits: 0 - 255

(nnn list)Defines a list of up to 10 schedule ID numbers, enclosed inparentheses and separated by commas.



SYSFILTER Parameter

The SYSFILTER parameter has the following format:

��─ ──┬ ┬──────────────────────────────── ───────────────────────────────�� │ │┌ ┐─ ──────────────

└ ┘──SYSFILTER= ──┼ ┼─systemid─────── ├ ┤─system�──────── │ │┌ ┐─,────── └ ┘──( ───� ┴systemid )

SYSFILTER=*|systemid|systemid*|(systemid list)(Optional) Defines the criteria for selecting the non-head of chain systemnames in the workflow.

Default: * (All system names)

systemidSpecifies a specific system name. This is a one- to eight-characteralphanumeric field.


(systemid list)Defines a list of up to 10 system names, enclosed in parentheses andseparated by commas.


Commands (SYSIN DD Statement)


After the workflow is built and saved in internal tables, CA 7 Jobflow Illustratorlooks at the SYSIN file for commands on how to use the workflow.

CA 7 Jobflow Illustrator processes three types of commands:

■ Ad hoc commands

■ System command

■ Output command

Ad Hoc Commands

The three ad hoc commands are ADDJOB, ADDDS, and DELJOB. They add ajob, add a data set, and delete a job, respectively, to/from the workflow. Whenone or more ad hoc commands are processed, a new workflow is generatedbefore CA 7 Jobflow Illustrator processes a system or an output command.

The ad hoc commands, combined with the SAVE system command andTYPE=CKPT start, provide the simulation, or what if capability, of simulationmode.

Note: To save processing time, a new workflow is not generated after each adhoc command. If multiple ad hoc commands follow each other, they areprocessed and the jobs, data sets, or both are added to the workflow as headsof chains. Jobs are deleted from the flow, one per DELJOB command. It is onlywhen a system or output command is encountered that trigger and requirementchains are run to generate a whole new workflow.

System Command

The system command, SAVE, writes workflow data to the checkpoint data set.If it is necessary to do multiple saves, each save should be written to a differentcheckpoint data set.



Output Command

The output command, FLOWCHART, produces workflow output in two differentformats.

FLOWCHART TYPE=PRINT produces a traditional flowchart with job and dataset names in connected boxes, suitable for printing. A keyword option cansuppress the data set boxes and produces only boxes with job names.

FLOWCHART TYPE=CSV produces a file of records consisting of fieldsseparated by commas. CSV stands for Comma-Separated Values. The file issuitable for importing into a spreadsheet program. The first record is the fieldnames (analogous to column headings), and subsequent records are the data.

Note: A CSV file produced by CA 7 Jobflow Illustrator online option has anadditional record called the properties record as the last record in the file.

Command Coding Rules

The following rules specify how commands must be coded:

■ Commands can be coded in columns 1-72 and can start in any column.

■ Commands can be continued on the following line if the last keyword on theline to be continued is followed by a comma.

■ No more than one command can be entered on a line.

■ An asterisk in column 1 signifies a comment.

ADDJOB Command—Add a Job

The ADDJOB command adds a job to the workflow as a head of chain.

Triggered and requisite jobs and data sets related to this job are included in theworkflow that is generated prior to the next system or output command.


��──ADDJOB─ ──JOB=jobname ──┬ ┬──────────────────────────── ───────────────�└ ┘──,START= ──┬ ┬──(mmddyy,hhmm)

└ ┘─hhmm──────────

�─ ──┬ ┬────────────────────────── ──┬ ┬────────────────── ────────────────��└ ┘──,END= ──┬ ┬──(mmddyy,hhmm) │ │┌ ┐─1───

└ ┘─hhmm────────── └ ┘──,SCHID= ──┴ ┴─nnn─



JOB=jobnameSpecifies a specific job name to be added to the workflow. This jobbecomes a head of chain.

Limits: The job name cannot be masked.

START=(mmddyy,hhmm)|hhmm(Optional) Specifies the date and time that the job begins.

Default: If START and END are both omitted, START defaults to the dateand time of the build parameters in the PARMDEF file. If START is omittedand END is specified, the START date and time is calculated from the ENDdate/time.


mmddyyDefines the date.


Limits: 01 - 12


Limits: 01 - 31

yyDefines the year.

hhmmDefines the time.

hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59

hhmmDefines the time. This parameter uses the current date.

hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59



END=(mmddyy,hhmm)|hhmm(Optional) Specifies the date and time for the job to end.

Default: If END is omitted, the date and time are calculated from theSTART date and time.




Limits: 01 - 12


Limits: 01 - 31

yyDefines the year.


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59

SCHID=1|nnn(Optional) Specifies the one- to three-digit schedule ID of the job beingadded to the workflow.

Default: 1

Limits: 1 - 255



ADDDS Command—Add a Data Set

The ADDDS command adds a data set to the workflow. Its main purpose is tosatisfy requirements.


��──ADDDS─ ──DSN=datasetname ────────────────────────────────────────────�

�─ ──┬ ┬────────────────────────────────────────── ───────────────────────�│ │┌ ┐─(current date,current time)─└ ┘──,CREDT= ──┼ ┼──(mmddyy,hhmm) ──────────────

└ ┘─hhmm────────────────────────

�─ ──┬ ┬────────────────── ──────────────────────────────────────────────�� │ │┌ ┐─1───

└ ┘──,SCHID= ──┴ ┴─nnn─

DSN=datasetnameDefines a specific data set name to add to the workflow.

Limits: 1 - 44 characters

CREDT=(mmddyy,hhmm)|hhmm(Optional) Specifies the date and time the data set was created.

Default: Current date and time




Limits: 01 - 12


Limits: 01 - 31

yyDefines the year.


hhDefines the hour.

Limits: 00 - 23




Limits: 00 - 59


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59

SCHID=1|nnn(Optional) Specifies the one- to three-digit schedule ID of the data set beingadded to the workflow.

Note: If you are unsure about the schedule ID of a data set, the generalrule is the data set inherits the schedule ID of the job that creates it.

Default: 1

Limits: 1 - 255



DELJOB Command—Delete a Job

The DELJOB command deletes a job from the workflow.

Triggered and requisite jobs and data sets related to this job are deleted fromthe workflow that is generated prior to the next system or output command.

If this job is a requisite for one or more jobs that are not in this job's triggerchain, this job is converted to a soft object, which is a placeholder with noSCHID.


��──DELJOB─ ──JOB=jobname ──,SCHID= ──┬ ┬─nnn─ ─────────────────────────────� └ ┘─�───

�─ ──┬ ┬──────────────────────────── ──┬ ┬────────────────────────── ───────�└ ┘──,START= ──┬ ┬──(mmddyy,hhmm) └ ┘──,END= ──┬ ┬──(mmddyy,hhmm)

└ ┘─hhmm────────── └ ┘─hhmm──────────

�─ ──┬ ┬─────────── ─────────────────────────────────────────────────────��└ ┘──,FUZZ=nnn

JOB=jobnameSpecifies a specific job name to delete from the workflow.

Limits: The job name cannot be masked.

SCHID=nnn|0Specifies the schedule ID of the job being deleted from the workflow.

nnnSpecifies a one- to three-digit number.

Limits: 1 - 255

0Specifies that any SCHID matches the criteria.

START=(mmddyy,hhmm)|hhmm(Optional) Specifies the date and time that the job begins.

Limits: Either START or END is required, but both cannot be coded.




Limits: 01 - 12




Limits: 01 - 31

yyDefines the year.


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59

END(Optional) Specifies the date and time that the job ends.

Limits: Either START or END is required, but both cannot be coded.




Limits: 01 - 12


Limits: 01 - 31

yyDefines the year.




hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59

FUZZ=nnn(Optional) Specifies the amount of time, plus or minus, in minutes, that thespecified START/END time can vary from the job's actual time for JobflowIllustrator to consider the job to match the time parameter.

Limits: 1 - 999

Example: Set FUZZ Parameter to 10 Minutes

The following example assumes that the job's start time is 0853. If theparameters are coded as follows, the job's start time matches because 0900 iswithin 10 minutes of 0853. Without the FUZZ keyword, there would be nomatch because 0900 does not equal 0853.

START=0900,FUZZ=10



SAVE Command—Write to the Checkpoint Data Set

The SAVE command writes the workflow to the checkpoint data set. Performingmultiple saves to the same data set overwrites previous data. Only data fromthe last save survives.

The correct way to do multiple saves is to use the DDNAME option and writeeach checkpoint to a different data set.


��──SAVE─ ──┬ ┬───────────────────── ────────────────────────────────────�� │ │┌ ┐─SAVE───

└ ┘──DDNAME= ──┴ ┴─ddname─

DDNAME=ddname(Optional) Defines a one- to eight-character ddname.

Default: SAVE



FLOWCHART Command—Generate a Jobflow Illustrator

The FLOWCHART command generates a workflow from data in the internaltables and output in one of two formats: print or CSV (comma-separatedvalue).

Print format is the traditional flowchart where information is presented in boxesconnected by lines that show relationships. Print format flowcharts are usuallysent to SYSOUT.

CSV format is usually sent to a data set. Fields in each record are separated bycommas. The first record in the file contains the names of the fields. These canbe used as column headings. This data set is suitable for importing into aprogram such as Microsoft Excel.


��──FLOWCHART─ ──┬ ┬────────────────── ──┬ ┬───────────────────────── ──────� │ │┌ ┐─PRINT─ │ │┌ ┐─,──────────

└ ┘──TYPE= ──┴ ┴─CSV─── │ ││ │┌ ┐─ ────────└ ┘──,JOB=( ───� ┴┼ ┼─jobname── )

├ ┤─jobname�─ ├ ┤─job?ame── └ ┘─jo?name�─

�─ ──┬ ┬─────────────────────────────── ──┬ ┬───────────────────────── ─────� │ │┌ ┐─,────────── │ │┌ ┐─,────────── │ ││ │┌ ┐─ ──────── │ ││ │┌ ┐─ ────────

└ ┘──,JOBFILTER=( ───� ┴┼ ┼─jobname── ) └ ┘──,SYS=( ───� ┴┼ ┼─systemid─ ) ├ ┤─jobname�─ └ ┘─system�── ├ ┤─job?ame── └ ┘─jo?name�─

�─ ──┬ ┬────────────────────── ──┬ ┬─────────────────────────────── ────────� │ │┌ ┐─,───── │ │┌ ┐─,────────── │ ││ │┌ ┐─�─── │ ││ │┌ ┐─ ────────

└ ┘──,SCHID=( ───� ┴┴ ┴─nnn─ ) └ ┘──,SYSFILTER=( ───� ┴┼ ┼─systemid─ ) └ ┘─system�──

�─ ──┬ ┬────────────────────────── ──┬ ┬─────────────────────────── ────────�│ │┌ ┐─,───── └ ┘──,FROM= ──┬ ┬─(mmddyy,hhmm)─

│ ││ │┌ ┐─�─── └ ┘─hhmm──────────└ ┘──,SCHFILTER=( ───� ┴┴ ┴─nnn─ )

�─ ──┬ ┬───────────────────────── ──┬ ┬───────────── ───────────────────────�└ ┘──,TO= ──┬ ┬─(mmddyy,hhmm)─ └ ┘──,SPAN=hhhmm

└ ┘─hhmm──────────

�─ ──┬ ┬─────────────────── ──┬ ┬───────────────────── ─────────────────────� │ │┌ ┐─ALL─ │ │┌ ┐─ALL──

└ ┘──,OBJECT= ──┴ ┴─JOB─ └ ┘──,CONTYPE= ──┴ ┴─TRIG─

�─ ──┬ ┬──────────────────── ──┬ ┬─────────────────────── ─────────────────�� │ │┌ ┐─SHOW─── │ │┌ ┐─FLOWPRT─

└ ┘──,LOOP= ──┴ ┴─NOSHOW─ └ ┘──,DDNAME= ──┼ ┼─FLOWCSV─ └ ┘─ddname──



Note: All of the preceding keywords (with the exception of TYPE andDDNAME) are designed to limit the output of the flowchart. The defaultcommand produces a flowchart containing all the objects that were built usingthe criteria specified by the building parameters. The preceding keywords canbe used to generate a subset of the total flow. They can be omitted if aflowchart containing the total flow is desired.

The following are available for TYPE=PRINT only.

��─ ──┬ ┬────────────────── ──┬ ┬─────────────────── ──┬ ┬───────────────── ──� │ │┌ ┐─133─ │ │┌ ┐─6�── │ │┌ ┐─ONLY─

└ ┘──,LRECL= ──┴ ┴─nnn─ └ ┘──,LPPAGE= ──┴ ┴─nnn─ └ ┘──,HDR= ──┴ ┴─ALL──

�─ ──┬ ┬────────────────────── ───────────────────────────────────────────� │ │┌ ┐─SHOW───

└ ┘──,BLANKP= ──┴ ┴─NOSHOW─

�─ ──┬ ┬──────────────────────────────────────── ─────────────────────────�│ │┌ ┐─CA 7 Jobflow Illustrator─└ ┘──,TEXT=( ──┴ ┴──heading text ──────────── )

�─ ──┬ ┬──────────────────────── ────────────────────────────────────────�� │ │┌ ┐─,──────

└ ┘──,JOBBOX=( ───� ┴variable )

TYPE=PRINT|CSV(Optional) Describes the output format of the flowchart.

PRINTFormats the flowchart for print, that is, jobs and data sets arerepresented in boxes connected by lines depicting relationships. Formore information about the printed output see “FLOWCHARTTYPE=PRINT Description” on page 314. This is the default.

CSVFormats the flowchart as records with fields separated by commas. Formore information about this format, see “CSV Flowchart FileDescription” on page 307.

JOB=*|jobname|jobname*|job?ame|jo?name*(Optional) Defines the jobs to be used as heads of chains in the flowchart.A single entry need not be enclosed in parentheses.

Default: * (all job names)

jobnameSpecifies a specific job name.

jobname*Specifies a generic job name terminated with an asterisk.





JOBFILTER=*|jobname|jobname*|job?ame|jo?name*(Optional) Defines the criteria for selecting the non-head of chain job namesin the workflow. A single entry need not be enclosed in parentheses.

Default: * (all job names)

jobnameDefines a specific job name.

jobname*Defines a generic job name terminated with an asterisk.



SYS=*|systemid|system*(Optional) Defines the systems as selection criteria for the head of chainjobs in the flowchart. A single entry need not be enclosed in parentheses.

Default: * (all system names)



SCHID=0|nnn(Optional) Defines the one- to three-digit schedule ID value as a selectioncriterion for the head of chain jobs in the flowchart. A single entry need notbe enclosed in parentheses.


Limits: 0 - 255

SYSFILTER=*|systemid|system*(Optional) Defines the criteria for selecting the non-head of chain systemnames in the workflow. A single entry need not be enclosed in parentheses.

Default: * (all system names)





SCHFILTER=0|nnn(Optional) Defines the criteria for selecting the non-head of chain scheduleIDs in the workflow (one- to three-digits). A single entry need not beenclosed in parentheses.


Limits: 0 - 255

FROM=(mmddyy,hhmm)|hhmm(Optional) Defines the earliest end date and time for jobs selected to bedisplayed in the flowchart.

Default: FROM time specified in the PARMDEF build parameter.




Limits: 01 - 12


Limits: 1 - 31

yyDefines the year.


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59



TO=(mmddyy,hhmm)|hhmm(Optional) Defines the latest end date and time for jobs selected to bedisplayed in the flowchart.

Default: TO time specified in the PARMDEF build parameter or calculatedusing the from time and span.

Limits: TO is mutually exclusive with SPAN.




Limits: 01 - 12


Limits: 1 - 31

yyDefines the year.


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59


hhDefines the hour.

Limits: 00 - 23


Limits: 00 - 59

SPAN=hhhmm(Optional) Defines the length of the time interval (that is, the duration) of theworkflow.

Default: None. If omitted, the span is calculated from the from and to times.



Limits: SPAN is mutually exclusive with TO.

hhhmmhhh is a three-digit field, with leading zeros, if necessary. mm must betwo digits. The maximum duration of the span is 16800, which is oneweek.

OBJECT=ALL|JOB(Optional) Defines which objects are to be displayed in the flowchart boxes:jobs and data sets or jobs only.

ALLSpecifies to display both jobs and data sets in boxes on the flowchart.This is the default.

JOBSpecifies to display only jobs in boxes on the flowchart. An exception ismade for data sets that are heads of chain, which are displayed.Connections that would involve a data set in an intermediaterelationship will be shown as indirect connections.

CONTYPE=ALL|TRIG(Optional) Defines whether to display requirement connections on theflowchart.

ALLDisplays all connections on the flowchart. This is the default.

TRIGDisplays only trigger and repeating connections on the flowchart. Thisincludes job creates data set connections.

LOOP=SHOW|NOSHOW(Optional) Sets display options for jobs that are part of a trigger loop.

SHOWSpecifies to show that a job is part of a trigger loop. This is the default.

NOSHOWSpecifies not to show that a job is part of a trigger loop.

DDNAME=FLOWPRT|FLOWCSV|ddname(Optional) Defines the ddname to which the flowchart is written.

FLOWPRTSpecifies the standard ddname for FLOWCHART TYPE=PRINT. It hasthe attributes of SYSOUT (RECFM=FBA, LRECL=133). The LRECLcan be overridden by use of the LRECL parameter. This is the default.

FLOWCSVSpecifies the standard ddname for FLOWCHART TYPE=CSV. It hasthe following DCB attributes: RECFM=VB, LRECL=1000.



ddnameDefines a different ddname to use from the two listed previously. TheDCB attributes must match those listed for FLOWPRT for TYPE=PRINTor for FLOWCSV for TYPE=CSV, or a system error may occur.

LRECL=133|nnn(Optional) Defines the number of horizontal characters per page of theprinted flowchart. This includes a printer carriage control character. This canbe used when using a non-standard printer font.

Default: 133

Limits: 20 - 999

LPPAGE=60|nnn(Optional) Describes the number of lines per page on the printed flowchart.

Default: 60

Limits: 10 - 999

HDR=ONLY|ALL(Optional) Describes whether to print the heading text on only the top pagesof the flowchart or on every page of the flowchart.

ONLYSpecifies to print the heading text on only the top pages (PAGE001.nnn) of the flowchart. This is the default.

ALLSpecifies to print the heading text on all pages of the flowchart.

BLANKP=SHOW|NOSHOW(Optional) Describes whether to print blank pages.

SHOWSpecifies to print blank pages. This is the default.

NOSHOWSpecifies not to print blank pages.

TEXT=(CA 7 Jobflow Illustrator)|(heading text)(Optional) Contains the text of the page heading.

Default: (CA 7 Jobflow Illustrator)

Limits: 1 - 68 characters enclosed in parentheses



JOBBOX=value(Optional) Describes which options to show in the job boxes on the printedflowcharts. If more than one option is selected, they must be enclosed inparentheses. Up to four of the listed options can be selected. If more thanfour are coded, an error message is generated and return code 8 is set.

BEGINSpecifies that the begin date and time should be displayed.

ENDSpecifies that the end date and time should be displayed.

DRCLASSSpecifies that the disaster recovery class should be displayed.

JOBNETSpecifies that the job network name should be displayed.

MAINIDSpecifies that the main ID (CPU on which the job can or cannot bescheduled) should be displayed.

SYSTEMSpecifies that the system name should be displayed.

WLBSpecifies that the workload balancing class should be displayed.

WLPSpecifies that the workload balancing priority should be displayed.


JCL Examples

JCL Examples

The following examples may help you understand the Jobflow Illustratorprocess.

Example 1: Cold Start

In this example, CA 7 Jobflow Illustrator starts normally with a COLD start. Thedefault PARM of MAXJOBS=0 is overridden with an EXEC PARM ofMAXJOBS=100. The internal tables are built with CA 7 database data specifiedusing the building parameters in the PARMDEF DD statement. The table datais then saved to the data set described by the SAVE DD statement (SAVEcommand). Next, the workflow is printed in flowchart format to SYSOUT, asspecified by the FLOWPRT DD statement (FLOWCHART TYPE=PRINTcommand).

//jobname JOB (accounting)//JS�1� EXEC PGM=CAL2FSIM,PARM='MAXJOBS=1��'//STEPLIB DD DSN=cai.ca7.loadlib,DISP=SHR//SAVE DD DSN=ckpt.data.set.name,// DISP=(NEW,CATLG,DELETE),// SPACE=(CYL,(1,1)),UNIT=SYSALLDA,// DCB=(RECFM=VB,LRECL=724,BLKSIZE=�)//FLOWPRT DD SYSOUT= //SYSMSGS DD SYSOUT= //SYSUSNAP DD SYSOUT= //SYSUDUMP DD SYSOUT= //INITDEF DD TYPE=COLDCA7=CA74LOGON=USERCA7PASS=USERPASS/ //PARMDEF DD FROM=(�331�7,��1)TO=(�331�7,18��)SYS= SCHID=(1,2,4)JOB=PAY JOBFILTER=PAYME JOBFILTER=(PAYYOU ,2)JOBFILTER=(PAYUS ,1)JOBFILTER=(PAYUS ,2)/ //SYSIN DD SAVEFLOWCHART TYPE=PRINT//


JCL Examples

Example 2: Checkpoint Start and CSV Flowchart

In this example, CA 7 Jobflow Illustrator starts with a CKPT start, reading datafrom the checkpoint data set created in Example 1 and described by theCHKPOINT DD statement. Because no ad hoc commands are being performed,the LOGON parameter in the INITDEF file is not required.

Next, a workflow in comma-separated value format is written to the data setdefined by DD statement FLOWCSV (command FLOWCHART TYPE=CSV).

//jobname JOB (accounting)//JS�1� EXEC PGM=CAL2FSIM//STEPLIB DD DSN=cai.ca7.loadlib,DISP=SHR//CHKPOINT DD DSN=ckpt.data.set.name,DISP=SHR//FLOWCSV DD DSN=csv.data.set.name,// DISP=(NEW,CATLG,DELETE),// SPACE=(TRK,(1,1)),UNIT=SYSALLDA,// DCB=(RECFM=VB,LRECL=1��,BLKSIZE=�)//SYSMSGS DD SYSOUT= //SYSUSNAP DD SYSOUT= //SYSUDUMP DD SYSOUT= //INITDEF DD TYPE=CKPT/ //SYSIN DD FLOWCHART TYPE=CSV//


JCL Examples

Example 3: Null Table Cold Start, Multiple Checkpoints

In this example, CA 7 Jobflow Illustrator initializes its tables using data from thePARMDEF file but does not read any information from the CA 7 instance CA74database (because of parameter EXTRACT=NO).

After table initialization is accomplished, workflow data is saved to thecheckpoint data set defined by DD CHKPOIN1. Then, using only the internaltables, job PAYME01 is added as a head of chain (command ADDJOB). Dataset company.DAILY.PAYME01, which is a requisite of PAYME01, is added tothe tables (command ADDDS). Because the subsequent command, SAVE, is asystem command, a workflow is generated. Jobs and data sets in the databasethat are triggered and are requisites that meet the start/end/SCHID criteria areincluded.

Next, the modified workflow is saved to the checkpoint data set defined by DDCHKPOIN2. Next, the workflow is printed to SYSOUT as specified by DDMYPRINT (command FLOWCHART TYPE=PRINT).

//jobname JOB (accounting)//JS�1� EXEC PGM=CAL2FSIM//STEPLIB DD DSN=cai.ca7.loadlib,DISP=SHR//CHKPOIN1 DD DSN=ckpt1.data.set.name,// DISP=(NEW,CATLG,DELETE),// SPACE=(CYL,(1,1)),UNIT=SYSALLDA,// DCB=(RECFM=VB,LRECL=724,BLKSIZE=�)//CHKPOIN2 DD DSN=ckpt2.data.set.name,// DISP=(NEW,CATLG,DELETE),// SPACE=(CYL,(1,1)),UNIT=SYSALLDA,// DCB=(RECFM=VB,LRECL=724,BLKSIZE=�)//MYPRINT DD SYSOUT= //SYSMSGS DD SYSOUT= //SYSUSNAP DD SYSOUT= //SYSUDUMP DD SYSOUT= //INITDEF DD CA7=CA74,LOGON=USER,CA7PASS=USERPASS/ //PARMDEF DD FROM=(�331�7,17��)TO=(�331�7,19��)SCHID=2EXTRACT=NO/ //SYSIN DD SAVE DDNAME=CHKPOIN1ADDJOB JOB=PAYME�1,START=(�331�7,173�), END=(�331�7,18��),SCHID=2ADDDS DSN=company.DAILY.PAYME�1, CREDT=(�331�7,17��),SCHID=2SAVE DDNAME=CHKPOIN2FLOWCHART TYPE=PRINT,DDNAME=MYPRINT//


JCL Examples

Example 4: Delete Job and Print Flowchart to DASD

In this example, CA 7 Jobflow Illustrator builds a workflow with a span of 24hours. The flow is expected to contain approximately 22,000 jobs. After tableinitialization is accomplished, job PAYME05 with SCHID=2 is deleted from theflow if it starts between 1235 and 1255. So are all jobs it triggers and all relatedrequirements (command DELJOB).

Next, CA 7 Jobflow Illustrator writes a print flowchart to a DASD data set. Theflowchart has more than the usual number of rows and columns per page(command FLOWCHART).

//jobname JOB (accounting)//JS�1� EXEC PGM=CAL2FSIM//STEPLIB DD DSN=cai.ca7.loadlib,DISP=SHR//FLOWPRT DD DSN=print.data.set.name,// DISP=(NEW,CATLG,DELETE),// SPACE=(TRK,(2,1)),UNIT=SYSALLDA,// DCB=(RECFM=FBM,LRECL=2��,BLKSIZE=�)//SYSMSGS DD SYSOUT= //SYSUSNAP DD SYSOUT= //SYSUDUMP DD SYSOUT= //INITDEF DD CA7=CA74LOGON=USERCA7PASS=USERPASSSIZE=MEDIUM/ //PARMDEF DD FROM=(�331�7,��1)JOB=PAY / //SYSIN DD DELJOB JOB=PAYME�5,START=(�331�7,1245), SCHID=2,FUZZ=1�FLOWCHART LRECL=2��,LPPAGE=1��//


CSV Flowchart File Description


The flowchart comma-separated value (CSV) file consists of records that arecomposed of fields that are separated by commas. The records represent theworkflow as it is kept in two internal tables. The five types of records are asfollows:

■ Header record, whose fields contain the field name. This is analogous to aspreadsheet column heading.

■ JOB record, which describes a job object

■ DSN record, which describes a data set object

■ XCN record, which describes a connection between two objects

■ Properties record, which describes the file

Note: The properties record is produced only by the Jobflow Illustrator onlineoption and is used internally by the online option. It is not generated when abatch job is run. The properties record, when present, is the last record in thefile.

Fields in each record are separated by commas. Each field has either a valueenclosed in double quotes or simply a pair of double quotes. All records havethe same number of fields. The first record in the file is the header record,which contains the names of the fields. These can be used as columnheadings.

This data set is suitable for importing into a program such as Microsoft Excel.The CSV output can also be used by an online application such as UnicenterWorkload Control Center (UWCC).



Fields (Columns)

This section describes the fields of the CSV file. The row type describes whichtypes of records the field applies to. Length is the length of the field value anddoes not include the double quotes.

Rel_NumberIndicates the row number of object in internal output table.

Row type: JOB, DSN,XCN

Length: 8

Row_TypeIndicates JOB if the object being described is a job in the output table, DSNif the object being described is a data set in the output table, or XCN if thisis a connection record.

Row type: JOB, DSN, XCN

Length: 4

XCN_Conn_TypeIndicates PR if the connection type is a prerequisite, TR for trigger, RP forrepeat, and ID for an indirect connection.

Row type: XCN

Length: 3

XCN_Conn_SubTypeIndicates NEG if the connection relationship is a negative dependency.COND if the connection relationship is a conditional dependency.

Row type: XCN

Length: 4

XCN_Fwd_Rel_NumberIndicates the number of the forward connection output entry (that is, theRel_Number field of the connected object).

Row type: XCN

Length: 8

Fwd_Conn_CountIndicates this object's number of forward connections.

Row type: JOB, DSN

Length: 5

Job_NameIndicates the name of the job.

Row type: JOB

Length: 8



SchidIndicates the CA 7 schedule ID.

Row type: JOB, DSN

Length: 5

DS_NameIndicates the name of the data set.

Row type: DSN

Length: 44

DS_NumberIndicates the schedule data set number.

Row type: DSN

Length: 10

Job_SystemIndicates the system name (jobset).

Indicates

Row type: JOB

Length: 8

Job_JobnetIndicates the job network name.

Row type: JOB

Length: 8

Hidden_ConnIndicates whether the job/data set has hidden connections (Y or N). Hiddenconnections are trigger or dependency connections to objects that are notincluded in the workflow because of date and time criteria or selection filters.

Row type: JOB, DSN

Length: 1

Soft_FlagIndicates whether this job is a soft object (Y or N). A soft object is one thatdoes not have a starting/creation point in the current workflow. For jobs,these are jobs that are dependency predecessors to one or more jobs in theworkflow, but there is no date and time schedule or trigger in the workflow todefine when the soft job will run. For data sets, these are data sets that aredependency predecessors to one or more jobs in the workflow, but none ofthe jobs in the workflow create that data set, so there is no way to tell whenthat creation will occur.

Row type: JOB, DSN

Length: 1



Job_HeadIndicates whether this job is the head of a chain (Y or N).

Row type: JOB

Length: 1

Job_Start_DateIndicates the target begin date in Julian format (yyyyddd).

Row type: JOB

Length: 7

Job_Start_TimeIndicates the target begin time of day in hh:mm:ss format.

Row type: JOB

Length: 8

Job_End_DateIndicates the target end date in Julian format (yyyyddd).

Row type: JOB

Length: 7

Job_End_TimeIndicates the target end time of day in hh:mm:ss format.

Row type: JOB

Length: 8

Job_Avg_ElapsedIndicates the job lead time or average run time in hh:mm:ss format.

Row type: JOB

Length: 8

Job_MainidIndicates the CPU on which the job can or cannot be scheduled.

Row type: JOB

Length: 8

Job_DR_ClassIndicates the job disaster recovery class.

Row type: JOB

Length: 8

Job_WLB_ClassIndicates the job workload balancing class.

Row type: JOB

Length: 1



Job_Maint_FlagIndicates whether the job is a MAINT job (Y or N).

Row type: JOB

Length: 1

Job_Xplat_TargetReserved for future use.

Row type: JOB

Length: 64

Job_Xplat_FlagIndicates whether the job is an XPJOB job (Y or N). If WCC flags the job asa CA7TOUNI job, this field will also be a Y after the next cycle.

Row type: JOB

Length: 1

Job_Nonexec_FlagIndicates whether the job is marked as EXEC=NO (Y or N).

Row type: JOB

Length: 1

Job_Verify_FlagIndicates whether the job is marked as VERIFY=YES (Y or N).

Row type: JOB

Length: 1

Job_Locked_FlagIndicates whether the job is locked (Y or N).

Row type: JOB

Length: 1

Job_Hold_FlagIndicates whether the job is marked as HOLD=YES (Y or N).

Row type: JOB

Length: 1

Job_JCLOverride_FlagIndicates whether the job is marked as OVERRIDE=YES (Y or N).

Row type: JOB

Length: 1



Job_Trig_Job_FlagIndicates whether the job triggers one or more other jobs (Y or N).

Row type: JOB

Length: 1

Job_Trig_Loop_FlagIndicates N unless both of the following conditions are met, then Y:

■ LOOP=NOSHOW is specified.

■ The job is triggered and is a duplicate (jobname/schid) of another job inthe trigger path of a chain. For example:

JOBA/001 triggers JOBB/001 triggers JOBA/001. The 2nd JOBA is aduplicate.

Row type: JOB

Length: 1

DS_Perm_FlagIndicates whether the data set is marked permanent (Y or N).

Row type: DSN

Length: 1

DS_Internal_FlagIndicates whether the data set is marked internal (Y or N).

Row type: DSN

Length: 1

DS_Cpost_FlagIndicates whether the data set is posted at creation time (Y or N).

Row type: DSN

Length: 1

DS_Auto_FlagIndicates whether the data set is AUTO type (Y or N).

Row type: DSN

Length: 1

DS_GDG_FlagIndicates whether the data set is a GDG (Y or N).

Row type: DSN

Length: 1



Manual_AddIndicates whether this object was manually added to the flow using anADDJOB or ADDDS command (Y or N).

Row type: JOB,DSN

Length: 1

Job_WLB_PriorityIndicates the job workload balancing priority.

Row type: JOB

Length: 3


FLOWCHART TYPE=PRINT Description


A printed flowchart has the following types of objects: jobs, data sets, pointers,dependencies, and connections. Pages are numbered going across, and thendown. Page 001.002 is immediately to the right of page 001.001. Page 002.001is immediately below page 001.001.

Jobs

A job object may look like this:

J--------------+| jobname /nnn || || || || |+--------------+

The J in the upper-left corner indicates that this box represents a job. The jobname and schedule ID are displayed on the first line in the box.

Certain attributes of the job may be displayed in the box. The attributes to bedisplayed are controlled by the JOBBOX keyword on the FLOWCHARTcommand.

For example, if JOBBOX=(SYSTEM,BEGIN,END,MAINID) is specified, a jobmight look like this:

J--------------+| PAYME�1 /��1 ||SYS=SYSTNAME ||BEG=�7�9�/�759||END=�7�9�/�8��||MNID=ALL |+--------------+

Additional job attributes are placed automatically on the top or bottom lines ofthe box when appropriate:

■ If the job is marked as maintenance only, MAINT is placed on the top lineon the left.

J-MAINT--------+

■ If the job is marked as non-executable, NOEX is placed on the top line onthe right.

J---------NOEX-+



■ If the job is marked as a cross-platform job, XPLAT is placed on the bottomline on the left.

+XPLAT---------+

■ If the job was manually added to the flow as the result of an ADDJOBcommand, MA is placed on the bottom line on the right.

+-------MA-----+

■ If the job is not scheduled or triggered, but is a requirement of another jobthat is scheduled or triggered, the predecessor job is marked with SOFT onthe bottom line on the right.

+----------SOFT+

Data Sets

A data set object might look like this:

D--------------+|xxxxxxxx.xxxxx||xxx.xxxxxxxx.x||xxxxxxx.xxxxxx||xx ||N=DSnnnnnnnn |+--------------+

The D in the upper-left corner indicates that this box represents a data set. Thedata set name and its data set number are displayed in the box.

Additional data set attributes are added automatically when appropriate:

■ If the data set is part of a generation data group, GDG is placed on the topline on the right.

D----------GDG-+

■ If the data set is marked to be posted at creation, POST is placed on theline above the data set number, right-justified.

■ If the data set is marked as external, EXT is placed on the bottom line onthe left.

+EXT-----------+

■ If the data set was manually added to the flow as the result of an ADDDScommand, MA is placed on the bottom line on the right.

+-------MA-----+

■ If the data set is not created by any scheduled or triggered job, but is arequirement for a job that is scheduled or triggered, SOFT is placed on thebottom line on the right.

+----------SOFT+



Pointers

A pointer object is shown in a flowchart when a job or data set appears morethan once. The first time a job or data set is shown, it appears as a normal jobor data set object, as described previously. A pointer is shown in all otherplaces where the job or data set is referenced. A pointer for a job looks likethis:

J------ -------+ jobname /nnn tag>>>xxx.yyy

The job's name and schedule ID are shown. The tag is a unique three-digitnumber to help you find where the original object is. The xxx.yyy is the pagenumber on which you'll find the tag number. The tag number is on theconnection immediately above the object. For example, if the pointer shows thefollowing:

J------ -------+ PAYME�5 /�� 2>>>��1.��1

On page 001.001 is a tag of 002 pointing to job PAYME05, like this:

��2>>>+ +J------ -------+| PAYME�5 /�� || || || || |+--------------+

A special type of pointer may be displayed when a never-ending trigger loop isdetected. An example of a trigger loop is JOBA schedule ID 1 triggers JOBBschedule ID 1, which triggers JOBA schedule ID 1 again. Instead of a tag andpage number, the word LOOP is displayed.

J------ -------+| jobname /nnn || || LOOP || || |+--------------+



Dependencies

A dependency is shown without any indication of when the job might run. It isexhibited only to let the viewer know that a dependency exists. Both negativeand conditional dependencies are shown. No additional information about thejob is displayed:

J------ -------+ jobname /nnn

The job may or may not appear elsewhere in the flowchart.

Connections

Connections show the relationships between the objects in the flowchart. Theconnections always go down and to the right.

The connection is labeled to show what type of connection it is. The characterused to print the connection may also indicate the type of connection. Ingeneral, the vertical bar (|) is used for triggers, repeats, and data set creation;the plus sign (+) is used for requirements; and X is used for dependencies. Ifmore than one type of connection is being shown, the vertical bar (|) is used.

The following types of connections are shown:

CONDIdentifies a conditional dependency.

DRJIdentifies a data set required by job.

DTJIdentifies a data set that triggers a job.

INDJRJIdentifies a job required by job indirectly. This connection type is shown onlywhen data sets are being excluded from the display. If JOBA creates dataset X, and data set X is required by JOBB, the flowchart shows JOBA as anindirect requirement of JOBB.

INDJTJIdentifies a job that triggers a job indirectly. This connection type is shownonly when data sets are being excluded from the display. If JOBA createsdata set X, and data set X triggers JOBB, the flowchart shows JOBAindirectly triggering JOBB.

JCDIdentifies a job that creates data set.

JRJIdentifies a job required by job.



JTJIdentifies a job that triggers a job.

NEGDEPIdentifies a negative dependency.

REPEATIdentifies a job that repeats itself.

Connections might look like this:

D------ -------+|COMPANY.DAILY.||PAYME�2 || || ||N=DS��316 |+------ -------+ | | | | ----------------- ----------------- -----------------

| | + +|DTJ |DTJ +DRJ +DRJ

��1>>>| ��2>>>| + +| | + +

J------ -------+ J------ -------+ J------ -------+ J------ -------+| PAYME�3/��2 | | PAYME�4/��2 | PAYME�3/��2 PAYME�4/��2|BEG=�7�9�/�9��| |BEG=�7�9�/�9�1| ��1>>>��1.��1 ��2>>>��1.��1|END=�7�9�/�9�1| |END=�7�9�/�9�2|| | | || | | |+--------------+ +--------------+

This example shows that when data set COMPANY.DAILY.PAYME02 isupdated, jobs PAYME03 and PAYME04 are triggered (DTJ = Data set TriggersJob). These jobs also have a data set dependency of the data set (DRJ = Dataset Required by Job).


Sample FLOWCHART TYPE=CSV File (Partial)


The following is a sample of comma-separated values for the FLOWCHARTTYPE=CSV File:

"Rel_Number","Row_Type","XCN_Conn_Type","XCN_Conn_SubType","XCN_Fwd_Rel_Number","Fwd_Conn_Count","Job_Name","Schid","DS_Name","DS_Number","Job_System","Job_Jobnet","Hidden_Conn","Soft_Flag","Job_Head","Job_Start_Date","Job_Start_Time","Job_End_Date","Job_End_Time","Job_Avg_Elapsed","Job_Mainid","Job_DR_Class","Job_WLB_Class","Job_Maint_Flag","Job_Xplat_Target","Job_Xplat_Flag","Job_Nonexec_Flag","Job_Verify_Flag","Job_Locked_Flag","Job_Hold_Flag","Job_JCLOverride_Flag","Job_Trig_Job_Flag","Job_Trig_Loop_Flag","DS_Perm_Flag","DS_Internal_Flag","DS_Cpost_Flag","DS_Auto_Flag","DS_GDG_Flag","Manual_Add","Job_WLB_Priority"

"1","JOB",,,,"2","PAYME�1","��1",,,"SYSTNAME",,"N","N","Y","2��7�9�","�7:59:��","2��7�9�","�8:��:��","��:�1:��","ALL",,"A","N",,"N","N","N","N","N","N","N","N",,,,,,"N","1��"

"1","XCN","TR",,"2"

"1","XCN","TR",,"3"

"2","DSN",,,,"1",,"��1","COMPANY.DAILY.PAYME�1","8",,,"N","N",,,,,,,,,,,,,,,,,,,,"N","Y","N","N","N","N""2","XCN","PR",,"13"

"3","DSN",,,,"4",,"��1","COMPANY.DAILY.PAYME�2","6",,,"N","N",,,,,,,,,,,,,,,,,,,,"N","Y","N","Y","N","N"

"3","XCN","TR",,"14"

"3","XCN","TR",,"15"

"3","XCN","PR",,"14"

"3","XCN","PR",,"15"

"4","JOB",,,,"3","PAYME�8","��1",,,"SYSTNAME",,"N","N","Y","2��7�9�","�7:59:��","2��7�9�","�8:��:��","��:�1:��","ALL",,"8","N",,"N","N","N","N","N","N","N","N",,,,,,"N","1��"

"4","XCN","TR",,"5"

"4","XCN","TR",,"6"

"4","XCN","PR",,"7"

"5","DSN",,,,"1",,"��1","COMPANY.DAILY.PAYME�8","9",,,"N","N",,,,,,,,,,,,,,,,,,,,"N","Y","N","N","N","N"

"5","XCN","PR",,"16"

"6","DSN",,,,"2",,"��1","COMPANY.DAILY.PAYME�9","7",,,"N","N",,,,,,,,,,,,,,,,,,,,"N","Y","N","Y","N","N"

"6","XCN","TR",,"7"

"6","XCN","PR",,"7"

"7","JOB",,,,"4","PAYME1�","��1",,,"TEST1�",,"N","N","N","2��7�9�","�8:15:��","2��7�9�","�8:16:��","��:�1:��","ALL",,"A","N",,"N","N","N","N","N","N","Y","N",,,,,,"N","1��""7","XCN","TR",,"17"

"7","XCN","TR",,"18"

"7","XCN","PR","NEG","15"

"7","XCN","PR",,"18"

"8","JOB",,,,"2","PAYME11","��1",,,"SYSTNAME",,"N","N","Y","2��7�9�","�7:59:��","2��7�9�","�8:��:��","��:�1:��","ALL",,"B","N" ,,"N","N","N","N","N","N","Y","N",,,,,,"N","1��"

"8","XCN","RP",,"9"

"8","XCN","TR",,"1�"


Appendix A. CA7TOUNI ConversionUtility


PHASE I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323PHASE II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Clean-Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Conversion Utility Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 335Pre-Conversion Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

The CA7TOUNI to XPJOB conversion utility lets users convert existingCA7TOUNI cross-platform jobs to XPJOB type job definitions. The conversionprocess consists of two phases. The first phase reads existing CA7TOUNI JCLmembers, extracting the information necessary to build the new XPJOBdefinition. The second phase takes that output as BTI input and defines theXPJOB in the CA 7 database.

The conversion utility has two benefits. First, it provides a semi-automatedmechanism for changing your CA7TOUNI jobs to XPJOB definitions. Second, itmaintains any requirements, triggers, and schedules associated with the originalCA7TOUNI job.

Due to the complexity of the conversion process, the following assumptionsmust be true or the conversion fails:

■ The job must have successfully executed in a CA 7 environment withoutQJCL updates. CA7TOUNI jobs that have run successfully should convert,assuming the remaining assumptions are met. Jobs that have not runsuccessfully most likely have errors that would preclude their successfulconversion.

■ All CA7TOUNI jobs to convert must reside in a PDS in non-compressedformat. You must move JCL that resides in a source control product (forexample, CA Endevor and CA Librarian) to a PDS. Only one PDS can beprocessed at a time. It must be cataloged and defined to CA 7.

■ A one-to-one match of the CA7TOUNI JCL member name and the CA 7CA7TOUNI job definition must exist. If the same member does not exist inCA 7, the conversion fails or worse, wipes out a CA 7 job definition havingthe same name.

Appendix A. CA7TOUNI Conversion Utility 321

■ The CA7TOUNI job cannot have a SYSIN DD data set, only in-stream data.It is assumed if the parameters are in a data set, the SUBPASS parameteris specified, which sites do not want displayed.

If your site has SYSIN DD data sets in their CA7TOUNI JCL, you must runthe pre-conversion utility to convert these data sets to instream data. Usethe output data set from the pre-conversion utility as input to the conversionutility.

■ A NODE parameter must exist in the CA7TOUNI job definition, either in the//PROFILE data set or in the SYSIN data. Multiple NODE parameters ineither location prevent the member from being converted.

■ A SUBFILE parameter must exist in the CA7TOUNI job definition SYSINdata. Multiple SUBFILE parameters will prevent the member from beingconverted.

■ Any # cards in the CA7TOUNI JCL stream prevent the member from beingconverted. The # cards are allowed in the CA7TOUNI SYSIN data as longas they follow the NODE and SUBFILE parameters.

The conversion utility generates a report that shows the processing for eachmember. Numerous error messages may be generated that indicate conversionwas not possible. However, if the assumptions listed previously are met, theconversion is expected to be successful.

It is expected, but not required, that the CA7TOUNI member job consists of asingle step. An input parameter is provided that lets you specify if the first stepinvokes a CA 11 RMS procedure. In this situation, the first step is ignored. Anysteps after the CA7TOUNI step are also ignored, and a warning message isgenerated to that effect.


PHASE I

In Phase I, the conversion utility program, SASSX2UN, is executed in a batchjob. The batch job consists of two steps.

The first step executes IEBCOPY, which creates a backup copy of the PDSagainst which the conversion is performed. The PDS can contain CA7TOUNIJCL, conventional CA 7 job JCL or both. You do not need to separate outCA7TOUNI JCL.

The second step executes program SASSX2UN. Only PDS members whosefirst statement begins with #7UNI are eligible for selection. All other membersare bypassed. The JCL is shown in the following (see member XPJCONV inSAMPJCL).

//jobname JOB ......,REGION=4�96K//JS�1� EXEC PGM=IEBCOPY//SYSUT1 DD DSN=highlvl.input.dsn,DISP=SHR//SYSUT2 DD DSN=highlvl.input.dsn.backup,// DISP=(NEW,CATLG,DELETE),// UNIT=SYSALLDA,// SPACE=(CYL,(�5,�2,2�),RLSE),// DCB=(RECFM=FB,LRECL=8�,BLKSIZE=�)//SYSPRINT DD SYSOUT= //SYSIN DD COPY INDD=((SYSUT1,R)),OUTDD=SYSUT2// //JS2� EXEC PGM=SASSX2UN//STEPLIB DD DSN=cai.ca7.loadlib,DISP=SHR//PDSDD DD DSN=highlvl.input.dsn,DISP=SHR//CONVCMDS DD DSN=highlvl.xpjconv.convcmds,// DISP=(NEW,CATLG,DELETE),// UNIT=SYSALLDA,// SPACE=(CYL,(1�,5),RLSE),// DCB=(RECFM=FB,LRECL=8�,BLKSIZE=�)//RESTCMDS DD DSN=highlvl.xpjconv.restcmds,// DISP=(NEW,CATLG,DELETE),// UNIT=SYSALLDA,// SPACE=(CYL,(1�,5),RLSE),// DCB=(RECFM=FB,LRECL=8�,BLKSIZE=�)//CARPROC DD DSN=cai.ca7.dprocs,DISP=SHR//REPORT DD SYSOUT= //SYSIN DD RESTMASK=$2RMSEXEC=RMSPROCMEMBER=AAAAMEMBER=B?CA MEMBER=DDDD //

The JCL that executes the SASSX2UN program consists of three input andthree output data sets.


PHASE I

Input JCL Statements

The following are the input data sets:

SASSX2UN PDSDD Statement(Required) The PDSDD data set contains the CA7TOUNI JCL and can alsocontain JCL for conventional CA 7 jobs. Only JCL whose first card startswith #7UNI will be selected for conversion. This data set must be defined toCA 7 as a CA 7 JCL library. #7UNI jobs can execute the CA7TOUNIprogram directly or from a JCL procedure (as shown in the following):

#7UNI//jobcard//SUBMIT EXEC PGM=CA7TOUNI,PARM='&C_L27#,&C_L2SN'//STEPLIB DD DISP=SHR,DSN=ca7.loadlib//PROFILE DD DISP=SHR,DSN=highlvl.ca7.profile//SYSPRINT DD SYSOUT= //SNAP DD SYSOUT= //SYSIN DD 7TRACE=YESNODE=TESTPLNSUBFILE=CAU9TEST

#7UNI//jobcard//SUBMIT EXEC CA7TPROC,PARM='&C_L27#,&C_L2SN'//SYSPRINT DD SYSOUT= //SYSIN DD 7TRACE=YESNODE=TESTPLNSUBFILE=CAU9TEST

When executed as a JCL procedure, the procedure name (for example,CA7TPROC) must exist as a member in the data set pointed to by theCARPROC DD statement.

If a site ran the pre-conversion utility, the final output from that job shouldbe used here in place of the original CA 7 JCL library.

SASSX2UN CARPROC Statement(Required) The CARPROC data set identifies the data set containing anydefined CA7TOUNI JCL procedures and is required, even if no JCLprocedures are used to execute the CA7TOUNI program. In this situation,supply an existing procedure library such as SYS2.PROCLIB orUSER.PROCLIB. It is only used if a JCL procedure is found in the #7UNImember being processed.


PHASE I

SASSX2UN SYSIN Statement(Optional) The SYSIN data set contains processing keywords used bySASSX2UN. If this statement is not supplied, the following processingoccurs:

■ All CA7TOUNI members in the PDSDD data set are eligible forselection.

■ No restore commands for backout are generated. Thus, you cannotrestore your original CA7TOUNI CA 7 job definition.

■ CA 11 RMS steps are not permitted. The first step in the CA7TOUNIJCL is assumed to invoke the CA7TOUNI program.

If the SYSIN DD statement is supplied, processing is influenced by thekeyword/value pair entered. The four valid keywords are PDSDDDSN,RESTMASK, RMSEXEC, and MEMBER.

Important! If a site has to run the pre-conversion utility, the SYSIN DDstatement must be supplied and have PDSDDDSN keyword specified.

RESTMASKDefines a 2-character value that creates the restore name of theCA7TOUNI job definition. If a RESTMASK is not provided, a backup ofthe CA7TOUNI job definition is not created. The member beingconverted will have a character in its name replaced by the mask. Thefirst character is the replacement character, and the second characterindicates the offset of the replacement character in the member name.For example:

RESTMASK=$2

The restore name for member CA7XJOB is C$7XJOB.

RESTMASK=#3

The restore name for member CA7XJOB is CA#XJOB.

If the member name is not as long as the offset position, the maskcharacter is placed in the first blank position of the member name. Forexample:

RESTMASK=$4

The restore name for member CA7X is CA7$.

The restore name for member CA7Y is also CA7$.

Important! If the mask character becomes the last character of themember name, you could end up with duplicate member names and getundesirable results during conversion. In the preceding situation, CA7Ywould not convert during Phase II. However, its JCL would be deleted.This is discussed in greater detail under SASSX2UN CONVCMDS DD.

The last RESTMASK value specified in the SYSIN DD statement is thevalue used when creating the restore name.


PHASE I

Before conversion, ensure that your CA 7 database has enough spaceto hold backup copies of the CA7TOUNI jobs being converted.

RMSEXECIdentifies the CA 11 RMS procedure used at your site. The value followsstandard JCL procedure naming conventions. If specified, and the firststep in the CA7TOUNI JCL contains a PROC that matches the value ofthis keyword, that JCL is bypassed, and the next step is assumed tocontain the CA7TOUNI program or procedure.

The last RMSEXEC value specified in the SYSIN DD statement is thevalue used to identify the CA 11 RMS procedure used at your site.

MEMBERIdentifies the members you want to convert. The value can be 1 to 8characters. You can enter up to 512 MEMBER cards. Full masking issupported. The following are some sample values:

MEMBER=CA7XJOB

The member name must match this name exactly.

MEMBER=CA7X*

All members matching the first four letters are eligible for selection.

MEMBER= C?7?J*

All members having a C in the first position, a 7 in the third position, anda J in the fifth position are selected for processing.

The CA7XJOB is not selected three times for processing, regardless ofthe order of these three member statements. The first match foundresults in the member being processed for conversion.

If no MEMBER= keywords are found, all members in the input PDS areeligible for selection.

PDSDDDSNIdentifies the original PDSDD data set name used as input to thepre-conversion utility and is only needed if the site has to run thepre-conversion utility.

If the PDSDDDSN keyword was not supplied, and a site ran thepre-conversion utility, the output BTI files produced by the conversion utilitywill reference the output data set generated by pre-conversion process, notthe real CA 7 JCL library containing the jobs to be converted.


PHASE I

Examples of SASSX2UN SYSIN Statements

The following are examples of SASSX2UN SYSIN statements.

Example 1

This example generates no Restore command because no RESTMASKkeyword is found. The first step in the CA7TOUNI job is checked for a JCLprocedure called RMSPROC. If found, the JCL procedure is bypassed, and thenext step is considered the CA7TOUNI step. If the first step in the job does notexecute a JCL procedure called RMSPROC, it is considered the CA7TOUNIstep. Members matching the mask or member name provided are eligible forselection. The data set name referenced in the PDSDDDSN keyword will bereflected in the DELETE and SAVE BTI commands. This must reference a validCA 7 JCLLIB.

RMSEXEC=RMSPROCMEMBER=C?ABCMEMBER=ABCMEMBER=TOUNIJOBPDSDDDSN=ABC.CA7.JOBLIB

Example 2

The following example generates a Restore command for each memberselected for processing. The Restore member name has a $ in the fourthposition. Because no RMSEXEC keyword is provided, the first step of the job isconsidered the CA7TOUNI step. All members are eligible for selection becauseno MEMBER keywords are provided.

RESTMASK=$4

Example 3

This example generates no Restore command because the RESTMASKkeyword was not provided. The first step of the job is considered theCA7TOUNI step because no RMSEXEC keyword was provided. All membersare eligible for conversion. For this situation, it is more efficient to omit theMEMBER=* entry as each member must be compared to the mask todetermine whether it is eligible for selection. If this card is omitted, no maskcomparison is performed (just like Example 2), members are automaticallyeligible for selection.

MEMBER=*


PHASE I

Output JCL Statements

The following are the output JCL statements:

SASSX2UN CONVCMDS Statement(Required) The CONVCMDS data set is a physical sequential output dataset. The CA 7 commands that will convert the CA7TOUNI job to theXPJOB are written to this data set. Though you can edit the CONVCMDSdata set before running it through the Batch Terminal Interface (Phase II), itis not recommended. Examples of the output are shown in the following:

/LOGON TRENT�5DBMCONVERT,CASE�4�1,BACKUP=C$SE�4�1XPJOBUPD,CASE�4�1,NODE=CA7NODE,EX1=(C:\PROGRA˜1\WINDOW˜3\MPLAYER2.EXE),MEMBER=CASE�4�1,SUTYPE=YJCLDELETE,CASE�4�1,DSN=APCDAL.DEVCA7.CA31CA76.JOBLIBJCL,CASE�4�1EDITMIXEDXSEQI ,PARM1=C:\MUSIC.MP3SUBUSER=CA7USER$IENDSAVESAVE,CASE�4�1,DSN=APCDAL.DEVCA7.CA31CA76.JOBLIBCLEARDBMXNODEADD,CA7NODE/LOGOFF

As the examples show, you always have the following commands:

■ CONVERT statement

■ XPJOB statement

■ JCL DELETE statement

Depending on your parameters, you may or may not have theJCL/EDIT/MIXED/XSEQ/I and $IEND/SAVE/CLEAR commands. XNODEADD commands are present for each unique node. Ensure that your VRMdatabase has space for these node entries.


PHASE I

Important! Conditions that can cause the conversion to fail are as follows:

Conversion is a destructive process. Each of the commands notedpreviously can be entered by itself and succeed or fail. For example, theCONVERT and XPJOB commands could fail, but the JCL DELETEcommand could succeed. Thus, you are left with a CA7TOUNI job definitionand no CA7TOUNI JCL (remember you do have a backup from theIEBCOPY step).

Two conditions can cause the conversion to fail.

■ The JCL member name contains the #7UNI statement and appropriateCA7TOUNI parameters but the definition in CA 7 does not indicate aCA7TOUNI job. If the assumptions identified at the beginning of thissection are true, this should not occur.

■ The Restore name provide already exists.

Regarding the second bulleted item, consider this example where theRESTMASK was set to 8$ (so the last character of the member name ischanged to the mask character).

CONVERT,ABCDE1,BACKUP=ABCDE$CONVERT,ABCDE2,BACKUP=ABCDE$

Job ABCDE1 completes successfully. Job ABCDE2 fails because thebackup name already exists. Job ABCDE2's JCL stream is deleted. Abackup of the ABCDE2 CA7TOUNI JCL exists in the copy of the PDSDDPDS created in the first job step.

Important! Ensure that duplicate backup members do not exist, or will notexist, when the CONVERT command is executed.

SASSX2UN RESTCMDS Statement(Required) The RESTCMDS data set is a physical sequential output dataset. The CA 7 commands that will restore the XPJOB back to theCA7TOUNI job are written to this data set. The Restore command is asingle line command.

RESTORE,CA7XJOB,BACKUP=CA7$JOB

The Restore command is a destructive command. It wipes out an XPJOBdefinition created by the Convert command. If the Restore command isexecuted, you will also need to copy the original CA7TOUNI JCL from thebackup data set (created during the conversion process) to the appropriateCA 7 JCL library.

Remember, if a RESTMASK is not provided, no back-up of the CA 7 jobdefinition will be created because no RESTORE command is generated. Torestore, you will need to delete the CA7 XPJOB definition, create a "new"job definition, and copy the original JCL back from data set created in theIEBCOPY step.


PHASE I

SASSX2UN REPORT Statement(Required) The REPORT data set is a SYSOUT data set. All informational,warning and error messages generated during the first phase of theconversion process are written to this data set. Inspect this reportthoroughly before proceeding to Phase II.

If your sites' CA7TOUNI job definitions meet the assumptions defined in thefirst part of this section, you should only see informational and, possibly,warning messages. A sample of the report is shown below. All possiblemessages are shown in “Conversion Utility Messages” on page 335.

SASSX2UN-�1 CA-7 CA7TOUNI Conversion UtilityDATE: 1�/25/yyMEMBER CASE�1�1 SELECTED FOR PROCESSINGMEMBER CASE�1�1 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE�1 ERROR - MEMBER CASE�1�1 NO NODE KEYWORD FOUND. CANNOT CONVERT THIS MMEMBER CASE�1�6 SELECTED FOR PROCESSINGMEMBER CASE�1�6 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE�1 ERROR - MEMBER CASE�1�6 - PARM2 HAS NO DATA ERROR - MEMBER CASE�1�6 PROCESSING FAILED - SEE PREVIOUS MESSAGESMEMBER CASE�1�7 SELECTED FOR PROCESSINGMEMBER CASE�1�7 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE�1 ERROR - MEMBER CASE�1�7 - SUTYPE HAS BAD PARAMETER VALUE ERROR - MEMBER CASE�1�7 PROCESSING FAILED - SEE PREVIOUS MESSAGESMEMBER CASE�1�8 SELECTED FOR PROCESSINGMEMBER CASE�1�8 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE�1 ERROR - MEMBER CASE�1�8 - CONTINUTATION FAILED ERROR - MEMBER CASE�1�8 PROCESSING FAILED - SEE PREVIOUS MESSAGESMEMBER CASE�1�9 SELECTED FOR PROCESSINGMEMBER CASE�1�9 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE�1 ERROR - MEMBER CASE�1�9 - WRONG OR UNKNOWN KEYWORD ERROR - MEMBER CASE�1�9 PROCESSING FAILED - SEE PREVIOUS MESSAGESMEMBER CASE�11� SELECTED FOR PROCESSINGMEMBER CASE�11� PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE�1MEMBER CASE�11� CONVERT COMMANDS SUCCESSFULLY CREATEDMEMBER CASE�11� RESTORE COMMANDS SUCCESSFULLY CREATEDMEMBER CASE�111 SELECTED FOR PROCESSINGMEMBER CASE�111 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE�1MEMBER CASE�111 CONVERT COMMANDS SUCCESSFULLY CREATEDMEMBER CASE�111 RESTORE COMMANDS SUCCESSFULLY CREATEDTotal Members................................ 7Members Selected for Conversion.............. 7Members Successfully Converted............... 2Members Not Converted........................ 5


PHASE I

SASSX2UN Return Codes

The conversion utility program (SASSX2UN) returns one of the following fourreturn codes:

RC=0Indicates that the job ran successfully, only informational messages arewritten to the REPORT DD statement.

RC=4Indicates that the job ran successfully but one or more members hadwarning messages issued. Check the warning messages in the REPORTDD statement and determine whether any action is necessary.

RC=8Indicates that the job ran successfully but one or more members had errorsthat prevented conversion statements from being created. Check the errormessages in the REPORT DD statement and determine whether any actionis necessary.

RC=12Indicates that the job failed. No CONVERT commands were generated.Check the WTO in the job's JES JOBLOG for the cause of the failure.

CA7TOUNI Keyword Processing During Phase I of Conversion

SASSX2UN processes CA7TOUNI keywords in the sequence in which theywere entered. User-ID and password information extracted from the jobstatement, //*LOGONID card, //*JOBFROM statement, or //*PASSWORD card iswritten out first, followed by keyword information extracted from the PROFILEdata set and then the SYSIN data stream.

The JOBNO, JOBSET, MONITOR, SUBCHECK, and 7TRACE CA7TOUNIkeywords are not valid for XPJOB definitions and ignored.


PHASE I

PHASE II

In Phase II, the Batch Terminal Interface (BTI) procedure is executed. This jobuses the Phase I output file CONVCMDS as input. JCL to execute thisprocedure is shown in the following:

//jobname JOB ......,REGION=4�96K//JS�1� EXEC CA7BTI//SYSIN DD DSN=highlvl.batch.convcmds,DISP=SHR//

If the member name specified on the CONVERT command does not exist, or isnot a CA7TOUNI job definition, the command will fail. If the BACKUP=parameter is specified on the CONVERT command, and the backup memberexists, the command will fail. Standard error processing is followed for all othercommands (such as XPJOB, JCL, SAVE, CLEAR) that may be found in thedeck.

When the BTI job completes, thoroughly inspect the output report and resolveany errors that were reported.

Be sure to use the BTI (CA7BTI) procedure during the conversion process.CA7BTI can handle PARMxx keyword/value pairs up to 80 characters in length.The CCI batch interface will truncate PARMxx keyword/value pairs greater than71 characters and cause your conversion to fail.

Execute the CONVERT Command Online

You can enter the CONVERT command within CA 7 from any panel. Thecommand creates an XPJOB shell definition that cannot be executed. You mustupdate this definition, providing the XPJOB information described in theDatabase Maintenance Guide, and modify the "JCL" as necessary with theCA7TOUNI parameter statements. We do not recommend using the CONVERTcommand in the CA 7 online environment.

The following is an example of executing the CONVERT command from anonline CA 7 panel and the output that would be produced from that command.

Command: CONVERT,XPJOB01,BACKUP=XPJOB01$

Output:

--- FUNCTION: CONVERT--- JOBNAME : XPJOB�1--- BACKUP : XPJOB�1$

SM27-�1 L JOB=XPJOB�1 CONVERT SUCCESSFULLY COMPLETED


PHASE II

Restore a Converted Member

You can restore a converted member or members using the commands foundin the RESTCMDS DD data set and the BTI JCL stream, as shown in thefollowing:

//jobname JOB ......,REGION=4�96K//JS�1� EXEC CA7BTI//SYSIN DD DSN=highlvl.batch.restcmds,DISP=SHR//

Because RESTORE is a single-line command, you can easily cut and pasteonly those members you wish to restore to another data set and use that asyour BTI input. Or, you can log on to your CA 7 environment and execute it asan online command. A sample is shown below:

Command: RESTORE,XPJOB01,BACKUP=XPJOB01$

Output:

--- FUNCTION: RESTORE--- JOBNAME : XPJOB�1--- BACKUP : XPJOB�1$

SM27-�1 L JOB=XPJOB�1 RESTORE SUCCESSFULLY COMPLETED

Remember, this simply restores the CA7TOUNI definition. You must still copythe CA7TOUNI JCL from the Phase I IEBCOPY back-up to the appropriateCA 7 JCL library.


Clean-Up

Clean-Up

As stated in the beginning of this section, this process maintains anyrequirements, triggers, and schedules associated with the original CA7TOUNIjob. It also maintains PROFILE and STEPLIB data set definitions resulting fromthe original CA7TOUNI LOAD, or done using the DB.6 panel. These definitionsare not required for the XPJOB type jobs and may be deleted using the DB.6panel. Review your original JCL or CA7TOUNI procedure to determine thePROFILE and STEPLIB data sets.


Conversion Utility Messages


The following messages can appear in the conversion utility REPORT DDstatement.

Informational Messages

MEMBER xxxxxxxx SELECTED FOR PROCESSING

Reason: This message indicates the member contained the #7UNI statement and wasselected for conversion processing.

MEMBER xxxxxxxx CONVERT COMMANDS SUCCESSFULLY CREATED

Reason: This message indicates that the member was successfully processed and thatCONVERT BTI commands for this member have been placed in the CONVCMDS DD dataset.

MEMBER xxxxxxxx RESTORE COMMANDS SUCCESSFULLY CREATED

Reason: This message indicates that the member was successfully processed and thatRESTORE BTI commands for this member have been placed in the RESTCMDS DD dataset. This message is only generated if the RESTMASK parameter was specified.

MEMBER xxxxxxxx CA7TOUNI PROC =

Reason: This message shows the CA7TOUNI JCL procedure the member invokes. If themember executes PGM=CA7TOUNI, this message is not displayed.

MEMBER xxxxxxxx PROFILE DSN IS

Reason: This message shows the PROFILE data set the member uses. The CACCENVmember is this data set is checked for CA7TOUNI parameters and values.

Warning Messages

*** WARNING *** - MEMBER xxxxxxxx COULD NOT BE OPENED AND WAS BYPASSED

Reason: A member in the PDSDD statement data set could not be processed.

*** WARNING *** - MEMBER xxxxxxxx JOB STEPS FOUND AFTER CA7TOUNI ARE IGNORED.REVIEW THEIR PURPOSE

Reason: A CA7TOUNI job had job steps after the CA7TOUNI step. Review these stepsand determine what action must be taken when the job is converted to an XPJOB sincethese steps will no longer be executed.



*** WARNING *** - MEMBER xxxxxxxx VALUE FOR USER=/LOGONID/JOBFROM BYPASSED,EXCEEDS 8 CHARACTER MAX

Reason: A CA7TOUNI job had a USER= parameter on the job statement, or a//*LOGONID statement, or a //*JOBFROM card. The conversion utility will create aSUBUSER parameter statement from any of these statements if the value is eightcharacters or less.

*** WARNING *** - MEMBER xxxxxxxx VALUE FOR PASSWORD EXCEEDS 14 CHARACTERMAXIMUM

Reason: A CA7TOUNI job had a PASSWORD= parameter on the job statement, or a//*PASSWORD statement. The conversion utility will create a SUBPASS parameterstatement from either of these cards if the value is 14 characters or less.

*** WARNING *** - MEMBER xxxxxxxx VALUE FOR USER=/LOGONID/JOBFROM OR PASSWORDNOT VALID

Reason: A CA7TOUNI job had one of the following:

■ USER= parameter on the JOB statement

■ PASSWORD= parameter on the JOB statement

■ A //*LOGONID statement

■ //*JOBFROM statement

■ //*PASSWORD statement

No value was specified for the parameter. The Conversion Utility will create eitherSUBUSER or SUBPASS parameter statements from these statements their value is valid.

*** WARNING *** - MEMBER xxxxxxxx SUBROOT PARM FOUND. SEE XPDEF INIT DECK PARMFOR SUBROOT DETAILS

Reason: A CA7TOUNI job had SUBROOT parameter. This parameter is processeddifferently in XPJOB definitions. For more information about this processing, see theXPDEF initialization statement in the Systems Programmer Guide.

*** ERROR *** - MEMBER xxxxxxxx PROCESSING FAILED - SEE PREVIOUS MESSAGES

Reason: The member listed has serious errors that prevented conversion. Previous errormessages in the REPORT DD output (for the member) will explain the exact cause of theproblem.

*** ERROR *** - MEMBER xxxxxxxx MULTIPLE NODES FOUND IN SYSIN DATA. CANNOTCONVERT THIS MEMBER

Reason: The member listed has multiple NODE parameter entries in the SYSIN data.The conversion utility allows for a maximum of one entry in the SYSIN data.



*** ERROR *** - MEMBER xxxxxxxx MULTIPLE NODES FOUND IN PROFILE DSN. CANNOTCONVERT THIS MEMBER

Reason: The member listed has multiple NODE parameter entries in the PROFILE dataset. The conversion utility allows for a maximum of one entry in the PROFILE data set.

*** ERROR *** - MEMBER xxxxxxxx # CARDS FOUND BEFORE THE NODE. CANNOT CONVERTTHIS MEMBER

Reason: The member listed has # statements before the NODE parameter in the SYSINdata. # statements are typically used for substitution and are resolved at job submission.The utility cannot determine how to process a NODE parameter that follows a # statement.

*** ERROR *** - MEMBER xxxxxxxx MULTIPLE SUBFILES FOUND IN SYSIN DATA. CANNOTCONVER MEMBER

Reason: The member listed has multiple SUBFILE parameter entries in the SYSIN data.The conversion utility allows for a maximum of one entry.

*** ERROR *** - MEMBER xxxxxxxx # CARDS FOUND BEFORE THE SUBFILE. CANNOTCONVERT THIS MEMBER

Reason: The member listed has # statements before the SUBFILE parameter in theSYSIN data. # statements are typically used for substitution and are resolved at jobsubmission. The utility cannot determine how to process a SUBFILE parameter thatfollows a # statement.

*** ERROR *** - MEMBER xxxxxxxx SYSIN DSN OR PROC FOUND IN SYSIN. CANNOTCONVERT THIS MEMBER

Reason: The member listed has a SYSIN data set or PROC concatenated to the SYSINDD statement. It is assumed a SYSIN data set will contain a SUBPASS parameter the sitedoes not want displayed so the member is not processed. Anything concatenated to theSYSIN DD * statement will cause an error.

*** ERROR *** - MEMBER xxxxxxxx PROC/PGM= VALUE EXCEEDS 8 CHARACTERS. CANNOTCONVERT THIS MEMBER

Reason: The member listed has a JCL error. The JCL procedure or the program nameexceeded 8 characters. One of the initial assumptions is that the job has run successfullyas a CA7TOUNI job. This will not be true if this error is displayed.

*** ERROR *** - MEMBER xxxxxxxx READ PAST EOL SEARCHING PROC/PGM LINE. CANNOTCONVERT THIS MEMBER

Reason: The member listed has a JCL error. One of the initial assumptions is that thejob has run successfully as a CA7TOUNI job. This will not be true if this error is displayed.



*** ERROR *** - MEMBER xxxxxxxx NO VALUE PROVIDED FOR PGM= OR PROC NAME.CANNOT CONVERT MEMBER


*** ERROR *** - MEMBER xxxxxxxx PROFILE DSN EXCEEDS 44 CHARACTERS. CANNOTCONVERT THIS MEMBER

Reason: The member listed has a JCL error. Data set names cannot exceed 44characters. One of the initial assumptions is that the job has run successfully as aCA7TOUNI job. This will not be true if this error is displayed.

*** ERROR *** - MEMBER xxxxxxxx READ PAST EOL SEARCHING //PROFILE DSN. CANNOTCONVERT MEMBER


*** ERROR *** - MEMBER xxxxxxxx NO VALUE PROVIDED FOR PROFILE DSN. CANNOTCONVERT THIS MEMBER

Reason: The member listed has a JCL error. No value was provided for the PROFILEdata set. One of the initial assumptions is that the job has run successfully as aCA7TOUNI job. This will not be true if this error is displayed.

*** ERROR *** - MEMBER xxxxxxxx PROFILE DSN NOT FOUND. CANNOT CONVERT THISMEMBER

Reason: The member listed has a JCL error. The PROFILE DSN could not be found.One of the initial assumptions is that the job has run successfully as a CA7TOUNI job.This will not be true if this error is displayed

*** ERROR *** - MEMBER xxxxxxxx COULD NOT ALLOCATE PROFILE DSN. CANNOTCONVERT THIS MEMBER

Reason: The member listed has a JCL error. The PROFILE DSN could not be allocated.One of the initial assumptions is that the job has run successfully as a CA7TOUNI job.This will not be true if this error is displayed

*** ERROR *** - MEMBER xxxxxxxx # CARDS FOUND BEFORE SYSIN DD CARD. CANNOTCONVERT THIS MEMBER

Reason: The member listed has # statements before the SYSIN data. # cards aretypically used for substitution and are resolved at job submission. The utility cannotdetermine how to process JCL when # statements are present.



*** ERROR *** - MEMBER xxxxxxxx NO SUBFILE KEYWORD FOUND. CANNOT CONVERT THISMEMBER

Reason: The member listed has no SUBFILE parameter in the SYSIN DD data. XPJOBdefinitions require a SUBFILE. If one is not found the job cannot be converted. Thismessage is also displayed if the first step found in the member is NOT the CA7TOUNIstep and does NOT match the RMSEXEC parameter value.

*** ERROR *** - MEMBER xxxxxxxx NO NODE KEYWORD FOUND. CANNOT CONVERT THISMEMBER

Reason: The member listed has no NODE parameter. XPJOB definitions require aNODE. If one is not found the job cannot be converted.

*** ERROR *** - MEMBER xxxxxxxx SYSIN KEYWORD CARDS EXCEEDED MAXIMUM. CANNOTCONVERT THIS MEMBER

Reason: The member listed has over 400 lines of SYSIN data. The member hasexceeded the maximum allowed.

*** ERROR *** - MEMBER xxxxxxxx TOO MANY KEYWORD LINES IN PROFILE DSN. CANNOTCONVERT THIS MEMBER

Reason: The member listed has over 25 lines of keywords, used by CA7TOUNI, in thePROFILE DD data set. The member has exceeded the maximum allowed.

*** ERROR *** - MEMBER xxxxxxxx FOUND PGM= STATEMENT AND PGM NOT CA7TOUNI.CANNOT CONVERT MEMBER

Reason: The first step found, that is assumed to be the CA7TOUNI step, does notexecute the CA7TOUNI program.

*** ERROR *** - MEMBER xxxxxxxx RESTORE NAME FOUND IN PDSDD FILE. CANNOTCONVERT MEMBER

Reason: The RESTMASK keyword was supplied to the Conversion Utility. A check isperformed to see if the member name generated for the back-up (using the RESTMASKvalue) exists in the PDSDD file. If this member already exists, the member is notconverted.

*** ERROR *** - MEMBER xxxxxxxx CANNOT BUILD JFCB FOR CARPROC DD. CANNOTCONVERT THIS MEMBER

Reason: This member referenced a JCL procedure for CA7TOUNI. The data setreferenced in the CARPROC DD statement should contain this member. There was anerror trying to access this data set.



*** ERROR *** - MEMBER xxxxxxxx UNABLE TO OPEN THE CARPROC DD. CANNOT CONVERTTHIS MEMBER

Reason: This member referenced a JCL procedure for CA7TOUNI. The data setreferenced in the CARPROC DD statement should contain this member. There was anerror trying to access this data set.

*** ERROR *** - MEMBER xxxxxxxx CONTINUATION FAILED

Reason: This member had a continuation error in a PARMxx or SUBFILE. There is nocontinuation on a line after a previous line that ends in a + sign. The member is notconverted.

*** ERROR *** - MEMBER xxxxxxxx WRONG OR UNKNOWN KEYWORD

Reason: This member had an invalid keyword parameter. The member is not converted.

*** ERROR *** - MEMBER xxxxxxxx yyyyyyyy HAS NO DATA

Reason: This member had a keyword (yyyyyyyy) for which no data was supplied. Themember is not converted.

*** ERROR *** - MEMBER xxxxxxxx yyyyyyyy EXCEEDS zzz CHARACTERS

Reason: This member had a keyword (yyyyyyyy) whose value exceeded the maximumsize (zzz) allowed. The member is not converted.

Note: If you receive this message for the SUBFILE keyword, you must continue to runthe job as a CA7TOUNI job. SUBFILE can support lengths up to 256 bytes. The field thatit is converted to can only support 244 characters.

*** ERROR *** - MEMBER xxxxxxxx yyyyyyyy HAS BAD PARAMETER VALUE

Reason: This member had a keyword (yyyyyyyy) whose value was incorrect for thekeyword. The member is not converted.


Pre-Conversion Utility


The CA7TOUNI conversion utility assumes that all CA7TOUNI SYSIN DD datais in-stream. Any CA7TOUNI jobs containing one or more permanent data setsin the SYSIN DD statement are not converted. The Pre-Conversion Utility canbe used to alleviate this situation.

How it Works

The Pre-Conversion Utility reads the same PDS, containing CA7TOUNI jobs,that the conversion utility reads. It reads and writes each record of any jobstarting with #7UNI (all other jobs are bypassed) to a new sequential file. Itdynamically allocates any permanent SYSIN DD data sets associated with theCA7TOUNI job and adds each record to the new sequential file as part of aSYSIN DD * statement. The sequential file is actually an IEBUPDTE job thatcontains control cards to add each CA7TOUNI job to a new PDS. After theIEBUPDTE has been run, the new PDS that can be used as input to theconversion utility.

The Pre-Conversion Utility consists of three steps.

■ Step 1 reads the PDS containing CA7TOUNI jobs and creates anIEBUPDTE job file and two other files. The report file contains informationabout each member that was processed. Errors that occurred processingthe member can be found in this file. The output data file containsinformation used in Steps 2 and 3.

■ Step 2 sorts the file.

■ Step 3 generates the Node/JobName report. Because the output data file isa CSV file, it can be downloaded to an Excel spreadsheet or MS-Accessdatabase and further manipulated if desired.



A sample of the JCL, found in SAMPJCL member XPJPCONV, follows:

//XPJPCONV JOB (ACCTINFO),PGMR,CLASS=A,MSGCLASS=A// //STEP1 EXEC PGM=SASSX2PD//STEPLIB DD DSN=cai.loadlib, <======// DISP=SHR//PDSDD DD DSN=&highlvl.xpjpconv.pdsdd, <======// DISP=SHR//OUNIJCL DD DSN=&highlvl.xpjpconv.ounijcl, <======// DISP=(NEW,CATLG,DELETE),// UNIT=SYSALLDA,// SPACE=(CYL,(�5,�2),RLSE),// DCB=(RECFM=FB,LRECL=8�,BLKSIZE=�)//OREPDATA DD DSN=&highlvl.xpjpconv.orepdata, <======// DISP=(NEW,CATLG,DELETE),// DISP=(NEW,CATLG,DELETE),// UNIT=SYSALLDA,// SPACE=(CYL,(�5,�2),RLSE),// DCB=(RECFM=FB,LRECL=8�,BLKSIZE=�)//REPORT DD SYSOUT=A//STEP2 EXEC PGM=SORT,REGION=2�48K,COND=(8,LT)//SORTIN DD DSN=&highlvl.xpjpconv.orepdata, <======// DISP=SHR//SORTOUT DD DSN=&&SORTOUT,// DISP=(,PASS),// UNIT=SYSDA,SPACE=(CYL,(5,2),RLSE),// DCB=(RECFM=FB,LRECL=8�,BLKSIZE=�)//SORTWK�1 DD UNIT=SYSDA,SPACE=(CYL,(1�,1�))//SORTWK�2 DD UNIT=SYSDA,SPACE=(CYL,(1�,1�))//SORTWK�3 DD UNIT=SYSDA,SPACE=(CYL,(1�,1�))//SYSPRINT DD SYSOUT=A//SYSOUT DD SYSOUT=A//SYSIN DD SORT FIELDS=(1,17,CH,A)/ //STEP3 EXEC PGM=SASSX2PR,COND=((8,LT,STEP1),(�,NE,STEP2))//STEPLIB DD DSN=cai.loadlib, <======// DISP=SHR//X2PRINPT DD DSN=&&SORTOUT,// DISP=(OLD,PASS)//X2PROUTP DD SYSOUT=A//SYSPRINT DD SYSOUT=A//



Input Parameters

By default, no input parameters are required. When SASSX2PD is executedwith no input parameters, SUBUSER and SUBPASS information is EXCLUDEDfrom the IEBUPDTE job (OUNIJCL).

EXEC PGM=SASSX2PD,PARM='SUBUSER'Executing SASSX2PD with this parameter setting will include SUBUSERinformation in the OUNIJCL file.

EXEC PGM=SASSX2PD,PARM='SUBUSER,SUBPASS'Executing SASSX2PD with this parameter setting will include SUBUSERand SUBPASS information in the OUNIJCL file (note SUBPASSinformation is NEVER written to the OREPDATA DD statement). Be aware,the Passwords may be compromised depending on who can run this job.

Input JCL Statements

There is one input data set:

SASSX2PD PDSDD Statement(Required) The PDSDD data set contains the CA7TOUNI JCL and can alsocontain JCL for conventional CA 7 jobs. Only JCL whose first card startswith #7UNI will be selected for pre-conversion. The input file specified onthis PDSDD statement must be supplied as the PDSDDDSN keyword valuein the conversion utility when it is run.



Output JCL Statements

The following are the output JCL statements:

SASSX2PD OUNIJCL StatementThis DD statement contains an IEBUPDTE job with all the CA7TOUNI jobsthat were processed (with all SYSIN DD data now in-stream). This job issubmitted to create the new PDS that will be used as input to theconversion utility. A sample of this file follows:

//PRECONV JOB (ACCTINFO),PGMR,CLASS=A,MSGCLASS=A//GENBLD EXEC PGM=IEBUPDTE,PARM=NEW//SYSUT2 DD DISP=(NEW,CATLG,DELETE),// DCB=(RECFM=FB,LRECL=8�,BLKSIZE=�),// SPACE=(312�,(13�,13,15)),// DSN=, <=== FILL WITH DSN// UNIT=, <=== FILL WITH UNIT// VOL=SER= <=== FILL WITH VOLUME//SYSPRINT DD SYSOUT= //SYSIN DD DATA,DLM=$$./ ADD NAME=PRECNV�1#7UNI//PRECNV�1 JOB (4�1��,IGN),'CA-7.TOUNI',// CLASS=K,MSGCLASS=P,NOTIFY=&SYSUID/ JOBPARM S= // JCLLIB ORDER=(PROCLIB.DSN)//SUBMIT EXEC CA7TOUNI//PROFILE DD DSN=PROFILE.DATA,DISP=SHR//SYSIN DD NODE=TRENT�5SUBFILE=C:\WINDOWS\+NOTEPAD.EXE/ //./ ADD NAME=PRECNV�2#7UNI//PRECNV�2 JOB (4�1��,IGN),'CA-7.TOUNI',// CLASS=K,MSGCLASS=P,NOTIFY=&SYSUID/ JOBPARM S= // JCLLIB ORDER=(PROCLIB.DSN)//SUBMIT EXEC CA7TOUNI//PROFILE DD DSN=PROFILE2.DATA,DISP=SHR//SYSIN DD node=JAMES�2SubFile=C:\WINDOWS\+NOTEPAD.EXE/ //$$//



SASSX2PD OREPDATA StatementThis DD statement contains a list of jobs that were processed. Specificinformation is the following:

NODE (8 characters max)

JOB (8 characters max)

SUBUSER (32 characters max)

SUBPASS Indicator (YES or NO)

The SUBPASS Indicator indicates whether password information exists forthe job. This data set is sorted in Step 2 and used to generate the CA 7Pre-Conversion Utility Report by Node/JobName. Optionally, you candownload this file to a MS-Access database or Excel spreadsheet andprocess as desired. A sample of the output file follows:

TRENT�5 ,PRECNV�1,USER56789�123456789�123456789�12,YESJAMES�2 ,PRECNV�2,user ,YES ,PRECNV�3,user ,NOTRENT�5 ,PRECNV�4, ,NOTRENT�5 ,PRECNV�5,myUserNameLongest89�123456789�12,YES

SASSX2PD REPORT StatementThis DD statement is a SYSOUT data set. All informational, warning, anderror messages generated during the pre-conversion process are written tothis data set. Inspect this report thoroughly before proceeding. If your sites'CA7TOUNI job definitions meet the assumptions defined in the conversionutility section, you should only see informational, and possibly, warningmessages. A sample of the report is shown below. The possible messagesare shown in “Pre-Conversion Utility Messages” on page 348.

MEMBER PRECNV13 SELECTED FOR PROCESSINGMEMBER PRECNV13 SYSIN DSN IS APCDAL.DEVCA7.CL2111.TESTDATA.B1JF.PDS(T)MEMBER PRECNV13 SYSIN DSN IS APCDAL.DEVCA7.CL2111.TESTDATA.B1JF.SEQDS�1MEMBER PRECNV13 PROCESSED SUCCESSFULLYMEMBER PRECNV14 SELECTED FOR PROCESSING ERROR MEMBER PRECNV14 SYSIN DSN IS INVALID. CANNOT PROCESS THIS MEMBER



SASSX2PR X2PROUTP StatementThis DD statement is a SYSOUT data set. It contains the CA 7Pre-Conversion Utility Report by Node/JobName. A sample of the reportfollows:

-------------------------------------------------------------------------------SASSX2PR CA 7 Pre-Conversion Utility Report by Node/JobNameNODE JOBNAME SUBUSER SUBPASS------------------------------------------------------------------------------- PRECNV�3 user NO Total Jobs Going to Node is ��1MARJA24 PRECNV�8 myuser4 YESMARJA24 PRECNV�9 myuser5 YESMARJA24 PRECNV1� user123 YESMARJA24 PRECNV17 USERNAME4 YES Total Jobs Going to Node MARJA24 is ��4USERX�6 PRECNV19 NO Total Jobs Going to Node USERX�6 is ��1JAMES�2 PRECNV�2 user YESJAMES�2 PRECNV�7 myuser3 YESJAMES�2 PRECNV11 user654 NOJAMES�2 PRECNV13 user654 NO Total Jobs Going to Node JAMES�2 is ��4TRENT�5 PRECNV�1 USER56789�123456789�123456789�12 YESTRENT�5 PRECNV�4 NOTRENT�5 PRECNV�5 myUserNameLongest89�123456789�12 YES

TRENT�5 PRECNV�9 Marja24User YESTRENT�5 PRECNV13 myuser YES Total Jobs Going to Node TRENT�5 is ��5 TOTAL JOBS = ��15



SASSX2PD Return Codes

The Pre-Conversion Utility program (SASSX2PD) returns one of the followingreturn codes:

RC=0Indicates that the job ran successfully. Only informational messages arewritten to the REPORT DD statement.

RC=4Indicates that the job ran successfully, but one or more of the PDSDDmembers could not be opened. Check the warning messages in theREPORT DD statement and determine whether any action is necessary.

RC=8Indicates that the job ran successfully, but one or more members haderrors that prevented them from being processed. Check the errormessages in the REPORT DD statement and determine whether anyaction is necessary.

RC=12Indicates that the job failed. No IEBUPDTE job was generated. Check theWTO in the job's JES JOBLOG for the cause of the failure.



Pre-Conversion Utility Messages

The following messages can appear in the Pre-Conversion Utility REPORT DDstatement.

Informational Messages

MEMBER xxxxxxxx SELECTED FOR PROCESSING

Reason: This message indicates the member contained the #7UNI statement and wasselected for pre-conversion processing.

MEMBER xxxxxxxx PROCESSED SUCCESSFULLY

Reason: This message indicates the member contained the #7UNI statement and wassuccessfully processed.

MEMBER xxxxxxxx SYSIN DSN IS yyyyyyyy

Reason: This message indicates the member contained a permanent SYSIN data setthat is being processed.

Warning Messages

*** WARNING *** MEMBER xxxxxxxx COULD NOT BE OPENED AND WAS BYPASSED

Reason: This message indicates input PDSDD member xxxxxxxx could not be opened.

Action: Determine whether the member should be processed. Ignore the message if it isnot a CA7TOUNI job. If it is a CA7TOUNI job, fix the problem and rerun thePre-Conversion Utility after deleting any data sets created during the prior job run.

Error Messages

*** ERROR *** MEMBER xxxxxxxx SYSIN DD ALLOCATION FAILED FOR yyyyyyyy

Reason: This message indicates the dynamic allocation for SYSIN data set (yyyyyyyy)failed.

Action: Determine whether the data set exists and should be processed. If the memberis bad, delete the member from the new PDS after the IEBUPDTE job has completed.

*** ERROR *** MEMBER xxxxxxxx SYSIN DSN IS INVALID. CANNOT PROCESS THIS MEMBER

Reason: This message indicates the SYSIN DD data set name was not valid.




*** ERROR *** MEMBER xxxxxxxx SYSIN DD OPEN FAILED FOR yyyyyyyy

Reason: This message indicates attempts to open SYSIN data set (yyyyyyyy) failed.



Appendix B. Batch Program CA7TOUNI


CA7TOUNI Submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352CA7TOUNI Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Appendix B. Batch Program CA7TOUNI 351

CA7TOUNI Submission

CA7TOUNI Submission

Submission consists of CA 7 submitting a batch job that executes programCA7TOUNI to send execution data through CAICCI to the XPS SERVER on thetarget platform. The XPS SERVER on that platform in turn submits the job andreturns CAIENF tracking data as it executes. Any output from the job will bedirected to the XPS SERVER console on that platform.

To use this interface, the MVS job must use JCL as described below. The JCLmust begin with a #7UNI statement and it must execute CA7TOUNI. All normalscheduling features are available for the job. It can have schedules,predecessors, triggers and resources.

When the job is submitted to MVS, it will execute and complete, but it will bereturned to the ready queue with a CPU indication of 7UWT to denote it iswaiting on XPS SERVER submission. If an error occurs, the job will abend andbe subject to restart considerations. When execution begins on the targetplatform, the XPS SERVER will return tracking data and normal job flow willresume. Also, the CPU indication will change to 7UNI.

CA7TOUNI has one required and one optional parameter on the EXECstatement. The required parameter is a unique number for tracking. Theoptional parameter is a jobset name. To facilitate supplying these parameters,we recommend that a CA-Driver procedure be used. The following is anexample of such a procedure:

//CA7TOUNI DPROC//STEP1 EXEC PGM=CA7TOUNI,// PARM='&C_L27#,&C_L2SN'//STEPLIB DD DISP=SHR,DSN=cai.ca7.caiload//PROFILE DD DISP=SHR,DSN=cai.ca7.xps.profile//SYSPRINT DD SYSOUT=

The CA-Driver variables &C_L27# and &C_L2SN are replaced by CA 7 jobnumber and CA 7 system name (for the job) respectively when the job issubmitted by CA 7.

The PROFILE DD statement must reference a card image PDS that contains amember named CACCENV. CACCENV contains keyword entries specifyingenvironment parameters for the Submit Function.

Note: The security ID under which the Submit job executes must have READaccess to the CA 7 XPS Profile.


CA7TOUNI Submission

The following is an example of JCL that uses the CA-Driver procedure:

#7UNI//CA7TOUNI JOB ...jobcard...values...//STEP1 EXEC CA7TOUNI (execute CA-Driver proc)//SYSIN DD ...platform... (this could be in a data set) ...specific... (instead of using DD ) ...data.../

Additional parameters are required to specify what to execute and where tosend the data. If the same parameter is encountered in multiple sources theywill be processed as follows:

■ EXEC parm values override SYSIN and PROFILE values

■ SYSIN values override PROFILE values

The following describe all parameters for CA7TOUNI:

DOMAINThis optional parameter can be required for some requests sent toWindows platforms.


Required: No

Source: SYSIN or PROFILE

Note: The DOMAIN variable will only be accepted from the same sourceas the NODE variable. That is, they either both have to come from thePROFILE data or both from the SYSIN data. If the DOMAIN variable issupplied from a source other than NODE it will be ignored and the requestwill be sent without a DOMAIN parameter.

JOBNOThis required parameter should match the CA 7 assigned job number toprovide uniqueness. It must be supplied as the first positional value ofPARM input on the EXEC statement. We recommend that you use aCA-Driver procedure to automatically insert the CA 7 job number in the JCLfor this parameter.

Limits: 1 to 5 numeric characters

Required: Yes

Source: EXEC parm

Note: Even though JOBNO can be up to five digits, CA NSM JobManagement Option only supports four-digit job numbers. Only the last fourdigits are actually sent with the cross-platform request. If the specified jobnumber is less than four digits it will be right-justified and zero-filled.


CA7TOUNI Submission

JOBSETWhen combined with the JOBNO and batch job name, this variableprovides a unique identifier for the cross-platform request. Specialcharacters should be avoided as they may not translate correctly on thetarget platform. If omitted, the MONITOR value will be used as JOBSET.We recommend that you use a CA-Driver procedure to insert the CA 7system name in the JCL for this parameter.

Default: MONITOR name


Required: No

Source: EXEC parm, SYSIN, or PROFILE

LINELENThis optional parameter controls the line length of the SYSIN input for theSUBFILE and PARMxx keyword parameters. Normally CA7TOUNIautomatically determines if columns 73 to 80 contain line sequencenumbers (LINELEN=AUTO). If column 72 contains a blank, null, or plussign, and columns 73 to 80 are numeric, then columns 73 to 80 areconsidered to be line sequence numbers. Line sequence numbers are notconsidered part of the SUBFILE or PARMxx keyword value.

The LINELEN keyword can be used to override this automaticdetermination and force CA7TOUNI to consider the full 80-byte record aspart of the data area (LINELEN=80). Or it can force CA7TOUNI to ignorecolumns 73 to 80 (LINELEN=72) regardless of the contents of thosecolumns.

Default: LINELEN=AUTO

Limits: AUTO, 72, and 80 are the only allowed values

Required: No


Note: This keyword can be specified multiple times. Processing forSUBFILE and PARMxx keywords is controlled by the last valid LINELENspecification processed before the current line.


CA7TOUNI Submission

MONITORWhen combined with the local CAICCI node this parameter uniquelyidentifies the copy of CA 7 submitting this cross-platform request. Thevalue must be exactly seven characters. CA7PROD should be avoided asthis is commonly used by CA NSM Job Management Option. If only onecopy of CA 7 is executing, a good choice might be CA7 followed by theSMF-ID of the originating system. If executing multiple CA 7 instances, agood choice may be CA7 followed by the instance name, such asCA7CA73. This value must match the one used by the CA 7Cross-Platform Tracking System (XTRK).

Limits: 7 alphanumeric characters

Required: Yes

Source: PROFILE

NODEThis parameter identifies the CAICCI node of the target system for thisrequest. It must match what is defined in CAICCI on that system.


Required: Yes


PARM1 thru PARM64These optional parameters supply values to be used on the target platform.Values can be 1 to 256 characters. Special characters should be avoidedas they may not translate correctly on the target platform. Embedded blankswill cause the value to be enclosed in double quotes by the XPS SERVERon the target platform. Since JCL is limited to 80 characters per record,continuation may be required. To continue a record, end it with a plus sign(+) and continue in column 1 of the next statement. The ending plus signwill not appear in the resulting value. Keyword checking will be suspendedduring a continuation operation.


Required: No

Source: SYSIN



CA7TOUNI Submission

SUBCHECKThis optional PROFILE parameter forces a security check for authorizationof the currently running user to submit jobs for the ID supplied inSUBUSER. This can override the instance default that is set by CAIRIM. Ifthe value of BSUBCHK is N, the security check is not done unlessSUBCHECK overrides it. For more information about BSUBCHK, see theSecurity Reference Guide.

Limits: YES and Y are the only allowed values

Required: No

Source: PROFILE

Note: This parameter cannot be used to turn off submit checking. Asetting of NO will cause a warning message and the parameter will beignored.

SUBFILEThis required SYSIN parameter identifies the script or command to beexecuted by the XPS SERVER. It has the same size, content andcontinuation considerations as the previous PARMx values. The scriptnamed must reside in a special directory identified to CA NSM JobManagement Option or must indicate a fully qualified path name. For moreinformation about Client/Server processing and the CAISCHD0004 variable,see the CA NSM Job Management Option documentation.


Required: Yes

Source: SYSIN


SUBPASSThis optional parameter identifies the password to be passed withSUBUSER to the target platform. The password will be sent to the targetsystem in an encrypted format. Some target systems may require that apassword accompany the SUBUSER on cross-platform requests.


Required: No


Note: The SUBPASS variable will only be accepted from the same sourceas the SUBUSER variable. That is, they either both have to come from thePROFILE data or both from the SYSIN data. If the SUBPASS variable issupplied from a source other than the SUBUSER it will be ignored and therequest will be sent without a password.


CA7TOUNI Submission

SUBROOTThis optional PROFILE parameter determines whether the special user IDof ROOT can be used for job submission. Since the user ID of ROOT hasspecial meaning and capabilities on many non-MVS platforms, it is best notto use it when submitting work from MVS. By default, ROOT is not allowedby this interface. To submit work using ROOT as the user ID, thisparameter must be present with a value of YES or Y.

Default: NO

Limits: YES, NO, Y and N are the only allowed values

Required: No

Source: PROFILE

SUBUSERThis optional parameter identifies the user ID for security purposes on thetarget platform. If omitted, the user ID of the executing MVS job will beextracted and used. A check will be done to see if the user ID ROOT isbeing used, in which case submission will be controlled by the setting forparameter SUBROOT. Regardless of the setting for SUBROOT, the use ofROOT as the user ID will cause a WARNING message to be issued. Sincethe user ID ROOT has special meaning on UNIX platforms, we recommendthat ROOT not be specified.

Default: Batch job user ID


Required: No


SUTYPEThis optional parameter determines the type of "switch user" command thatwill be executed if the target node is UNIX.

YESExecutes an 'SU-' command causing the environment setup to includeexecution of the '.PROFILE' for the target user.

NOExecutes an 'SU' command without the profile option.

Default: YES

Limits: YES, NO, Y and N are the only allowed values

Required: No



CA7TOUNI Submission

XPHAOEnables the High Availability Option (HAO) for tracking CA7TOUNI jobs.The value must match the value set in the XPDEF file initializationstatement XPHAO keyword of the copy of CA 7 that will submit theCA7TOUNI batch job.

Default: None

Limits: Must match XPDEF XPHAO keyword value

Required: No


7TRACEThis optional parameter can be used to turn on the trace facility to assist intracking down problems. If the parameter is set to YES additional messageswill be written to the SYSPRINT DD that may be helpful in pinpointingexactly when an error is encountered.

Default: NO

Limits: YES, NO, Y or N are only allowed values

Required: No


Examples: The following is an example of a job to list the status of CA NSMJob Management Option on on the target platform.

#7UNI//TESTJOB1 JOB ...jobcard...values...//STEP1 EXEC CA7TOUNI (CA-Driver proc)//SYSIN DD node=newyorksubuser=ca7usersubfile=unifstat/

The following is an example of a CACCENV member.

monitor=ca7mvsajobset=fromca7

Note: If the submit function encounters an error or problem that prevents therequest from being sent to the target system, the submit step will abend with aUser 4000 code (U4000). See the messages produced in the submit job outputto determine the exact nature of the problem.


CA7TOUNI Considerations

CA7TOUNI Considerations

Similar to the Submit Function, any job whose JCL starts with #7UNI is treatedas a cross-platform job. When such a job completes on MVS, it is requeued tothe ready queue with a CPU indication of 7UWT. The job will stay in the readyqueue until another job initiation record is received. When initiation is receivedthe CPU indication is changed to 7UNI and normal job flow continues.

In the area of reporting, you should realize there will be two sets of log recordsfor each 7UNI job submitted. The first set represents the MVS job thatsubmitted data to the XPS SERVER. The second set represents the jobexecution on the XPS SERVER platform. This second set will consist of jobinitiation, step termination, and job termination records only. There will be nodata set records, and not all fields will be filled in for the other records.

Concerning restart considerations, we recommend that 7UNI jobs not include aCA 11 restart step or have CA 7 insert such a step. Including CA 11 isunnecessary since these jobs will consist of a single step, produce no data setsand must be totally rerun if restarted.

Since commands and parameters can be included in the JCL as SYSIN data,certain special considerations are applied to jobs flagged for submittal toanother system. Many platforms are case sensitive to their input; howeverunless CA 7 Mixed Case Editing is enabled, the CA 7 editor forces all data touppercase. Therefore, edit functions of CA 7 can only be used against JCL forcross-platform jobs if INITCASE=Y is specified in the CA 7 initialization file.

Note: If CA 7 Mixed Case Editing is not enabled, the following JCL editrelated features will not be available for cross-platform (7UNI) jobs.

The following applies to:

■ DB.7 (JCL panel) FE function

■ QM.5 (QJCL panel) FE and FETCH functions

■ QM.1-X (XQ panel) E function

If the JCL for a 7UNI job must be changed, you must use an editor outside ofCA 7, such as TSO/ISPF or CA Roscoe. If the JCL must be changed after thejob enters the queues, change the JCL outside of CA 7. Next, cancel anddemand a new version of the job. If the job was scheduled or triggered andcannot be canceled and demanded, change the JCL outside CA 7. Use theJCL panel to FETCH it (do not use FE or EDIT). Next use the QJCL panel toREPL the request queue job's JCL thus bypassing the CA 7 editor.


Appendix C. XTRK as a STC or Job


CA 7 Cross-Platform Tracking JCL . . . . . . . . . . . . . . . . . . . . . . 362CA 7 XPS Client Implementation Checklist . . . . . . . . . . . . . . . . . . 365

Appendix C. XTRK as a STC or Job 361

CA 7 Cross-Platform Tracking JCL


The following is an example of the JCL for the CA 7 Cross-Platform TrackingSystem (XTRK):

//CA7XTRK EXEC PGM=CAL2XTRK,PARM='...parm...values...'//STEPLIB DD DISP=SHR,DSN=...ca7..caiload...//XCKPT DD DISP=OLD,DSN=...xtrk..checkpoint...//XEVENTS DD DISP=SHR,DSN=...xtrk..xtracking(rules)... optional //XPRINT DD SYSOUT= //XSNAP DD SYSOUT=

The XCKPT DD must point to a CA 7 Cross-Platform Checkpoint file. Eachcopy of XTRK must have its own Checkpoint file. The DCB parameters forCheckpoint files are:

DSORG=PS,RECFM=FB,LRECL=4�96,BLKSIZE=4�96

One track should be sufficient for most sites. The Checkpoint file does not haveto be preformatted.

The XEVENTS DD is optional. If specified, it should point to an 80-bytestatement-image sequential data set, or PDS member, which contains CA 7cross-platform external tracking rules. These rules define what events thatoccur on other systems should be tracked by CA 7 even though CA 7 did notsubmit the work that caused these events to take place. See “CA 7Cross-Platform External Tracking” on page 218 for information about the formatof these rules.

The EXEC PARM values for XTRK are:

PARM='monitor,ca 7 instance name,trace-codes'

monitorThis required parameter is the seven character monitor name that uniquelyidentifies the copy of CA 7 whose cross-platform jobs are to be tracked. Itmust match the MONITOR= value used by the CA 7 Cross-Platform Submitjobs to be tracked (CA7TOUNI).

ca 7 instance nameThis optional parameter specifies the instance name of the CA 7 for whichthis copy of XTRK is collecting. This parameter controls which copy ofCA 7 will receive the pseudo-SMF feedback generated by this copy ofXTRK. The primary copy of CA 7 (called the production copy in r3.3) hasan instance name of CA71. The secondary copy of CA 7 (called the testcopy in r3.3) has an instance name of CA72. Other available instances arenamed CA73 through CA78. The values PROD or UC07 can be usedinstead of CA71, and the values TEST or UCT7 can be used instead ofCA72.

Note: The RNAME value does not affect this setting.



trace-codesThese optional codes specify the level of diagnostic messages and snapsthat should be generated by XTRK. There are two codes that can bespecified: print/snap trace code and console message trace code. The firstvalue controls what messages will be written to the XPRINT DD, and whatrecords and control blocks will be written to the XSNAP DD. The secondvalue controls what WTOs are issued to the system console.

The default trace codes are '21'. Possible trace codes are:

0 QUIET MODE - Only severe error WTOs. This value is onlyhonored for the console trace code. If entered for the print tracecode it will be interpreted the same as a code of 1.

1 NORMAL MESSAGES/WTOS. These messages indicate XTRKsystem startup and shutdown. They also indicate whencommunication with remote systems is first established, if suchcommunication is lost, and if it is reestablished.

2 FEEDBACK MESSAGES/WTOS. Besides the messages issuedfor trace code 1, messages relating to cross-platform feedbackevents will be issued.

3 COMMUNICATION MESSAGES/WTOS. Besides the messagesissued for trace code 2, messages relating to CCIcommunications with other systems will be issued. Also,messages will be issued for pseudo-SMF records generated andsent to CA 7. Also, if the XSNAP DD is available, snap dumpswill be taken of the storage areas related to CCI control blocksand records, as well as pseudo-SMF records.

4 PROGRAM PATH MESSAGES/WTOS. Besides the messagesissued for trace code 3, messages relating to internal XTRKprocessing will be issued. Also, if the XSNAP DD is available,snap dumps will be taken of the storage areas related to XTRKcontrol blocks, besides the communication and feedback relatedsnaps.

Note: Trace code 4 should only be used at the direction of CATechnical Support Support since it will produce a significantnumber of messages.

5-9 Currently trace codes 5 through 9 do not have specificdefinitions. If entered, they will be interpreted the same as tracecode 4.

Note: Messages that indicate critical errors will always be issued as WTOsregardless of the trace code settings. Also, all error and warning messages(message-IDs ending with E or W) will always be written to the trace print(if available) regardless of the current trace code settings.



PARM Example: To start XTRK for a production CA 7 system whose monitorname is 'CA7IPO1', a print trace code of '3' and a console trace code of '1', theparm value on the EXEC statement would be:

PARM='CA7IPO1,CA71,31'



CA 7 XPS Client Implementation Checklist

1. Define CAICCI connections among systems. See “CAICCI Cross-PlatformConnections” on page 203.


Note: This interface requires CA Common Services for z/OS.

If you are communicating with a Windows platform and also have CA WCCon the same machine, you must ensure that CAICCI Remote Services andthe CAICCI-PC Properties use different System Names for the Windowsmachine. The CAICCI Remote Services System Name is defined in fileCCIRMTD.RC (local node). The CAICCI-PC Properties System Name canbe accessed through the CAIC3CFG.EXE window.

2. Allocate and initialize the CA 7 XPS Profile PDS.

See CA 7 SAMPJCL member XPSPROF and Appendix B, “Batch ProgramCA7TOUNI” on page 351.

3. Allocate CA 7 XTRK Checkpoint files.

See CA 7 SAMPJCL member XPSCKPT and “CA 7 Cross-PlatformTracking JCL” on page 362.

Note: This may have been completed when installing or upgrading CA 7and may not be necessary.

4. Define and start CA 7 Cross-Platform Tracking Tasks (XTRK).

See CA 7 JCLLIB member CA7XTRK (prefix may have changed based onSYSGEN) and “CA 7 Cross-Platform Tracking JCL” on page 362. Thisprocedure may appear in the PROCLIB if the CA07N020 installation jobwas executed.

5. Define the CA-Driver Procedure for the CA 7 XPS Submit Function.

See CA 7 SAMPJCL member CA7TOUNI and Appendix B, “Batch ProgramCA7TOUNI” on page 351. If you are not familiar with CA-Driver, seeChapter 4, “CA Driver Procedures, Variable Parameters, and Functions” onpage 121.

6. Define the CA 7 cross-platform jobs and JCL for the Submit Function.

See CA 7 SAMPJCL member CA7XSUB and to Appendix B, “BatchProgram CA7TOUNI” on page 351. The jobs should be defined andscheduled like any other CA 7 job, only the JCL is different.

7. Schedule/Demand the Cross-Platform Job on CA 7.

See the CA 7 documentation on scheduling and demanding CA 7 jobs.

When the cross-platform jobs are submitted the request will be routed to thespecified platform (XPS Server), and the feedback will be returned to CA 7(XPS Client).


Appendix D. XTRK Under ICOM


Cross-Platform Tracking ICOM PARM Values . . . . . . . . . . . . . . . . 368Cross-Platform Tracking ICOM DD Statements . . . . . . . . . . . . . . . 369Cross-Platform Tracking ICOM WTOR/MODIFY Replies . . . . . . . . . . 370

Appendix D. XTRK Under ICOM 367

Cross-Platform Tracking ICOM PARM Values

Cross-Platform Tracking ICOM PARM Values

If you want to execute the CA 7 Cross-Platform Tracking System (XTRK) as asubtask in the ICOM address space, add the following parameters to theSASSICOM EXEC statement.

XMONITOR=monitor-name

This required parameter is the seven-character monitor name that uniquelyidentifies each copy of CA 7 whose cross-platform jobs are to be tracked. Itmust match the MONITOR= value used by the CA 7 Cross-Platform Submitjobs to be tracked (CA7TOUNI).

Note: This parameter is required if you want to execute the CA 7 XTRKsystem in the ICOM address space. If this parameter is specified then theXCKPT DD statement for the CA 7 Cross-Platform Tracking Checkpoint filemust be present in the ICOM JCL.

XTRC=trace-codes

These optional codes specify the level of diagnostic messages and snaps thatshould be generated by XTRK. Two codes can be specified: print/snap tracecode and console message trace code. The first value controls what messageswill be written to the XPRINT DD, and what records and control blocks will bewritten to the XSNAP DD. The second value controls what WTOs are issued tothe system console.

The default trace code is 'XTRC=21'. For more information about trace codevalues, see “CA 7 Cross-Platform Tracking JCL” on page 362.

Note: If used, the XMONITOR= and XTRC= keywords should be added to theend of the SASSICOM parameter list and preceded by commas to separatethem from other PARM values.


Cross-Platform Tracking ICOM DD Statements

Cross-Platform Tracking ICOM DD Statements

If you want to execute the CA 7 Cross-Platform Tracking System (XTRK) as asub-task in the ICOM address space the following DD statements should beadded to the SASSICOM JCL.

XCKPT(Required if the XMONITOR keyword is specified in the SASSICOM EXECparameters) Points to a CA 7 Cross-Platform checkpoint file. Each copy ofXTRK must have its own checkpoint file. That is, if you are running ICOMon two separate mainframe images and you want to run CA 7 XTRK, eachcopy must have a separate checkpoint file.

Note: For more information about the Cross-Platform Checkpoint files,“CA 7 Cross-Platform Tracking JCL” on page 362.

XEVENTS(Optional) Points to an 80-byte card-image sequential data set, or PDSmember, which contains CA 7 cross-platform external tracking rules. Theserules define what events that occur on other systems should be tracked byCA 7 even though CA 7 did not submit the work that caused these eventsto take place. For information about the format of these rules, see “CA 7Cross-Platform External Tracking” on page 218.

Note: If you are running CA 7 XTRK on multiple mainframe images, youshould not specify the same external tracking rules for more than one copyof CA 7 XTRK. This could cause CA 7 to receive multiple copies of thesame tracking information from different copies of CA 7 XTRK.

XPRINT(Optional) Specifies a SYSOUT class for CA 7 Cross-Platform Tracker(XTRK) trace messages. The type and volume of messages produced iscontrolled by the first value of the XTRC= keyword in the SASSICOMEXEC parameters.

XSNAP(Optional) Specifies a SYSOUT class for CA 7 Cross-Platform Tracker(XTRK) storage snap output. The type and volume of output produced iscontrolled by the first value of the XTRC= keyword in the SASSICOMEXEC parameters.

Appendix D. XTRK Under ICOM 369

Cross-Platform Tracking ICOM WTOR/MODIFY Replies

Cross-Platform Tracking ICOM WTOR/MODIFY Replies

If you execute the CA 7 Cross-Platform Tracking System (XTRK) as a subtaskof ICOM you can pass commands to the XTRK task using the CA-7.575 WTORor a MODIFY command. Responses to these commands are issued as WTOsand are explained in the Message Reference Guide.

The ICOM reply/command for XTRK is:

XTRK=...native XTRK command...

For example, to issue a MODIFY command to display all nodes connected toXTRK issue:

F CA7ICOM,XTRK=NODE

For more information about specific XTRK commands, see “CA 7Cross-Platform Tracking Commands” on page 215.


Index

Special Characters& (ampersand) (CA Driver) 134&C_DATE parameter 137&C_DAY parameter 137&C_JDATE parameter 137&C_MONTH parameter 137&C_TIME parameter 137#statements

See alphabetical listing

Aactivating CA Driver 121allocating space 175ampersand (&) (CA Driver) 134API requirements 40arrays 142ARTS command 20asynchronous processing time (NCF) 178attribute testing 144

BBatch Card Load program

See BCLPbatch commands

format 74installation process 76

batch step execution 86BCLP

ABORT 107and NJE 184and U7SVC facility 85CA 7 requirements 106control statements 109DB 107DBPARMS 108description 106ERR 107EXITPROG 107JCL requirements 107using 106

BPXBATCH program 68BTI

and WLM 69N220 job 76

BTI (continued)overview 71parameters 79

CCA 7 CA 7 Job Management Smart Console

Option 64CA 1 interface 17CA 11

ARTS Command Monitor 20automatic

CMT updating 21RMS insertion 21

interface 19CA APCDDS interface 22CA APCDOC interface 22CA Dispatch interface 24CA Driver

activating 121branching

conditional 156unconditional 154

commands 153comments 161functions 147overview 121procedure library 125procedure, expanding 153reserved-name variable parameters 137sequence numbers 136variable parameters 130

CA Earl reporting 26CA Easytrieve reporting 26CA JCLCheck interface 26CA Librarian interface 28CA Netman interface 28CA NSM Job Management Option 201CA Opera interface 35CA OPS/MVS interface 35CA Panvalet interface 36CA Service Desk 52CA Workload Control Center 22CA-Driver

cross-platform scheduling 352

Index 371

CA7TOUNIconverting to XPJOB 321

CAICCICCI interface 71cross-platform scheduling 212

CAICCI connections 203CAIENF events 212CAIRIM

requirement for 165, 176resource initialization manager 166, 168

CAISMFI dynamic SMF event interceptor 168calculating region size 174calling U7SVC from a user program 89Commands

ARTS 20CA Driver 153LOGOFF 75LOGON 74NCF 188

communications data setand ICOM 169file description 175overview 170

conditional procedure expansion 153control statements for BCLP 109CPM 60CPM tracker 61CREATE (data set request statements) 115Critical Path Monitoring 60cross-platform scheduling

and CA-Driver 352overview 201XPS CLIENT 207XPS SERVER 223

cross-platform Server password requirements 229CWORK 17

DDABORT command 160DASD

devices 174requirements 175

data inclusion 129data set request statements 115Data sets 183DATA statement (CA Driver) 128DAY function (CA Driver) 150DB.1 panel

Execution segment 180JCL segment 181

DB.1 panel (continued)Messages segment 181Resources segment 180

DBM batch commands, format 74DCM SAMPJCL member 35, 64defining CA Driver procedures 125DEND statement 128DFLUSH command 160DGOTO command 154DIF command 156disk drives supported 174DLCTR command 159DM3Y function 149DM3YR function 150DMY function 149DMYR function 149DNEST statement 126, 135DOW function 150DOW# function 150DSET command 158DSTEP command 154DTADD function 148DTDIF function 148DTSUB function 148dynamic initialization routines 168

EEnd-of-Data Set (EODS) Statement 118error recovery 187events, CAIENF 212examples

Data Flow Within One CPU 166NCF VTAM PARM 179

execution options 178External

See External CommunicatorsExternal Communicators 71

Ffiles, permanent CA 7 NCF 175Flows 61Forecasting print volumes with CA Dispatch 24format

NCF communications data set 175UDQ 175

functions for CA Driver 147


IICOM

and WLM 70communications data set 176cross-platform tracking 367requirements 174

implementation considerationsCA 7 facilities 184data sets 183database 180DB.1 panel 180DD statements 183EXEC statements 183execution JCL 181general usage 184JES NJE capabilities 177JES2 statements 182JES3 statements 182JOB statement 181LOAD process 185NCFNODE parameter 184overview 177scheduling 180XPS CLIENT 365XPS SERVER 234

including data 127Interfaces

CA 1 17CA 11 19CA APCDDS 22CA APCDOC 22CA Dispatch 24CA Earl 26CA Easytrieve 26CA JCLCheck 26CA Librarian 28CA Netman 28CA Opera 35CA OPS/MVS 35CA Panvalet 36list 16TSO/ISPF 43UNIX System services 37Workload Management (WLM) 69

ISPFinterface 43with CA Driver 125

JJCL requirements for BCLP 107JDOM function 152JES2 statements 182JES3 statements 182JOB statement 181

LLDOM function 152length attribute 145Librarian

See CA Librarian interfaceLINELEN 354link editing node table 169List function in batch commands 75LJDOM function 152LOAD process (SASSJJCL) 184LOGOFF command 193LOGON command 192loop control 159

MM3DY function 149M3DYR function 150managing workloads 69MDY function 149MDYR function 149memory requirements 174MNADD function 148MNSUB function 148MNT override statement 106MODIFY command 188MON function 150MON# function 150MONTH function 150multi-access spool 170

NN220 job 76NCF system

commands 188components 166Data Flow Within One CPU 166operations

CA 7 NCF functions 186create control blocks 186error recovery 187establish communications 186initialization 186

Index 373

NCF system (continued)operations (continued)

loading node table 186overview 186scanning files 186standard operations 187status information 187termination 187

overviewCA 7 NCF components 166CAIRIM 168ICOM 169NCF Communications Data Set 170NCF undeliverable queue (UDQ) 170NCF VTAM Application Program 170node table 169OPERATOR commands 188purpose 164requirements 165SVC interface 168unknown node table 169

requirements 165NCF VTAM

application program 170application program functions 170PARM 179

NCFNODE parameter 184NEST statement 126nested procedures 126, 135network job entry (NJE) 164Node Table

loading 186requirements 169

non-DBM batch commands, format 76null value 143number attribute 146

Ooperating system environment 174operator commands

format 189LOGOFF 193LOGON 192MODIFY 188overview 188PURGE 194response 189SHUTDOWN 189, 190STARTUP 191STATUS 190, 195

operator commands (continued)STOP 188, 189TRACE 198

OPTION statement (BCLP) 111Options for CA 7 64

Ppassword requirements for cross-platform

scheduling 229permanent files, CA 7 NCF 175PF key support 48Pre-Conversion Utility 341procedure for CA Driver

creating 125expansion

aborting 160conditional 153controlling loops 159shifting during 136

nesting 126, 135parameter substitution 130retrieving 125storing 125

PURGE command 169, 194

Rregion size, calculating 174Reporting

CA Earl reporting 26CA Easytrieve reporting 26

requirementsCAIRIM 176DASD 175

reserved-name variable parameters 137resource initialization manager 166, 168restarting jobs with CA Driver 155retrieving procedures for CA Driver 125return codes and SASSXXBT message table 77router, XPS 226

SSASSBCLP (Batch Card Load Program)

using 106using with NCF 184

SASSBSTR programoverview 77PARM values 79


SASSDPCH module 24SASSLIBR module 28SASSNC01 module 198SASSNC03 module 198SASSNC04 module 198SASSNC12 program 175SASSNC15 program 175SASSPANV module 36SASSTRLR program 184SASSXXBT message table 77scheduling

cross-platform 201day and time values 180environments 69

SCHID keyword 236Service Desk

See CA Service Deskshifting during expansion 136SHUTDOWN command, NCF

and STOP command 189description 190terminating NCF 187

SMF interface exits 165, 168space allocations 175STARTUP command 191status

CA 7 NCF VTAM 196command 187, 190, 195information 187

STOP command 187, 189submitting jobs with NCF 164substring referencing 140SVC interface 165, 168system information

&C_DATE 137&C_DAY 137&C_JDATE 137&C_MONTH 137&C_TIME 137

Ttermination 187terminology 172TIQ interface 17TRACE command 198trailer data 169, 170trailer step facility

and NJE 184JCL 83overview 81

TSO/ISPF interface 43type attribute 144Typical NCF environment 167

UU7SVC facility

at remote nodes 184overview 71using 85

UCC7NODE table 187UDQ

See undeliverable queue (UDQ)undeliverable queue (UDQ)

and PURGE command 187and unknown node table 169DASD requirements 175overview 170

Unicenter CA-7 Agent 201Unicenter Event Console 52UNIX System Services

interface 37scheduling jobs 68

unknown node table 169

Vvariable parameter

arrays 142, 146attribute testing 144coding 132in nested procedures 135length attribute 145number attribute 146reserved-name 137substitution 130, 134substring referencing 140types 144values

changing 158defining 132multiple 142null 143overriding 133testing 144

verification of data inclusion 129verifying JCL with CA Driver 124Virtual Resource Management and WLM 70Virtual terminals, installation requirements 51VRM and WLM 70

Index 375

VTAMPARM for NCF VTAM application program 179requirements for CA 7 under TSO/ISPF 43

WWOM function 150workload

management (WLM) 69management and cross-platform scheduling 232management and NCF 164

WOY function 151

XXPJOB

conversion from CA7TOUNI 321XPS CLIENT

submission 207tracking 207

XPS Router 226XPS Submit Monitor

creating status information 223submission 223

YYM3D function 149YMD function 149YRM3D function 150YRMD function 149


ca7 workload automation refgd

Documents