CA7 Workload Automation RefGd

CA 7 Workload Automation
Interface Reference Guide

r11.1 SP04
Fourth Edition
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 by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be used or disclosed by you except as may be permitted in a separate confidentiality agreement between you and CA. Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print a reasonable number of copies of the documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement 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 is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors.
All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies. Copyright 2007 CA. All rights reserved.
CA Product References
This document references the following CA products: CA 7 Workload Automation (CA 7) CA 7 Job Management Smart Console Option (CA 7 Job Management Smart 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 Management Option (CA NSM Job Management Option) CA Workload Control Center (CA WCC) Unicenter Event Console (Unicenter Event Console) Unicenter Universal Job Management Agent (Unicenter Universal Job Management Agent)
Contact CA
Contact Technical Support
For your convenience, CA provides one site where you can access the information you need for your Home Office, Small Business, and Enterprise CA products. At http://ca.com/support, you can access the following: Online and telephone contact information for technical assistance and customer 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, you can send a message to techpubs@ca.com. If you would like to provide feedback about CA product documentation, complete our short customer survey, which is also available on the CA Support website, found at http://ca.com/docs.
4 Interface Reference Guide
Contents
Chapter 1. Introduction
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13 15 16 17 18 19 20 21 21 22 22 22 23 24 24 24 26 26 26 27 28 28 29 30 30 31 32 35 35 36 37 37 38 40 43 44 46 51 51 52 52 52 53 53
Chapter 2. Interfaces and Options . . . . . . . . . . . . Interfaces with Other Products . . . . . . . . . . . . . . . . CA 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIQ Command . . . . . . . . . . . . . . . . . . . . . . CA 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . ARTS Command Monitor . . . . . . . . . . . . . . . . Automatic RMS Step Insertion . . . . . . . . . . . . . Automatic CMT Updating . . . . . . . . . . . . . . . . CA Workload Control Center (UWCC) . . . . . . . . . CA APCDDS . . . . . . . . . . . . . . . . . . . . . . . . CA APCDOC . . . . . . . . . . . . . . . . . . . . . . . . Compare FSTRUC to a Database Flowchart . . . . . CA Dispatch . . . . . . . . . . . . . . . . . . . . . . . . Forecast Print Volumes . . . . . . . . . . . . . . . . . Create a Plan Data Set . . . . . . . . . . . . . . . . . CA Earl . . . . . . . . . . . . . . . . . . . . . . . . . . . CA Easytrieve . . . . . . . . . . . . . . . . . . . . . . . CA JCLCheck . . . . . . . . . . . . . . . . . . . . . . . CA 7 Considerations . . . . . . . . . . . . . . . . . . CA Librarian . . . . . . . . . . . . . . . . . . . . . . . . CA Netman . . . . . . . . . . . . . . . . . . . . . . . . . CA 7 Considerations . . . . . . . . . . . . . . . . . . CA Netman Considerations . . . . . . . . . . . . . . . CA Netman Model Transactions . . . . . . . . . . . . CA Netman Model Transactions - Continuation Rules CA Netman Model Transactions - Variables . . . . . CA Opera . . . . . . . . . . . . . . . . . . . . . . . . . . CA OPS/MVS . . . . . . . . . . . . . . . . . . . . . . . CA Panvalet . . . . . . . . . . . . . . . . . . . . . . . . UNIX System Services Interface . . . . . . . . . . . . . Invoke the Interface . . . . . . . . . . . . . . . . . . . Environment Variables . . . . . . . . . . . . . . . . . CA 7/API Requirements . . . . . . . . . . . . . . . . . TSO/ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . VTAM Considerations . . . . . . . . . . . . . . . . . . ISPF Considerations . . . . . . . . . . . . . . . . . . . CA 7 Considerations . . . . . . . . . . . . . . . . . . Other CA Schedulers and Agents . . . . . . . . . . . . Unicenter Event Console . . . . . . . . . . . . . . . . . CA Service Desk . . . . . . . . . . . . . . . . . . . . . . Configure CAISDI/els for CA 7 . . . . . . . . . . . . . Configure CA Service Desk for CA 7 . . . . . . . . . Configure CA 7 . . . . . . . . . . . . . . . . . . . . .
Contents 5
CAISDI/els Events Provided by CA 7 . . . . . . . . . . . . SERVDESK Rules . . . . . . . . . . . . . . . . . . . . . . . Event Variables . . . . . . . . . . . . . . . . . . . . . . . . . Critical Path Monitoring . . . . . . . . . . . . . . . . . . . . . Critical Path Definition . . . . . . . . . . . . . . . . . . . . . CA 7 Requirements for Critical Path Monitoring . . . . . . CA 7 CA 7 Job Management Smart Console Option . . . . . . Schedule UNIX System Services Jobs . . . . . . . . . . . . . . Interface with IBM Workload Manager (WLM) . . . . . . . . . . CA 7 and ICOM IBM Workload Manager Resources . . . . Automatic Scheduling Environment JOB Statement Insertion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
54 55 58 60 60 62 64 68 69 69 70 71 73 74 75 76 76 77 77 78 78 79 81 85 86 86 87 88 89 90 91 93 94 96 97 99 101 101 103 104 105 106 106 107 107 109 111 115
Chapter 3. External Communicators . . . . . . . . . . . . . . . . . Batch Terminal Interface (BTI) . . . . . . . . . . . . . . . . . . . . . . Command Format and Sequence . . . . . . . . . . . . . . . . . . DBM List Functions . . . . . . . . . . . . . . . . . . . . . . . . . . Non-DBM Batch Commands . . . . . . . . . . . . . . . . . . . . . Installation Process Batch Commands . . . . . . . . . . . . . . . Batch Terminal Interface Execution . . . . . . . . . . . . . . . . . Processing Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . CA7BTI JCL Procedure . . . . . . . . . . . . . . . . . . . . . . . Sample BTI JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . JCL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . Trailer Step Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . U7SVC Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Batch Step Execution . . . . . . . . . . . . . . . . . . . . . . . . . Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Call U7SVC From a User Program . . . . . . . . . . . . . . . . . Interface with CAICCI . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Considerations . . . . . . . . . . . . . . . . . . . . . . . . . CA 7 CAICCI Batch Interface Execution . . . . . . . . . . . . . . CAL2X2WB JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . CAL2X2WB Return Codes . . . . . . . . . . . . . . . . . . . . . CA 7 CAICCI REXX Interface Execution . . . . . . . . . . . . . . CA-GSS REXX Address Environment Interface Execution . . . CA 7 CAICCI Program to Program Interface Execution . . . . . Call CAL2X2WP . . . . . . . . . . . . . . . . . . . . . . . . . . . CAL2X2WP Response Buffer . . . . . . . . . . . . . . . . . . . CAL2X2WP Return Codes . . . . . . . . . . . . . . . . . . . . . Sample Invocation of CAL2X2WP . . . . . . . . . . . . . . . . . Batch Card Load Program (BCLP) . . . . . . . . . . . . . . . . . . . . Use BCLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CA 7 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . JCL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . Control Statements for BCLP . . . . . . . . . . . . . . . . . . . . OPTION Statement . . . . . . . . . . . . . . . . . . . . . . . . . Data Set Request Statements CREATE, REPLACE, MODDATA
End-of-Data Set (EODS) Statement Control Statement Examples . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
118 119
Chapter 4. CA Driver Procedures, Variable Parameters, and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JCL Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure Library . . . . . . . . . . . . . . . . . . . . . . . . . . Create Procedures . . . . . . . . . . . . . . . . . . . . . . . Call Procedures . . . . . . . . . . . . . . . . . . . . . . . . . Nest Procedures . . . . . . . . . . . . . . . . . . . . . . . . . Include Data . . . . . . . . . . . . . . . . . . . . . . . . . . . Verify Data Inclusion . . . . . . . . . . . . . . . . . . . . . . Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Code Variable Parameters . . . . . . . . . . . . . . . . . . . Define Default Values . . . . . . . . . . . . . . . . . . . . . Supply Values On The EXEC Statement . . . . . . . . . . Reference Variable Parameters in the Procedure . . . . . Use Variable Parameters In Nested Procedures . . . . . . Shift During Expansion . . . . . . . . . . . . . . . . . . . . Reserved-Name Variable Parameters . . . . . . . . . . . . . . . . . CA Driver Reserved-Name Variable Parameters Substrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Null Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attributes of Variables . . . . . . . . . . . . . . . . . . . . . . The Type Attribute . . . . . . . . . . . . . . . . . . . . . . . Test the Type Attribute . . . . . . . . . . . . . . . . . . . . The Length Attribute . . . . . . . . . . . . . . . . . . . . . . Test the Length Attribute . . . . . . . . . . . . . . . . . . . The Number Attribute . . . . . . . . . . . . . . . . . . . . . Test the Number Attribute . . . . . . . . . . . . . . . . . . . Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CA Driver Functions . . . . . . . . . . . . . . . . . . . . . . . Arithmetic Date Functions . . . . . . . . . . . . . . . . . . . Date Conversion Functions . . . . . . . . . . . . . . . . . . Day-Of-Month Functions . . . . . . . . . . . . . . . . . . . Conditional Procedure Expansion . . . . . . . . . . . . . . . . . Define Step Names (DSTEP) . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . Branch (DGOTO) . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . Define Conditions (DIF) . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . Set Variable Parameters (DSET) . . . . . . . . . . . . . . . Control Loops (DLCTR) . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abort Expansion (DFLUSH) . . . . . . . . . . . . . . . . . . Abort Expansion of the Current Procedure (DABORT) . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
121 123 124 125 125 125 126 127 129 130 132 132 133 134 135 136 137 137 140 142 143 144 144 144 145 145 146 146 147 148 148 149 152 153 154 154 154 154 156 156 158 159 159 160 160
Contents 7
Comments Inside CA Driver Procedures . . . . . . . . . . . Comments for CPU Jobs . . . . . . . . . . . . . . . . . . Comments for XPJOB Jobs . . . . . . . . . . . . . . . . Use CA Driver in the CA 7 Environment -- Some Examples Conditional Execution Based on Schedule ID . . . . . . XPJOB Driver Procedures . . . . . . . . . . . . . . . . . Chapter 5. NCF . . . . . . . . . . . . . . . . Purpose . . . . . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . . CA 7 NCF Components . . . . . . . . . . . . CAIRIM (Resource Initialization Manager) SVC Interface . . . . . . . . . . . . . . . ICOM . . . . . . . . . . . . . . . . . . . . Node Table . . . . . . . . . . . . . . . . . Unknown Node Table . . . . . . . . . . . NCF Communications Data Set . . . . . NCF Undeliverable Queue (UDQ) . . . . NCF VTAM Application Program . . . . Functions . . . . . . . . . . . . . . . . . CA 7 NCF Test Data Generator . . . . . Planning and System Requirements . . . . . General Notes . . . . . . . . . . . . . . . Terminology . . . . . . . . . . . . . . . . Installation . . . . . . . . . . . . . . . . . Resource Requirements . . . . . . . . . Operating System Environment . . . . Memory Requirements . . . . . . . . . DASD Devices . . . . . . . . . . . . . . DASD Requirements . . . . . . . . . . . CAIRIM System Requirements . . . . . Implementation Considerations . . . . . . . . Execution Options . . . . . . . . . . . . . Sample NCF VTAM PARM . . . . . . . Sample NCF VTAM JCL . . . . . . . . CA 7 Database . . . . . . . . . . . . . . Scheduling . . . . . . . . . . . . . . . . DB.1 Panel . . . . . . . . . . . . . . . . User Execution JCL . . . . . . . . . . . . JOB Statement . . . . . . . . . . . . . . JES2 Statements . . . . . . . . . . . . . JES3 Statements . . . . . . . . . . . . . EXEC Statements . . . . . . . . . . . . DD Statements . . . . . . . . . . . . . . Data Sets . . . . . . . . . . . . . . . . . . General Usage . . . . . . . . . . . . . . . NCFNODE Parameter . . . . . . . . . . CA 7 LOAD Process . . . . . . . . . . System Operations . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
161 161 161 162 162 162 163 164 165 166 168 168 169 169 169 170 170 170 170 171 172 172 172 173 174 174 174 174 175 176 177 178 179 179 180 180 180 181 181 182 182 183 183 183 184 184 185 186
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initialization . . . . . . . . . Establish Communications Standard Operations . . . Status Information . . . . Error Recovery . . . . . . . Termination . . . . . . . . . Operator Commands . . . . . . STOP Command . . . . . . Response . . . . . . . . . . SHUTDOWN Command Response . . . . . . . . . STARTUP Command . . . Response . . . . . . . . . LOGON Command . . . . Response . . . . . . . . . LOGOFF Command . . . . Response . . . . . . . . . PURGE Command . . . . Response . . . . . . . . . STATUS Command . . . . Response . . . . . . . . . TRACE Command . . . . . Deactivate the Trace Facility
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
186 186 187 187 187 187 188 189 189 190 190 191 191 192 192 193 193 194 194 195 196 198 199 201 203 204 206 207 207 209 209 212 213 214 215 218 222 223 223 224 225 226 229 229 230 230 231 232
Chapter 6. Cross-Platform Scheduling . . . . . . . . . . . CAICCI Cross-Platform Connections . . . . . . . . . . . . . . . Non-MVS CAICCI Connections . . . . . . . . . . . . . . . MVS CAICCI Connections . . . . . . . . . . . . . . . . . . The XPS CLIENT . . . . . . . . . . . . . . . . . . . . . . . . . . Direct Submit Function . . . . . . . . . . . . . . . . . . . . Batch Submit Function . . . . . . . . . . . . . . . . . . . . Direct Submit Function Parameters . . . . . . . . . . . . . Cross-Platform Tracking . . . . . . . . . . . . . . . . . . . Cross-Platform Tracking Under the CA 7 Started Task . Set up the High Availability Option (HAO) of CA 7 XTRK CA 7 Cross-Platform Tracking Commands . . . . . . . . CA 7 Cross-Platform External Tracking . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . The XPS SERVER . . . . . . . . . . . . . . . . . . . . . . . . . The XPS Submit Monitor . . . . . . . . . . . . . . . . . . . Submission . . . . . . . . . . . . . . . . . . . . . . . . . . Status Update . . . . . . . . . . . . . . . . . . . . . . . . The Cross-Platform Scheduling Router (XPS Router) . . Cross-Platform Server Password Requirements . . . . . . Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . Manage the Cross-Platform Workload . . . . . . . . . . .
Contents 9
CA 7 XPS Server Implementation Checklist Chapter 7. Email . . . Email Address Members Email Templates . . . . Special Characters Email Test Utility . . . . Control Statements Data Set for TCP/IP Data
. . . . . . . . . . . . . . .
234 237 239 241 244 245 245 247 249 250 250 250 250 251 253 254 256 257 258 258 259 259 259 259 260 261 261 261 262 262 263 264 264 265 266 267 268 269 270 271 272 273 273 274 276 277
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 8. Global Variables . . . . The Substitution Process . . . . . . . CA 7 JOB Statements . . . . . . CA Driver Procedures . . . . . . . Standard Procedures . . . . . . . Substitution Rules and Restrictions . General Reserved Variable Names . Job-Specific Reserved Variable Names Examples . . . . . . . . . . . . . . . .
Chapter 9. Jobflow Illustrator . . . . . . . . . . Purpose . . . . . . . . . . . . . . . . . . . . . . . . Connections . . . . . . . . . . . . . . . . . . . Simulation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . Ad Hoc Adds and Deletes Checkpoint Save and Start . . . . . . . . . . Flowchart Output . . . . . . . . . . . . . . . . The Workflow Building Process . . . . . . . . . . . Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CA 7 Sample User JCL . . . . . . . . . . . . . . . . Input DD Statements . . . . . . . . . . . . . . Output DD Statements . . . . . . . . . . . . . Dynamically Allocated DD Statements . . . . Initialization Parameters (INITDEF DD Statement) TYPE Parameter . . . . . . . . . . . . . . . . . CA7 Parameter . . . . . . . . . . . . . . . . . LOGON Parameter . . . . . . . . . . . . . . . CA7PASS Parameter . . . . . . . . . . . . . . SIZE Parameter . . . . . . . . . . . . . . . . . NODE Parameter . . . . . . . . . . . . . . . . RECEIVER Parameter . . . . . . . . . . . . . CKPTDDN Parameter . . . . . . . . . . . . . . Building Parameters (PARMDEF DD Statement) Global Building Parameters . . . . . . . . . . MAXJOBS Parameter . . . . . . . . . . . . . FROM Parameter . . . . . . . . . . . . . . . TO Parameter . . . . . . . . . . . . . . . . . SPAN Parameter . . . . . . . . . . . . . . . .
EXTRACT Parameter . . . . . . . . . . . . . . . . . . . QTIME Parameter . . . . . . . . . . . . . . . . . . . . . Search Building Parameters . . . . . . . . . . . . . . . . JOB Parameter . . . . . . . . . . . . . . . . . . . . . . . SCHID Parameter . . . . . . . . . . . . . . . . . . . . . SYS Parameter . . . . . . . . . . . . . . . . . . . . . . . Filter Building Parameters . . . . . . . . . . . . . . . . . JOBFILTER Parameter . . . . . . . . . . . . . . . . . . SCHFILTER Parameter . . . . . . . . . . . . . . . . . . SYSFILTER Parameter . . . . . . . . . . . . . . . . . . Commands (SYSIN DD Statement) . . . . . . . . . . . . . . Ad Hoc Commands . . . . . . . . . . . . . . . . . . . . . System Command . . . . . . . . . . . . . . . . . . . . . . Output Command . . . . . . . . . . . . . . . . . . . . . . Command Coding Rules . . . . . . . . . . . . . . . . . . ADDJOB CommandAdd a Job . . . . . . . . . . . . . ADDDS CommandAdd a Data Set . . . . . . . . . . . DELJOB CommandDelete a Job . . . . . . . . . . . . SAVE CommandWrite to the Checkpoint Data Set . . FLOWCHART CommandGenerate a Jobflow Illustrator JCL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . Example 1: Cold Start . . . . . . . . . . . . . . . . . . . . Example 2: Checkpoint Start and CSV Flowchart . . . . Example 3: Null Table Cold Start, Multiple Checkpoints . Example 4: Delete Job and Print Flowchart to DASD CSV Flowchart File Description . . . . . . . . . . . . . . . . . Fields (Columns) . . . . . . . . . . . . . . . . . . . . . . . FLOWCHART TYPE=PRINT Description . . . . . . . . . . . Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependencies . . . . . . . . . . . . . . . . . . . . . . . . Connections . . . . . . . . . . . . . . . . . . . . . . . . . Sample FLOWCHART TYPE=CSV File (Partial) . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
278 278 279 279 280 281 282 282 283 284 285 285 285 286 286 286 289 291 294 295 303 303 304 305 306 307 308 314 314 315 316 317 317 319 321 323 324 327 327 327 327 328 331 331 332 332 333 334
Appendix A. CA7TOUNI Conversion Utility . . . . . . . . . . . . . PHASE I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input JCL Statements . . . . . . . . . . . . . . . . . . . . . . . . . Examples of SASSX2UN SYSIN Statements . . . . . . . . . . . Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Output JCL Statements . . . . . . . . . . . . . . . . . . . . . . . . SASSX2UN Return Codes . . . . . . . . . . . . . . . . . . . . . CA7TOUNI Keyword Processing During Phase I of Conversion PHASE II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute the CONVERT Command Online . . . . . . . . . . . . . Restore a Converted Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clean-Up
Contents 11
Conversion Utility Messages . . . . Informational Messages . . . . . Warning Messages . . . . . . . Pre-Conversion Utility . . . . . . . . How it Works . . . . . . . . . . . Input Parameters . . . . . . . . Input JCL Statements . . . . . . Output JCL Statements . . . . . SASSX2PD Return Codes . . . Pre-Conversion Utility Messages Informational Messages . . . . Warning Messages . . . . . . Error Messages . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
335 335 335 341 341 343 343 344 347 348 348 348 348 351 352 359 361 362 365 367 368 369 370 371
Appendix B. Batch Program CA7TOUNI CA7TOUNI Submission . . . . . . . . . . . CA7TOUNI Considerations . . . . . . . . . Appendix C. XTRK as a STC or Job . . CA 7 Cross-Platform Tracking JCL . . . . CA 7 XPS Client Implementation Checklist
Appendix D. XTRK Under ICOM . . . . . . . . . . . . Cross-Platform Tracking ICOM PARM Values . . . . . Cross-Platform Tracking ICOM DD Statements . . . . Cross-Platform Tracking ICOM WTOR/MODIFY Replies Index
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 Services scheduling. It is designed for use by both the operator and data center personnel 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 . . . . . . . . . . . . CA 7 CA 7 Job Management Smart Console Option Schedule UNIX System Services Jobs . . . . . . . Interface with IBM Workload Manager (WLM) . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16 64 68 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 security product 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 the CA 1 TMC. After a TIQ or TIQU command is entered, the terminal is placed in TIQ 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 statement in the initialization file can be used to cause an automatic cancel from TIQ mode 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 is not defined to the CA 1 Security module, a message appears and a different CA 1 password must be entered. Messages produced by the CA 7 TIQ interface are in the Message Reference Guide. 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 be linklisted to use this feature. When the TIQ interface is used, the CWORK value for CA 7 should be increased by 10 for each concurrent TIQ session through CA 7 (see the chapter "Execution" in the Systems Programmer Guide). Note: The CA 1 TIQ interface in CA 7 dynamically loads the appropriate TIQ interface module based upon the current release of CA 1 found on your system during execution. Therefore no special application statements are required.
TIQ Command
This command has the following format: TIQ TIQU YES ,DSN=NO
U Indicates updating is to occur. DSN Indicates whether the data set name is to be verified before CA 1 will allow updating of the TMC record. YES is the default. This parameter is only valid with TIQU.
CA 11
CA 7 interfaces with CA 11 by supporting the ARTS command monitor, by allowing automatic RMS step insertion, and by providing automatic CMT updating when jobs are restarted, forced to complete, or canceled. The CA 11 interface is included automatically during the install of the CA 7 base product (FMID CL2B100). Note: A separate FMID is no longer required for the CA 11 interface. Sites no longer need to assemble the CA 11 interface at APPLY time. The CA 11 interface is delivered already assembled. Should a future release of CA 11 require a re-assembly of the interface, you can use SAMPJCL member UL2B143. Add the following statements to the initialization file before the APPLCTN statement for SASSPROG: APPLCTN,NAME=SASSRMS1,ATTR=PERM APPLCTN,NAME=SASSRMS2,ATTR=PERM The CA 11 load library must be concatenated to the CA 7 STEPLIB or linklisted since CA 11 modules perform part of the interface. The following initialization file statement is required to turn on the CA 11 interface: 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 information as described in CA 11 documentation. The ARTS interface is very similar to the TIQ interface. The monitor mode is entered and can be limited by the MONLIM value 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 the CA 11 Security module, a message appears and a different CA 11 password can be entered. Messages produced by the CA 7 ARTS interface can be found in the Message Reference Guide. Those produced by CA 11 are documented in CA 11 documentation. 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 parameter for CA 7 should be increased by a count of 20 for each concurrent ARTS session through CA 7. If CA 7 is being run in a large enough region, CWORK may not need adjusting. Normally, five or less interfaces are concurrent even in large terminal networks. However, since CWORK reduces the external storage available to other CA 7 interfaces, it may be better to increase region size (see the chapter "Execution" in the Systems Programmer Guide). When issuing CA 11 commands that have multiple panels of output, it is necessary to retype the first letter of the command (or a blank) before pressing Enter to view secondary panels.
Automatic RMS Step Insertion

For jobs submitted by CA 7, a job-level option can cause a CA 11 RMS procedure to be inserted in the job's JCL. The default procedure name inserted depends on the release level of CA 7. You can change the procedure name by using the PROCRMS parameter of the RESTART statement in the initialization file. (You can find a sample RMS PROC in the CA 11 SAMPJCL data set as member CA11RMS.) When CA 7 inserts the RMS procedure, the parameter passed is determined as follows: If restart data is present in the JCL as part of the //*UCC7RESTART statement, the restart data is passed as the parameter. If you have no restart data for //*UCC7RESTART, the parameter is set to P unless Load processing is needed. If you have no restart data and Load processing is needed, the parameter is set to F.
This parameter can be overridden by using the PARMRMS parameter of the RESTART statement in the initialization file. To request automatic RMS step insertion for a job, set the INSERT-RMS field on the DB.1 panel to Y. (For more information, see the chapter "Jobs" in the Database Maintenance Guide.) If CA 11 is not installed, the insert feature is not active regardless of the INSERT-RMS field on the DB.1 panel. Note: If IBM OS Restart (JOB statement RESTART parameter) is used, then it is possible that the RMS step inserted by CA 7 will be bypassed. This could result 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 canceled through CA 7, the CMT is updated automatically. If CA 7 NCF is installed, then, for jobs executed at nonlocal NCF nodes, CMT updating cannot occur and the restart data is passed by the //*UCC7RESTART statement. When a job is resubmitted, force completed, or canceled, the interface attempts to clear the CMT flags. When a job is restarted, the interface posts the restart data to the CMT then sets the restart data to P. If the QM.4 panel SET PARM field 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, XQ function C or F, and XRST.
CA Workload Control Center (UWCC)

The CA WCC (UWCC) is a portal-based application that allows you to monitor and manage CA 7 from a web browser. It was formerly known as the Unicenter EJM. UWCC provides user-friendly portlets to define and maintain CA 7 definitions for jobs, schedules and other objects. It also allows graphical drag-and-drop scheduling along with graphical monitoring of the active CA 7 workload. UWCC also allows you to manage and monitor your enterprise job management environment with multiple copies of CA 7 and CA AutoSys from a single workspace. To enable the CA 7 interface for CA WCC, see CA 7/API Requirements on page 40.
CA APCDDS
CA APCDDS automates the manual, often neglected task of data verification, thereby increasing the accuracy and consistency of your output while reducing reruns and improving auditability. CA APCDDS is a rule-based menu-driven system that provides comprehensive data verification routines to catch errors in a timely fashion -- before mistakes are propagated throughout the system. CA APCDDS adds to the flexibility of CA 7 by allowing an out-of-balance condition to directly affect the production workflow. CA APCDDS has the ability to directly issue a CA 7 command in response to an out-of-balance condition. No longer is it necessary to manually balance a report and then manually demand jobs for execution. Implementation of CA APCDDS requires no changes to your existing application programs.
CA APCDOC
If you have CA APCDOC (CA production documentation product) installed on your system, you can use its flowcharting facility to show schedule and job flowcharts from the CA 7 database. These flowcharts can be based on the current workload or forecasted for a future date. Users with CA 7 can use the DOCCHART 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 database or by reading an FSTRUC report. If the user chooses the FSTRUC option, the CA 7 FSTRUC command should be issued first, placing the output into a sequential file, which DOCCHART then reads. The differences between creating a CA 7 flowchart from FSTRUC output and creating one from the database include: The database flowchart shows job and data set requirements, which FSTRUC does not. The database flowchart shows a starting point and continues on until it reaches the end, whereas FSTRUC just shows one job at a time. The database flowchart is not time sensitive. It shows the relationship between jobs regardless of the time it is run. It gives an undistorted view of triggers and requirements, and database relationships. The database flowchart runs independently of CA 7 and does not require CA 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 many resources that the database flowchart does not. Since the database flowchart issues its own reads to the database, it can run against any copy of the database (current, old, or restored). A user can compare 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 from CA 7 to CA Dispatch or from CA Dispatch to CA 7. The CA 7 to CA Dispatch part of the interface is discussed in Forecast Print Volumes on page 24. The CA Dispatch to CA 7 part of the interface is discussed in the CA Dispatch Reference Guide.
Forecast Print Volumes

When CA Dispatch is used for managing printed output, the forecasting of print volumes by CA Dispatch may be desirable for planning activities associated with 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 Dispatch user 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 command through a batch terminal interface, to forecast the jobs for which print volumes are wanted. This places data in a data set reserved for FWLP purposes. This card-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. For further discussion of this command and its function, see the discussion of the FWLP command and the DDNAME keyword parameter in the Command Reference Guide. 2. Run a batch job using module SASSDPCH to reformat the data from Step 1 into plan records in the format required by CA Dispatch. 3. Using the output file from SASSDPCH, produce the forecast of print volumes as described in the CA Dispatch user documentation.
Alternatively, the data set created in Step 1 could be modified or created manually by the user prior to Step 2. The following is a sample of the JCL needed 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 operatorid FWLP,....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 library generated during installation and a copy of CA Earl. If a full copy of CA Earl is installed, it can be used. If a full copy of CA Earl is not available, you can install the service from the CA Common Services distribution tape. For more information about installing the CA Earl subset product, see the Installation Guide. For JCL and usage considerations, see the Report Reference Guide. The CAIMAC EARL report member, prefix CA7ER, contains record and report definitions 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, if that product is in use at your site. A standard set of reports can be produced using either the CA 7 log history file or output from the CA 7 database backup utility as input to CA Easytrieve. For information about producing reports from CA Easytrieve, see the chapter "CA Earl and CA Easytrieve Reporting" in the Report 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 in the CA 7 editor and on the LJCK command. It also supports batch validation of JCL for a stream of forecasted jobs. In the online environment, the interface greatly extends the CA 7 validation facilities. For example, the interface displays procedure expansions, so that error messages are reported in a meaningful context. Also, the interface supports checking for the existence of data sets that may prove useful in testing production job streams. The interface also includes a batch utility that uses the FJOB command to forecast a series of jobs and then the LJCK command to extract JCL for them so that CA JCLCheck can validate the JCL for the stream as a whole. This utility is requested from an ISPF panel that is provided with CA JCLCheck. For more information, see the CA JCLCheck documentation.
CA 7 Considerations
The interface is requested through the JCLCHECK statement in the CA 7 initialization file. An OS LOAD macro is used during CA 7 initialization to locate the JCLCHECK load module. The address returned by the LOAD macro is used for all subsequent accesses of CA JCLCheck by CA 7. If the JCLCHECK module is not resident or in a linklist library, concatenate the library containing the JCLCHECK load module to the CA 7 STEPLIB. The storage requirement for CA 7 may increase significantly if the CA 7 CA JCLCheck interface is used. A CWORK increment of 250 is proposed as a starting value. However, this should be considered a tentative recommendation as the storage required may vary according to several factors such as the number of concurrent interface users and the number of input statements to be parsed. For more information about CA JCLCheck storage requirements, see the CA JCLCheck documentation. The execution JCL for CA 7 must be modified to include a DD statement that points to the libraries on which cataloged procedures reside. The name of the DD statement must be SYSPROC. If this DD statement is not found, the CA JCLCheck option AUTOPROC can be specified. For more information about the AUTOPROC option, see the CA JCLCheck documentation. If the JCLCHECK statement in the CA 7 initialization file uses the DDNAME parameter, an additional DD statement is required using the name from the DDNAME parameter. The DD references a card-image file specifying additional options for CA JCLCheck. For a list of valid options, see the discussion of the JCLCHECK statement in the Systems Programmer Guide. For more information about these options, see the CA JCLCheck documentation.
CA Librarian
Add the following DD statement to the CA 7 online JCL for each CA Librarian data set. //JCLnnn DD DISP=SHR,DSN=name-of-librarian-data-set
Add the following JCL statement to the CA 7 initialization file for each CA Librarian 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 same value as nnn on the DD statement (leading zeros are required on the DD statement). Access is read-only using JCL panels, list commands or job scheduling functions such as DEMAND, RUN, and so forth. Normal access expands "include" references, but a list option is available to suppress 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 job completions using the realtime CA Netman interface. When CA 7 detects a job completion, one or more CA Netman API transactions are issued based on information about the job from the CA 7 status queues. In the standard implementation, the realtime interface can be used to OPEN or UPDATE problems in CA Netman for CA 7 jobs that end abnormally and CLOSE CA Netman problems for those restarted CA 7 jobs when they complete normally. A batch interface between CA 7 and CA Netman is also available that uses the Machine Generated Problem Tracking feature of CA Netman and the CA 7 batch 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 in the CA 7 initialization file. This statement is used to set CA Netman API control values and parameters regulating the activity of the CA 7 subtask that invokes the CA Netman API. The interface also requires a NETMAN DD statement in the JCL used to start CA 7. This statement identifies a file containing CA Netman API transaction schema that are used to build the CA Netman API transactions that are issued when a CA 7 job completes. For more information, see CA Netman Model Transactions on page 30. The realtime CA Netman interface uses CA Netman API deferred processing so that API transactions created by the interface will be retained in the event that the CA Netman CAICCI receiver is inactive. This requires the presence of a CA Netman API deferred request data set. Any CA Netman API request issued by the interface will be written to this file for subsequent processing with the NTM920 utility. The data set must be defined as RECFM=FB and LRECL=80 and must be identified in the CA 7 procedure with the ddname NTMADFR. For more 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 issued indicating successful initialization of the CA Netman interface. The storage requirement for CA 7 may increase significantly if the CA Netman interface is used. An increase in region size of 1MB is recommended as a starting value. A larger increase may be required depending on the volume of CA Netman transactions to be issued.
CA Netman Considerations
If the realtime CA Netman interface is indicated, a task in the CA 7 address space will be created to asynchronously accept CA 7 job completion data, build CA Netman transactions based on the schema in the model CA Netman transaction file and issue API requests to send those transactions to CA Netman. The CA Netman API requires the presence of an active CA Netman CAICCI listener. A listener can be requested either through a CA Netman transaction or through the use of the CA Netman Asynchronous Services Task (NTMASYN). For more information about implementing the CA Netman API, see the CA Netman documentation. Also see the CA Netman documentation for a discussion of security using the API. 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 the CA 7 execution JCL by a NETMAN DD statement. Each time the CA Netman interface is invoked, CA Netman commands built from the model transactions will be issued. For example, if the following model CA Netman transaction is coded: MGPT FUN=UPDATE SOURCE=XXX CAT=YYY SD='JOB 1' Each time the CA Netman interface is invoked, an attempt is made to issue an MGPT transaction conforming to the above format. The model transaction file must be defined as as DSORG=PS, LRECL=80 and RECFM=F or FB. CA Netman transactions are issued in the order that they appear in the model transaction file for each invocation of the interface. The next example illustrates the use of variables in model CA Netman transactions: SIGNON MJM MGPT FUN=&&MFUN SOU=CA7 CAT=U + DESC='&&L2PME_L2JOBN ENDED WITH &&L2PME_L2CC' + IDAT= &&L2DATE ITIM= &&L2PME_L2JOB# + OCCRD=&&L2OCDT OCCRT=&L2OCTI SIGNOFF
Variables can be used in the model transactions to refer to useful data such as job name, JES number, date, time, and so forth. With model transactions coded as in the above example the following CA Netman API transaction could be generated when job ABC123 completes: SIGNON MJM MGPT 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 completion information. In this example suppose that job ABC123 abended with a S-0C4 on 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, the problem can be referenced by incident date and CA 7 job number. For a list of variable names and their values, see CA Netman Model Transactions - Variables on page 32.
CA Netman Model Transactions - Continuation Rules

Model transactions can be continued. A continuation is indicated by the occurrence of + as the last non-blank character on the line. The continuation resumes at column 1 of the next line. The length of a CA Netman transaction built by this interface cannot exceed 1000 bytes. The number of continuations for 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 &&L2NTM_DBASENM &&L2PME_L2JOBN &&L2PME_L2JES &&L2PME_SYSID &&L2PME_L2JOB &&L2PME_L2SID &&L2PME_L2SYSN &&L2PME_L2RSN &&L2PME_L2CC Length 16 08 05 04 05 03 08 08 06 Value The value of the DBASENM keyword on the CA Netman System Information (SYST) panel Name of the job scheduled by CA 7 JES number of the job scheduled by CA 7 Execution SMF ID of the job scheduled by CA 7 CA 7 assigned job number CA 7 schedule ID associated with the job System name from the CA 7 job definition Restart step name Completion code: C-nnnn - normal completion CFnnnn - job forced complete JCLERR - JCL error R-nnnn - condition code test failed S-nnnn - system abend U-nnnn - user abend &&L2PME_L2RC &&L2PME_L2CPUT &&L2PME_L2JCLI &&L2PME_L2DOYR &&L2PME_L2DODY &&L2PME_L2DOT &&L2PME_L2DLYR &&L2PME_L2DLDY &&L2PME_L2DLT &&L2PME_L2SMYR &&L2PME_L2SMDY &&L2PME_L2SMT &&L2PME_L2STYR &&L2PME_L2STDY &&L2PME_L2STT 04 08 03 04 03 04 04 03 04 04 03 04 04 03 04 Restart count CPU time CA 7 JCL ID for the job CA 7 due-out year CA 7 due-out day CA 7 due-out time CA 7 deadline year CA 7 deadline day CA 7 deadline time CA 7 submit year CA 7 submit day CA 7 submit time CA 7 start year CA 7 start day CA 7 start time
Variable Name &&L2PME_L2ETYR &&L2PME_L2ETDY &&L2PME_L2ETT &&L2PME_L2EM
Length 04 03 04 04
Value CA 7 end year CA 7 end day CA 7 end time The entry mode of the job: ADEM ADST AEXT AJBT ANWT APS ARFJ ARUN ASSC DEMD DSTR EXTL JBTR NWTR PSCH RPET RUN SSCN XDEM XPS XRUN Job entered by DEMAND command in ARF recovery Data set triggered in ARF recovery Externally tracked job in ARF recovery Job triggered in ARF recovery Network triggered in ARF recovery Job entered by Personal Scheduling in ARF recovery ARF recovery job Job entered by RUN command in ARF recovery Job entered by Schedule Scan in ARF recovery Job entered by DEMAND command Data set triggered Externally tracked job Job triggered Network triggered Job entered by Personal Scheduling Repeat job Job entered by RUN command Job entered by Schedule Scan Cross-platform scheduled using XPSSCHD=DEMAND Cross-platform scheduled using XPSSCHD=RUNREF Cross-platform scheduled using XPSSCHD=RUN
&&L2PME_L2OVR &&L2PME_L2MNT &&L2PME_L2EX &&L2DATE &&L2OCDT &&L2OCTI &&DATE
01 01 01 05 06 04 06
OVERRIDE=Y or N from CA 7 job definition MAINT=Y or N from CA 7 job definition EXEC=Y or N from CA 7 job definition CA 7 due-out date: format is YYDDD Occurrence date: format is MMYYDD Occurrence time: format is HHMM System date: format is CYYDDD
Variable Name &&TIME &&MFUN
Length 06 06
Value System time: format is HHMMSS Expected value for MGPT FUNCTION keyword. If job ends abnormally, &&MFUN=UPDATE. If job ends normally but was restarted, &&MFUN=CLOSE.
CA Opera
CA Opera provides an interface to CA 7 using the U7SVC facility. This interface allows CA 7 commands to be issued based on events recognized by CA Opera. Any commands issued using the CA Opera interface require operator 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 add the CA 7 browse event to your CAIENF database. To add this event, see member L2DCM1 in the CA 7 sample JCL library.
CA OPS/MVS
CA OPS/MVS provides an interface to CA 7 using the U7SVC facility. This interface allows CA 7 commands to be issued based on events recognized by CA OPS/MVS. Any commands issued using the CA OPS/MVS interface require operator 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. This facility 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 REXX Address Environment Interface Execution on page 99. For CA OPS/MVS to monitor CA 7 browse data set messages, you need to add the CA 7 browse event to your CAIENF database. To add this event, see member L2DCM1 in the CA 7 sample JCL library. CA OPS/MVS can also monitor CA 7 Critical Path Monitoring events. CA OPS/MVS can then interface with other CA solutions to track and display critical paths. For information about implementing Critical Path Monitoring in CA 7, see Critical Path Monitoring on page 60. For information about using CA OPS/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 each CA 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 file for 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 same value as nnn on the DD statement (leading zeros are required on the DD statement). Access is read-only using JCL panels, list commands or job scheduling functions such as DEMAND, RUN, and so forth. Normal access expands "include" references, but a list option is available to suppress the expansion when doing an LLIB command. If a new version of CA Panvalet is installed, CA 7 needs to be recycled (a WARM start is sufficient).
UNIX System Services Interface

The UNIX System Services interface provides a method of communication for requests to CA 7 from the UNIX System Services environment. The interface can be called directly from the UNIX shell or from the MVS batch interface Unix Systems Services MVS BPXBATCH. This includes user applications, shell scripts, and the command prompt. The request can be any valid CA 7 command that is normally passed to U7SVC and must be syntactically correct. For information about the installation and setup of the CA 7 USS Interface modules, see UNIX System Services Interface in the Systems Programmer Guide. For a detailed discussion on using the UNIX Services with the shell environment, see the IBM documentation for the UNIX System Services User's Guide and the UNIX System Services Command Reference. For invoking the CA 7 interface, see the following examples.
Invoke the Interface

From the UNIX shell environment command prompt, you can invoke the interface as follows: ca7oecom demandh,job=payjob1 The preceding example invokes the CA 7 UNIX Services interface executable CA7OECOM and passes the command on to CA 7 through U7SVC. In this case, a DEMANDH command for job PAYJOB1 is requested. A return code is supplied to indicate the status of the request to U7SVC. The UNIX shell can be entered by issuing the TSO/E OMVS command from within 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 prevents the shell from evaluating the special characters as part of the command. For example: ca7oecom 'addrq,job=payjob1,usr=this is a user requirement'
Environment Variables
CA7DIR: This environment variable specifies the fully qualified path name for the location of the interface executable CA7OECOM. This variable is required to be set prior to execution of the interface. Example Path /users/applications/ca7/bin CA7TRACE: This environment variable is used for diagnostic purposes. When set to a value of "ON", the interface module CA7OECOM will issue diagnostic messages during execution to assist in problem determination. Set Environment Variables: Environment variables can be set from within the shell by using the UNIX "export" command. If you are using the MVS Batch interface Unix Systems Services MVS BPXBATCH, you can set the environment variables in a file pointed to by ddname STDENV. Examples: To set the CA7DIR variable in the UNIX environment from the command 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 the variable to the value as follows: CA7DIR=/users/applications/ca7/bin
Special Considerations: The UNIX environment is case-sensitive. The CA7DIR environment variable name must be specified in uppercase. The path name 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) to communicate with CA 7. If you want to use one of these with CA 7, take the following steps: 1. Add the CA 7 CAILOAD to the Server JCL The CA 7 load library (CAILOAD) must be available to the server task that communicates with CA 7. If the CA 7 CAILOAD is linklisted in your environment, no changes to JCL or CLISTs should be required. The CA 7 CAILOAD should be added to the STEPLIB concatenation for the Server Task (started task). For directions on how to identify/define the server 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 PROFILE data set used by the CA 7/API. This is pointed to by the PROFILE DD in the Server started task. The variables that must be added to the CACCENV member are: CA7APPL=applid This variable identifies the VTAM APPLID for the CA 7 you want the API to communicate with. This can be found on the APPL= keyword of the UCC7VTAM statement in the CA 7 initialization file. For example, if your APPLID for CA 7 is PRODCA7 then specify CA7APPL=PRODCA7. Note: The CA 7/API can communicate with any CA 7 that is defined to the VTAM system where the API is executing. If you have cross-domain definitions to a CA 7 on a remote system, the CA 7/API executing locally can communicate with that CA 7. CA7SESS=high-acb-name This variable identifies the set of VTAM ACB names that can be used by the CA 7/API locally to establish communications with CA 7. For example, if you have 10 ACBs (CA70001 through CA70010), you should specify CA7SESS=CA70010. The interface will deduce from this that 10 ACBs are available to choose from (1 through 10) and will locate an available ACB from that pool. If the CA 7 TSO ISPF interface is installed, the same VTAM ACBs used by that interface can also be used by the CA 7/API. If so, check to ensure you have enough ACBs to satisfy both ISPF and API users. If ACBs need to be defined, For detailed instructions, see VTAM Considerations on page 44.
3. If CA 7 Jobflow Illustrator Microsoft Visio Option is installed, you can skip this step unless you are connecting to multiple instances of CA 7 on the same LPAR. Three variables must be added to the CACCENV member of the PROFILE data set used by the CA 7/API. This is pointed to by the PROFILE DD in the Server started task. WFDSN=datasetname Defines the data set name to use for all Jobflow Illustrator checkpoint files that are saved. This value must contain either a data set name prefix or a fully qualified data set name that is part of a generation data group (GDG). If datasetname contains a data set name prefix, the length of this value must not exceed 26 characters. When a Jobflow Illustrator checkpoint is saved, the data set name prefix is suffixed with the following format: .Dyyyyddd.xhmmssth where yyyyddd contains the Julian date and xhmmssth contains the hour, minute, second, tenth, and hundredth of a second when the Jobflow 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=value Defines the storage class, management class, data class or unit that will be allocated for the Jobflow Illustrator checkpoint data set name specified in WFDSN. class This value must contain one of the following types where value can be from 1-8 characters in length: STORCLAS=value MGMTCLAS=value DATACLAS=value UNIT=value Note: If the WFALLOC variable is missing, the default is the following: WFALLOC=UNIT=SYSALLDA
WFSPACE=(type,primary,secondary) Identifies the type and the amount of disk space that will be used to allocate the Jobflow Illustrator checkpoint data set name specified in WFDSN. type This value must contain one of the following types: CYL (for cylinders) TRK (for tracks) primary This value must contain the primary space allocation. The value must be numeric and in a range of 1-9999. secondary This value must contain the secondary space allocation. The value must 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 Jobflow Illustrator 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 with which it is communicating. If you do not have Virtual Terminals defined, or if you need to increase the number of Virtual Terminals, see the discussions of the UCC7VTAM, LINE and TERM initialization statements in the Systems Programmer Guide. 5. Enable Online Calendar Maintenance facility If you want to use the facilities in CA WCC to maintain your CA 7 base calendars, you need to enable the Online Calendar Maintenance facility in CA 7. This feature allows you to create, update, and delete CA 7 base calendars online without the need for batch assemblies. If you want to enable Online Calendar Maintenance, see the CALENDAR initialization statement in the Systems Programmer Guide.
TSO/ISPF
CA provides an interface that gives the TSO/ISPF user access to a wide range of CA 7 functions. With the interface, the CA 7 user can now enjoy many of the benefits that derive from TSO/ISPF (such as split-panel capability and ISPF Editor) while using CA 7. However, it should be noted that the ISPF jump facility 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 a command area and pressing Enter. One must either split the panel or end the CA 7 terminal session. In the TSO/ISPF environment, the ISPF user requests interface services by means of a CLIST. Programs executed under the CLIST acquire a CA 7 virtual terminal and a VTAM LU-LU session is set up between ISPF(SLU) and CA 7(PLU). With the exception of edit sessions, panel data is presented as it is in any CA 7 online terminal session. The interface processes panel input and output for the ISPF session by invoking the appropriate ISPF Dialog Manager services. Interface modules issue VTAM SEND and RECEIVE macros to handle the data traffic with CA 7. Note: Because the interface uses a CA 7 VTAM terminal, all restrictions that apply 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 the exception of /SHUTDOWN commands. The JCL syntax checking facility that is used by the native CA 7 Editor is NOT available in the ISPF environment. JCL validation through CA JCLCheck can be requested using the !JCK edit macro. For more information about !JCK, see the CA JCLCheck documentation if you are using the full CA JCLCheck product. To use the CA 7 TSO/ISPF interface, virtual terminals must be defined in the CA 7 initialization file. For more information about the installation of this interface, see the Installation Guide. This discussion of the CA 7 TSO/ISPF interface installation follows in three topics: VTAM considerations ISPF considerations CA 7 considerations
VTAM Considerations
The TSO/ISPF interface requires VTAM node definitions to support the LU-LU session between CA 7 and ISPF. The following discussion provides information about 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 using the ACBNAME keyword on the VTAM APPL statement. The interface imposes strict conventions that must be observed when coding the value for this keyword. The application minor node name that is created by the label on the APPL statement is not referenced by the interface directly. This name is used by VTAM and must be unique within the network. The ACBNAME values must be exactly seven bytes long. The first three characters can be chosen by the user, subject to VTAM naming conventions. The last four characters must be numeric and numbered consecutively from 0001 to nnnn, where nnnn represents the maximum number of concurrent uses of the interface. For example, suppose that all of the node names to be used by ISPF during CA 7 sessions begin with the characters CA7. If the maximum number of concurrent 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 such an installation. CA7ISPF CA71 1 CA71 2 CA71 3 CA71 4 VBUILD APPL APPL APPL APPL TYPE=APPL ACBNAME=CA7 ACBNAME=CA7 ACBNAME=CA7 ACBNAME=CA7 1 2 3 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 should then be copied to the appropriate VTAMLST library to correctly define the VTAM application.
Each request for a CA 7 terminal session from an ISPF panel requires the use of one of these nodes dedicated for interface use. Thus, in this example, anywhere from one to four ISPF users can be allowed depending on terminal characteristics. In most instances, an ISPF user requires the use of only one CA 7 terminal session. However, nothing would prevent one ISPF user from having more than one CA 7 terminal session going at one time using ISPF's split panel capability. For example, one user could split the panel into four ISPF panels, and from each screen maintain a CA 7 terminal session. This would imply four concurrent uses of the interface or four CA 7 terminal sessions going on at once. In this example, any attempt to use the interface during this time from another terminal would fail since no nodes would be available for this purpose. Unlike the node for CA 7 that requires that AUTH=ACQ be coded on the VTAM APPL statement, the ISPF nodes have no such special requirements. A VTAM application similar to the one just described must be defined in each VTAM domain where TSO/ISPF sessions with CA 7 are to be supported. For CLIST compatibility, the ACBNAME values should be the same across domains, only the node names that are created by the labels on the VTAM APPL statements need be changed for network uniqueness. In the following example, the CA7ISPF member could be used as a model for an application definition in another domain of the network. CA7ISPF2 CA72 1 CA72 2 CA72 3 CA72 4 VBUILD APPL APPL APPL APPL TYPE=APPL ACBNAME=CA7 ACBNAME=CA7 ACBNAME=CA7 ACBNAME=CA7 1 2 3 4
When the install is complete, make sure to activate the applications where the interface nodes are defined. In this example, issue a VARY command on the MVS 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 load modules. The CLIST used to invoke the interface is provided in the CA7CLIST member of CAICLS0. This CLIST must be edited to reflect changes appropriate for your installation. It should then be copied to a library that is part of the SYSPROC concatenation 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 ERROR UPDATE: + %CA7INIT ENDPF: + CALL '&LIB(L2ISPF )' + 'CA7APL=&CA7APL,SESSAPL=&SESSAPL' FREE DA('&LIB') GOTO FINAL ERROR: + WRITE CA-7.X 45 - ERROR IN VGET FROM APPLICATION POOL GOTO FINAL APPLERR: + WRITE CA-7.X 46 - LAST 4 CHARACTERS OF SESSAPL MUST BE NUMERIC FINAL: + SET &CA7ACT = ISPEXEC VPUT (CA7ACT) SHARED EXIT In the CLIST above, the CA7APL keyword supplies the name of the ACB for CA 7. This value should be identical with the value coded for the APPL keyword in the UCC7VTAM statement in the CA 7 initialization file. The value on the SESSAPL keyword should be the ACBNAME with the highest value. In this example, CA70004 would be coded since four nodes were defined for CA 7 TSO/ISPF communication.
When performing an installation, you can run SMP/E USERMOD UL2B111 in the SAMPJCL library. The job replaces the default TSO/ISPF CLIST with a copy that is customized by the CA 7 Stage I SYSGEN. Also, several CLISTs are used as EDIT macros when the ISPF Editor is called in the CA 7 environment. The edit macros are CA7EXIT, CA7SAVE, CA7SS, and CA7SR. These correspond respectively to EXIT, SAVE, SS, and SR in the CA 7 environment. Another edit macro CA7ED0 is supplied and is required for internal 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 SYSPROC concatenation in the TSO LOGON procedure. The following load modules are required. They are used to handle the VTAM link with CA 7, invoke Dialog Manager services and perform other interface functions. These modules do not execute in the CA 7 address space but in the TSO 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 from the CA 7 production load library to a smaller load library that is accessed by TSO users. In this way, use of the interface does not entail allocation of the CA 7 load library. The library containing the interface modules is dynamically allocated using a CALL statement. Three ISPF panel definitions are supplied on CAIPNL0 and are required for the interface: CA7@PRIM CA7P CA7 3 The CA7@PRIM panel is the menu panel for CA 7 under ISPF. CA700003 is a documentation 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 definitions should be copied to a library that is part of the ISPPLIB concatenation in the TSO LOGON procedure.
Although a CA 7 online terminal session can be acquired by simply executing CA7PDRVR, ISR@PRIM should be modified to issue the CA7PDRVR command with NEWAPPL (CA7). If CA7PDRVR is invoked in this way, an ISPF application named CA7 is recognized by ISPF. If the interface is invoked in any other way (for example, by executing CA7PDRVR or CA7CLIST from ISPF option 6) then you have no CA 7 PF key support. See the sample ISR@PRIM provided in CAI.SAMPJCL for an example of an ISPF primary menu where the CA 7 TSO/ISPF interface is an option. If the CA7@PRIM panel is defined as a SELECT option with the NEWAPPL(CA7) parameter and if the CA 7 TSO/ISPF interface option is selected from the ISPF primary menu, then ISPF searches for a user profile named CA7PROF, an edit profile named CA7EDIT, and a command table named CA7CMDS. The CA7CMDS member of CAITBL0 is provided as part of the installation. CA7PROF and CA7EDIT are built by ISPF dynamically. ISPF retrieves all profile information from CA7PROF while the CA7 application is in control, thus allowing the user the capability of defining ISPF PF key settings that are unique to the CA7 application. When the online option (option 1 from the CA 7 TSO/ISPF menu) is invoked for the first time, PF keys are assigned the following default settings: PF 1 PF 2 PF 3 PF 4 PF 5 PF 6 PF 7 PF 8 PF 9 PF1 PF11 PF12 HELP SPLIT END RETURN RFIND RCHANGE UP DOWN SWAP LEFT RIGHT CURSOR PF13 PF14 PF15 PF16 PF17 PF18 PF19 PF2 PF21 PF22 PF23 PF24 HELP SPLIT END RETURN RFIND RCHANGE UP DOWN SWAP LEFT RIGHT 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 input and is treated as such. CA 7 input can be entered either from the "top line" or from any area considered appropriate for a CA 7 formatted panel if a formatted panel is displayed. ISPF commands are usually issued from any area preceded by the character string '====>' or through the PF key. However from a CA 7 session under ISPF, ISPF commands can be entered only through the PF key, since all panel input is taken to be CA 7 terminal input.
CA 7 allows assignment of CA 7 commands to PF keys as does ISPF. In a CA 7 terminal session under ISPF, a PF key interrupt can be used for ISPF command input or CA 7 command input but not both. Since it is desirable to use PF keys for both types of command input, most users may want to specify that certain PF keys provide ISPF command input, and that other PF keys are treated like CA 7 PF keys. When using CA 7 formatted input panels, PF3 is used 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 ISPF command will prevent that key from being used by CA 7 in any way; transfers between panels will require the user to enter the panel name each time. When an ISPF command is entered, ISPF searches a table to determine the action that should be taken when this command is input. Such a table is known as 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 the TSO 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 when the command was entered. If an ISPF command is entered from a CA 7 terminal 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 the table that matches the command entered, then ISPF takes the action specified on 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 processes the command as if there were no table entry for it. If NOP is specified, then the command associated with it is deactivated for that application. If PASSTHRU is specified, then the command with its PF key interrupt is passed to the application in effect, which in this case is the CA 7 TSO/ISPF interface. An action can also be specified dynamically by using an ISPF variable. A command table (CA7CMDS) is provided that is intended to be used with the default PF key settings for the CA7 application previously listed. Use of this table 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 7 terminal 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 an assignment allows the ISPF commands SPLIT, SWAP, and END to always be input using PF keys when in the CA7 application. The CA7CMDS member should be copied from CAITBL0 to a PDS that is in the ISPTLIB concatenation in the TSO LOGON procedure.
The following entries are in the CA7CMDS member supplied in CAITBL0: VERB T ACTION DESCRIPTION NOP &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT
.... SUBMIT .... HELP .... RETURN .... RFIND .... RCHANGE .... UP .... DOWN .... LEFT .... RIGHT .... CURSOR
The ACTION NOP on the entry for SUBMIT causes the ISPF SUBMIT command to be deactivated for the CA7 application. This prevents users from using the ISPF SUBMIT command to submit jobs while in the ISPF editor in a CA 7 terminal session. This is strongly recommended since jobs submitted through the ISPF SUBMIT command are not tracked by CA 7. Use of the &CA7ACT variable on the other table entries allows the interface programs and CLISTs to set the action dynamically, so that the action can be changed when the need arises. If the ISPF editor is invoked from a CA 7 terminal session, then the value of &CA7ACT is set to blanks, otherwise the value of the variable is set to PASSTHRU. To see how this works, suppose that the PF01 key has been pressed in a CA 7 terminal session where the ISPF editor is not currently being used. Suppose also, that the PF01 key is associated with the ISPF HELP command under the CA7 application. ISPF searches the CA7CMDS table for an entry for the ISPF HELP command. The entry is found and the variable &CA7ACT has been set by the interface programs to PASSTHRU. The HELP command is not processed by ISPF but instead is sent to the interface programs that send the PF01 interrupt to CA7. CA7 sees the interrupt and processes the command (if any) 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 interface programs set the value of &CA7ACT to blanks. Thus, the action associated with the ISPF HELP command in the CA7CMDS table has been set to blanks. This causes the ISPF HELP command to be processed normally when PF01 is pressed. Most of the default PF key settings provided for the CA7 application equate with ISPF commands that have no significance in a CA 7 terminal session unless the ISPF editor is invoked. Great care should be exercised when modifying the ISPF PF key settings or the command table for the CA7 application. Only those PF keys that are associated with ISPF commands that appear in the CA7CMDS table with an action of PASSTHRU or &CA7ACT are honored by CA 7. The default command table CA7CMDS that is found in CAITBL0 does not include entries for SPLIT, SWAP and END. This causes these ISPF commands to always be honored. We recommend that PF keys be set up (using option 0 from the CA 7 TSO/ISPF menu) for all essential ISPF or TSO command input that must be entered from the CA 7 terminal session. If such command input is always to be handled by ISPF 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 call needs to be the following: ADDRESS ISPEXEC "SELECT CMD(CA7CLIST) NEWAPPL(CA7)"
CA 7 Considerations
Virtual terminal definitions are required. The number of virtual terminals defined should be greater than or equal to the number of nodes defined for CA 7 TSO/ISPF communication. For more information about installation of the TSO/ISPF interface for CA 7, see the Installation Guide. The ISPF display services used by CA 7 do not support scrolling. The display of 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 7 panel 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 platforms managed by other CA schedulers and agents (cross-platform scheduling). For more information, see Chapter 6, Cross-Platform Scheduling on page 201.
Unicenter Event Console

CA 7 can route master station messages to a designated Unicenter Event Console. 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 events occur in CA 7. For example, if a payroll job abends, a request can be automatically opened to track the problem. The following CA 7 events can be used to create a request in CA Service Desk: 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 Service Desk r11 or higher is also required. You may not want requests open for all job completions or queue full conditions. 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 Services tape, 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 using CAICCI. In other words, there must be a CAICCI connection between the system where CA 7 is executing and the system where CAISDI/soap is executing. If CAISDI/soap is executing on the same system with CA 7, no CAICCI connection is necessary. CA 7 provides an event library for CAISDI/els. The default name of this library is CAI.CA7.CAIEVENT. Event library member AL2CNTL is called the control member. The control member may need some customization for some shops, but should be sufficient for 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 with CA 7. If your site needs to tailor an event, copy the event member to another name and change the copy. Event member names have the format xxxxxxnn where xxxxxx is the six-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, and options. The summary section contains a one-line problem description. The description section contains a lengthy HTML-formatted description of the problem. The final section, options, specifies the priority (severity) of the problem. The summary and description sections can contain variables that will be filled by CA 7. For example, a job completion event in CA 7 will provide variables for the job name, JES number, completion code, and so forth. For a complete list of the variables available, see the topic Event Variables. After each IPL or change to the event library, the event library must be loaded by CAISDI/els on the system where CA 7 is executing. The load is done by the CAISDI/els CASDIELS procedure. The CASDIELS define statement for CA 7 should 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 be spelled 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 contact and asset names. These names must be defined to CA Service Desk, or the appropriate options must be set in CA Service Desk to allow the contacts and asset names to be dynamically added. Read the comments in the control member and the CA Service Desk documentation for more information.
Configure CA 7
The CA Service Desk interface is activated by the SERVICEDESK initialization file statement. SERVICEDESK has no keywords.
When CA 7 finds the SERVICEDESK initialization file statement, it reads filtering rules from the SERVDESK DD statement. The filtering rules control when a CA Service Desk request is to be created. For example, the rules may indicate that requests should be opened for job names that start with PAY and that abend. For more information, see SERVDESK Rules. CA 7 will write the CA Service Desk request number that was opened to the SERVLOG DD statement. SERVLOG should be a SYSOUT file allocated to the CA 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. In addition to the text (contents) of the request, the events also control the formatting and priority of the request. CA 7 provides events both with and without HTML formatting for the description. Using the HTML formatting may require you to change installation options in CA Service Desk. Events that start with @ do not use HTML formatting. Events that do not start with @ do use HTML formatting. The following CAISDI/els events are provided by CA 7. Name without HTML Formatting @ABND1 @ABND2 @ABND3 @FAIL1 @FAIL2 @FAIL3 Name with HTML Formatting ABEND1 ABEND2 ABEND3 FAILD1 FAILD2 FAILD3 Intended Use
Job completions where the job has abended. Event names ending in 1 create priority 1 requests, ending in 2 create priority 2 requests, etc. Job completions where the job has ended with an unacceptable return code. Event names ending in 1 create priority 1 requests, ended in 2 create priority 2 requests, etc. One of the CA 7 queues (scratch, DQTABLE, or trailer) is at or above 80% full. These events create a priority 1 request.
@QFUL1
QFULL1
Any number of additional CAISDI/els events can be created at your site by adding additional members to the event library.
SERVDESK Rules
The SERVDESK DD statement points to an FB 80 data set containing the rules for when CA 7 should create requests in CA Service Desk. The SERVDESK rules are read at CA 7 startup when the SERVICEDESK initialization file statement is processed. The rules are then stored in memory. The SERVDESK rules 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 currently active 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 any column. The following are valid types: JOBCOMP Job completion. All CA 7 job completions are compared against JOBCOMP rules to determine whether a request should be opened. This includes job abends, job condition code failures, normal (successful) completions, and "force completes." Note: Non-executable jobs and "force completes" are treated as zero return code completions (C-C0000). Also, cross-platform jobs (CA7TOUNI) are not evaluated if the MVS submit execution of the CA7TOUNI step is successful. In that case, the completion code reflects the return code returned by the cross-platform target node. QFULL Queue 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 keywords are valid for all rule types): ATIME=, BTIME= Specifies after and before times used for all rule types. If the after time is less than the before time, then the event (that is, job completion) must occur between the two times. If the after time is greater than the before time, the event must occur outside of the time range. ATIME defaults to 0000. BTIME defaults to 2359. COMP= Specifies a required completion code or completion code mask used for JOBCOMP rules. The completion code uses the same format as seen on the LQ command (that is, an S806 abend would be "A-S806"). COMP= is required on JOBCOMP rules. A value of FAILED can be used to match any code that is not a successful completion. For example, COMP=FAILED matches any abend, bad return code, or JCL error. EVENT= (Required for all rule types) Specifies the six-character name of the CAISDI/els event that will create the request in CA Service Desk. The CAISDI/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 match job completion events in CA 7. JOB= defaults to *. QUEUE= Specifies a queue name or queue name mask used for QFULL rules. See message 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 is opened in CA Service Desk. If multiple rules would match an event, then the first 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 to match 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 in any of the SERVDESK fields that accept masks. Example SERVDESK Rules: This example creates a priority 1 request if any job 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 that abends or gets a bad return code: JOBCOMP,SYSTEM=ACCT,COMP=A ,EVENT=ABEND2 JOBCOMP,SYSTEM=ACCT,COMP=R ,EVENT=FAILD2 This example creates a request for abending jobs with an X in column 3 and that end in $ and are in the BILLING system. If the abend occurs during the day, use priority 2, otherwise use priority 1. JOBCOMP,JOB=??X $,SYSTEM=BILLING,ATIME= 8 ,BTIME=17 , COMP=A ,EVENT=ABEND2 JOBCOMP,JOB=??X $,SYSTEM=BILLING,COMP=A ,EVENT=ABEND1 Note: The second JOBCOMP rule does not need the ATIME and BTIME fields because 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 Desk can contain variables. Variables start with an ampersand (&) and are in uppercase. When the values are substituted into the CAISDI/els events, any trailing blanks are dropped. The following variables are available. Note that not all variables are available for all CA 7 event types. Variable &DLDATE &DLTIME &DODATE &DOTIME &EDATE &ENTRYMOD &ETIME &EXEC &EXSYS &INSTANCE &JESNUM &JOB &JQUSER &MAINT &NL &NUM &P &QUEUE &RESTARTS &SCHDID &SDATE CA 7 Event Types JOBCOMP JOBCOMP JOBCOMP JOBCOMP JOBCOMP JOBCOMP JOBCOMP JOBCOMP JOBCOMP All JOBCOMP JOBCOMP JOBCOMP JOBCOMP All JOBCOMP All QFULL JOBCOMP JOBCOMP JOBCOMP Description Deadline date Deadline time Due out date Due out time End date Entry mode of the job (demanded, auto, sscan) End time EXEC flag Execution system SYSID (is 7UNI for cross-platform jobs and 7XPJ for XPJOB) CA 7 instance name (that is, CA71) JES number (can be *NA* for force complete and cross-platform jobs) Name of the job Contents of the JQUSER field MAINT flag Single carriage return (new line) CA 7 job number Double carriage return Name of the queue that is 80% full Number of times job has been restarted Schedule ID Start date
Variable &STAT8 &STAT80 &STIME &SUBDATE &SUBTIME &SYSDATE &SYSEDATE &SYSID &SYSTEM &SYSTIME &SYSJOB
CA 7 Event Types JOBCOMP JOBCOMP JOBCOMP JOBCOMP JOBCOMP All All All JOBCOMP All All
Description The 8-byte status of the job, as seen on the LQ command A longer, user-friendly, status of the job Start time Submission date Submission time Current date in format MM/DD/YYYY Current date in format DD/MMM/YYYY SMF ID where CA 7 is executing Job's SYSTEM Current time Name of the CA 7 task
Critical Path Monitoring

Large production workloads can be difficult to manage in the absence of monitoring 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 job streams, "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 graphically display the status of CA 7 critical paths. These solutions are not provided as part of the CA 7 installation package. For more information about this option, see the CA OPS/MVS documentation. Critical Path Monitor Version 3 is supplied as part of the CA 7 installation package. You can use it to track CA 7 critical paths and to display critical path information in text-based formats on ISPF panels. For more information about this option, see the Critical Path Monitor Version 3 User Guide.
Critical Path Definition

The definition of CA 7 critical paths and the creation of critical path events by CA 7 is the same regardless of which CPM tracking tool is being used. Unless otherwise noted, the following description of Critical Path Monitoring applies to either 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 a FLOW. 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 and terminates when its ending job completes successfully. CA 7 considers an active FLOW to include the beginning job and all of its job and dataset triggered descendants up to and including the ending job. The CA 7 command FLOWL can be used to display active FLOWs in CA 7. For information about the FLOWL command, see the Command Reference Guide. CA 7 uses ENF to report status information for all FLOW jobs to the CPM Tracker. When CA 7 notifies the CPM Tracker that a FLOW has begun, the CPM Tracker will request forecast information from CA 7 to chart the "critical path" that connects the FLOWs beginning and ending jobs. The CPM Tracker then uses the CA 7 ongoing status information to monitor the progress of the critical path. FLOW initiation occurs at job submission as part of the VRM resource evaluation process. This implies a restriction on defining the starting job in a FLOW. A job must be eligible to use VRM resources to initiate a FLOW. This means that a nonexecutable job cannot start a FLOW. However, nonexecutable jobs can be included in a FLOW and can be defined as the ending job of a FLOW. Note: If flows are not properly defined, active flows may become stranded. For example, if the specified ending job is no longer in the trigger flow, all related jobs may complete without finding the end of flow. Also, if a job in the critical trigger path is CANCELed, the flow never recognizes the ending job. Current releases of CA 7 automatically delete active flows if there are no longer any jobs connected to it (see message CAL2P099W). However, you should periodically issue a FLOWL command and check for active flows that have not completed as expected, and use the FLOWD command to delete them because active 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 is coded on the OPTIONS statement in the CA 7 initialization file. When active, this interface provides services that can be used to define those portions of the triggered workload that require special management attention using CPM. These services are used to define the limits of a key segment of the triggering stream and to assign a name to the segment for subsequent references in the CPM environment. For information about initialization 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 the CPM Tracker to build an image of a critical path. At least one CA 7 CAICCI terminal must be defined in the CA 7 initialization file. For information about the interface, see Interface with CAICCI on page 90. For information about GROUP, LINE, and TERM statements for CA 7 CAICCI terminals (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 the CPMSRVR started task JCL. If you are using CA OPS/MVS then the OSF server task JCL acts as the CPM Tracker. The CPM Tracker must have access to the CA 7 load library. If the library is not in the LNKLST or LPALIB, you must add them to the OSF server's STEPLIB DD. Optionally, you may need to add a CA7PARMS DD statement to the CPM Tracker JCL to set parameters to be used by the CA 7 CAICCI interface to gather information about active flows. If specified, the CA7PARMS DD must 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. The following lists keywords and their defaults: CA7NODE= Specifies the CAICCI node where CA 7 resides. The default is local node. CA7SSCT= Specifies the CA 7 instance name (CA71, CA72, and so forth). The default is CA71. CA7USER= Specifies the user ID to log on to CA 7 with. The default is CPM Tracker user 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: 0 Suppresses trace 1 CPMF WTO trace only 2 CPMF and CCI interface WTO trace only 3 CPMF WTO trace and CPMF snap trace only 4 CPMF 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 a CA7TRACE 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 be used to log on to CA 7. Regardless of the source, the CA 7 user ID used by the CPM Tracker must have authority to issue FJOB, FLOWL, FQJOB, FRJOB, LQ and LRLOG CA 7 commands as well as having CA 7 UID access 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 7 browse data set messages, you need to add the CA 7 browse event to your CAIENF database. To add this event, see member L2DCM1 in the CA 7 sample JCL library. The CA 7 CA 7 Job Management Smart Console Option Cross System Communication provides for two major functions: CA 7 CA 7 Job Management Smart Console Option to CA 7 CA 7 Job Management Smart Console Option and 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 Job Management Smart Console Option Users can define cross system actions where a message is selected by CA 7 CA 7 Job Management Smart Console Option on one system and specific actions are performed on another system executing CA 7 CA 7 Job Management 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 will have their console messages routed to all defined systems executing CA 7 CA 7 Job Management Smart Console Option. Commands issued from a system executing CA 7 CA 7 Job Management Smart Console Option can be routed to another system executing CA 7 CA 7 Job Management Smart Console Option. The command output is returned to the console that issued the command. The principle of integrated services will be used to communicate between systems. The use of CA Common Communication Interface (CAICCI) insulates CA products from the dependencies of the operating 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 Job Management 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 Option Multi-System Console Facility, only console messages are routed between systems executing CA 7 CA 7 Job Management Smart Console Option. CICS messages are not routed unless they are issued to the console using the SENDOPER action. Simulate Mode This feature functions at the action record level. By defining an action record in the SIMULATE state, you instruct the action processor not to actually perform the action, but to record that it would have been performed in the log instead. The log entry can also be sent to the console as a WTO or system log based on the CA 7 CA 7 Job Management Smart Console Option system parameters. The inclusion of an action record in the simulate state within a list of actions has no effect on any of the other actions; they are still processed normally. You can 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 a specified number of times within a time frame. After this maximum has been reached, the selection record can be suspended for a specific time period. This selection process will allow messages to be selected only after a specified number of occurrences. After this frequency has been reached, the selection record can be suspended for a specific time period. You can specify substitution variables as scan text. Substitution variables work with the SETEVENT action. When the SETEVENT action occurs, all the variables for that message are saved. By entering the Event ID in the token field and the actual variable name in the SCAN TEXT field, the selection processor will resolve the variable and perform the SCAN using the data that variable contains. The selection processor allows specification of up to eight SCAN TEXT qualifications. Selection processing supports lowercase characters as your SCAN TEXT data. Be aware that, SCAN TEXT data defaults to lowercase when specifying the data in the CA 7 CA 7 Job Management Smart Console Option Dialog. Also, the scan options allow positional offset specification (offset from the 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. Valid parameters for this field are: WTO, CMD, and CICS. The default is WTO, which is used to define console messages. CMD is used for selection of operator commands. CICS is used for the selection of internal CICS messages that are typically written to the MSGUSR DCB. Use these messages to detect terminal and printer errors, transaction abends, and other information relevant to a CICS address space. Use the SUBSYSTEM field with the JOBNAME field to select CICS messages from specific address spaces.
The selection processor allows for selection of the MVS Nucleus Initialization Program (NIP) messages. NIP messages are produced from the time the system operator selects the LOAD function at the system console to the time that the operating system is initialized. System initialization is considered the point in time when the system log becomes available. To select NIP messages, CA 7 CA 7 Job Management Smart Console Option must be initialized before the Job Entry Subsystem (JES) is started. Keep in mind that the NIP messages have already occurred by the time CA 7 CA 7 Job Management Smart Console Option initializes; these messages are not selected realtime. CA 7 CA 7 Job Management Smart Console Option processes them as if the messages were occurring at CA 7 CA 7 Job Management Smart Console Option initialization time. This provides the ability to determine that an IPL has occurred or perform action processing based on the produced NIP messages. Since the NIP messages occur before the CA 7 CA 7 Job Management Smart Console Option address space is active, CA 7 CA 7 Job Management Smart Console Option does not respond to them; however, CA 7 CA 7 Job Management Smart Console Option does provide action processing capability for the messages. Date Qualification is available. This will allow you to specify a date or range of dates on which the selection record will be active. Day/Time Qualification is available. This will allow you to specify a certain day or days and also specific time ranges on those days within which 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-core selection, action, and event tables are automatically refreshed upon changes to the selection or action database file.
Four-Digit Reply IDs Support is provided for four-digit Reply IDs that were introduced with MVS/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 processing occurs every minute.
Licensing Management Program (LMP) CA 7 CA 7 Job Management Smart Console Option interfaces with CAIRIM to determine product licensing authorization.
Schedule UNIX System Services Jobs
Schedule UNIX System Services Jobs

The mainframe environment provides a UNIX implementation referred to as UNIX System Services. These services allow UNIX users to operate from within the mainframe environment without having to learn the MVS system internals while using most of the standard UNIX facilities such as shell commands, shell scripts, and binary executables. This UNIX shell runs as an MVS system task and can be accessed from any MVS batch job through a program called BPXBATCH. The BPXBATCH program is invoked from MVS batch and executes shell scripts or 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 manage workload distribution, transaction balancing, and resource distribution in z/OS environments. WLM allows the specification of policies to control the distribution of workloads throughout a sysplex. While used primarily to control and manage online transaction workloads, such as CICS user transactions, WLM also has features you can use to help manage batch workloads. CA 7 provides interfaces which help you to use IBM WLM to treat CA 7 and the CA 7 Independent Communications Manager (ICOM) as WLM resources. CA 7 also provides features which help you use WLM scheduling environments to manage your batch workload. Use these interfaces separately or concurrently based 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 and the CA 7 Independent Communications Manager (ICOM) as WLM resources. You can group WLM resources into scheduling environments. Scheduling environments allow you to manage the scheduling of tasks in a sysplex where different hardware or software applications are available on each system. The resources which make up scheduling environments are defined to the IBM Workload Manager. They can represent something physical such as a hardware device. They can represent the presence of a software application such as DB2. Or, they can represent something intangible, such as a day of the week. MVS or JES operator commands can set WLM resource states. Interface calls to WLM by software applications can also set them. You can assign IBM WLM resource names to the CA 7 online started task and the CA 7 Independent Communications Manager (ICOM) started task. When specified CA 7, ICOM, or both will call the IBM Workload Manager to set the state of the designated resource to ON when the started task is initiated. When the started task terminates, a call is made to set the state of the resource to OFF. One possible use of these resources is to control which MVS images CA 7 Batch Terminal Interface (BTI) jobs are directed to. Since these jobs require the same CA 7 system interfaces as CA 7 ICOM, you could use an IBM WLM scheduling environment to ensure that these jobs are only directed to images where ICOM is running. To assign an IBM WLM resource name to the CA 7 started task, see the documentation for the WLMCA7= keyword on the CA 7 initialization file OPTIONS statement in the Systems Programmer Guide.
To assign an IBM WLM resource name to the ICOM started task, see the documentation 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 scheduling environments to manage your batch workload. A scheduling environment is a list 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 are differences in the hardware or software applications available on each system. If an MVS image matches the scheduling environment requirements, then that task can be routed to that system. Through CA 7 Virtual Resource Management (VRM) definitions, you can assign IBM WLM scheduling environments to individual jobs and have CA 7 automatically add the appropriate SCHENV= keyword at job submission time. These VRM definitions use the variable (VAR) resource type and can be associated based on CA 7 schedule ID. Also, CA 7 can optionally validate the specified scheduling environment with the current IBM WLM policy prior to job submission. This avoids pre-execution JCL errors that occur when a SCHENV= keyword is specified with a scheduling environment 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 file OPTIONS statement in the Systems Programmer Guide. To create Virtual Resource Management (VRM) definitions to associate scheduling environments with individual jobs, see VRM Variable Definitions in the Database Maintenance Guide.
Chapter 3. External Communicators

This section contains the following topics: Batch Terminal Interface (BTI) . . Trailer Step Facility . . . . . . . . . U7SVC Facility . . . . . . . . . . . Interface with CAICCI . . . . . . . Batch Card Load Program (BCLP)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
73 81 85 90 106
External communicators enable the processing of work that is under CA 7 control, based on events that are not under CA 7 control. One example would be an RJE site transmitting data to a central location for processing. The remainder of the processing, to be done under the control of CA 7, must consider the creation of the data file as a prerequisite task and is triggered when the data file is received from the RJE site. Such activities are handled 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 database functions within a batch job instead of through an online terminal. Many of the same commands that are available online can be performed through a batch terminal when a CA 7 online terminal is unavailable or impractical. Trailer steps communicate queue posting commands to CA 7 for some action that has taken place. On receiving this communication, CA 7 automatically initiates all tasks defined as dependent on that posting action. The U7SVC program combines the BCLP and trailer step functions. U7SVC can be executed as a step, in the same manner as a trailer step, or it can be called from another program to send commands to CA 7 or post a data set creation. Through U7SVC, the user can post to CA 7 the creation of a noncard-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 batch commands to CA 7 on the same or another MVS image. It also receives back the CA 7 output from those commands so that the caller can evaluate the success of the command string, extract information from the command output for future processing, or both. The CA 7 CAICCI interface can be executed in a batch mode, called from a REXX CLIST or environment, or called directly from another program.
Chapter 3. External Communicators 71
BCLP is used to transfer batches of card-image data to disk or tape. Once the data files are created, work under CA 7 control can use those files. On creation of the file, completion information is posted to the CA 7 log data set and all dependent processing tasks are initiated. These facilities provide the ability to have work performed outside of the data center, perhaps at an RJE site, with the production control functions remaining at the central computer location. Inherent advantages of having full data center security are maintained. Remote personnel need not be involved in data center operations, JCL, and so forth. Of course, work that begins with any task external to CA 7 can still realize the advantages of automated production control.
Batch Terminal Interface (BTI)

Batch terminals provide the ability to process commands in batch as if from an online terminal. You can perform many of the same commands available online in this manner if no CA 7 online terminal is available, if hardcopy output is desired from the commands performed, or if more than 255 pages of output could be produced. Each batch terminal is actually a pair of disk data sets, one input 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 CPU where SASSBSTR is running; but the batch terminal must have access to the Communications data set. However, when using the trailer step, U7SVC or BCLP 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 in batch 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 data set. Notifies CA 7 to start the batch terminal for processing. Waits for CA 7 to process the commands in the input data set and place responses in the output data set. Retrieves the output and writes it to a SYSOUT data set. The BTI output can be checked against a user-defined table of messages to detect error or warning conditions. For more information about the batch terminal interface error message table (SASSXXBT), see the chapter "User Exits and Modifications" in the Systems Programmer Guide.
Command Format and Sequence

The input to the program (SYSIN) consists of CA 7 commands. The /LOGON and /LOGOFF commands are the required first and last records, respectively, for each batch terminal interface input data set. They must begin in column 1 of the record. To log on, the format is: /LOGONopid ,password
opid Specifies the required operator identification. password Specifies an optional password (site-specific). Note: When using an external security interface, the /LOGON statement can be omitted, and the batch terminal interface program generates one using an extracted security ID for the user who submitted the BTI job. The format of the DBM batch commands consists of placing the equivalent panel top line command by itself in the first statement. In the second and following statements are the function, positional parameters and optional keywords. Statements begin in column 1. If the statement is to be continued it must end with a comma following the last value entered. There must be a non-blank character in column 72 and the next statement must begin in column 1. In the following, notice that function is a positional parameter and must appear where it is shown. command function,positional-parameter,optional-keywords... The following is an example of the command format:
JOB ADD,jobname,SYSTEM=sys,...,(other optional keywords)
To terminate database maintenance mode, enter DBM starting in column 1. For example: /LOGON JOB ADD,ACCT 1,SYSTEM=S1 UPD,ACCTPAY,USERID= 3 JOBCONN UPD,JDEP,ACCTPAY,DEPJOB=ACCT DBM LJOB,JOB=ACCTPAY,LIST=RQMT /LOGOFF To log off, the format is: /LOGOFF
1,OPT=C
DBM List Functions

The DBM LIST function in batch commands only validates the existence of the target and does not actually provide an image of the equivalent online formatted panel containing field names and values. For example: JOB LIST,ACCTPAY Does not list the ACCTPAY job, but does indicate that it either found or did not find 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 be continued (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 and non-DBM commands, there is a significant difference: For non-DBM commands, the batch statement format is the same as the online 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, which includes many commands in BTI format. These commands perform database maintenance (DBM) functions and some inquiry functions. These commands provide a good example of how to use the BTI facility effectively. The user can benefit from reviewing that data and understanding better 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 the N220 job is an execution of CA 7 in batch mode. The same commands, however, can be used with the Batch Terminal Interface program. The batch commands for job N220 reside in member N220DECK in the JCLLIB from installation. Check with your installation's CA 7 specialist or systems programmer who installed CA 7 for the data set name.
Batch Terminal Interface Execution

Processing Flow
The batch terminal interface program (SASSBSTR) controls the BTI processing flow. 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 the SYSPRINT data set. If the user-defined batch error message table module SASSXXBT is available, each line of output is compared against entries in the table. If matched, a message is written to the ERRORS DD (if available). Also, the matching table entry return code is saved if it is higher than any previously saved return code. The following are the possible return codes: 0 Indicates that the SASSBSTR program successfully completed its functions without detecting an error. SASSBSTR does not validate that the SYSIN commands were processed successfully by CA 7. 8 Indicates that SASSBSTR detected an error condition that prevented successful completion of its tasks. Usually, a WTO or message in the SYSPRINT is issued indicating the error condition. Note: If a /SHUTDOWN, Z3 (or Z5) is done with the batch terminal, it gets a return code of 8. 16 Indicates that a security violation occurred that prevented successful execution of SASSBSTR. Usage of the SASSXXBT message table may generate additional return code values. For more information about SASSXXBT, see the Systems Programmer Guide.
You should never cancel a BTI job while it is executing. This kind of cancel does not interrupt the execution of the CA 7 commands that the BTI has given to CA 7 to process on the specified (or pooled) batch terminal. All of these commands have to complete before CA 7 can make the batch terminal available for another BTI execution. If you do a cancel, the only way to possibly recover (reuse) that batch terminal is to run another BTI specifying the appropriate ID number. This causes CA 7 to produce the CA-7.252 WTOR, and a reply of RESET allows the BTI to proceed. However, if the previous BTI commands have not yet completed, the current BTI still fails. Also, no BTI using pooling is able to use the same ID again of the canceled one until a recycle of CA 7 or the use of the above procedure.
CA7BTI JCL Procedure

The CA 7 installation procedures generate a batch terminal interface JCL procedure 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)
n Can be 0 or specific BTI terminal. A value of 0 (zero) indicates that Dynamic BTI Management should be used. (The program automatically locates and uses an available BTI terminal.) A specific BTI terminal number (1-8) indicates that the program should use that specific batch terminal. If that terminal is already in use by another job, the current job checks every five seconds for a total of one minute to see if the terminal becomes available. If the terminal is still unavailable, a CA-7.252 WTOR is issued so that you decide whether you want this job to wait for the terminal to become available or cancel this job. Remember that if a specific BTI terminal number is coded, then the POOL parameter is ignored. POOL=(x-y,b,c) The POOL= keyword can be used with Dynamic BTI Management to specify the pool of batch terminals to be considered when searching for an available 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 pool is all eight possible batch terminals. The POOL= parameter can be used to reserve particular batch terminals for specific jobs. If these terminal numbers are excluded from the pool, Dynamic BTI Management never allocates them, thus they should always be available for BTI executions that reference them specifically. If all batch terminals in the pool are busy, the BTI program enters a cycle where it looks for an available batch terminal every five seconds. This continues for five minutes. If no batch terminals have become available during 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 code of 8. If a reply of WAIT is issued, the BTI program continues its wait/check cycle indefinitely. If several BTI jobs are waiting on any available batch terminal, there is no serialization in the order in which they obtain a terminal.
DSNPFX='batch.dsn.prefix.' Specifies an alternate data set name prefix for the BATCHIN and BATCHOUT data sets. The BTI program dynamically allocates the BATCHIN and BATCHOUT files associated with a specific batch terminal. Normally, the BTI program constructs the data set names for these files using the data set name prefix from the CA 7 communication data set (UCC7CMDS DD). The suffix BATCHI#n/BATCHO#n is appended to the prefix to construct the full data set names (where n is the associated batch terminal number). Note: If a specific batch terminal (1-8) is specified and the BATCHIN and BATCHOUT DDs in the BTI JCL are coded, no dynamic allocation occurs. CA7 Specifies the instance of CA 7 used to determine whether submit checking is turned on. instance can be one of the following values. The default is CA7=CA71. CA7n Specifies the true instance name to use where n is a value from 1 through 8. alias Defines a one- to four-character alias specified at CA 7 resource initialization. PROD Defaults to instance CA71. UC07 Defaults to instance CA71. TEST Defaults to instance CA72. UCT7 Defaults to instance CA72. NOMCHK Suppresses BTI output message checking against the SASSXXBT message table. If this parameter is not specified and a user-coded SASSXXBT table module is available, the message checking is done. For a description of the SASSXXBT message table, see the chapter "User Exits and Modifications" in the Systems Programmer Guide. NOWAIT If this parameter is specified, BTI terminates with an RC=8 if CA 7 is not active when the BTI job starts. If this parameter is not specified and the CA 7 address space is not active when the BTI process starts, it issues a WTOR (CA-7.255) and waits for CA 7. When CA 7 becomes active, BTI processing 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 job to cause the processing of CA 7 commands at strategic points within the processing. Jobs executing trailer steps need not be defined to CA 7, but can be if so desired. Use the CA 7 trailer step by including an extra step in the job stream. This step does not affect the operational function of the job but causes activity within CA 7. A CA 7 application is executed that performs the operation requested in trailer step JCL. You can use the trailer step to perform any of the commands belonging 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 post of a data set requirement. Normally, CA 7 does not post data set requirements for jobs in the request queue until normal completion of the job that creates the data sets. This is due to the possibility of a restart that would again create the data 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 the request queue that is waiting for that data set creation. Another example is jobs that cannot run until an online system is down. The job dependency could be established even though the online system is not a CA 7 job. The final step of the online system could post these jobs with a trailer step to satisfy this requirement. The /MSG command is also allowed in the trailer step. You can send messages to logical terminals by this process. The /WTO command is allowed in the trailer step. You can send messages to the console operator on the system where CA 7 is running. The /WLB command is allowed in the trailer step. You can turn workload balancing 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 as noted later in this chapter. To use the trailer step facility, a trailer terminal must be defined in the initialization file and ICOM must be active on the CPU where the trailer step is to run. Only one trailer terminal can be defined. See 83 for a trailer step JCL sample. A JCL procedure similar to this is provided during installation and should be used to ease maintenance and release upgrades. Check with your systems programmer or your installation's CA 7 specialist for the correct procedure 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-ID CA 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|INACT ACT indicates that ICOM must be active or the data is not sent. If ACT is specified and ICOM is not active, the program issues an error message and ends with RC=8. When the parm value of INACT is used, the data is held in CSA to be processed when ICOM is started. INACT is the default. CA7 Specifies 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: CA7n where n is a value from 1 through 8. This is the true instance name to use. alias Is a one- to four-character alias specified at CA 7 resource initialization. PROD Defaults to instance CA71. UC07 Defaults to instance CA71. TEST Defaults to instance CA72. UCT7 Defaults to instance CA72.
NCFNODE Indicates the name of an NCF node for routing. If NCFNODE is specified, the CA7= parameter must be CA71. The following are possible return codes: 0 Indicates PARM value supplied. 4 Indicates that PARM defaulted to INACT and/or an invalid command was found in the input. If an invalid command is found, the following WTO is issued: CA-7.TRLR-10 COMMAND NOT IN SPO0 APPLICATION. 8 Indicates an invalid PARM, INACT assumed. Various error conditions, denoted with a WTO that describes the error. For more information about the various WTOs, see the Message Reference Guide. For more information about SASSTRLR and the /LOGON statement, see the Security Reference Guide. For information about the use of SASSTRLR with a test copy of CA 7, see the Systems Programmer Guide. To prevent command interleaving among multiple tasks on the same CPU and tasks 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 to terminate a block.) In some situations, it may be necessary to add the DCB parameter to the SYSIN 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 Load program (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 posting commands. A program is provided to allow the user flexibility in the use of the SVC. The name of this program is U7SVC and it can be executed as a job step in batch or called from a user program. U7SVC allows the user to post to CA 7 that a data set has been created. The data set may have been created in a previous step of a job that is running external to CA 7. The created data set need not be fixed blocked with a record length of 80, as is the case with BCLP. The program also allows the user to issue CA 7 batch commands. All commands that are authorized for the trailer terminal may also be issued. Thus, the U7SVC program is not limited to queue maintenance commands as is the case with SASSTRLR. Note: If the U7SVC program is used to post a data set creation, then the data set should not be specified by the SASSXDSN exit table, or possible double postings (and double triggering) can occur.
U7SVC Facility
Batch Step Execution

The input to U7SVC consists of PARM and/or DD * data. Both are optional, but at 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 a CA 7 batch command or a data set creation statement. (Each entry can begin and end with one or more blanks.) The format of the PARM consists of an optional instance name and one or more entries separated by semicolons. Each data record consist of one or more entries separated by semicolons.
Parameter
By default, U7SVC communicates with instance CA71. To communicate with a different instance, place a 'CA7=xxxx;' at the beginning of the PARM= string, using the following format: CA71 CA7=alias; CA7n PROD TEST
CA71 Indicates the default, which maps to what used to be called the "production" copy of CA 7. alias Indicates a one- to four-character alias. This alias must correspond to an alias assigned to a CA 7 instance during initialization by CAIRIM. CA7n Indicates an instance where n can be an integer from 2 to 8. PROD Indicates to map to instance CA71. TEST Indicates to map to instance CA72.
U7SVC Facility
Syntax
To indicate that the creation of a data set has completed, a statement in the following format is required: D=dsname,, vvvvvv xxx ,tttttttt
dsname Specifies the data set name. Limits: 1 to 44 alphanumeric characters vvvvvv (Optional) Indicates a positional parameter specifying the volume serial number where the data set was created. Not needed if the data set has been cataloged. If not specified, a comma must be used to denote its absence. Limits: 1 to 6 alphanumeric characters xxx (Optional) Indicates a positional parameter specifying the schedule ID to be used for the data set creation. If not specified, a comma must be used to denote its absence. Default: 1 Limits: 1 to 3 numeric characters from 1 to 255 tttttttt (Optional) Indicates a positional parameter specifying the logical terminal or station name to be notified of the data set creation. Default: MASTER Limits: 1 to 8 alphanumeric characters Note: When external security is present, a resource check is made for all data set creation requests. Since CA 7 treats these requests as if the data set was really created, it can cause posting or triggering to occur. Therefore, a security resource check is made to verify the current user is authorized to create the named data set (even though it may not exist.)
U7SVC Facility
Examples
The following are two examples of the use of the U7SVC program. The CA7SVC procedure is written to a user-specified PROCLIB during the execution of the N020 installation job. Example 1: This example indicates creation has been completed for data set CA7.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 communicates with 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 TEST2 and TEST3, and a logoff. All could have been provided in the CA7DATA data set 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=TEST2 DEMAND,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 to the corresponding absolute generation number. For example, if D=A.B(+1) is specified, it is converted to D=A.B.GnnnnVnn where GnnnnVnn is the corresponding absolute generation number. The absolute zero generation number can also be specified, for example D=A.B.G0000V00. This format is not converted, but it is recognized as a GDG data set. If queue maintenance commands (other than D commands) are entered through the U7SVC facility, they must follow the same sequence as if using a CA 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. For more details on security interfaces, see the Security Reference Guide. The U7SVC facility uses the same blocking technique noted for the trailer step facility 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 to the 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 the address of the parameter list. The parameter list must be on a halfword boundary where the first 2 bytes are the length of the parameter (commands). These are normal IBM conventions. The format of the command area is the same 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 is calling the U7SVC multiple times during a single execution, then the parameter list 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 X LINK=OS, REQUEST OS LINKAGE X EQU=YES REQUEST REGISTER EQUATES LA R1,PARMA POINT TO PARAMETER ADDRESS LINK EP=U7SVC,ERRET=OOPS B #UCC7RET RETURN TO CALLER OOPS DS H WTO 'U7SVC NOT LINKED' LA R15,16 SET ERROR CODE B #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 COMMENTED COMMANDS 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 the CA 7 address space. The interface can be executed from batch, from a REXX address environment, or in a program-to-program mode. Because the interface uses CAICCI, there is no requirement for shared DASD between the MVS images where CA 7 executes and where the CA 7 CAICCI interface environment executes. CAICCI is a CA common component that allows CA applications to communicate with each other without dealing with the specifics of a particular communication protocol. The actual transfer of data may be in the form of cross-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) common component. The CA 7 CAICCI interface establishes communication with the CA 7 CAICCI receiver in the CA 7 address space. This receiver is created when there are one or more CA 7 CAICCI Terminals (DEVICE=CCI) defined in the CA 7 initialization file. For information about the CA 7 initialization file options, see the 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 for z/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 address space is executing and where the CA 7 CAICCI interface environment is executing. 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) defined and active in the CA 7 address space. Note that if you execute long-running commands, the associated CAICCI terminal is not available for other commands until the first command is complete. You may want to use a Batch Terminal (BTI) for long-running commands such as large forecasts or generic RESOLVes. A valid CA 7 operator ID must either be supplied explicitly in a /LOGON command, or the security owner of the environment where the CA 7 CAICCI interface is executing must be a valid CA 7 operator. There is no requirement for shared DASD between the MVS image where the CA 7 CAICCI interface executes and the image where CA 7 itself executes. There is no requirement that CA7ICOM executes on the MVS image where the 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. XTM xxxx, where xxxx is the CA 7 instance name, or a value specified on the XTMNAME= keyword of the SVCNO statement in the CA 7 initialization file.
Prior to r11, the default values for CA 7 instance names (previously called ssct names) were UC07 for the production copy (alias of PROD) and UCT7 for the test copy (alias of TEST). With r11, the default instance name for PROD is CA71, and the default instance name for TEST is CA72. To make the transition from previous releases smoother, the interface can automatically search for alternate instance names if the requested instance is not found. This substitution is made under the following conditions: If instance=PROD and CA71 is not found, the search looks for instance UC07 if the local CA 7 system environment is in release compatibility mode. If instance=TEST and CA72 is not found, the search looks for instance UCT7 if the local CA 7 system environment is in release compatibility mode. If instance=UC07 and UC07 is not found, the search looks for instance CA71 if the local CA 7 system environment is not in release compatibility mode. If instance=UCT7 and UCT7 is not found, the search looks for instance CA72 if the local CA 7 system environment is not in release compatibility mode.
Message CAL2C405I is issued if a different instance is successfully substituted.
CA 7 CAICCI Batch Interface Execution

The CA 7 CAICCI Batch Interface program (CAL2X2WB) provides the capability to send commands to CA 7 and receive the output from those commands as a step in a batch job. The CAL2X2WB program does the following: Reads the commands to be processed from SYSIN and builds a command block. Calls the CA 7 CAICCI interface module CAL2X2W0 passing the command block. Receives CA 7 command output through CAL2X2W0 and writes each line to SYSPRINT. If the user-defined batch error message table module SASSXXBT is available, each line of output is compared against entries in the table. If matched, a message is written to the ERRORS DD (if available). Also, the matching table entry return code is saved if it is higher than any previously saved 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 NODE Specifies the CAICCI node name where the CA 7 address space is executing. The default is to attempt to communicate with a CA 7 executing at 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 7 CAICCI interface should attempt to dynamically locate the CAICCI node where a CA 7 with a matching instance name resides. CA 7 INSTANCE NAME Specifies 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 an instance name of CA71. The secondary copy of CA 7 (called the test copy in r3.3) has an instance name of CA72. Other values include instance names CA73 through CA78 and a 1-4 character alias if one was set at CA 7 resource initialization. The value PROD can be used instead of CA71 and the value TEST can be used instead of CA72. For more information about instance names, see Usage Considerations on page 91.
OPTIONS Specifies a one- to four-character option string: TRACE OPTION If set to 'Y' it turns on diagnostic WTOs for the CA 7 CAICCI interface process. Any value other than a capital Y results in no trace. The default is no trace. CMD SEPARATOR The character used to separate commands when they are read from SYSIN and stacked into a command block. The default command separator character is a semicolon (;). -- unused -The third and fourth characters of the options are reserved for future use. CMDIN DDNAME Specifies the ddname of the source for CA 7 commands. The default is SYSIN. CMDOUT DDNAME Specifies the ddname for the CA 7 command output. The default is SYSPRINT. ERRORS DDNAME Specifies the ddname for messages produced when a CA 7 command output 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 a SASSXXBT table is available, specify *NOMCHK* as the override ddname in the parameter list.
CAL2X2WB Return Codes

Module CAL2X2WB issues WTO CAL2C509I when processing completes that lists the return code and condition code for the process. The possible return and condition codes from CAL2X2WB are as follows: 0 Indicates that the CAL2X2WB program was able to successfully complete its functions without detecting an error. 8 Indciates a processing error: CC=1 No valid CA 7 commands were read from SYSIN. CC=2 No command output responses were received from CA 7. CC=8 Nonzero return code from CA 7 CAICCI interface module (CAL2X2W0). See message CAL2C596E. CC=9 Error attempting to GETMAIN storage. See message CAL2C594E. CC=10 Error attempting to LOAD a needed module. See message CAL2C595E. 16 Indicates a parameter list error: CC=1 Invalid parameter list. See message CAL2C590E. CC=2 Invalid parameter value. See message CAL2C591E. CC=3 Required DD statement missing or invalid. See message CAL2C592E. CC=4 DCB open error. See message CAL2W593E. Note: Usage of the SASSXXBT error message table may generate additional return code values. For more information about SASSXXBT, see the Systems Programmer 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 from those commands in a REXX environment. Program CAL2X2WA establishes the REXX CA 7 Address environment, and program CAL2X2WR processes the command handling. CA 7 provides a REXX example in the CAICLS0 installation library. The sample EXEC 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 command rslt = cal2x2wa() / / / ca7_node = 'xxxxxxxx' ca7_ssct = 'CA71' ca7_debug = 'N; ' / / /
address CA7 command say 'rc =' rc x = queued() say 'queued() =' x do i = 1 to x / Note that the parse function allows for mixed case parse pull line line2 = substr(line,2) / strip carriage control char say line2 end return
/ /
Note: The reserved value *AUTO* can be used for the ca7_node variable value to indicate that the CA 7 CCI interface should attempt to dynamically locate 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 be explicitly set with the XTMNAME= or RNAME= keywords of the SVCNO statement in the CA 7 initialization file. This allows each copy of CA 7 to be unique across a CAICCI network even though more than one may be production or test copies. Assignment of unique CAICCI receiver names allows the *AUTO* ca7_node variable to be used to dynamically target a specific copy of CA 7. For more information about instance names, see Usage Considerations on page 91.
CA-GSS REXX Address Environment Interface Execution

OPS/REXX (the REXX implementation used by CA OPS/MVS) uses CA-GSS to execute CA 7 commands and return the response lines to the external data queue (stack) of the OPS/REXX program that issues the ADDRESS CA7 command. CA 7 provides the following OPS/REXX EXEC in the CAICLS0 installation library. Copy this EXEC to a data set in your SYSEXEC concatenation. The sample 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 command say 'rc =' rc lines = queued() say 'queued() =' lines do i = 1 to lines parse pull line say line end return / / / / / / / / / / / / / / /
Note: The following statement should be added to the CA-GSS initialization parameters:
ADDRESS CA7 CAL2X2WR 15 TYPE
Also, the following variables can be customized as needed using the following CA-GSS initialization parameters:
GLOBVAL &CA7_NODE /xxxxxxxx/ GLOBVAL &CA7_SSCT /xxxx/ GLOBVAL &CA7_DEBUG /xxxx/ / / / CCI Node where CA 7 resides (default - local node) CA 7 instance name (CA71-CA78) / CA 7 CCI interface options / /
Address commands can be established for multiple copies of CA 7 in the same CA-GSS environment. For each copy, add an ADDRESS statement with a unique 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-GSS initialization statements.
ADDRESS CA7 CAL2X2W 15 TYPE ADDRESS CA72 CAL2X2W 15 TYPE GLOBVAL &CA7_NODE /xxxxxxx/ GLOBVAL &CA7_SSCT /xxxx/ GLOBVAL &CA7_DEBUG /xxxx/ GLOBVAL &CA72_NODE /yyyyyyyy/ GLOBVAL &CA72_SSCT /yyyy/ GLOBVAL &CA72_DEBUG /yyyy/ / / / / / / Node where primary CA 7 resides / Instance name for primary CA 7 / Optional Debug options / Node where second CA 7 resides / Instance name for second CA 7 / Optional Debug options /
Note: The reserved value *AUTO* can be used to indicate that the CA 7 CAICCI interface should attempt to dynamically locate the CAICCI node where a 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 slash if 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 be explicitly set with the XTMNAME= or RNAME= keywords of the SVCNO statement in the CA 7 initialization file. This allows each copy of CA 7 to be unique across a CAICCI network even though more than one may be production or test copies. Assignment of unique CAICCI receiver names allows the *AUTO* &CA7_NODE variable to be used to dynamically target a specific copy of CA 7. For more information about instance names, see Usage Considerations on page 91.
CA 7 CAICCI Program to Program Interface Execution

The CA 7 CAICCI Program-to-Program Interface (CAL2X2WP) can be called directly from another program. The calling program passes a string of CA 7 batch commands. CAL2X2WP interfaces with CA 7 and builds a buffer in storage that contains the command responses from CA 7. The calling program can then parse the responses and take other appropriate actions based on the results.
Call CAL2X2WP
To invoke the CA 7 CAICCI Program-to-Program Interface, the CA 7 load library must be available to the program being executed. A standard parameter list is passed in register 1. The format of the parameter list is: +0 Address of the CA 7 batch command string. If there is more than one command they must be separated by a command separator character. The default is semicolon (;). This parameter is required. +4 Length of the string of CA 7 batch commands. This parameter is required. +8 Address of an eight-byte field where the address and length of the CA 7 response buffer is placed. The first four bytes will contain the address, and the second four bytes will contain the length of the buffer. If the caller wants the response buffer to be in storage above the 16 MB line, the first byte of the 8-byte field should contain the value X'80'. Otherwise, the buffer storage is GETMAINed below the 16 MB line. This parameter is required. IT IS THE CALLER'S RESPONSIBLITY TO FREEMAIN THE RESPONSE BUFFER STORAGE. +12 Pointer to a 64-byte field that contains the CAICCI node name where the CA 7 address space executes. The default is the local node. This parameter is optional. Note: The reserved value *AUTO* can be used to indicate that the CA 7 CCI interface should attempt to dynamically locate the CAICCI node where a CA 7 with a matching CA 7 instance name resides.
+16 Pointer to the instance name of the CA 7 to communicate with. The value CA71 or PROD can be used to indicate the primary instance. The value CA72 or TEST can be used to indicate the secondary, or "test" instance. Other values include instance names CA73 through CA78 and a 1-4 character 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 of CA 7 can be explicitly set with the XTMNAME= or RNAME= keywords of the SVCNO statement in the CA 7 initialization file. This allows each copy of CA 7 to be unique across a CAICCI network even though more than one may be production or test copies. Assignment of unique CAICCI receiver names allows the *AUTO* CA-7 CAICCI node parameter to be used to dynamically target a specific copy of CA 7. +20 Pointer to a four-character Options field. The first character indicates whether diagnostic trace messages are to be generated (value of Y). The default is to not produce trace messages. The second character can specify the command string separator character. Any non-blank non-null character can be used as a command separator. The default separator is a semicolon (;). 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 lines received from CA 7 in response to the command string provided. If no responses were received from CA 7 because of an error, no response buffer is created, and the address/length field supplied by the caller is null. If an error was encountered after CAL2X2WP began receiving responses from CA 7, a response buffer is still created, and the address and length are set in the caller's address/length field. IT IS POSSIBLE TO RECEIVE A NONZERO RETURN CODE FROM CAL2X2WP AND STILL HAVE A RESPONSE BUFFER. CA 7 responses in the response buffer are fixed length records. Each record is 133 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 and begins with a carriage control character. It is the caller's responsibility to FREEMAIN the response buffer once it is no longer needed. The buffer is obtained from subpool 0. If the first byte of the caller's 8-byte address/length field contains X'80' on entry to CAL2X2WP, the response buffer is obtained from storage above the 16 MB line (LOC=ANY GETMAIN option). IT IS THE CALLER'S RESPONSIBLITY TO FREE THE RESPONSE BUFFER STORAGE.
CAL2X2WP Return Codes

On exit from module CAL2X2WP, the return code is in register 15, and the condition code is in register 0. The possible return and condition codes from CAL2X2WP are: 0 Indicates the CAL2X2WP program was able to successfully complete its functions without detecting an error. 4 Indicates no responses from CA 7 received. 8 Indicates a processing error: CC=9 Error attempting to GETMAIN storage. CC=10 Error attempting to LOAD a needed module. 12 Indicates error return from CAL2X2W0 (nonabend) CC= AL2(CAL2X2W0 rc),AL2(CAL2X2W0 cc) 16 Indicates parameter list error: CC=1 Invalid parameter list. CC=2 Invalid parameter value. 20 Indicates 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 LINK CLC BE L L LA DS CLC BE LA CR BL WTO B DS WTO B DC R1,X2WPPARM EP=CAL2X2WP R1 -> PARM LIST CALL CA 7 CCI PGM-PGM
LOOP
BUFFADR,=A( ) ANY CA 7 RESPONSES ? #UCC7RET NO - EXIT WITH RC R2,BUFFADR R2 -> RESPONSES R3,BUFFLEN R3 = BUFFER LENGTH R3, (R2,R3) R3 -> END OF RESPONSES H SPO7 , (R2) GOOD DEMAND RESPONSE ? GOOD YES - EXIT LOOP R2,133(,R2) R2 -> NEXT LINE R2,R3 REACHED END ? LOOP NO - CYCLE 'X2WPSAMP : JOB DEMAND NOT SUCCESSFUL ' #UCC7RET BRANCH TO PROGRAM EXIT H 'X2WOSAMP : JOB DEMANDED SUCCESSFULLY ' #UCC7RET BRANCH TO PROGRAM EXIT CL1 ' SPO7F A(CMDLIST) A(CMDLISTL) A(BUFFSET) X'8 ',AL3( ) D A( ) F' ' ' GOOD DEMAND MSG PREFIX CA 7 CCI IFACE PARM LIST ADDRESS OF COMMAND STRING LENGTH OF COMMAND STRING BUFFER ADDRESS/LENGTH FIELD END OF PARMLIST SPOT FOR BUFFER ADDR/LENGTH ADDR OF CA 7 RESPONSE BUFFER LENG OF CA 7 RESPONSE BUFFER
GOOD
SPO7
X2WPPARM DS DC DC DC DC BUFFSET BUFFADR BUFFLEN CMDLIST DS DC DC
DC DC DC CMDLISTL EQU END
C C'CA7=CA7n;' (REQUIRED IF INSTANCE NOT CA71) C'/LOGON USERX;DEMAND,JOB=TESTJOB;/LOGOFF' (L'CMDLIST) X2WPSAMP
Batch Card Load Program (BCLP)

The Batch Card Load program (BCLP) loads card-image data to sequential data sets required for CA 7 jobs. Through BCLP, sequential data sets may be created, replaced or modified. When BCLP is executed, CA 7 is notified by ICOM of successful data set manipulation through the communications data set. In this way, the database index entries are updated to reflect a new creation date and time.
Use BCLP
When BCLP is used, CA 7 is notified of successful data set manipulation. CA 7 then scans the request queue for jobs that use this data set as an input requirement. 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 of BCLP. 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 be marked as a maintenance job to prevent the posting of SMF records. To mark BCLP as a maintenance job, use the DB.1 panel that is defined in the Database Maintenance Guide or the #MNT special purpose override statement. For further information about the #MNT statement, see the chapter "JCL Management" in the Database Maintenance Guide. If the job is not marked as a maintenance job, then message SMF0-17 is issued (unless suppressed with SASSMSGS) and the type-99 record (DSN creation) is ignored. This could cause improper scheduling if the data set request included the SCHID keyword. BCLP dynamically allocates space required for each data set. This is accomplished by spooling card images to a work data set and calculating the number of disk tracks required to store the data. Generation data groups can be handled through BCLP; however, the following differences exist: Since new generation data set catalog maintenance is done at the time of creation, relative GDG numbers greater than +1 are not allowed. That is, if the user wishes to create three new GDG versions in one run, each must be referenced as +1. A model DSCB is not required. An attempt to catalog a generation that has already been dropped results in an error.
If BCLP terminates with an error, the completion code is the hexadecimal equivalent of the error message number. Error messages are listed in the Message 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 the CA 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 of one or more of the following parameters. If more than one is entered, they must be separated by commas. CA7=xxxx Indicates which instance of CA 7 BCLP communicates with, where xxxx is one of the following: an instance name from CA71 through CA78 a one- to four-character alias specified during CA 7 initialization with CAIRIM PROD, which defaults to CA71 TEST, which defaults to CA72
If CA7 is omitted, the default is CA71. EXITPROG=xxxxxxxx Describes the name of the user exit routine that is to receive control immediately 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 data statements pertaining to that data set only). If EXITPROG is omitted, SASSBCX1 is assumed. ERR=ABORT Indicates that whenever any error is detected, the run should be aborted with a dump. If this option is not specified, then a dump is not produced. DD Statements: The following DD statements are required: SYSPRINT Receives a listing of all statements read and any messages generated. SYSUDUMP Used for a dump under certain error conditions. UCC7IDS Specifies the index data set. See the DBPARMS DD discussion in the Systems Programmer Guide.
UCC7JLIB Specifies the job data set. See the DBPARMS DD discussion in the Systems Programmer Guide. UCC7DLIB Specifies the dataset data set. See the DBPARMS DD discussion in the Systems Programmer Guide. DBPARMS Used to define parameters in the database. See the Systems Programmer Guide for a description of this data set. The same values used in the UCC7DBASE statements when the database was last loaded must also be used here to ensure correct access to the database. UCC7WORK Allocates a work file that is to temporarily contain card images for a data set. Enough space must be allocated to contain the largest data set to be processed. U7xxxxxxxx One U7 statement must be present for each volume referred to by the VOL keyword, or used as a result of a catalog search. xxxxxx should match the VOL=SER of the DD statement. If it does not match, a warning message is generated. Volumes are located by VOL=SER, not by ddname. Note: Only one DD for nonspecific volume allocation is allowed. The name must be U7VOLSER and it should be the first U7 statement in the JCL. SYSIN Source of input control statements and data. BCLP JCL: The following is a sample of BCLP JCL with CA7 and EXITPROG PARMs.
//ST1 //STEPLIB //SYSPRINT //SYSUDUMP //UCC7IDS //UCC7JLIB //UCC7DLIB //DBPARMS //UCC7WORK // //U7VOLSER //U7111111 //U7222222 //U7333333 //SYSIN UCC7 statement1 UCC7 statement1 statement2 UCC7 EODS / EXEC DD DD DD DD DD DD DD DD PGM=SASSBCLP,PARM=('CA7=CA74,EXITPROG=PX1') DSN=cai.ca7.caiload,DISP=SHR SYSOUT=A SYSOUT=A DSN=user-defined-index-data-set,DISP=SHR DSN=user-defined-job-data-set,DISP=SHR DSN=user-defined-dataset-data-set,DISP=SHR DSN=user-defined-location-of-DBPARMS,DISP=SHR VOL=SER=111111,UNIT=SYSDA, DISP=(NEW,DELETE),SPACE=(TRK,(1 ,1 )) UNIT=SYSDA,SPACE=(TRK, ) VOL=SER=111111,UNIT=SYSDA,DISP=SHR VOL=SER=222222,UNIT=SYSDA,DISP=SHR VOL=SER=333333,UNIT=SYSDA,DISP=SHR
DD DD DD DD DD CREATE DSN=A.B.C,VOL=111111
REPLACE DSN=X.Y.Z,VOL=222222
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 and operation fields are separated by one or more blanks. The operation field and the first keyword parameter are separated by one or more blanks. Keyword operands 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 of each control statement, including continuation statements. Operation Field The operation field must be separated from the identifier by one or more blanks. If multiple statements are used for the same operation, the operation field must appear on the first statement. Keyword Parameters The operation field and the first keyword parameter are separated by one or more blanks. Keyword parameters can appear in any order. For a continuation, the last keyword on a statement to be continued must be followed by a comma. The next keyword parameter and its operand (with the exception of JOBS) must appear on the next statement. On continuation statements, the identifier (*UCC7) and the first keyword parameter must be separated by at least one blank. Comments Comments can be entered in two ways. A comment can be entered beyond the last keyword of a statement. It must be separated from the keyword and its operand by one or more blanks. If an entire statement is to contain comments, 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 UCC7 UCC7 UCC7 UCC7 UCC7 operation1 keyword1=x,keyword2=y operation2 keyword=x, THIS VALUE IS REQUIRED ON MONDAYS keyword=y,keyword=z, 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 of BCLP. If the OPTION statement is used, it must be first. If standard defaults are sufficient, you can omit this statement. Options specified in the statement can be 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 entries and input requirement posting, a data set completion message is generated. The LTERM keyword designates the logical terminal to receive the data set completion message. This message is generated when CA 7 has updated its database index entries and appropriate requirements are posted as satisfied. This action, and the associated message, are not produced 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 terminal name (STANIDS) in the CA 7 initialization file. If this keyword is omitted, MASTER is assumed. Default: MASTER MASTER Specifies the master terminal is to receive the data set completion message. xxxxxxxx Specifies the logical terminal name to receive the completion message. Limits: 1 to 8 alphanumeric characters
DETLIST (Optional) Specifies whether to produce a detail list of all statements entered. Default: YES YES Specifies a list of all statements is to be produced. NO Specifies only control statements and messages are to be listed. VOLROT (Optional) Indicates whether, on a specific volume request, an insufficient space condition results in a search of other volumes for the space. Default: NO NO Indicates an insufficient space condition resulting in an error. YES Specifies a search of U7xxxxxxxx volumes, in DD statement sequence, is made for sufficient data set space. Rotation begins with the first volume and proceeds as if it were a nonspecific request. REQSAT (Optional) Specifies whether a successful operation on a data set should result in either a requirement being satisfied or a job being triggered. Default: YES YES Indicates that CA 7 is notified of the successful operation with a type-99 record generated by BCLP. NO Indicates that the operation is performed but a type-99 record is not generated 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 data sets or for a single data set. Default: 3120 Limits: 2 to 5 numeric characters from 80 to 32720 3120 Specifies the block size of 3120. nnnnn Specifies the block size. The block size specified must be divisible by 80 and cannot be larger than the track size of the receiving device or 32720, whichever is smaller. EXITPROG (Optional) Designates the name of the user exit routine to receive control after 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 control statements (except OPTION) and data statements (specified on the OPTION statement), or only for the data statements of a specific data set request. The various options available to the exit program are discussed in the Systems Programmer Guide. Default: SASSBCX1 Limits: 1 to 8 alphanumeric characters SASSBCX1 If EXITPROG keyword is omitted (and is not present in the PARM information about the EXEC statement), SASSBCX1 is the default. xxxxxxxx Specifies the name of the user exit routine.
MAXJOBS (Optional) Specifies the maximum number of job names to appear in any JOBS parameter on a data set request statement. If a data set request is encountered that contains more job names than the maximum, the data set request is bypassed. Default: 10 Limits: 1 to 3 numeric characters from 1 to 255 10 Specifies ten job names are to appear in JOBS parameter on a data set request statement. nnn Specifies the number of job names to appear in JOBS parameter on a data set request statement. SCHID (Optional) Specifies which schedule ID created the data set. This can be done on a data set basis or for the whole job. Default: 1 Limits: 1 to 3 numeric characters from 1 to 255 1 Specifies the default schedule ID to be associated with each data set. nnn Specifies the schedule ID to be associated with each data set. CVOL (Optional) Specifies the volume containing the system catalog to be searched and/or updated. This keyword is required only if a proper index structure has not been established for a data set. Default: SYSRES Limits: 1 to 6 alphanumeric characters SYSRES Specifies the system resident device as the volume containing the system catalog. xxxxxx Specifies 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 a data set. A data set statement always immediately precedes the first data statement for the data set being acted on. These statements have the following format: UCC7CREATE,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
CREATE Creates 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 volume pointed 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 data set is not scratched. If VOLROT=YES is specified and the data set is found during volume rotation, an error occurs and the data set request is bypassed. REPLACE Replaces an existing data set. The data set specified in the DSN keyword must exist on the volume pointed to by the catalog, or if VOL has been specified, on that volume. If VOLROT=YES was specified and there is not enough space on the volume originally containing the data set, another volume is assigned and the catalog is updated. MODDATA Adds data to an existing data set if it exists, or creates a new data set if it does not exist. If the data set does exist, the keyword VOLROT has no meaning. When creating a new data set, the rules described under the CREATE option apply.
DSN Describes the name of the data set operated on. The name must be a valid OS 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 defined in the CA 7 database. Limits: 1 to 44 alphanumeric characters BLKSIZE (Optional) Describes the output block size to be used for this data set. The rules for BLKSIZE are described in the BLKSIZE keyword of the OPTION Statement on page 111. CATALOG (Optional) Indicates whether the data set is to be cataloged after a successful operation. Default: NO NO Specifies that the system catalog is not modified. YES Specifies that the data set is to be cataloged. May also be used to catalog a data set being created, replaced, or modified. DETLIST (Optional) Specifies whether a detail list of all statements entered is to be produced. Default: YES YES Specifies a detail list of all statements entered is to be produced. NO Specifies that only control statements and messages are to be listed. JOBS (Optional) Indicates that a data set request is to occur only if the specified job or jobs have run since the last data set update. A maximum of ten jobs can be entered with this keyword unless MAXJOBS has been entered on the OPTION statement to increase the maximum number. If more than one job is entered, the group of job names must be enclosed in parentheses. The JOBS keyword is the only keyword whose operand can be continued. If continued, 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 right parenthesis must appear immediately after the last job name. Limits: 1 to 8 alphanumeric characters
LTERM (Optional) Overrides the default logical terminal and follows the rules described in the LTERM keyword of the OPTION Statement on page 111. If present, this keyword overrides the default only for this data set. Limits: 1 to 8 alphanumeric characters REQSAT (Optional) Described in the OPTION statement. If present, it overrides the default only for this data set. SCHID (Optional) Specifies which schedule ID created the data set. It overrides the default schedule ID. SCHID is described in the OPTION Statement on page 111. VOL (Optional) Indicates the volume to be used for this data set. The keyword overrides the catalog if the data set is cataloged. If a volume is entered it must be described with a U7xxxxxxxx DD statement. If VOLROT=YES is specified and there is insufficient space on the volume, another volume is chosen. If VOLROT=NO or is defaulted, an insufficient space condition results in an error. Specific Requests. If VOL is not specified, the system catalog is searched in an attempt to locate the data set. If the data set is located both in the system catalog and on the volume pointed to by the system catalog, the data set is replaced or added to on the volume. If a data set is not found for a 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 added to the data set. If the data set is not found for a MODDATA, the data set is created. Nonspecific Requests. If a CREATE request is encountered or if a MODDATA data set is not found, and the VOL parameter is not present, the data set is assigned to the first U7xxxxxxxx volume. If there is insufficient space on that volume, an attempt is made to obtain space on subsequent volumes. Volumes are assigned in the same sequence as their respective DD statements in the job stream. Note: For nonspecific requests, the U7xxxxxxxx JCL statements must have a volume specified or the first U7xxxxxxxx must be named U7VOLSER. 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 program specified here is used only for data statements and the EODS control statement 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 set request. If the EODS statement is omitted, an EODS is generated if another control statement is encountered. If EODS is entered, it must be followed by another 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 a given job.
Control Statement Examples

Example 1: Create data set A on volume 111111. The data set is an input requirement for JOB Z. The data set is to be cataloged after creation. The BCLP control statements would appear as follows. UCC7 CREATE statement1 statement2 UCC7 EODS DSN=A,VOL=111111,CATALOG=YES
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 run since the last creation (see the JOBS description for restrictions discussed earlier in this chapter). UCC7 CREATE UCC7 JOBS=Z statement1 statement2 UCC7 EODS DSN=A,VOL=111111,CATALOG=YES,
Example 3: Replace cataloged data set A. UCC7 REPLACE statement3 statement4 statement5 DSN=A
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 a U7xxxxxxxx DD statement.
Example 4: Add data to the end of a cataloged data set B. JOBS X, Y, and Z must have run since the last update of data set B (see the JOBS description for restrictions discussed earlier in this chapter). UCC7 MODDATA statement M statement N . . . . statement Z UCC7 EODS DSN=B,JOBS=(X,Y,Z)
Note: If data set B does not exist on the volume, the MODDATA is changed to CREATE. The volume on which the data set does (or will) exist must be defined by a U7xxxxxxxx DD statement. Example 5: Replace data set C. Data set C is not presently cataloged, but is to be cataloged after this run. UCC7 REPLACE statement A statement B statement C DSN=C,VOL=111111,CATALOG=YES
Note: Volume 111111 must be defined with a U7xxxxxxxx DD statement.
Chapter 4. CA Driver Procedures, Variable Parameters, and Functions

This section contains the following topics: Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . JCL Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure Library Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conditional Procedure Expansion . . . . . . . . . . . . . . . Comments Inside CA Driver Procedures . . . . . . . . . . . Use CA Driver in the CA 7 Environment -- Some Examples
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
123 124 125 130 147 153 161 162
This section describes how to store JCL, variables, and data in the CA Driver procedure 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 the procedures are retrieved Use CA Driver functions Conditionally expand procedures based on logic or variables in the procedure.
CA Driver is activated when the //CARPROC DD statement is added to the CA 7 execution JCL. CA 7 calls CA Driver for each statement in a job at the job's submission time. For CPU jobs, CA Driver scans the JCL statements looking for either of the following control statements embedded in the job stream.
// EXEC procname or // EXEC PROC=procname
For XPJOB jobs, CA 7 scans the parameters looking for DPROC=name and changes 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 CA Driver procedure libraries looking for a matching procname (procedure name). If that procedure name is found in a procedure library, CA Driver expands the procedure and passes back a set of expanded statements to the job stream one statement at a time instead of passing back the // EXEC procname or // EXEC PROC=procname or DPROC= statement. If the procedure name is NOT found in a CA Driver procedure library, the statement is passed back to the job stream unchanged. Thus, CA Driver procedure calls can be embedded anywhere in the job stream. If the DPROC= statement is returned for an XPJOB job, this produces a JCL error status for the job, forcing it back to the request queue. The allocation of CA Driver procedure libraries is normally determined by the CARPROC DD statement. However, this allocation can be altered in any defined CA 7 JCL or PARM library. If the definition of the CA 7 JCL or PARM library includes a reference to a CA Driver procedure library, that procedure library is searched prior to the libraries in the CARPROC concatenation when CA Driver is invoked for statements from that library. For more information about associating a CA Driver procedure library with a CA 7 JCL or PARM library, see the discussion of the DPROC keyword on the JCL initialization file statement in the Systems Programmer Guide or the discussion of the DPROC keyword 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, the exit receives the statements after they have been manipulated by CA Driver. If the user exit inserts or modifies statements, the changed statements are not inspected by CA Driver. If the SASSXX05 user exit is being used, it receives the statements as the job enters the queues (prior to submission). Therefore, any statements inserted or changed are available to CA Driver. All scheduled overrides (such as #JI and #XO) are applied prior to CA Driver 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 (//name DPROC variables), but then include PARMnn keywords that will be inserted in the data transmitted to the destination scheduling agent. All references to CA Driver specific statements are coded as if they would be used in a CPU job. For example, the // DNEST procname would be used to call another CA Driver procedure. Although XPJOB job data is case sensitive, all CA Driver keywords must be specified in uppercase only. For XPJOB jobs, an alternative to CA Driver Procedures would be to use the Global Variable features, which allow variable substitution directly into the parameter data.
JCL Verification
JCL Verification
The CA 7 interface with CA Driver is invoked at job submission time. It is also invoked when the LJCK command is issued, and for CPU jobs, when certain CA 7 editor subcommands are used (any JCLxx command). Default CA 7 variable values vary depending on the command environment. For example, the value of &C_L2JN will be the job name defined in the CA 7 database if evaluated in LJCK processing. If CA Driver is invoked using the JCLL editor subcommand for a CPU job, the value of &C_L2JN is the character string UNKNOWN because the job name is unavailable when the command is entered. Use these commands to verify that CA Driver is modifying the statements appropriately. For information about the LJCK command, see the Command Reference Guide. You can find details on the use of JCLL and other CA 7 editor subcommands in the "Edit Facility" chapter of the Database Maintenance 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 DPROC statement as the first statement in the procedure. The contents of the procedure consist of all the statements following the DPROC statement. When a procedure is called (retrieved from the library), CA Driver replaces the calling statement with the contents of the procedure. Give the name of the procedure immediately following the slashes on the DPROC 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, use a standard OS EXEC statement and specify the name of the procedure after PROC=.
//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 //LIST1 //VOL //SYSPRINT //SYSIN //CALL // JOB ,JOHN.DOE,CLASS=A EXEC PQM=IEHLIST DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR DD SYSOUT=V DD EXEC PROC=LVTOC
Procedure Library
CA Driver replaces the EXEC statement with the contents of the procedure and submits this expanded job stream to JES for execution.
//LIST //LIST1 //VOL //SYSPRINT //SYSIN LISTVTOC // JOB ,JOHN.DOS,CLASS=A EXEC PGM=IEHLIST DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR DD SYSOUT=V DD VOL=339 =VSIAUX,FORMAT
Note the following about this expansion process: Any EXEC statements that are part of the contents of a procedure are included in the expanded job stream that is submitted to JES. For CPU jobs, if there is no member of the CA Driver procedure library by the name specified on the EXEC statement, the search passes to the OS procedure library. (This is what would happen if the EXEC statement misspelled LVTOC as LVTIC.) If CA Driver detects any error conditions during its expansion, a DERR statement with an appropriate error message passes to JES. This is then flagged as an invalid statement by JES and displayed on the SYSLOG listing. For XPJOB jobs, if there is no member of the CA Driver procedure library by the name specified, the DPROC keyword is returned and the XPJOB will fail with a JCL error. Because you cannot correct errors to the output data stream, use the command LJCK to resolve any errors before allowing the XPJOB job to execute in a production stream.
Nest Procedures
One procedure can call another procedure, which can, in turn, call other procedures. Each time a procedure calls another procedure, this is counted as a nesting level. When the first procedure is retrieved, any procedures nested in it 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 be retrieved, as needed, by nesting them in other procedures. If one of these separate procedures needs modification, you only need to make the changes to that one procedure. When the procedure is called by another procedure, the updated version is automatically retrieved; so the expanded job stream reflects all changes. Use a DNEST statement to introduce each nested procedure.
// DNEST procname
Procedure Library
This sample shows both the LVTOC procedure and the LVTOCS procedure that is nested in the LVTOC procedure.
//LVTOC //LIST1 //VOL //SYSPRINT //SYSIN // //LVTOCS LISTVTOC DPROC EXEC PGM=IEHLIST DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR DD SYSOUT=V DD DNEST LVTOCS DPROC VOL=339 =VSIAUX,FORMAT
When the LVTOC procedure is retrieved, it calls the LVTOCS procedure that is nested in it. Therefore, this sample job stream calls both procedures.
//LIST //CALL // JOB ,JOHN.DOS,CLASS=A EXEC PROC=LVTOC
The EXEC statement is replaced by the contents of both procedures and this job stream is submitted to JES for execution.
//LIST //LIST1 //VOL //SYSPRINT //SYSIN LISTVTOC // JOB ,JOHN.DOE,CLASS=A EXEC PGM=IEHLIST DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR DD SYSOUT=V DD 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 is run 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 at which you want expansion to stop.
// DATA
CA Driver will replace the DATA statement with the statements that follow the EXEC statement in the input job stream. When CA Driver reaches a DEND statement, it returns to the procedure and continues expansion. For example, we could have designed procedure LVTOC so that the LISTVTOC statement is submitted from the job stream rather than from within the procedure itself. Instead of including LISTVTOC in the procedure, we use the DATA statement at the same point.
//LVTOC //LIST1 //VOL //SYSPRINT //SYSIN // DPROC EXEC PGM=IEHLIST DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR DD SYSOUT=V DD DATA
Then we include the LISTVTOC statement on the input job stream followed by a DEND statement.
//LIST //CALL LISTVTOC // // JOB ,JOHN.DOE,CLASS=A EXEC PROC=LVTOC VOL=339 =VSIAUX,FORMAT DEND
When the procedure is expanded, the LISTVTOC statement replaces the DATA statement. You can use any number of DATA statements in a procedure. Each DATA statement directs CA Driver back to the job stream until a DEND statement is found. Therefore, if a job procedure contains three DATA statements, the job stream submitted for processing must contain three DEND statements. Variable parameters must be within the DPROC and cannot be within the statements that the DATA and DEND include.
Procedure Library
Verify Data Inclusion

To ensure that the correct data is inserted into the expanded procedure at the appropriate places, you can use a verification name on each DATA statement and the same name on the DEND statement that terminates that data.
// // DATA DEND LVTOCX LVTOCX
If the name on the DATA statement and the name on the DEND statement are not the same, CA Driver flags the condition as an error. The verification name must be one- to eight-alphanumeric characters, beginning with an alpha character, and does not have to relate to the name of the procedure. This example shows the same procedure with a data verification name.
//LVTOC //LIST1 //VOL //SYSPRINT //SYSIN // DPROC EXEC DD DD DD DATA PGM=IEHLIST UNIT=SYSDA,VOL=SER,VSIAUX,DISP=SHR SYSOUT=V LVTOCX
The same verification name is coded on the DEND statement that signals the end of the data inclusion statements.
//LIST //CALL LISTVTOC // // JOB ,JOHN.DOE,CLASS=A EXEC PROC=LVTOC 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 is created. When the procedure is expanded, each parameter is replaced by its default value or by a value on the EXEC or DPROC statement that calls the procedure. (If no default value is defined, a value must be supplied on the EXEC or DPROC statement or on a DSET statement.) To use these symbolic parameters, list them on the //DPROC statement when the procedure is created, with or without a default value. (For specific coding requirements, see Code Variable Parameters on page 132.)
//procname DPROC parmname=value,parmname=value,...
Then precede them with an ampersand (&) whenever they are referenced in the body of the procedure. When the procedure is expanded, CA Driver replaces each occurrence of the parameter with: The value supplied on the EXEC or DPROC statement or on a DSET statement. 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 a default value.
//LVTOC //LIST1 //VOL //SYSPRINT //SYSIN LISTVTOC DPROC VOL=339 ,ID=VSIAUX EXEC PGM=IEHLIST DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR DD SYSOUT=V DD DD 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 in place of &VOL and &ID.
//LIST1 //VOL //SYSPRINT //SYSIN LISTVTOC // EXEC PGM=IEHLIST DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR DD SYSOUT=V DD 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 //VOL //SYSPRINT //SYSIN LISTVTOC // EXEC PGM=IEHLIST DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR DD SYSOUT=V DD VOL=338 =VSIAUX,FORMAT
Variable Parameters
Code Variable Parameters

Up to 64 variable parameters can be defined for each procedure. Each parameter must be named on the //DPROC statement when the procedure is defined. 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, we recommend that you do not use the underscore character in a variable name defined on the //DPROC statement so that you avoid conflicts with reserved-name variable parameters.
Define Default Values

A default value of up to 64 characters can be optionally defined for each parameter: If the value contains any blanks or special characters, it must be enclosed in 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 //LVTOC //LVTOC //LVTOC DPROC DRPOC DPROC DPROC VAR1=YES VAR2='A B C' VAR3=/JOHN'S/ VAR4=
In the first example, the default value for VAR1 is YES. Since this consists only of alphanumeric characters, no quotes or other delimiters are needed. In the second example, VAR2 has a default value of A B C. Since this contains spaces, 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 a quote, a special character other than a quote must be used as a delimiter. In this example, a slash (/) is used. In the fourth example, no default value is defined.
Variable Parameters
Supply Values On The EXEC Statement

If no default value is defined on the procedure, a value for the parameter must be given on the calling EXEC or DPROC statement. (If values are given in both places, the value on the EXEC or DPROC statement overrides the defined default value.) Values supplied on the calling EXEC or DPROC statement are coded the same way as default values: If the value contains other than alphanumeric characters, delimiters are required. 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 by commas. For CPU jobs to continue an EXEC statement to the next line, end the first line with a completed parameter, including the separation comma. Code the second line with slashes in columns 1 and 2, and the additional parameters beginning in column 16 or before. For XPJOB jobs to continue the statement with additional variables, end the first line with a completed parameter, including the separation comma. Code the second line with the variable name starting in column 1. Note, the line being continued does not need to have a plus (+) sign on the end. If you desire to put a plus sign, leave at least one space between the command and the plus (+) sign. Examples:
//CALL //CALL // EXEC PROC=LVTOC,VAR1=NO,VAR2='D E F',VAR3=/MARY'S/
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 value is not specified on the DPROC or EXEC statements, it can be specified on the DSET statement. You can test for an omitted variable value with the Type test of 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 the body of the procedure. (Never use an ampersand on the DPROC or EXEC statements.) It is the ampersand that signals CA Driver to replace the variable parameter with a value. For example, assume the default value FILE has been defined for the variable parameter VAR1.
This statement in the procedure //&VAR1 //SYSUT1 DD DD DSN=DATA.SET DSN=DATA.&VAR1 will be expanded as: //FILE //SYSUT1 DD DD DSN=DATA.SET 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 is to be followed by a period after replacement, it must appear in the procedure followed by two periods. For example:
This statement in the procedure //SYSUT1 //SYSUT1 DD DD DSN=&VAR1.DATA DSN=&VAR1..DATA will be expanded as: //SYSUT1 //SYSUT1 DD DD DSN=FILEDATA DSN=FILE.DATA
A variable parameter is NOT preceded by an ampersand when it is the object of a DSET statement (that is, a value is being assigned to it), or the FIRST object of a DIF statement.
// // // // DSET VAR1=&VAR2 DSET VAR1=VAR2 DIF VAR1 EQ &VAR2 GOTO STEP DIF VAR1 EQ VAR2 GOTO STEP will will will will assign VAR1 the contents of VAR2 assign VAR1 the string 'VAR2' compare the contents of VAR1 and VAR2 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 nested procedure. To do this, the variable parameter must be defined in each procedure using either the same parameter name or different parameter names. For example, a nested procedure being passed a parameter from a calling procedure could be created as:
//LVTOC DPROC VAR1=YES . . . DNEST LVTOCS,VAR2=&VAR1 DPROC VAR2=
// //LVTOCS
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 be shorter or longer than the parameter name. CA Driver shifts the character string during 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), the character string will be shifted left the number of bytes that the replacement character string is shorter than the variable parameter. This shift will continue until a string of two or more spaces is encountered, at which point the shift will terminate. As a result, these spaces will be increased by the number of bytes that the variable parameter exceeds the replacement character string. If the replacement character string is longer than the variable parameter, all following bytes will be shifted right by the number of bytes that the replacement character string is longer than the variable parameter. This shift will continue until a string 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 string of spaces is not available, an error message will be issued and the procedure expansion will terminate. Two or more character strings can also be shifted right if the number of spaces between them is sufficient to contain the number of characters shifted and still leave one space.
In these examples, the variable parameter &F has a replacement value of FILE and &DATASET has a replacement value of DSN.
Original Expanded Original Expanded Original Expanded stmt: stmt: stmt: stmt: stmt: stmt: //&F //FILE //INP //INP //INP //INP DD DD DD DD DD DD DSN=PAYROLL.MASTER COMMENT DSN=PAYROLL.MASTER COMMENT DSN=&DATASET..XYZ COMMENT DSN=DSN.XYZ COMMENT DSN=MASTER.&F..INPUT COMMENT DSN=MASTER.FILE.INPUT COMMENT
Note: We do not recommend the use of sequence numbers or extraneous data 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 can reference anywhere that a variable parameter can be referenced in a CA Driver procedure. Values are automatically assigned by CA Driver when the reserved-name variable parameter is referenced during procedure expansion. These reserved-name variable parameters cannot be defined in a DPROC statement, and assigned values cannot be changed using the DSET statement. All reserved-name variable parameters begin with &C_ to avoid conflicts with variable 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_DATE Indicates the current system date in mm/dd/yy format. &C_DAY Indicates the current day of the week (MONDAY, TUESDAY, ...). &C_JDATE Indicates the current system Julian date in yyddd format. &C_L2CA7 Indicates the CA 7 instance name. &C_L2SMF Indicates the SMF ID of the LPAR where CA 7 is executing. &C_L27RL Indicates the CA 7 release. &C_MONTH Indicates the current month name (JANUARY, FEBRUARY, ...). &C_TIME Indicates the current system time in hhmmss format. Example This example procedure uses four of the CA Driver reserved-name variable parameters.
//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 referenced through the use of the following variables: &C_L2JN Indicates the name of CA 7 scheduled job. &C_L2UID Indicates the UID of CA 7 scheduled job. &C_L2MID Indicates the MAINID value for CA 7 scheduled job. This variable is not applicable to XPJOB jobs. &C_L2SN Indicates the SYSTEM name of CA 7 scheduled job. &C_L2QN Indicates 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_L2LT Indicates the LTERM value for CA 7 scheduled job. Value is the job name on LJCL displays. &C_L2RO Indicates the RO value for job level COND-CODE test. &C_L2CC Indicates the value for job level COND-CODE test. &C_L2PRY Indicates the PRIORITY value for CA 7 scheduled job as defined on the job definition panel. &C_L2CLS Indicates the CLASS value for CA 7 scheduled job as defined on the job definition panel. &C_L2SID Indicates the SCHEDULE-ID value for CA 7 scheduled job. Value supplied from SCHID keyword on LJCK displays.
Variable Parameters
&C_L2#T1 Indicates the number of TAPE1 tape drives for CA 7 scheduled job as defined on the job definition panel. This variable is not applicable to XPJOB jobs. &C_L2#T2 Indicates the number of TAPE2 tape drives for CA 7 scheduled job as defined on the job definition panel. This variable is not applicable to XPJOB jobs. &C_L2EM Indicates the entry mode for CA 7 scheduled job, such as DEMAND or RUN. Value is SSCAN on LJCK displays. &C_L2DOD Indicates the due-out date for CA 7 scheduled job (YYDDD). &C_L2DOT Indicates the due-out time for CA 7 scheduled job (HHMM). &C_L2DLD Indicates the deadline date for CA 7 scheduled job (YYDDD). &C_L2DLT Indicates the deadline time for CA 7 scheduled job (HHMM). Note: All values for the CA 7 reserved-name variables are derived from JQREC for the CA 7 submitted job, unless CA Driver is invoked from LJCK in which case some values are determined from database information. Example: This example illustrates the use of CA 7 reserved-name variable parameters.
//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 and used 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 the entire value. To do this, specify two numbers in parentheses following the parameter name.
&parmname(n,m)
n Is the location within the value of the start of the substring. m Is the length of the substring (one or more bytes). These examples show how the two numbers identify the substring that is being referenced. Parameter &VAR1 &VAR1 Value HOWDY 89 Substring Reference &VAR1(1,2) &VAR1(2,1) Substring Value HO 9
Substrings can also be identified by variable parameters that represent numbers. This is illustrated below. Parameter &VAR2 &VAR3 &VAR4 Value 4 2 12/31/07 &VAR4(&VAR2,&VAR3) 31 Substring Reference Substring Value
Variable Parameters
These sample control statements show how procedure expansion can be based on the contents of a substring, rather than on the entire parameter value: This control statement // DIF C_DATE(1,2) NE 01 GOTO MONTHERR // DIF C_DATE(3,1) NE '/' GOTO ERROR // DSET VAR1=&C_DATE(7,2) // DIF VAR1(&VAR2,&VAR3) EQ 9 GOTO OK1 References a substring to Test only the month portion of the date value (1st and 2nd positions) Check for a slash in the date (3rd position) Set VAR1 equal to year portion of date value (7th and 8th positions) Test only part of VAR1 (VAR2 and VAR3 represent numbers)
Variable Parameters
Arrays
A variable parameter can be assigned multiple values or array elements. To indicate that a parameter has an array of values, give the total number of values in parentheses following the parameter name on the DPROC statement. For example, VAR(4) indicates that a parameter has four values. When this procedure is expanded, each of these four values can be individually referenced as: &VAR(1) &VAR(2) &VAR(3) &VAR(4) To define default values for any of these elements, specify the values in parentheses separated by commas in the order of the array elements. To omit a 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 of which have default values. A parameter named Y, which consists of three elements in an array, each of 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 the third of which has a default value (TESTJOB).
To supply array values on the calling EXEC statement, list the values, enclosed in parentheses and separated with commas. To omit a value, code a comma in place of the value.
//CALL EXEC PROC=LVTOC,VAR=(A,B,,D,,F)
This statement retrieves the LVTOC procedure and supplies override values for the first, second, fourth, and sixth array elements of the VAR parameter. The third and fifth elements would retain their default values. (These default values must be defined when the procedure is created.)
Variable Parameters
Null Values
You must supply a value for every variable parameter listed on the DPROC statement or else the procedure cannot be expanded. However, this value can be a null value. A null value can be used either as the default value when the procedure is created or as the override value when the procedure is called. To specify a null value on either the DPROC or EXEC statement, code two delimiters with nothing in between.
//CALL EXEC PROC=LVTOC,Y=(1,2,'',4)
This example supplies override values for array elements one through four of the Y parameter. The value for the third element is a null value. (If the default value were really supposed to be two apostrophes, you could use slashes as the delimiters: /''/). If &Y(3) is referenced in the procedure, it will be replaced with nothing; in other words, the statement will be expanded as though the parameter reference were not there. The same thing would happen if the default value is a null value and no override is supplied. For example, assume that the parameter Y was defined with a null default value. No override value is supplied when the procedure is called. When the procedure is expanded, each occurrence of Y is replaced with a null character string; therefore, Y is effectively removed from the expanded statement as these examples show.
This statement in the procedure: //SYSUT1 //SYSUT1 DD DD DSN=&Y.FILE.DATA DSN=FILE&Y will be expanded like this: //SYSUT1 //SYSUT1 DD DD DSN=FILE.DATA DSN=FILE
A null value is different from having no value associated with a variable parameter. If a parameter has no default or override value, an error message is issued indicating that the procedure cannot be expanded.
Variable Parameters
Attributes of Variables
Every variable parameter has two attributes: type and length. Variable parameter arrays also have a third attribute: number. Each of these attributes can be tested during conditional expansion using the following format: To test for Type Length Number Specify T'parmname L'parmname N'parmname
The Type Attribute

Variable parameters (or parameter array elements) fall into one of four categories, depending on the type of value that replaces them when the procedure is expanded. (The type is determined by the actual replacement value, not by the defined value or how the value was stated.) If the replacement value is A character format A positive integer A negative integer Omitted (not the same as a null value) The type is C N M O
Test the Type Attribute

To test a variable parameter for type, prefix it with T'.
// // DIF DIF T'VAR1 EQ C GOTO CHARVALU T'VAR2 EQ N GOTO ISNUMERC
Since variable parameters that are used in array indexing and segment subscripting must be positive integers (type N), it is a good idea to test the type attribute 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 number of bytes in the replacement value. If the replacement value is CA Driver X 0049 (null) 27 The length is 9 1 4 0 2
Test the Length Attribute

To test a variable parameter for length, prefix it with L'.
// // DIF DIF L'VAR3 EQ GOTO NOVALUE L'VAR4 GT 4 GOTO TOOLARGE (zero length - null value)
Variable Parameters
The Number Attribute

The number attribute gives the number of elements in a variable parameter array that have values assigned to them, regardless of whether the value was assigned by default or on the DPROC statement. For example, assume the procedure 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, the number attribute of the parameter Q is 4, since four of the eight array elements have default values. If it is retrieved with an EXEC statement that supplies two additional 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 DIF N'VAR6 N'VAR7 LT 1 GOTO NOVALUES EQ 5 GOTO DONEALL
Functions
Functions
CA Driver also recognizes a set of predefined functions. A CA Driver function has a reserved name and accepts one or more parameters. The general format of a function is:
function(parameter1,parameter2,..)
Function parameters can be absolute constants or can be coded as variable parameters containing valid values that the function expects. In either case, parameters values must be in valid format and must follow the order required by the function. CA Driver functions are recognized on the right side of the DSET statement. To set 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 result in variable VAR1. (All month-end and leap-year adjustment is automatically handled by the DTADD function.) The primary value of these functions is that they can be used to automate your JCL setup. By encoding the functions in your CA Driver procedures, you eliminate the need for JCL staging and manual manipulation. Because all of the functions have parameters that accept or default to CA Driver variable parameters, the power of the functions and the variable parameters can be combined. The functions perform more than simple arithmetic operations because they take into account transitions between months, years, and periods so that they return the expected values.
Functions
CA Driver Functions
Arithmetic Date Functions
CA Driver offers the following arithmetic date functions. CA Driver automatically handles all leap-year, month-end, and year-end adjustments. Function and Parameters DTADD(n,&var) Explanation Adds "n" to variable "&var." The variable &var must contain a valid Julian date in the yyddd format. n represents a number of days to be added to &var and can be a positive numeric constant or a variable containing 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 a valid Julian date in the yyddd format. n represents a number of days to be subtracted from &var and can be a positive numeric constant or a variable 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 &var1 and &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 valid Julian date in the yyddd format. n represents a number of months to be added to &var and can be a positive numeric constant or a variable containing 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 a valid Julian date in the yyddd format. n represents a number of months to be subtracted from &var and can be a positive numeric constant or a variable 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. Function and Parameters DMY(&var) Explanation Converts variable "&var" into ddmmyy format. The variable &var must contain 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 must contain 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 must contain 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 &var must 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 &var must 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 &var must 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 must contain 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 must contain 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 must contain a valid Julian date in the yyddd format. Example: If &C_JDATE=07032, YM3D(&C_JDATE)=07FEB01
Functions
Function and Parameters DM3YR(&var)
Explanation Converts variable "&var" into ddmonccyy format. The variable &var must 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 &var must 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 &var must 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 Julian date 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 Julian date in the yyddd format. Example: If &C_JDATE=07032, MONTH(&C_JDATE)=FEBRUARY
MON(&var)
Converts variable "&var" into a three character abbreviation of the month name (JAN, FEB, and so on). The variable &var must contain a valid 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 day of the week name (SUN, MON, and so on). The variable &var must contain 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). The variable &var must contain a valid Julian date in the yyddd format. Example: If &C_JDATE=07032, DOW#(&C_JDATE)=02
Functions
Function and Parameters WOM(&var)
Explanation 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 the yyddd 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 the yyddd 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 the yyddd 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 the yyddd 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 functions return dates or portions of dates by counting a specified number of days forward from the beginning of months or backwards from the end of months. All leap-year, month end, and year end adjustments are automatically handled by CA Driver. The functions are useful for coding procedures that require a date that is always a certain number of days from the beginning or end of the month such as a billing date that is constantly on the 10th day of the month. Function and Parameters LDOM(n,yyddd) Explanation Returns the day-of-month number by counting n days backwards from the end of the month of the Julian date (yyddd) specified. Counting begins at 1 on the last day of the month. (n=1 returns the last day of the 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)=30 Example 2: LDOM(2,07045)=27 JDOM(n,yyddd) Returns a Julian date by counting n days from the beginning of the month of the the Julian date (yyddd) specified. Counting begins at 1 on the first day of the month. (n=1 returns a Julian date representing the first 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)=07002 Example 2: JDOM(2,07045)=07033 LJDOM(n,yyddd) Returns a Julian date by counting n days backward from the end of the month of the Julian date (yyddd) specified. Counting begins at 1 on the last day of the month. (n=1 returns a Julian date representing the last 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: LJDOM(2,07025)=07030 Example 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 the procedure. Branch forward or backward within a procedure, based on variable parameter values supplied on the EXEC statement.
These commands are available to program conditional procedure expansion. To Assign a name to a control statement Branch to a step Define conditions for branching Set variable parameters Control looping Flush all calling procedures Abort current procedure Use this command DSTEP DGOTO DIF DSET DLCTR DFLUSH DABORT
Code the commands in control statements like the following:

//name command operands
Where name is an optional user-defined value given to a control statement so that 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 a control statement allows you to branch to that statement from a DIF or DGOTO statement.
//name DSTEP
Names can be one to eight alphanumeric characters. A maximum of 256 names can be defined in each procedure.
Examples
//ONE //DAILYRUN //STEP1 //1 DSTEP DSTEP DSTEP DSTEP
Branch (DGOTO)
Use the DGOTO command to stop procedure expansion, branch forward or backward to another control statement, and continue expansion at that point.
//name1 DGOTO name2
Examples
//name //name //name //name DGOTO DGOTO DGOTO DGOTO ONE DAILYRUN STEP1 1
The following example demonstrates how to use DSTEP and DGOTO statements 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 RESTART that 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 RESTART parameter 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 step selection stop at any specified step name as well as start at any specified step name.
Define Conditions (DIF)

Use the DIF command for conditional forward and backward branching. Code the DIF control statement in this format, supplying the values shown in the chart below.
//name1 DIF parmname operator value GOTO name2
Note: Do not confuse the DGOTO statement with the GOTO clause of the DIF statement. At this point name1 parmname operator Specify this value An optional name for this control statement that allows it to be referenced in other DIF or DGOTO statements. A variable parameter that was defined on the DPROC statement when the procedure was cataloged. The relationship between the parameter and the value as one of these operators: LT, GT, EQ, NE, GE, or LE. The symbols =, <, > can be used instead of EQ, LT, and GT. A character string against which to test the variable parameter. It can be from 1-64 characters in length and must be delimited by quotes or some other special character if it contains other than all alphanumeric characters. (If this character string is a different length than the value of the parameter, the length of the parameter value is used.) This can also be a variable. The name of another control statement that is to be branched to if these conditions are met.
value
name2
Examples
// // // // DIF DIF DIF DIF VAR1 VAR2 VAR3 SIZE EQ NE LE GT YES GOTO STEP1 'DAILY RUN' GOTO MONTHLY 99 GOTO TESTOK 12 GOTO TOOLARGE
The following example demonstrates how conditional procedure expansion selects different job steps from a large procedure, depending on the day of the week. The reserved variable C_DAY is used to inform the procedure of the day of 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 is submitted.
// 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 during conditional expansion. Code the name of the parameter and the new value in this 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 DSET DSET VAR1=4 VAR=+22 VAR=-3 (positive value is assumed) (positive value can be explicit) (negative value must be explicit)
The result of an arithmetic expression using integer values and arithmetic operators (+, -, *, /).
DSET DSET DSET DSET VAR1=4-2 VAR1=8+7 VAR1=4 3 VAR1=8/4
// // // //
// //
A character string.
DSET DSET VAR1=NO VAR1='A CHARACTER STRING'
//
The value of another variable parameter.

DSET VAR1=&VAR2
The result of an arithmetic expression using two variable parameters or one variable parameter and an integer. (Variable parameters used in arithmetic expressions must have numeric values associated with them, rather than character values. The results of all arithmetic operations are truncated to provide only integer results.)
DSET DSET DSET DSET DSET VAR1=&VAR1+1 VAR1=&VAR1+&VAR2 VAR1=&VAR2-&VAR3 VAR1=&VAR2 &VAR3 VAR1=&VAR2/2
// // // // //
Control Loops (DLCTR)

As a result of backward step branching during procedure expansion, procedure expansion can enter a loop. CA Driver automatically terminates procedure expansion when any step name is referenced more than 16 times. To override the default value of 16 step references, use the DLCTR command and specify a number.
//name DLCTR n
The number you specify (n) is the maximum number of times any one step can be branched to. If any step is referenced n+1 times, an error message is produced and procedure expansion is terminated.
Examples
// // // DLCTR DLCTR DLCTR 4 9 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 current procedure, 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 inside an 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 the procedure and is subject to modification by CA Driver. Even those statements that begin with '//*' and are considered comments in JCL are eligible for CA Driver variable substitution. This can be useful in certain situations, but the need may arise for comments inside CA Driver procedures that do not appear in expansions. CA Driver can be instructed to ignore comment statements altogether. In this way, comment statements can be used for documentation inside the procedure but will not appear in any displays where the procedure is expanded. The DPROCCOM keyword on the OPTIONS statement in the CA 7 initialization file controls the use of comments inside CA Driver procedures. The default is DPROCCOM=NO. All CA Driver procedure statements beginning with '//*' are subject to variable substitution and will be included in procedure expansions. If DPROCCOM=YES is specified, any CA Driver procedure statement beginning with '//*' will be ignored by CA Driver and will not appear in procedure expansions. Should there be a need for comment statements inside CA Driver procedures that begin with a character string other than '//*' then that string can be coded as a value on the DPROCCOM keyword. The value must not exceed eight bytes and should not include blanks or commas. The value also cannot be one of 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 can embed comments into the CA Driver procedure, but these are not used nor shown in the data sent to the destination agent. If the procedure uses variables on the line, these variables are not reflected anywhere but in the returned comment 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 on schedule ID and XPJOB driver procedures.
Conditional Execution Based on Schedule ID

You can use the &C_L2SID reserved name variable parameter to modify a parameter for a job. For example, by convention, schedule ID 001 indicates that the job should run with a parameter of MONTHLY, schedule ID 002 is associated with a parameter of WEEKLY. Schedule ID 003 is considered a DAILY run by the job. You can use CA Driver to generate a parameter to the job based on schedule ID.
//procname // // // //DOIT // //STEPNAME DPROC RUNTYPE=,VAR(4)=(MONTHLY,WEEKLY,DAILY,OTHER),HOLDSEL= DSET HOLDSEL=&C_L2SID DIF HOLDSEL LE 3 GOTO DOIT DSET HOLDSEL=4 DSTEP DSET RUNTYPE=&VAR(&HOLDSEL) EXEC PGM=USERPGM,PARM=&RUNTYPE
XPJOB Driver Procedures

For an XPJOB, the CA Driver Procedure XPJDPROC is stored in the DPROC library (either CARPROC DD statement or the DPROC library associated with the JCL or PARM library as defined through initialization parameters). Notice the 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 sent to the platform is represented here): PARM 1 PARM 2 T=3 F= 12
Chapter 5. NCF
This section contains the following topics: Purpose . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . CA 7 NCF Components . . . . . . . Planning and System Requirements Implementation Considerations . . . System Operations . . . . . . . . . . Operator Commands . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
164 165 166 172 177 186 188
This section defines the purpose and basic requirements for CA 7 NCF (Network Communications Facility) and describes the primary components of the system. Functional descriptions of the operator commands are also included.
Chapter 5. NCF 163
Purpose
Purpose
It is often desirable, for maximizing use and effectiveness of computer resources, to route CPU jobs (and their products) to some other data centers for processing, printing, and so forth. Generally these data centers are widely dispersed geographically. They may be located very close to each other, however. In any case, routing of jobs is performed by JES over a communications link between the data centers. This is accomplished with JES control statements included within the JCL for the job. IBM provides a Network Job Entry (NJE) facility within JES to handle the routing of jobs to be processed at another data center. NJE also routes any print or punch output to whatever location the user wishes to perform that function. Printing and punching of job output does not have to be done at the location where job execution occurs. CA 7, in its native form, performs dynamic workload management functions such as scheduling, prerequisite verification, job submission, and so forth, based on SMF data. In an NJE environment, as in all environments, SMF data is only produced at the location where job execution occurs. CA 7 may or may not be installed at that location. SMF data must, however, be returned to the CA 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 to allow the user to fully use all workload management facilities of CA 7, whether some jobs are processed on an NJE basis. With NCF, jobs submitted by CA 7 can execute at any site within a network of sites just as if the site were a local CPU. NCF ensures that the CA 7 that submitted a job receives the necessary SMF data for the job regardless of which site processed the job. No changes are required to the CA 7 database for a job to be run on an NJE basis. The JCL for any such job must, however, contain the JES statements necessary to cause JES to route the job to the desired location after it has been submitted by CA 7. When execution does occur, CA 7 performs its functions related to the job just as if the job executed in an initiator on a local CPU. This transparency to both CA 7 and the production user would not be possible without the NCF component.
Requirements
Requirements
CA 7 must exist at each node from which CA 7 controlled jobs are to be submitted. ICOM (the CA 7 Independent Communications Manager) must be installed on each CPU where these jobs are to execute. CAIRIM plus the CA 7 SMF 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 one site. 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 a single CPU and a typical NCF environment (however, many variations are available 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 is the common driver for a collection of dynamic initialization routines that eliminate the need for preinstalled user SVCs, SMF interface exits, subsystems, and other installation requirements commonly encountered when installing systems 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 a subcomponent of CAIRIM), so SMF recording must be active in the system for any SMF event or data handling product routines. The CAIRIM SMF Interceptor component does not require any particular SMF records.
SVC Interface
When each job is submitted to JES by CA 7, the JOB statement is flagged with the originating node ID. The CA 7 UJV SMF interface exit preserves this ID in either the SMF Reader Time or SMF User ID fields depending on which location the user designates, in ICMDSECT, for this purpose. The CA 7 SVC, when called by the CA 7 SMF interface exits, uses this node ID to identify the CA 7 location that submitted the job and to which all SMF data for the job should be returned. The originating CA 7 node ID is used to distinguish between data that should be retained locally and that data that should be routed back to CA 7 at some other node. The CA 7 SVC interface obtains data from the CA 7 SMF interface exits and the CA 7 trailer or U7SVC programs and transfers this data across address spaces for subsequent processing by ICOM. The SVC interface and SMF interface exits must be installed at all sites for NCF processing to occur. Although the execution location must generate the necessary SMF record types to satisfy CA 7 requirements, the data need not be also written to the SMF MANX/Y data sets unless the user so desires. This data that occurs at the execution site is available at the originating CA 7 site for logging into the CA 7 log 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 modules available (for example, STEPLIB) and an extra DD statement pointing to the NCF communications data set. This is an extension of the standard CA 7 ICOM program. It must be installed at each node. It processes data for local and remote records by extracting data from the SVC interface and writing local records to the CA 7 communications data set and remote records to the NCF communications data set. Data received through VTAM at an originating node is routed through the SVC interface 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 222 nodes can exist in any one network. Each NCF node corresponds to a JES NJE node on a one-to-one basis. UCC7NODE is the required name for the node table. Generation of the node table is accomplished with the UNCNOD macro 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 a unique 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 NCF VTAM tasks at any two nodes in the network, a validation of the two node tables is automatically performed at "bind" time. A discussion of this validation procedure 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 the node table, an entry is created in the unknown node table dynamically by the NCF VTAM task. Any SMF or trailer data for such nodes are written to the undeliverable queue besides creating an entry to this table. Unless the user changes the node table while jobs are executing at a remote node in the network, no unknown nodes should ever occur. If the unknown node table becomes full, a warning message is issued and any new undeliverable data is dropped. Data in the undeliverable queue for an unknown node can be purged with the PURGE command. Any reoccurrence of data for this unknown node is also written to the undeliverable queue, and the existing entry in the unknown node table 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 data collection at each node in the network. It contains SMF and CA 7 trailer data for jobs submitted from a remote node. This file must exist for NCF processing to occur. This data set has a one-to-one relationship with a JES NJE SPOOL or job queue. In a multi-access spool (MAS) complex or a single CPU site, only one data set is defined.
NCF Undeliverable Queue (UDQ)

The UDQ contains data for nodes that do not have an active link, or that are not defined in the node table. Any data that cannot be transmitted due to communication interruptions are saved in this data set. This file must exist for NCF processing to occur. If the UDQ becomes full, data contained in the file must be purged or transmitted or new data is lost. A progressive series of warning messages are issued beginning when the file threshold (80 percent) is reached and continuing until the percentage used drops below the threshold value.
NCF VTAM Application Program

The NCF VTAM application program receives and transmits CA 7 NCF data between nodes in the network. This program receives control once VTAM and the 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 VTAM facilities 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 for processing 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 7 NCF. For testing purposes, the EXEC statement for the NCF VTAM task should be changed to include two additional PARM values. The PARM value TEST indicates 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 use in a normal production environment. To test the establishment of a session between two or more NCF nodes, The TEST and TABLE parameters can be used to execute two or more nodes on a single machine. The VTAM APPL definitions must be correctly coded to allow a local-LU to local-LU session. To test data transmission between two nodes, a data generator program is supplied that can be executed with the following JCL:
// EXEC //STEPLIB DD //UCC7NCFD DD //SYSIN DD PGM=SASSNCDG,PARM='TABLE=xxxxxxxx' DISP=SHR,DSN=user load library DISP=SHR,DSN=user defined NCF communications data set DUMMY,BLKSIZE=8
The TABLE parameter should specify the same table used by the NCF VTAM application program that is to transmit the data. Sample data is generated, according to this table, for transmission to all remote nodes. The SYSIN DD statement is required and should always be coded as shown in the JCL above unless otherwise directed by Technical Support. Note: The CA 7 SVC is never invoked by CA 7 NCF when PARM=TEST is specified. When you have completed testing with the NCF Test Data Generator, you should reinitialize the ICOM communications data set (COMMDS), the NCF communications 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 of CA 7 NCF is incorporated in the Installation Guide. The information in this topic 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 different from 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 Installation Guide and helps distinguish between environments. NCF Network Communication Facility, a component of CA 7. Also refers to the VTAM application program used to pass certain CA 7 data from site to site. NCF Complex Used to refer to all the sites connected by NCF. NCF1 A site that runs CA 7 and NCF. NCF2 A site that runs NCF but not CA 7. site A node in an NJE network. Consists of one or more CPUs running with or without 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 and NCF 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 7 SMF interface exits installed. ICOM must be run on each CPU in the complex. However, NCF itself only runs on one CPU per site. The JOB statements for all jobs submitted by CA 7 must have blanks in columns 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/time problems. The time values in the CA 7 database that are established by the user (for example, DOTM) must be set according to the time zone where the 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 resources together. CA 11 controlled jobs require the CA 11 database and programs be at the site where the jobs are run. Also, all sites to which CA 7 submits CA 11 controlled jobs must use the same procedure name for RMS. The RMS procedure name must be in the CA 11 Option Table or in the CA 7 initialization file (RESTART statement). The LOAD procedure inserted into jobs submitted by CA 7 must exist at all sites 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 a CA 7 site that does run NCF (NCF1 or NCF2) if a LOAD step is included in the JCL. This results in a U0110 abend in the LOAD step. If there is no LOAD 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 for the 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 are supported 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 are to execute. CA 7 must exist at each site from which CA 7 controlled jobs are to be submitted. The CA 7 SVC interface and SMF interface exits must be installed at all sites and on all CPUs that can execute CA 7 controlled jobs. CAIRIM, CA Resource Initialization Manager, must be on each CPU as well.
Memory Requirements
The virtual memory requirements of the VTAM task are variable, based on the number of nodes in the node table. The following formula should be used to calculate 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 itself and one data set used by ICOM. Following is a description of the permanent files. NCF Communications Data Set: The NCF communications data set contains CA 7 formatted SMF and trailer data to be transmitted to remote nodes. In a multi-CPU site, this data set must reside on a shared DASD device. Each CPU in the complex must execute a copy of ICOM, each of which shares this data set. The NCF communications data set is a formatted physical sequential data set with the following characteristics: DCB=(RECFM=F,BLKSIZE=1 24,LRECL=1 24) The space required by the NCF communications data set depends on the amount of NCF activity. A minimum allocation of 900 blocks is recommended. This data set must be formatted using the SASSNC12 program. See the CA 7 install job N030 for sample JCL. Undeliverable Queue (UDQ): The UDQ contains CA 7 formatted SMF and trailer data that could not be transmitted because communication with a node was interrupted or could not be established. It also contains data for any nodes encountered 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 the following characteristics: DCB=(RECFM=F,BLKSIZE=1 24,LRECL=1 24) The space required by the UDQ depends on the amount of NCF activity. No less than one cylinder is recommended. At least 600 blocks of space should be allocated for each node to which data can be transmitted. Experience may show that more space is required for a particular site. This data set must be formatted using the SASSNC15. See the CA 7 install job N030 for sample JCL.
Chapter 5. NCF 175
ICOM Communications Data Set: The ICOM communications data set contains CA 7 formatted SMF and trailer data to be processed by the local CA 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 7 installation. The ICOM communications data set is a formatted physical sequential data set with the following characteristics: DCB=(RECFM=F,BLKSIZE=1 24,LRECL=1 24) Space required for the ICOM communications data set at NCF2 sites should be about 100-150 blocks (about five tracks on 3390 devices). At NCF1 sites, space is determined during CA 7 installation. For NCF2 sites, the *CPU* statement used to format the file should specify UCC7NCF2 (not UCC7IRDR or UCC7SUB1). Failure to do this could possibly result in ICOM looping. For more information about formatting the communications data set, see the installation requirements in the Systems Programmer Guide.
CAIRIM System Requirements

The installation of CA 7 NCF requires that CAIRIM be installed at each site where CA 7 NCF will execute. This service may have already been installed with 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 production processing in a CA 7 environment not only requires the installation of the necessary software at the processing sites, but also requires some production considerations 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 to control and monitor the jobs as if they were executing locally. Even without the support of CA 7 NCF, jobs routed to a remote site or node through JES can execute 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 since all SMF data for the job would occur only at the remote node at which execution occurred. Using the NCF component software, production processing can occur at any remote node as if the remote processor and initiator were a local initiator. However, there are implementation considerations for the production user that are critical to the success of this processing. These considerations are discussed 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 the NCF VTAM application program. The option is specified as follows: PARM= 3 'TIME=tttttttt'
TIME Is the duration of the WAIT that is issued by the NCF VTAM application program when an attempt to enqueue the NCF communications data set fails. You may need to adjust this parameter to minimize data set contention, especially in an MAS environment. This time limit is also used to synchronize the initial LOGON processing during NCF startup. If all remote nodes have not attempted to LOGON when the limit is reached, a warning message (CA7.NC203) is issued and the remaining LOGONs are allowed to complete asynchronously while normal processing commences. This parameter is optional. 00003000 Is the default time limit (30 seconds) in one hundredths of a second. Leading zeros can be omitted. tttttttt Is the user-specified time limit in one hundredths of a second. Leading zeros can be omitted.
Sample NCF VTAM PARM

The following is a coded example of the PARM for the NCF VTAM application program: //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 / JOBPARM // //NODE1 EXEC //STEPLIB DD //SYSPRINT DD //UCC7SNAP DD //SYSABEND DD //SYMDUMP DD //UCC7NCFD DD //UCC7NCFU DD // user job statement specifications user specifications PGM=NCF,PARM='TIME=3 ' DISP=SHR,DSN=cai.ca7.caiload SYSOUT= SYSOUT= SYSOUT= DUMMY DISP=SHR,DSN=user defined communications data set 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. The execution location is essentially transparent to the production control person. However, CA 7 database considerations for scheduling and the DB.1 panel are important for NJE jobs.
Scheduling
All CA 7 scheduling considerations are the same for NJE jobs as for jobs that execute locally. Triggers, calendar schedules, job dependencies, use of networks, and so forth, are fully supported for NJE jobs. The only difference is that NJE jobs execute at a remote site. It is a user's responsibility to ensure that 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 jobs are 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 the job is defined in the CA 7 database at site B, then the due-out time for the job should be marked as 7:00 AM.
DB.1 Panel
Fields on the DB.1 panel are used for NJE jobs with only a few special considerations. The GENERAL, JCL, REQUIREMENTS, and MESSAGES segments 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 except that the MAINID field for an NJE job should, when used, specify a CPU from which JES can transmit the job to the proper remote node (after CA 7 submits the job to JES). It is still the user's responsibility to ensure that the job contains the JCL necessary to cause JES to do the routing once JES receives an NJE job submitted by CA 7. If the INSERT-RMS field in the EXECUTION segment has a value of Y, CA 7 inserts the step that executes CA 11. In these cases, CA 11 must be installed at the location where the job executes. Fields in the RESOURCES segment of the DB.1 panel apply to resources that must be available at the remote node.
User Execution JCL

User execution JCL for the NJE jobs must be located at the CPU site from which CA 7 initially submits the job to JES. The JCL segment of the DB.1 panel must define where the JCL can be found. Care must be taken also to ensure that any LTERM value specified in the MESSAGES segment of the DB.1 panel (or in the JCL statement in the initialization file) causes messages to go to a terminal where problems can be properly addressed if they arise.
JOB Statement
Since the job executes at a remote site with its own version of the operating system, fields in the JOB statement must meet the requirements of the remote site. 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 reserved for indicators that CA 7 manages. Position 69 must always contain a blank (to prevent JCL errors) and positions 70 and 71 contain indicator bytes set by CA 7 for execution control purposes. These reserved positions in the JOB statement must be reserved in all CA 7 controlled jobs whenever NCF support is used for any jobs. In a CA 7 environment without NCF support, only positions 70 and 71 of the JOB statements were reserved. To avoid problems when NCF is installed, the user must ensure that all JOB statements to be handled by CA 7 do not violate this convention. Note: Use of external security can require an additional column of the JOB statement. For more information, see the chapter "Installation Requirements" in the Systems Programmer Guide.
Chapter 5. NCF 181
JES2 Statements
Jobs can be routed to a remote node for execution, through JES2, through one of 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 immediately after the JOB statement. Once the job is submitted to JES by CA 7, these statements direct JES2 to route the job to the proper NJE node. JES2/NJE also supports the /*XMIT control statement. This statement is only documented in the JES2 manual. When used, the name of the job transmitted to the remote node must be the same as the name of the job that caused the job to be transmitted. Use of the /*ROUTE statement to direct printed or punched output to the proper location, should be carefully considered since its function varies depending on where it is positioned in the JCL relative to the position of a /*ROUTE XEQ statement.
JES3 Statements
In a JES3 environment, the following JES3 statements are used to control the routing 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 must exist at the execution node as opposed to the submission node. Existence of the programs at the execution node is a user's responsibility. Cataloged procedures used in NJE jobs must also be located at the site where conversion and interpretation of the cataloged procedures occur.
DD Statements
Data definition (DD) statements, besides referencing a data set located at the execution 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 must also ensure that production data sets are located at the execution node and, if applicable, are cataloged correctly. Some production data sets can always be maintained at one site while others may be required at more than one site. The user must ensure that the correct version of each data set is available at the execution node prior to job execution. References to data sets in all DD statements must meet the requirements of the execution node.
Chapter 5. NCF 183
General Usage
Several CA 7 facilities routinely used at local nodes can also be used at remote NJE 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 remote nodes. Jobs can be demanded, requirements can be posted, and so forth, by executing these programs at the execution node. Activities that are to be performed by CA 7 as a result of the execution of these programs are controlled by CA 7, wherever it resides, based on the feedback provided by NCF support. Jobs demanded or released by these facilities can execute at any node in the network based on the routing that is specified in JES control statements within the JCL for the jobs.
NCFNODE Parameter
When executing SASSTRLR, the EXEC statement can be coded with a node name in the PARM parameter. This causes the event posting data to be routed to CA 7 residing at the node name specified. If this parameter is not coded, the feedback 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. The node name must exist in the NCF node table as defined with the NODNAME parameter of the UNCNOD macro. (For further details on node names, see the node table assembly discussion in the appendix "VTAM and NCF Node Table Definitions" in the Installation Guide.)
CA 7 LOAD Process
The LOAD process is performed at the execution site. Data from this process is automatically returned to the originating CA 7 site for updating of the CA 7 database. Job characteristics in the database reflect the resource and data set information from the execution environment. This includes the RESOURCE data on the DB.1 panel, information on the CA 7 cross-reference reports, and all other references to data sets and resources within CA 7. Data set requirements and triggers are supported no matter where the job executes. The data sets must physically reside at the execution node for proper execution 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 has been 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, they must be reinitialized prior to execution of NCF. For a discussion of the programs provided to satisfy this requirement, see the appendix "VTAM and NCF Node Table Definitions" in the Installation Guide.
Establish Communications
When the system is started, it automatically establishes communications with VTAM 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 do become 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 nodes encountered during processing. It indicates whether they are active or inactive and displays activity counts. Status can be displayed for one node or all of the nodes. See STATUS Command on page 195 for more information.
Error Recovery
Data for nodes with which NCF cannot communicate, or which are not in the UCC7NODE table, is put in the undeliverable queue (UDQ). Data for these unknown nodes remains on the UDQ until communication can be established or until the data is purged using the PURGE command. If communication is not established with that node in the near future, you may want to purge its data to prevent 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 SHUTDOWN command followed by the STOP command. This allows all pending processes to complete and provide an orderly termination. By using only the STOP command, pending processes are cut off and the job terminates. Data cannot be lost using this method because the data set pointers are not updated until a positive response has been received. However, duplicate data can be sent because the data may have been successfully received before the positive response was issued. See STOP Command on page 189 and SHUTDOWN Command on page 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 MODIFY command with the exception of the MVS STOP command. The other commands discussed in this topic require that a MODIFY taskname precede the command text in the following format: MODIFY taskname,command operand
The short form of the MODIFY command, F, can be used interchangeably with MODIFY. The maximum acceptable length for the command [operand] is 36 characters. Any command that is not syntactically and logically correct will be rejected with the message: CA-7.NC1 1 UNKNOWN COMMAND IGNORED
Operator Commands
STOP Command
The STOP command immediately detaches the subtask and terminates the NCF job. You should issue a SHUTDOWN command prior to a STOP command to complete all pending processes. This command has the following format: STOP jobname
jobname Defines the OS job or task name of the NCF VTAM application to be terminated.
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 their pending processes and logs off. The command terminates communication with VTAM by closing the ACB and freeing all control blocks. The only valid commands after a SHUTDOWN are STARTUP or STOP. The SHUTDOWN command also issues a STATUS command. This command has the following format: MODIFY jobname,SHUTDOWN
jobname Defines the OS job or task name of the NCF VTAM application to be terminated.
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 the status of the nodes. See STATUS Command on page 195 for details.
Operator Commands
STARTUP Command
The STARTUP command, after a SHUTDOWN command, reestablishes communications. The command rebuilds all control blocks, opens the ACB, and logs on all nodes. This command has the following format: MODIFY jobname,STARTUP
jobname Defines the OS job or task name of the NCF VTAM application to be attached.
Response
The following message will appear for each node (xxxxxxxx) that was logged on successfully: 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 node specified. This is usually done after that node has been logged off. Once the link has been established, any undeliverable data in the UDQ will be sent. This command has the following format: MODIFY jobname,LOGON nodename
jobname Defines the OS job or task name of the NCF VTAM application. nodename Defines 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 that node has completed any pending processes, the LOGOFF command will be executed, communications will be terminated and all future data will go to the undeliverable queue until the node is again logged on. This command can be issued at any node. This command has the following format: MODIFY jobname,LOGOFF nodename
jobname Defines the OS job or task name of the NCF VTAM application. nodename Defines 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 for the node specified in the command. The entire undeliverable queue must be read and processing of the communications data set is suspended until this is completed. Multiple nodes can be purged only by entering multiple commands. This command has the following format: MODIFY jobname,PURGE nodename
jobname Defines the OS job or task name of the NCF VTAM application. nodename Defines the node to be purged.
Response
A message is not issued when the purge is complete. To verify that the purge completed, a STATUS command must be issued. Note: Since UDQ processing must be serialized to ensure chronological integrity of the SMF data, a PURGE command can require several minutes to complete depending on the volume of records. This command deletes records that CA 7 uses for tracking jobs. This can result in 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. The nodes displayed will be those in the UCC7NODE table plus any unknown nodes that were encountered during processing. The percentage of blocks used in both the NCF communications data set and undeliverable queue is also displayed. Record counts reflect the volume of data since the last STARTUP. This command has the following format: All Nodes: To display the status of all nodes: MODIFY jobname,STATUS
jobname Defines the OS job or task name of the NCF VTAM application. Single Node: To display the status of a single node: MODIFY jobname,STATUS nodename
nodename Defines 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__ ADL 1 1 ACH 2 1 nodename (ID) _STATUS_ ( 2) INACTIVE ( 3) ACTIVE ( 4) UNKNOWN _LUTYP_ PLU _RECV_ 57 485 _SENT_ 57 485 _UNDL_ 146 UND QUEUE ..23% USED _PURG_
NCF QUEUE ..41% USED
This panel contains the following fields: NODE The VTAM APPL ACBNAME of the node whose status information is displayed. Each unknown node name will be printed on a separate line. ID The node ID in hexadecimal. STATUS The status of each node: ACTIVE Communication is established with this node. INACTIVE Communication is not established with this node. UNKNOWN This node is not in the UCC7NODE table but data was received and is either being held on the undeliverable queue or was purged. LUTYPE If a node is active, it is either a primary logical unit (PLU) or secondary logical unit (SLU). The node that initiated the communications link is the PLU. RECV The number of blocks received from the node specified. SENT The number of blocks sent to the specified node. UNDL The number of blocks on the undeliverable queue (UDQ) that contain data for this node. The physical blocks on the UDQ can contain data for multiple nodes. Therefore, the total of the UNDL counts on the STATUS command does not necessarily correlate to the physical blocks used on the UDQ. PURG The number of blocks on the UDQ that contained data for the node that was purged.
Operator Commands
NCF QUEUE The percentage of blocks used in the NCF communications data set compared to total blocks available. UND QUEUE The percentage of blocks used in the UDQ compared to total blocks available. When the UND QUEUE % USED first exceeds 80 percent, 85 percent, and 90 percent, a warning message will be issued. The warning message will be issued every time a block is added while it exceeds 95 percent.
Chapter 5. NCF 197
Operator Commands
TRACE Command
As a debugging aid, the TRACE command is used to activate or deactivate the NCF tracing facility. This facility can provide SNAP dumps or WTOs to assist in isolating problems. Note: Due to the extreme volumes of WTO and SNAP output produced, this facility should only be used when requested by Technical Support for problem resolution. This command has the following format: MODIFY jobname,TRACE=SNAP n (n,mm,mm,...,mm)
jobname Defines the OS job or task name of the VTAM subtask. TRACE= SNAP|n|(n,mm,mm,...,mm) Activates the trace facility. SNAP Indicates that SNAP dumps are to be taken. n Indicates 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 valid values for WTOs. Level 1 provides the most general WTOs. Levels 4 and 7 provide progressively more detailed WTOs. Level 7 provides the most detailed WTOs. A special level number of 127 can be used to request PCB SNAP dumps each time a PCB is dispatched. A PCB (Program Control Block) is an NCF internal data area used in controlling all processing. (n,mm,mm,...,mm) Indicates that the specified level of WTOs (n) is desired only from the modules specified as mm in the list. The parentheses must be coded as shown. The specification for n is the same as previously indicated. As an example, (7,01,03,04) indicates that the most detailed WTOs are desired 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 is used: MODIFY jobname,TRACE=OFF
jobname Specifies the same meaning as in the previous TRACE command entered to activate the tracing facility.
Chapter 5. NCF 199
Chapter 6. Cross-Platform Scheduling

This section contains the following topics: CAICCI Cross-Platform Connections The XPS CLIENT . . . . . . . . . . . The XPS SERVER . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
203 207 223
A CA scheduling solution can request work to be run on its behalf by another CA scheduling solution on a different platform. For example, CA AutoSys on a UNIX platform can request that CA 7 schedule MVS jobs on its behalf. The following 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 as an MVS job or UNIX script, and so on) as the XPS CLIENT. The XPS SERVER is the CA scheduling solution controlling execution of the work requested by the XPS CLIENT. In the previous example, CA AutoSys is the XPS CLIENT and CA 7 is the XPS SERVER. The workload can be thought of as primarily under the control of the XPS CLIENT. The XPS CLIENT requests work and monitors status for purposes of workload control (evaluating requirements, triggering other work). The XPS SERVER only acts to initiate work and to communicate status information about the work to the XPS CLIENT. CA 7 can act as the XPS CLIENT by requesting work on other platforms and can also act as the XPS SERVER by submitting and tracking work in response to requests from XPS CLIENTs.
Chapter 6. Cross-Platform Scheduling 201
This section discusses the requirements that allow CA 7 to participate in the cross-platform scheduling environment. All forms of cross-platform scheduling require communications between systems using CA Common Communication Interface (CAICCI). The other requirements necessary for CA 7 to run as an XPS CLIENT are distinct from those that are needed for CA 7 to act as an XPS SERVER. For this reason, the discussion of CA 7 and cross-platform scheduling follows in two sections: The XPS CLIENT on page 207 and The XPS SERVER on page 223.
CAICCI Cross-Platform Connections

The MVS system and the system running the other scheduler or agent must be connected by CAICCI (CA Common Communications Interface). Specifically, Cross-Platform Scheduling uses the TCP/IP Gateway protocol of CAICCI. The connection 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 fewest number of connections, and/or the system that is recycled most often. A typical site probably has a small number of MVS systems that are active the majority of the time and many non-MVS systems, some of which may be shut down frequently. In this case, it makes sense to make the CAICCI connection definitions on the non-MVS system.
Non-MVS CAICCI Connections

CAICCI connections are defined in the following files, depending on the platform: Platform UNIX Product CA NSM Job Management Option or Agent CA NSM Job Management Option Agent File $caiglbl0000/cci/config/<machine-name>/ccirmtd.prf where <machine-name> is the CCI name of the machine.
Windows
\TNG\CAIUSER\CCIRMTD.RC
Windows
\CA\CAIUSER\CCIRMTD.RC
The format of the CCIRMTD file is the same on all non-MVS platforms. The first line must be a LOCAL statement and can be followed by any number of REMOTE 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 that can be resolved into a TCP/IP address. A TCP/IP PING command on this value should be successful. "cciname" is the name that CAICCI will use for this node. This value may or may not be the same as the IP address. The name must match the CAICCI name defined at the remote node. For MVS, the CAICCI name is defined by the SYSID 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 is the default port for CA NSM Job Management Option and agent. The default port 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 than eight characters, a one- to eight-character alias must be used to accommodate CAICCI on MVS systems. Other CAICCI systems see the local system by this alias name. RETRY is only valid on the REMOTE statement. If the connection cannot be made 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 CAICCI parameters, which are pointed to by the CAIENF started task. A TCP/IP Gateway PROTOCOL statement is required for any CAICCI cross-platform scheduling communication. This is necessary even if the individual node connnections are defined on the non-MVS platforms. The types of 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 CONNECT statement. NODE(TCPIPGW,ip-address:port,retry,cciname) CONNECT(cciname) "TCPIPGW" should match the type of gateway specified on your PROTOCOL statement (TCPIPGW, TCPIP3GW, or TCPIPSGW). "ip-address" is either the numerical TCP/IP address of the node or a name that can be resolved into a TCP/IP address. A TSO PING command on this value should 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 or reestablish the connection. "cciname" is the name that CAICCI will use for this node. This value may or may not be the same as the IP address. The name must match the CAICCI name defined at the remote node (or the ALIAS= if specified). On MVS, the node name is not case sensitive. The NODE and CONNECT statements can also be issued from a console by prefixing 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 scheduling solution (XPS SERVER) that can be running on a remote platform and receives status feedback (job initiation and job termination information) from the XPS SERVER. The XPS CLIENT for CA 7 performs two functions: submission and tracking. Jobs can be submitted to a remote platform directly (XPJOB definitions) or by using the batch program CA7TOUNI. The tracking function is provided by the CA 7 Cross-Platform Tracking System (XTRK).
Direct Submit Function

When CA 7 detects a job should be submitted for execution, CA 7 reads the database and determines the type of job. If the job is an internal cross-platform job (XPJOB), CA 7 builds a request containing the information required to run the job on the remote platform. The remote platform location, or node, is extracted from the XPJOB definition. After all requirements are met, CA 7 sends this information to the remote platform using CA Common Services CAICCI. 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 builds and sends the scheduling request to the remote platform. The job is validated against rules relevant for XPJOBs as opposed to regular CPU jobs (for example, a JOB statement is not required). All the CA 7 features that are applicable to regular jobs (triggering, scheduling, prose, and so on) are applicable for XPJOBs. XPJOBs flow through the CA 7 queues the same as regular CPU jobs. A CPU indication of XPJ distinguishes it from a regular CPU job.
The XPS CLIENT
XPJOB definitions provide many benefits when compared to using the batch program CA7TOUNI. The XPJOB function makes it simpler for users not familiar with z/OS JCL to 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 user IDs, passwords, or both visible in JES displays. Optionally, this information can be placed in yet another data set that the JCL must reference. With XPJOB definitions, the sensitive data does not appear in JES displays and may be stored in the CA 7 data base, an indirect location, or in the job definition's parameter library. Access to this data can be protected using CA 7's external security interface. XPJOB definitions improve system resource utilization by eliminating the need to run a z/OS job for every cross-platform job. This reduces or eliminates the overhead and runtime problems that users often face when dealing with batch jobs. Additional batch initiators are not required. XPJOBs jobs are not subject to JCL errors, extraneous resource conflicts, or processor delays often found with batch jobs. Because transmission of the XPJOB request is handled entirely within the CA 7 address space, more effective control of the job submission process occurs at program level. If an alternative remote node is defined for the primary remote platform node, and the primary remote platform node is not currently active, CA 7 can reroute the XPJOB information to the alternate node. Also, with direct connections to the remote nodes, a user can request a job cancellation, assuming the cross-platform agent supports such a request. CA 7 relies on SMF data for posting batch job information. Using an internal interface to communicate to the cross-platform agent eliminates the SMF tracking overhead, delays, and ambiguities. Because the cross-platform jobs are submitted for execution through a separate subtask directly to CA Common Services CAICCI, the normal batch job throughput through a JES internal reader is reduced.
Sites can convert their CA7TOUNI jobs to XPJOB definitions using the CA7TOUNI-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 remote platform. This was the initial method CA 7 used to schedule jobs on a remote platform and is still supported. Sites wanting to use variable substitution for the NODE name or wanting a protected data set for password information should continue to use the batch CA7TOUNI program. Sites that do not have a CAICCI connection on the operating system where CA 7 runs should also use CA7TOUNI because it lets them route the job for execution on an operating system with a CAICCI connection. Note: For more information about using batch program CA7TOUNI, see Appendix 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, see the 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 requests sent to Windows platforms. Limits: 1 to 15 alphanumeric characters Source: Optional parameter library or associated to a node/owner access definition (for more information, see XPSWD in the Database Maintenance Guide).
The XPS CLIENT
LINELEN (Optional) Controls the line length of the SYSIN input for the SUBFILE and PARMxx keyword parameters. Normal XPJOB submission processing automatically determines whether columns 73 to 80 contain line sequence numbers (LINELEN=AUTO). If column 72 contains a blank, null, or plus sign, and columns 73 to 80 are numeric, columns 73 to 80 are considered to be line sequence numbers. Line sequence numbers are not considered part of the PARMxx keyword value. The LINELEN keyword can override this automatic determination and force XPJOB submission processing to consider the full 80-byte record as part of the data area (LINELEN=80). Or it can force XPJOB submission processing to ignore columns 73 to 80 (LINELEN=72) regardless of the contents of those 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 for PARMxx keywords is controlled by the last valid LINELEN specification processed before the current line. PARM1 thru PARM64 (Optional) Supply values to be used on the target platform. Values can be 1 to 256 characters. Avoid special characters because they may not translate correctly on the target platform. Embedded blanks cause the value to be enclosed in double quotes by the XPS SERVER on the target platform. 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 sign does not appear in the resulting value. Keyword checking is suspended during a continuation operation. Limits: 1 to 256 alphanumeric characters Source: Optional parameter library. If only one parameter is needed (and it is 128 characters or less), it can be specified in the XP PARM field on the XPJOB definition, described in the Database Maintenance Guide. Note: The contents of columns 73 to 80 can be included or excluded based on the processing controls currently in effect. Normally, line sequence 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 the target platform. The password is sent to the target system in an encrypted format. Some target systems may require that a password accompany the SUBUSER on cross-platform requests. Limits: 1 to 14 alphanumeric characters Source: Optional parameter library Note: XPJOB definitions provide a number of more secure alternatives to using SUBPASS and SUBUSER. Review the OWNER parameter in the XPJOB definition and the XPSWD command. For more information about XPJOB and XPSWD, see the Database Maintenance Guide. For more information about the XPDEF initialization file statement, which discusses the hierarchy of cross-platform job submission user ID and password processing, see the Systems Programmer Guide. SUBUSER (Optional) Identifies the user ID for security purposes on the target platform. Limits: 1 to 32 alphanumeric characters Source: Optional parameter library Note: XPJOB definitions provide a number of more secure alternatives to using SUBPASS and SUBUSER. Review the OWNER parameter in the XPJOB definition and the XPSWD command. For more information about XPJOB and XPSWD, see the Database Maintenance Guide. For more information about the XPDEF initialization file statement, which discusses the hierarchy of cross-platform job submission user ID and password processing, see the Systems Programmer Guide. Additional parameters that are valid for CA7TOUNI jobs are either not applicable for XPJOBs (for example, JOBNO, JOBSET, SUBCHECK, 7TRACE), or handled differently. MONITOR information is now extracted from the XMONITOR keyword of the XPDEF file initialization statement. Sites wanting to use the equivalent of SUBROOT must set the SUBROOT keyword of the XPDEF file initialization statement to Y and associate the ROOT user ID to an Owner or Node using the XPSWD command. Lastly, SUTYPE is now a field in the XPJOB definition.
The XPS CLIENT
Cross-Platform Tracking
Tracking consists of the XPS SERVER returning feedback records for CA 7 submitted jobs to the system that sent the request. These records are transmitted using CA Common Services CAICCI and represent job initiation, job termination, and job failure events. The CA 7 Cross Platform Tracking System (XTRK), running on the MVS system where the CA 7 cross-platform job submission occurred, receives these events and converts them to SMF-like feedback recognized by CA 7. CA 7 then processes this information like any other job to determine when it becomes active, completes, or fails. There should be one copy of CA 7 XTRK per CA 7 instance executing on each system where CA 7 cross-platform jobs can be submitted. 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 execution method. This method is required for tracking XPJOB defined jobs submitted directly from CA 7. It also tracks jobs submitted using CA7TOUNI. Sites not planning 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 or batch job, see Appendix C, XTRK as a STC or Job on page 361. For more information about running CA 7 XTRK as a subtask under ICOM, see Appendix 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 (XPJOB job type) submitted by the downed CA 7 system. If a site has a dormant copy of CA 7, or starts CA 7 on another system, with the same primary name as the original CA 7 system, CA Common Services CAICCI reroutes the tracking information to that CA 7 system so that XPJOB posting continues to occur. Also, events such as job execution and file creation/update that occur on non-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 executing at 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 acting as 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 DD statement: //XCKPT DD DISP=OLD,DSN=xtrkcheckpoint
The XCKPT DD points to the CA 7 Cross-Platform Checkpoint file. Each copy of CA 7 XTRK must have its own Checkpoint file. The DCB parameters 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 the SYSGEN) allocates a checkpoint file that can be used for the XCKPT DD statement. Optionally, sites can use an existing CA 7 XTRK checkpoint data set that is currently used in a XTRK started task, batch job, or ICOM JCL stream. This assumes sites are converting to run CA 7 XTRK as a subtask under CA 7. //XPRINT DD SYSOUT= The XPRINT DD specifies the SYSOUT class for CA 7 XTRK trace messages. The type and volume of messages produced is controlled by the first value of the XTRKTRC keyword of the XPDEF initialization file statement. //XSNAP DD SYSOUT=
The XSNAP DD specifies the SYSOUT class for CA 7 XTRK storage snap output. The type and volume of output produced is controlled by the second value of the XTRKTRC keyword of the XPDEF initialization file statement. //XEVENTS DD DISP=SHR,DSN=xtrk..xtracking(rules) The XEVENTS DD is optional. Note: For more information about the XEVENTS DD statement, see CA 7 Cross-Platform External Tracking on page 218. 3. Update the CA 7 started task initialization file tracking tracing statement if needed. XTRKTRC=21 CA 7 XTRK is automatically enabled when an XCKPT DD statement is found in the CA 7 online started task. optional
The XPS CLIENT
Note: For more information about the XPDEF initialization file statement keywords, see the Systems Programmer Guide. 4. Recycle the CA 7 started task. Check for the CAL2X101I - CAL2X103I messages (in the CA 7 JOBLOG) showing the status of the cross-platform tracking 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 Database Maintenance 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 file initialization statement XPHAO keyword. The XPHAO value must be unique across the enterprise. If two or more copies of CA 7 have the same XPHAO value, it cannot be determined which copy should receive the cross-platform job feedback. 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 of CA 7 fail. Note: For more information about setting up a dormant copy of CA 7, see the Systems Programmer Guide. Sites can also shut down CA 7 and resubmit the same CA 7 started task on a different LPAR. As long as the XPDEF file initialization statement XPHAO keyword has not changed, cross-platform tracking information will be routed to the new copy of CA 7 as soon as it is active. Important! If you chose to activate HAO, you should do so when no XPJOB cross-platform jobs are active. Failure to do so could result in cross-platform tracking 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 /XTASK command to display its status or add/update information. CA 7 XTRK running as a batch job, started task, or subtask under ICOM accepts MODIFY or STOP operator commands. The following explains the parameters that are available: ADDNODE(nnnnnnn) Adds a CAICCI node (nnnnnnnn) to the XTRK Node Table. XTRK will attempt to establish communications with that node. BLDXEVT Rebuilds the Cross-Platform External Tracking table from the rules defined in the XEVENTS DD. If the rebuild is successful XTRK will attempt to resynchronize with each remote node to pass the new set of external tracking rules. DELNODE(nnnnnnn) Deletes a CAICCI node (nnnnnnnn) from the XTRK Node Table. XTRK will no longer attempt to communicate with that node. NODE[(nnnnnnnn),status] Lists nodes from the XTRK Node Table indicating the current status, last activity and checkpoint dates and times. The default is to list all nodes. A full or partially qualified argument can be specified to limit the display. For example: NODE(AIX*). See messages CAL2X155I and CAL2X156I. In addition to a node argument, a status argument can be specified to limit the display to nodes that have a particular connection status. The status keywords 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). For example, NODE(AIX*),INACT. Or, NODE,ACTIVE. NODEN[(nnnnnnnn),status] Lists nodes from the XTRK Node Table indicating the CAICCI node name and the remote node name. This display can be useful if you are using CAICCI Alias names. The default is to list all nodes. A full or partially qualified argument of the CAICCI node name can be specified to limit the display. For example: NODEN(AIX*). See message CAL2X154I. In addition to a node argument, a status argument can be specified to limit the display to nodes that have a particular connection status (see the previous NODE command). NODEX[(nnnnnnnn),status] Lists nodes from the XTRK Node Table indicating the current status, last activity and checkpoint dates and times, and the internal status flags. The default is to list all nodes. A full or partially qualified argument can be specified to limit the display. For example: NODEX(AIX*). See messages CAL2X155I and CAL2X156I. In addition to a node argument, a status argument can be specified to limit the display to nodes that have a particular connection status (see the previous NODE command).
The XPS CLIENT
PING Forces the XTRK Tracking Manager to send a CAICCI record to each node in the XTRK Node Table to confirm a connection, or attempt to initiate a connection. Normally this process is done on a timer basis. SNAP(..option..) Forces a storage snap to be written to the XSNAP DD (if available and open). The options are: SVT XTRK System Vector Table TAB XTRK Node Table Blocks XEVT XTRK External Event Table entries ALL All of the above STOP Causes XTRK to perform normal shutdown processing. This can also be done 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 the print trace code to 2 and the console trace code to 1. Both codes must be 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. XEVT Lists rules from the XTRK External Tracking Event table. See messages CAL2X185I and CAL2X186I. The default is to list all event rules. A full or partially qualified CAICCI node argument can be specified to limit the display 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 7 XTRK 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 or batch 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 ),ACTIVE ICOM - F CA7ICOM,XTRK=NODE(TEST ),ACTIVE Display Nodes CA 7 Subtask - /XTASK,M=(CMD,TRACKER,NODEX) Batch Job - F jobname,NODEX ICOM - F CA7ICOM,XTRK=NODEX Ping Nodes CA 7 Subtask - /XTASK,M=(CMD,TRACKER,PING) Batch Job - F jobname,PING ICOM - 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 events and 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, the creation or update of files can be detected by the CA scheduler or agent even if it is done by a task outside of their control. When XTRK starts, it checks for an XEVENTS DD statement. If present, it should point to a 80-byte statement-image data set or PDS member that contains the event rules for CA 7 Cross-Platform External Tracking. When XTRK establishes communication with a remote system, it passes to that system the rules that apply to it. When a matching job initiation, termination, or file create/close occurs on that system, the feedback record for that event is sent to XTRK using the same format as normal cross-platform work. When XTRK receives this external feedback it will generate pseudo-SMF records for CA 7 that match the format of CA 7 External Tracking. The CA 7 address space treats these pseudo-SMF records in the same manner as other external tracking records. For information about setting up CA 7 to process external 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 are meaningful for all types of events. Unless otherwise specified, case does not matter. All data must be between columns 1 and 72. To continue lines at any point (inside or outside a keyword), end the line with " -" (a blank followed by a dash). 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 be tracked. TYPE(DSN) Indicates that matching file creation/update events should be tracked. TYPE(CONNECT) Indicates that XTRK should always attempt to establish contact with the CAICCI node specified in the NODE( parameter. JNO( For event TYPE(JOB), the four-digit job number of the job to be tracked as defined 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 defined to CA NSM Job Management Option. JOBSET( is REQUIRED for TYPE(JOB) events. It is ignored for other types. For CA AutoSys, use a fixed value of XXXX. MVSNAME( For event TYPE(JOB), the job name that conforms to MVS standards to be used by CA 7 to track this job. For event TYPE(DSN), the fully qualified data set name that conforms to MVS 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 the other CA scheduling system. For event TYPE(DSN), the fully qualified name of the file to be tracked, or in certain configurations masking is allowed. For more information about masking, see the Command Reference Guide. The value of NAME( is case-sensitive when used for a job name, and it may be case-sensitive when 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 should watch for this event. For TYPE(CONNECT) it is the node name that XTRK should 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 for TYPE(JOB) or TYPE(DSN) events. STAT( For EVENT(DSN), STAT( indicates which method should be used on UNIX machines to determine when the file has been updated. STAT(N), the default, uses hooks in the UNIX kernel and is the fastest and most reliable method. STAT(Y) uses a UNIX statistics utility to determine when the file has been updated. For more information about these methods, see the documentation 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-Platform Tracking 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 will track the creation/update of data set name NTBOX1.MYFILE.TXT as a CA 7 external 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 and terminates at node UNIX01. XTRK will track it as a CA 7 external job with the name 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 Node name begins with the characters 'AIX', will be asked to send XTRK feedback when job 'aix-job1', job number '0001' in jobset 'aix-jobset' initiates and terminates. 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 job regardless of which AIX machine it runs on.
The XPS CLIENT
XEVENTS Example 4 EVENT( TYPE(CONNECT) NODE(AIX EVENT( TYPE(CONNECT) NODE(AIX EVENT( TYPE(CONNECT) NODE(AIX 1) ) 2) ) 3) )
These rules ensure that XTRK will attempt to communicate with each of these systems (AIX001, AIX002, AIX003). Normally, XTRK communication will only take place if CA 7 submits a cross-platform job to that remote system. If you simply want to listen for cross-platform external tracking events at a node, the TYPE(CONNECT) rule ensures that XTRK will attempt to establish communication with that system.
Usage Notes
Duplicate External Events: If you are running CA 7 Cross-Platform Tracking System (XTRK) on more than one MVS image, you should not use the same XEVENTS rules for both copies. If you do, each XTRK could receive feedback for 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), or unnecessary overhead in the CA 7 address space (at best). We recommend having one copy of XTRK handle the Cross-Platform External Tracking for CA 7. Using TYPE(CONNECT) Event Rules: Normally the CA 7 Cross-Platform Tracking System (XTRK) only communicates with those remote systems where CA 7 Cross-Platform jobs are submitted to. If you want to use CA 7 Cross-Platform External Tracking for remote systems that do not receive any CA 7 cross-platform work, you need to define at least one XEVENTS rule that explicitly references that node. If the only rules that apply to that node have generic NODE( parameters, use a TYPE(CONNECT) rule to explicitly identify the node to XTRK. SASSEXTT Model Queue Record Table Module: For CA 7 to track external tasks (local or cross-platform), the Model Queue Record Table module, SASSEXTT, must be available to the CA 7 address space. The External Job/STC Filter Table module, SASSEXTL, is NOT required for cross-platform external tracking. For information about enabling CA 7 external tracking, see Tracking External Tasks in the Systems Programmer Guide.
The XPS SERVER
The XPS SERVER

The CA 7 XPS SERVER receives scheduling requests from a CA scheduling solution that can be running on a remote platform. It responds by servicing the requests (job submission), and returning appropriate feedback to the XPS CLIENT. In this way, the XPS CLIENT is notified of job initiation and termination. The CA 7 XPS SERVER comprises two distinct functions: the XPS SUBMIT MONITOR and the XPS Router. The programs that make up the XPS Router function normally run as subtasks in the CA 7 address space. The XPS SUBMIT MONITOR function is accomplished by main task and subtask programs.
The XPS Submit Monitor

The XPS SUBMIT MONITOR is the function that interprets the scheduling request from the XPS CLIENT, schedules the job in CA 7 and sends status feedback to the XPS CLIENT through the XPS Router. The XPS SUBMIT MONITOR is responsible for two activities: submission of CA 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 the XPS SUBMIT MONITOR using CAICCI. The SUBMIT MONITOR builds a terminal command based on parameters provided in the scheduling request or from options coded in the CA 7 initialization file. The submit MONITOR then uses an internal terminal to issue a command that causes the job to be scheduled. The definition of an internal terminal is marked by the specification of DEVICE=TRXDV. If CA 7 is to be an XPS SERVER, at least one internal terminal must be defined. The value of the XPSSCHD keyword on the SVCNO and XPDEF statements in the CA 7 initialization file determines the scheduling command that is issued when a cross-platform scheduling request is received. For more information about this important parameter, see Manage the Cross-Platform Workload on page 232 and the discussion of the XPSSCHD keyword of the SVCNO and XPDEF initialization file statements in the Systems Programmer Guide. The XPS SUBMIT MONITOR respects CA 7 terminal security. A USERID is required 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 USERID is supplied on the scheduling request from the XPS CLIENT then the value of the XPSSID keyword on the SECURITY statement will be used for the logon to the internal terminal. If no USERID is supplied and if no value is coded for the XPSSID 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 are requested by an XPS CLIENT will report an entry mode of 'XPS' in the output of queue displays. Jobs that are requested by another CA scheduling system must be defined on the CA 7 database PRIOR to scheduling. If the job is not defined to CA 7, the scheduling request from the XPS CLIENT will fail. The command that is used by the XPS SERVER to schedule the job is recorded in the CA 7 Log. If an XPS CLIENT scheduling request fails, the terminal command as well as the CA 7 error message that is produced may prove useful in problem determination.
The XPS SERVER
Status Update
The XPS SUBMIT MONITOR function will send status information to the XPS CLIENT in the form of CAIENF events. The CAIENF event that is used for this purpose is named 'CAXPSFBK'. CA 7 will create CAXPSFBK records to signal status changes such as job initiation, job termination and job failure. These CAIENF events will be captured by the XPS Router and forwarded to the XPS CLIENT. 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 record reporting the failure to be sent to the XPS CLIENT. A CAIENF record reporting job initiation is created when CA 7 receives the job initiation record from SMF. The value of the XPSSCHD keyword on the SVCNO and XPDEF initialization file statements affect the way job completion status updates are reported to the XPS CLIENT. If the default of XPSSCHD=RUNREF is used, a CAIENF record for job completion is created immediately when the job terminates. If XPSSCHD=DEMAND or XPSSCHD=RUN is coded, the job completion status update 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 job submission, then CA 7 will create a CAIENF record indicating that the job failed. If, however, the job has already run at least once, then a CAIENF record indicating job termination will be created. Note: Exercise care with jobs using XPSSCHD=RUNREF and CA 7 step condition code checking (#SSC statements). If #SSC processing detects an error situation, then the code returned to the requesting system is the return code detected by #SSC processing. This may or may not be the highest condition 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 present a single point of communication. The cross-platform scheduling router (XPS Router) is this single point of communication on MVS systems. On a given MVS system there can be more than one CA scheduling solution executing. For example, there can be multiple instances of CA 7 executing on the same MVS image. The cross-platform scheduling router enables all instances of CA 7 to participate in cross-platform scheduling. On MVS systems, the cross-platform scheduling router receives all requests for work from other systems. It then routes each request to the appropriate CA scheduling solution on that system. The feedback information (job initiation, termination, failure) generated by the CA scheduling solution is used to create CAIENF cross-platform feedback events (CAXPSFBK). The cross-platform scheduling router intercepts these events and sends the feedback to the original requester. Logging this information in CAIENF also prevents the loss of feedback data if communications problems interrupt the links among platforms. When the link is reestablished, the cross-platform scheduling router can retrieve the logged feedback events from CAIENF and send them to the system that originated the request. Cross-platform scheduling communication is performed by using the CA Common Communications Facility (CAICCI). A copy of CAICCI runs on each system where CA solutions require it. The copies of CAICCI on each system communicate with each other using various protocols based on CAICCI control parameters. The gateway communication protocol is used for cross-platform scheduling (host-to-host connection). Each copy of CAICCI has a unique identifier known as the node name. On each system, CA solutions register with the local copy of CAICCI as a CAICCI application. The local CAICCI then makes those applications known to the copies of CAICCI on other systems that it is connected to. There are several unique CAICCI application names that are used only for cross-platform scheduling. The combination of the node name and the unique CAICCI application names enable CA scheduling solutions to route requests for work and the feedback from that work. Besides the unique node and CAICCI application names, each CA scheduling solution that participates in cross-platform scheduling has a seven-character identifier known as a monitor name. In an MVS environment, each CA scheduling solution must have a monitor name that is unique in the local MVS environment. Thus, on a system where there are multiple instances of CA 7 at the same node, each instance must have a different monitor name for cross-platform scheduling to work properly for all defined instances.
The XPS SERVER
The CAICCI application names used by cross-platform scheduling are based on the functions they perform. The CAICCI application that receives requests for work has a fixed name that is common to all systems, and there can only be one copy at a CAICCI node. Other CAICCI applications that participate in cross-platform scheduling have a common format where the monitor name makes 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 CA Scheduling solutions on other systems. The SUBMITC Server routes the request 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 node regardless of how many CA Scheduling solutions are executing at that node. On MVS, this application is controlled by the cross-platform scheduling router. On non-MVS platforms there can only be one CA Scheduling solution so the SUBMITC Server is controlled directly by that solution. CAU9SET Setup Manager This CAICCI application name controls the Checkpoint Synchronization process with other systems. The Setup Manager initiates the Synchronization process and sends feedback (job initiation, termination, failure information) that was previously logged but not yet sent to the other system participating in the synchronization. There can only be one copy of the Setup Manager on a given node regardless of how many CA Scheduling solutions are executing at that node. On MVS, this application is controlled by the cross-platform scheduling 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 a piece of work. There can only be one copy of the Track Task on a given node regardless of 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 different system. The request for work is sent to the SUBMITC Server at the target node where the work is to be executed. The CAICCI application name consists of the seven character monitor name followed by the fixed text 'Job Submit' or 'Job Submit2'. There can be as many copies of Job Submit applications on a given node as there are CA Scheduling solutions executing at that node. On MVS, these applications are controlled by each CA scheduling solution participating in cross-platform scheduling.
monitor-name Job track This CAICCI application name receives the cross-platform feedback (job initiation, termination, and failure information) for jobs it requested to be run on a remote system. The feedback is sent either by the SetUp Manager or Track Task at the system where the job was actually run. The CAICCI application name consists of the seven-character monitor name followed by the fixed text 'Job track'. There can be as many copies of Job track applications on a given node as there are CA Scheduling solutions executing at that node. On MVS, these applications are controlled by each CA scheduling solution participating in cross-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 SUBMITC Server application running at the local node. The CAICCI application name consists 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 as there are CA Scheduling solutions executing at that node. These applications appear only on MVS and are controlled by each CA scheduling solution participating in cross-platform scheduling.
The XPS SERVER
Cross-Platform Server Password Requirements

The password requirement rules for the cross-platform server on MVS define when a password must accompany an explicit user ID in a cross-platform request. Using these rules you can discriminate between trusted and non-trusted systems when receiving requests. That is, if you are confident that requests from a given system have already gone through security checks to ensure that the user ID passed with the request should be honored, you can specify a rule so that the cross-platform router will accept the user ID without a password. For other systems that are not 'trusted' you can write rules so that any request from them that contains a user ID must also carry a password that can be validated by the cross-platform server. Requests received from these systems that have a user ID but no password will be automatically rejected by the XPS Router. The Password Requirement process in the XPS Router will not validate the user ID/password combination itself. That process will be done by the XPS Server scheduling system based upon it's own security processing (internal or external). Password Requirement Rules are defined in a data set pointed to by the XPSPSWD DD statement in the Cross-Platform Scheduling Router (XPS) environment. This data set is a sequential file consisting of fixed 80 byte records (physical sequential or a member of a PDS). The records can be blocked or unblocked. If the XPSPSWD DD statement is not present, or contains no valid rules, the default processing is to accept all requests without checking for the presence of passwords. When the Cross-Platform Scheduling Router (XPS) goes through initialization processing 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 accessed during normal processing. Changes made to the rules will not take effect until XPS is reinitialized.
Syntax Rules
Lines beginning with a blank or an asterisk (*) are considered comment lines. Each individual rule must be contained on a single line between columns 1 through 71. Continuation lines are not supported. The rule definition consists of a series of keywords/values beginning in column 1, separated by commas with no embedded blanks.
The XPS SERVER
Keywords
NODE=caicci-node-name Identifies the one- to eight-character CAICCI node name that a Cross-Platform request can be received from. It must be specified as a specific name or an asterisk (*) that indicates all nodes. If not specified, the default is NODE=* indicating all nodes. MONITOR=monitor-name Identifies the seven-character scheduling system monitor name that a Cross-Platform request can be received from. It must be specified as a specific name or an asterisk (*) that indicates all monitor names. In cases where a given node may have multiple scheduling systems (such as multiple instances of CA 7), the NODE and MONITOR combination will uniquely identify a specific scheduling system. If not specified, the default is MONITOR=* indicating all monitor names. ID=user-id Identifies the one- to eight-character user ID that can be passed with a cross-platform request. It must be specified as a specific name or an asterisk (*) that indicates all user IDs. If not specified, the default is ID=* indicating all user IDs. PSWD=YES/NO Indicates whether a cross-platform request that matches the NODE/MONITOR/ID parameters of the rule must have a password to accompany the user ID in the request. A value of YES (or Y) indicates that such requests must have a password. A value of NO (or N) indicates that passwords are optional for such requests. If not specified, the default is PSWD=YES.
Processing
When a cross-platform request is received by the XPS Router a check will be made 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 check will not be made. 2. If the request contains both a user ID and a password, a password requirement check will not be made. 3. If the request contains a user ID but no password, a password requirement check will be made. The XPS Router will attempt to find the 'best match' between the current request 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 rules equally match a request then the rules that require a password will take precedence over those that do not. If no match is found in the table then the request 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 explicit user ID. NODE= ,ID=MASTER,PSWD=YES The preceding rule indicates that any request that contains a user ID of MASTER must have a password, regardless of what CAICCI node or scheduling system sent the request. Note that the default for MONITOR= is '*' if it is not specified. NODE=A 4IENF,ID=TESTUSER,PSWD=NO The preceding rule indicates that a request from CAICCI node A04IENF with a user ID of TESTUSER is not required to have a password associated with it. NODE=A 4IENF,ID= ,PSWD=YES NODE= ,ID=TESTUSER,PSWD=NO If a request is received from CAICCI node A04IENF with a user ID of TESTUSER it will partially match on both of the preceding rules. The second rule will take precedence because a specific ID match will take precedence over a specific NODE match. A password is not be required. NODE=A 4IENF,MONITOR= ,ID= ,PSWD=YES NODE= ,MONITOR=CA7CA71,ID= ,PSWD=NO If a request is received from CAICCI node A04IENF, scheduling system CA7CA71 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, ID generic). In the case of a tie, the rule that requires a password will take precedence 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 to consider the question of managing the cross-platform workload. There are two approaches to scheduling that can be distinguished in terms of the degree of control granted the XPS CLIENT versus the degree of control granted the XPS SERVER. The manager-agent model may be useful in making this distinction. The scheduling manager is the focal point of control for the workload. The scheduling manager requests work and monitors status for purposes of workload control (evaluating requirements, triggering other work). The scheduling agent initiates work at the request of the manager and communicates status information to the manager. Scheduling definitions (triggers, requirements) are primarily the responsibility of the scheduling manager. The question then arises: should scheduling manager functions be handled by the XPS CLIENT or the XPS SERVER? These roles are largely determined by the way in which cross-platform jobs enter 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 value of the XPSSCHD keyword on the XPDEF initialization file statement. Values include RUNREF, DEMAND and RUN. By default, cross-platform jobs enter CA 7 using the RUNREF option. This assigns the role of scheduling manager to the XPS CLIENT, the requester of the job on another platform (for example, CA AutoSys). The primary responsibility for workload control belongs to the XPS CLIENT. Jobs scheduled using this option do not honor requirements defined in CA 7, they are not considered requirements for other CA 7 jobs and they will not trigger other CA 7 jobs at completion. This variant of the RUN command differs from the standard RUN command in that it will not allow a CA 7 restart. A job scheduled using this command is considered "complete" at either normal or abnormal termination. An entry for the job will appear in the CA 7 RUNLOG, however no entry 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 assigned to CA 7 using the XPSSCHD=DEMAND or XPSSCHD=RUN options. If either of these options is used, then additional management functions become the responsibility of CA 7. XPSSCHD=RUN confers additional responsibility on CA 7 for monitoring and control of restart and rerun conditions. However, because the RUN command is used to schedule the job, CA 7 requirement and trigger definitions will be ignored. XPSSCHD=DEMAND confers even more management responsibility on CA 7. Because the DEMAND command is used to schedule the job, CA 7 requirement and trigger definitions will be honored, and CA 7 must be used to monitor restart and rerun conditions. Note: The XPSSCHD keyword on the XPDEF initialization file statement is used to declare a global option that applies to all jobs requested from XPS CLIENTs. This parameter can be overridden for selected jobs by coding this keyword in the 'Filename' field (Job Detail - Submission - Filename) in CA NSM Job Management Option. See Step 6 in CA 7 XPS Server Implementation Checklist on page 234. Exercise care with jobs using XPSSCHD=RUNREF and CA 7 step condition code checking (#SSC statements). If #SSC processing detects an error situation, then the code returned to the requesting system is the return code detected by #SSC processing. This may or may not be the highest condition code actually produced by the job. The default schedule ID for cross-platform jobs is 1. This value can be overridden for selected jobs by coding a SCHID keyword in the Filename field (Job Detail - Submission - Filename) in the requesting system definition. For more information about SCHID, see CA 7 XPS Server Implementation Checklist on page 234.
The XPS SERVER
CA 7 XPS Server Implementation Checklist

1. Define CAICCI connections among systems. See CAICCI Cross-Platform Connections on page 203. These CAICCI connections are the same regardless of which side is acting as the XPS CLIENT or XPS SERVER. 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 the member 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 XPDEF initialization file statement: a. Specify XSERVER=YES. This indicates to activate CA 7 XPS SERVER functions. b. The XPS Router executes on only one copy of CA 7 at any given CAICCI node. The XPS Router starts on the primary copy of CA 7 by default if XSERVER=YES is coded. If cross-platform scheduling is to be used only with a non-primary instance of CA 7, code XROUTER=YES on the XPDEF statement for that instance of CA 7 to start the XPS Router. c. Determine the appropriate value for the XPSSCHD parameter (on the XPDEF statement) based on the needs of your environment. Remember that the default value gives the greatest degree of workload control to the XPS CLIENT and limited control to CA 7. If a greater degree of control over cross-platform jobs should be given to CA 7 consider either DEMAND or RUN values for XPSSCHD. d. If you have more than one instance of CA 7 on the target MVS system and you want to route jobs to all of them, determine the appropriate value for the XPDEF file initialization statement XMONITOR keyword. If this keyword is enabled, the MONITOR name for a given instance of CA 7 is displayed at startup in message 'CA-7.ISVC - XPS SERVER INITIALIZED. MONITOR VALUE: xxxxxxx. Refer to Step 6 in this checklist for information on how this value is used. At least one internal terminal must be defined for use by cross-platform scheduling. For more information about terminals with DEVICE=TRXDV, see the Systems Programmer Guide. For information about the initialization options for CA 7 XPS SERVER functions, see the Systems Programmer Guide. You need to shut down and restart 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 rules create a data set or PDS member to hold the rules. Add an XPSPSWD DD statement to the CA 7 JCL where the XPS Router will execute (see step 3 b 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 where CA 7 executes. For the specific procedures to define a Station, see the CA NSM Job Management Option documentation. The Station should represent the MVS system 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 Management Option. For the specific procedures to define Jobsets and Jobs, see the CA NSM Job Management Option documentation. a. Use the 'Station' defined above in the Job definition (Job Detail - Main Panel). 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 system and you want to route this job to a specific instance of CA 7, add the keyword ',MONITOR=monitor-name' after the MVS job name in the 'Filename' field. For example, if you want to execute job TESTJOB1 on the third instance of CA 7 whose monitor name is CA7CA73, specify the following in Filename: TESTJOB1,MONITOR=CA7CA73 d. The value of the XPSSCHD keyword on the XPDEF initialization file statement specifies how a job requested by an XPS CLIENT is to be scheduled. This is a global value and applies to all jobs requested by XPS 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 third instance of CA 7 but the XPSSCHD value in CA 7 is RUNREF, then specify 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 than 1, 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 1 and 255. For example, if job TESTJOB1 is to be DEMANDed with schedule 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 MVS job 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 will default according to the XPSSID= option on the SECURITY statement in the CA 7 initialization file. A password may or may not be required depending on the MVS Password Requirement Table described in Step 4, above. If no Password Requirement Table has been set up, a password is not required.
7. Define the MVS jobs to CA 7. The jobs that will be initiated by cross-platform requests must be defined in the CA 7 database. These are the MVS jobs identified in the 'Filename' field of the CA NSM Job Management Option jobs. For information about defining a job in CA 7, see the CA 7 documentation. The Automated Recovery Facility (ARF) CANNOT be used with cross-platform jobs. 8. Schedule/Demand the CA NSM Job Management Option Jobset. For more information about procedures to schedule Jobsets/Jobs, see the CA NSM Job Management Option documentation. When the cross-platform jobs are submitted the request will be routed to CA 7 on the specified MVS system (XPS SERVER), and the feedback from CA 7 will be returned to the requesting system (XPS CLIENT).
Chapter 7. Email
This section contains the following topics: Email Address Members Email Templates . . . . Email Test Utility . . . . Data Set for TCP/IP Data
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
239 241 245 247
CA 7 can generate and send email messages. The content of the email messages can be generic or contain information about a specific job in the CA 7 queues. The EMAIL initialization file statement must be successfully processed before the CA 7 email interface is initialized. Sites can use the /DISPLAY,ST=EMAIL command to determine whether the email interface has been initialized. For information about the EMAIL initialization file statement, see the Systems Programmer Guide. The email interface uses an email template (read from the EMAILLIB PDS) to build 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. If additional email recipients are needed, the email must be sent again using a second 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 /EMAIL command can optionally specify a job in the CA 7 queues (using the JOB keyword). For information about the /EMAIL command, see the Command Reference Guide. The /EMAIL command can be issued anywhere a CA 7 top-line command can be issued, including from an ARFSET. Depending on your local implementation of TCP/IP, it may be necessary to add a //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 cautions against using email as the sole notification of a problem, such as an abended or failed job.
Chapter 7. Email 237
Note for JES3 Sites: Regardless of whether you run IPv4 or IPv6, be sure the name of your global is in the HOSTS.LOCAL file for the system on which CA 7 is running.
Email Address Members

Members of the EADDRLIB PDS are used to build the list of email addresses to which an email is sent. The member name is specified by the TO=xxxxxxxx keyword on the /EMAIL command. Each member can have 1 to 100 email addresses. Each address must start in column one and can be up 70 characters long. The addresses can contain both uppercase and lowercase letters, as well as any special characters needed in the email address. CA 7 does not verify the email address in any way. Email addresses are used as is. Email addresses can be internal or external to your company. Note that your SMTP (email) servers may need to be configured to deliver mail outside of your company. Comments can be included in the email address member by starting each comment line with an asterisk in column one. The default reply email address (specified by the EMAIL initialization file statement on the EREPLY keyword) can be overridden by starting the first email address with the word "reply:" followed by the reply address. The new reply address starts immediately after the colon. The word "reply:" can be in uppercase or lowercase.
Example 1: The simplest address member is a single line with an email address:
Top of Data =COLS> ----+----1----+----2----+----3----+----4----+----5----+-1 user.one@company.com Bottom of Data
Example 2: An example of multiple email addresses with comments included:

=COLS> 1 2 3 4 Top of Data ----+----1----+----2----+----3----+----4----+----5----+-Payroll application group user.one@company.com another_user@company.com 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:operations_group@company.com 2 application_programmer@company.com Bottom of Data
If the application programmer receiving this email replies to it, then the reply will go to the operations group. A site may choose to use this method to allow email recipients to respond to a problem directly to the person or group responsible for correcting the problem. For example, the application programmer might instruct the operations group to restart the abended job in a certain 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 member name 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 with the word "subject:" starting in column one. The remainder of that line is used as the subject of the email. The rest of the email template is used for the body of the email. The body can be in any valid email format, such as simple (ASCII) text or HTML. Note: Emails are translated from EBCDIC to ASCII using the IBM XLATE service or the CA 7 CAL2XLAT translation module. The XLATE service does not translate all characters correctly. For more information, see Special Characters on page 244. The CA 7 CAL2XLAT module is described in the Systems Programmer Guide. Trailing blanks on each line are discarded. Any line can have one or more variables that CA 7 resolves before sending the email. Variable names must start with an ampersand (&) and be in uppercase. Trailing blanks are removed from the values of all variables. Note that some variables do not always have a value. The following variables are always available in an email template: Variable Name &AMPER &CA7 &CA7CCI &CA7CUST &CA7HOST &CA7LVL &CA7NAME &CA7RLSE &CRLF Variable Contents The ampersand (&). The instance name (PROD, TEST, CA71, etc.) of CA 7 that is generating and sending the email. The 8-byte CAICCI node name of the system on which CA 7 is executing. The 44-character heading value specified on the CUST,ID=xxxxx initialization file statement. The SMFID of the system on which CA 7 is executing. The service pack level of CA 7, such as "SP1". The name of the product, "CA 7". The release of CA 7, such as "r11.1". The carriage return/line feed.
Email Templates
Variable Name &EFROM
Variable Contents The value that will be displayed in the "from" field of the email. The value is specified on the EMAIL,EFROM=xxxx initialization file statement, and can be changed by the /EADMIN,EFROM=xxxx command. The default is "CA-7". The reply email address for this email. The value is specified on the EMAIL,EREPLY=xxxx initialization file statement and can be changed by the /EADMIN,EREPLY=xxxx command. The reply address can also be overridden in the email address member. The default is "CA-7@do.not.reply". Contents of the VAR=(xx,xx,) keyword on the /EMAIL command. If the VAR= keyword is not specified then these variables are blank.
&EREPLY
&VAR1 to &VAR8
The following variables are available when the JOB= keyword is specified on the /EMAIL command: Variable Name &DEADDATE &DEADTIME &DUEDATE &DUETIME &EDATE &EMODE &ETIME &JES# &JOB# &JOBNAME &JQUSER &MAINID &MCNT &QUEUE &RC &SCHDID Variable Contents The deadline date for the job The deadline time for the job The due out date for the job The due out time for the job The date the job ended The entry mode for the job, such as "DEMANDED." The time the job ended The JES number for the job The CA 7 job number The name of the job The 20-byte contents of the JQUSER field The MAINID for the job The current master requirement count for the job The current queue REQ, RDY, or ACT The return code for the job The job's schedule ID 3 4 6 2,3 3 Notes 1 2 1 2 1,3
Email Templates
Variable Name &SDATE &SMFID &STATUS &STIME &SYSTEM &UID Notes 1. 2. 3.
Variable Contents The date the job started The SMFID of the system where the job is executing (or did execute). The job's current status The time the job started The job's SYSTEM (from the job definition) The CA 7 UID (userid) value for this job
Notes 1,3 3 5 2,3
Dates are formatted as "Tue, 14 Sep 20xx" Times are formatted as "hh:mm:ss". If the specified time does not have seconds, then "00" is used for the seconds. 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 yet ended, the end date and time are "*Unknown" and the return code (RC) will be blank. For cross-platform jobs, the possible SMFID values are 7XPJ, 7UNI, 7UWT, or blank. The value depends on how the job completed (job status) and the timing of when the email is generated. No conversion is done on the JQUSER contents. If the contents are not EBCDIC characters, the ASCII translation necessary for sending the email may generate garbage characters. The job status variable will contain the same string that would appear in the column of an LQ command display. For XPJOBs, the MAINID is XPJ.
4.
5. 6.
The CAI.CAIEMAIL data set provides some sample email templates. You can use these as is or tailor them to your needs. The samples are formatted for HTML. The following sample templates are provided: Template @JOBABND @JOBEND @JOBFAIL @JOBLATE Suggested Use Job abends Job successful completions Job failures (bad return codes) Jobs being marked late
Email Templates
Special Characters
Emails must be sent in ASCII. CA 7 uses the translate table defined by module CAL2XLAT, if available. You can modify this table to translate certain special characters such as the exclamation mark (!), the square brackets ([ ]), the caret (^), and the vertical bar (|). For more information about EBCDIC/ASCII Translation Tables, see the Systems Programmer Guide. If you are using HTML format for your email template, you can use JavaScript codes for these special characters. The following is a partial table of JavaScript codes 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 and ends with a semicolon. If your site has implemented the CA 7 CAL2XLAT module, characters are translated based on the definitions assigned in the program. If you have not remapped the special characters described previously, you will have the same issues as the XLATE service.
Email Test Utility
Email Test Utility

A batch utility, CAL2EMLT, is available to test the email interface in an isolated environment. The utility can be used to test different SMTP (email) servers, new templates, and/or new email address members. CAL2EMLT provides information about a "dummy" job so that email templates with variables referencing job information will be displayed with realistic data. Program CAL2EMLT should complete with RC=0. However, it generates a variable 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 //SYSPRINT DD SYSOUT= //EMAILLIB DD DISP=SHR,DSN=cai.CAIEMAIL //EADDRLIB DD DISP=SHR,DSN=address.lib //SYSIN DD control statements // (CA 7 LOAD LIBRARY) (EMAIL TEMPLATES) (EMAIL ADDRESSES)
For more information, see the L2EMAIL SAMPJCL member.
Control Statements
The control statements must begin in column one. The keywords (such as ESERVER) should be entered in uppercase. Some keywords (again, such as ESERVER) accept mixed case values. Comments can be included by starting the line with an asterisk in column one. ESERVER=value Identifies the primary SMTP (email) server that should be used. If the primary SMTP server is not available or if the ESERVER keyword is not specified, then the SMTP server on the z/OS image where CAL2EMLT executes is used. The ESERVER value can be a one to 70 character name to be resolved by a Domain Name Server (DNS) or an IP statement in the format n.n.n.n or x:x:x:x:x:x:x:x, where n is a decimal number from 0 through 255 and x is a hexadecimal number from 0 through FFFF. Leading zeros can be specified for both. The short form of an IPv6 address using a double colon (::) can be used. EPORT=value Specifies the TCP/IP port number to use when communicating with the SMTP (email) server. The value defaults to 25, which is the well-known port number for SMTP and should rarely, if ever, need to be changed. Valid values are 1 to 99999.
Email Test Utility
EFROM=value Specifies the value to appear in the "From" field of the email. The value can be one to 70 characters and defaults to "CA-7." EREPLY=value Specifies the email reply address to be used if the recipient replies to the email. The value can be 1 to 70 characters and defaults to CA-7@do.not.reply. ETIMEOUT=value Specifies the maximum number of seconds CAL2EMLT should wait for responses from TCP/IP and the SMTP (email) server. The default is 10 seconds. Valid values are 5 to 20 seconds. TO=value Identifies the member in the EADDRLIB PDS to read for the email addresses. The TO keyword is required and has no default. TXT=value Identifies the member in the EMAILLIB PDS to read for the email template. The TXT keyword is required and has no default. VARn=value The VAR1 to VAR8 keywords allow the user to specify one to eight character values. The values are substituted for the &VAR1 to &VAR8 variables 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 least one TCP started task. TCP/IP configuration data is contained in a data set pointed to by a //SYSTCPD DD statement in the TCP started task. Depending on 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 to one of these TCP "stacks." If the data set is not dynamically allocated, or if your site runs multiple TCP stacks, it may be necessary to add a //SYSTCPD DD statement to your CA 7 online JCL. Check with your TCP/IP support person to see if this DD statement is necessary at your site. If needed, this DD statement should be the same as the //SYSTCPD DD statement 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 JCL of the email test utility.
Chapter 8. Global Variables

This section contains the following topics: The Substitution Process . . . . . . . Substitution Rules and Restrictions . General Reserved Variable Names . Job-Specific Reserved Variable Names Examples . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
250 251 253 254 256
The CA 7 global variables feature permits users to perform variable substitution without requiring the use of CA Driver procedures. It also provides functionality for customers who want to use the feature instead of, or in addition to, CA Driver. The feature allows users to define global variables and assign values to those variables. There are also a fixed set of reserved global variables that are always available (for example, current date, job name, and more). Reserved global variables are identified by a one-character prefix (7 is the default) that can be set by the site. Note: To add, update, and delete global variables, see the /GVAR command in the Command Reference Guide. Variable substitution takes place if the GVARSUB=YES option was specified when 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 test substitution without actually submitting the job. Note: For more information about the LJCK,JOB=jobname,LIST=ONLY command, 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. It is designed for CA 7 JOB statements. Global variable substitution behaves differently 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 a character string prefix that can be specified by the site. The default prefix is an ampersand followed by a colon (&:). When a valid variable is found, the value for that variable is substituted in place of the variable. After the entire statement has been parsed, it is submitted.
CA Driver Procedures
When CA Driver is active, the CA Driver process takes place before global variable substitution. In effect, two variable substitution processes take place. In a statement of a CA Driver procedure, the CA Driver variables are first replaced with their values. Next, any global variables are replaced with their own values before being submitted. Note: The value of a CA Driver variable can be a global variable, which is then 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 may occur.
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 the JCL 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 also followed by at least one blank. If the global variable is followed by a comma, the replacement data is also followed by a comma. If the global variable is followed by a right parenthesis, the replacement data is also followed by a right parenthesis. If the global variable is followed by a single period, the replacement data is not followed by a period. The period is omitted, and the replacement data is concatenated 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 bytes the replacement character string is shorter than the global variable. The shift continues until a space is encountered, at which point the shift terminates. At that point, the number of spaces is increased by the number of bytes that the global variable exceeds the replacement character string. If the replacement character string is longer than the global variable, all following bytes are shifted right by the number of bytes that the replacement character string is longer than the global variable. This shift continues until a string 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 string of spaces is not available, an error message is issued and the process terminates. Two or more character strings can be shifted right if the number of spaces at the end of the statement is sufficient to contain the number of characters shifted and still leave one space.
In the following examples, global variable &:F has a replacement value of FILEAB and &:DATASET has a replacement value of DSN: Original Expanded Original Expanded Original Expanded stmt: stmt: stmt: stmt: stmt: stmt: //&:F //FILEAB //INP //INP //INP //INP DD DD DD DD DD DD DSN=PAYROLL.MASTER DSN=PAYROLL.MASTER DSN=&:DATASET..XYZ DSN=DSN.XYZ DSN=MASTER.&:F..INPUT DSN=MASTER.FILEAB.INPUT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT
The value for a global variable can contain one or more other global variables. For example, the following value is legal: AB&:CD.EF&:WX.YZ. If the value for global variable &:CD is 7 and the value for &:WX is 5, the final substituted value will be AB7EF5YZ Recursion is allowed and means that a global variable can return another variable in the first position. Examples: global variable &:ABC returning the string &:XYZ is recursive. &:ABC returning XY&:ZW is not recursive because 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 of MASTER: Original stmt: //DD1 DD DSN=PAYROLL.&:RC1 Expanded stmt: //DD1 DD DSN=PAYROLL.MASTER COMMENT COMMENT
If the number of recursions for a global variable exceeds the limit specified by the GVARLVL parameter on the initialization OPTIONS statement, a JCL error occurs. The error is described in the CA 7 browse data set. Note: For more information about the GVARLVL parameter, see the Systems Programmer Guide.
When right-shifting, the number of characters moved is the largest number moved during any of the intermediate or final substitutions. In the following example, the value for the variable &:MODEL is &:X. and the value for the variable &: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 during and after substitution. Original stmt: // Intermediate (unseen) stmt: // Intermediate (unseen) stmt: // Final stmt: // &:MODEL &:X. &:7CA7. CA74 15 &:MODEL.XX 3 15 &:X.XX 3 15 &:7CA7.XX 15 CA74XX
3 3
General Reserved Variable Names
General Reserved Variable Names

The following table contains the general reserved variable names. Variable Name 7CA7 7CA7CCI Variable Contents Instance/alias name of CA 7 CAICCI node name of the system on which CA 7 is executing SMFID of the system on which CA 7 is executing Service pack level of CA 7, such as "SP1" Release of CA 7, such as "r11" or "r11.5" Current system date in Gregorian format (mm/dd/yy) Current system date in Julian format (yyjjj) Current day of the week (SUNDAY,...) Current month (JANUARY,...) Current system time (hh:mm:ss) Current day of the month Current hour Current month Current minute Null Current second Current year (yy) Current year (yyyy) Variable Length =<4 =<8 Notes See note. See note.
7CA7HOST 7CA7LVL 7CA7RLSE 7CDATE 7CDATEJ 7CDAYW 7CMONTH 7CTIME 7DD 7HH 7MM 7MN 7NULL 7SS 7YY 7YYYY
=<4 =<4 =<5 8 5 =<9 =<9 8 2 2 2 2 0 2 2 4
See note. See note. See note.
See note. See note.
Note: The length of returned text varies. Trailing blanks are omitted to avoid embedded blanks in case of concatenation.
Job-Specific Reserved Variable Names

The following table lists the job-specific reserved variable names. Variable Name 7CA7JOB# 7CC 7CLASS 7DLDATE 7DLTIME 7DODATE 7DOTIME 7EMODE 7JOBNAME 7LTERM 7MAINID 7PRY 7QUEUE 7RO Variable Contents CA 7 job number Value for condition code test in job definition Job workload balancing (WLB) class value Job deadline date (mm/dd/yy) Job deadline time (hh:mm:ss) Job due out date Job due out time Job entry mode Job name Job LTERM value Job MAINID Job WLB priority value Job current queue Relational operator value for condition code test in job definition Job schedule ID Job system in job definition Number of WLB TAPE1 tape drives for job Number of WLB TAPE2 tape drives for job Job UID Variable Length 5 5 1 8 8 8 8 =<8 =<8 =<8 =<4 3 =<8 2 1 6 3 1,4 1 1,5 1 3 Notes 2
7SCHDID 7SYSTEM 7TAPE1 7TAPE2 7UID
3 =<8 3 3 3
7 1
Notes 1. The length of returned text varies. Trailing blanks are omitted to avoid embedded 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 blanks in 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 the value 25/11/07: &:7DD./&:7MM./&:7YY Alternate Date Format: The following sequence can be used to produce the value 2007.11.25: &:7YYYY..&:7MM..&:7DD
Chapter 9. Jobflow Illustrator

This section contains the following topics: Purpose . . . . . . . . . . . . . . . . . . . . . . . . The Workflow Building Process . . . . . . . . . . . Implementation . . . . . . . . . . . . . . . . . . . . Initialization Parameters (INITDEF DD Statement) Building Parameters (PARMDEF DD Statement) Commands (SYSIN DD Statement) . . . . . . . . JCL Examples . . . . . . . . . . . . . . . . . . . . CSV Flowchart File Description . . . . . . . . . . . FLOWCHART TYPE=PRINT Description . . . . . Sample FLOWCHART TYPE=CSV File (Partial) .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
258 260 261 264 272 285 303 307 314 319
This chapter defines the purpose and basic requirements for Jobflow Illustrator and describes how to generate, save, restore, modify, print, and report on workflows.
Chapter 9. Jobflow Illustrator 257
Purpose
Purpose
A workflow is a comprehensive view of the CA 7 workload for a specific period of time, which is known as the span. The workload comprises objects (jobs and data sets) and the direct relationships, or connections, between them. For an object or connection to be included in a workflow, the object or connection must first be defined in the CA 7 database.
Connections
Jobflow Illustrator reports the following connections: COND Identifes a conditional dependency. DRJ Identifes a data set is a requirement (prerequisite) for a job. DTJ Identifes a data set triggers job. INDJRJ Identifes a job is indirectly a requirement for a job. (See Note) INDJTJ Identifes a job indirectly triggers a job. (See Note) JCD Identifes a job creates a data set. JRJ Identifes a job is a requirement for a job. JTJ Identifes a job triggers a job. NEGDEP Identifes a negative dependency. REPEAT Identifes a job that repeats. Note: Indirect relationships are reported when the user selects the option not to display data sets in the workflow. For example: JOBA creates DSN1, which triggers JOBB. If data sets are not displayed in the workflow, JOBA shows as indirectly triggering JOBB.
Purpose
Simulation Mode
Simulation Mode is a manner of operation in which all workflow data comes from the CA 7 database. No information comes from the queues. The workflow is built in internal tables depending on building parameters supplied at startup. Because no data comes from the queues, the workflow is static, 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 Jobflow Illustrator 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 adding jobs, data sets, or both, and by deleting jobs to or from the workflow to see how the outcome would change.
Checkpoint Save and Start

You can create a baseline workflow by saving the workflow to a data set. This data set can be used as input on a TYPE=CKPT start to create a workflow that can be used as the baseline starting point for a new simulation.
Flowchart Output
Jobflow Illustrator produces two kinds of flowchart output: print and comma-separated value (CSV). In print output, boxes contain data about job and data set objects. An option allows users to omit the data set boxes and print only job boxes. The boxes are connected and information about the types of connections is displayed. The maximum size print flowchart is 999 pages horizontally by 999 pages vertically. A sample print flowchart can be found in the FLOWCHART TYPE=PRINT Description 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 column headings. This data set is suitable for importing into a program such as Microsoft Excel. An extract of a CSV file is shown in the Sample FLOWCHART TYPE=CSV File (Partial) on page 319. The CSV output can also be used by an online application such as CA Workload Control Center.
The Workflow Building Process
The Workflow Building Process

The workflow building process consists of two phases: search and filter. When CA 7 Jobflow Illustrator builds its tables, it uses search parameters to query the CA 7 database to see what scheduled jobs meet all the specified criteria. Each matching job becomes head of a workflow chain. After heads of chain are identified, each chain is run to add triggered jobs and data sets and required (prerequisite) jobs and data sets. The filter parameters specify 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 filter phases, see Building Parameters (PARMDEF DD Statement) on page 272. Once the workflow build completes, commands from the SYSIN file process the selected 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 work correctly, the instance of CA 7 to which the workflow will relate must be up and running. The CA 7 Jobflow Illustrator job must run on an LPAR that can communicate with the appropriate CA 7 instance. For information about implementing CAICCI, see the Interface with CAICCI on page 90. Note: For more information about running CA 7, see the Systems Programmer Guide.
Sample User JCL

The following is an example of the JCL for CA 7 Jobflow Illustrator with all required and optional DD statements. The DD statements you use depends on the 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 provided later.
Implementation
Input DD Statements
The following are the CA 7 Jobflow Illustrator input DD statements: STEPLIB Specifies the CA 7 load library. CHKPOINT Specifies the CA 7 Jobflow Illustrator checkpoint data set to read. Required only if a TYPE=CKPT start is being done. Can be a different ddname if the CKPTDDN initialization parameter is specified. INITDEF Identifies the source of initialization parameters or identifies the data set containing the initialization parameters. Required. PARMDEF Identifies the source of building parameters or identifies the data set containing the building parameters. Required for TYPE=COLD start. Ignored for TYPE=CKPT start. SYSIN Identifies the source of control statements or identifies the data set containing the control statements. Required.
Output DD Statements
The following are the CA 7 Jobflow Illustrator output DD statements: SAVE Specifies the data set to which a checkpoint file will be saved. Required if the SAVE command statement is specified. Can be a different ddname if the DDNAME option is specified on the SAVE command statement. FLOWCSV Specifies the data set to which to which a comma-separated value file will be written. Required if the FLOWCHART TYPE=CSV command statement is specified. Can be a different ddname if the DDNAME option is specified on the FLOWCHART command statement. FLOWPRT Specifies SYSOUT or the file to which a flowchart will be printed. Required if the FLOWCHART TYPE=PRINT command statement is specified. Can be a different DD name if the DDNAME option is specified on the FLOWCHART command statement.
Implementation
SYSMSGS Specifies SYSOUT or the file to which CA 7 Jobflow Illustrator messages are 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 is dynamically allocated, and the default sysout class is used. SYSUSNAP (Optional) Specifies SYSOUT or the file to which SNAPs will be written in the 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 in the case of an abend.
Dynamically Allocated DD Statements

The following are the CA 7 Jobflow Illustrator dynamically allocated DD statements: DBPARMS Defines parameters in the database. The same DBPARMS data set as the associated CA 7 online instance is allocated dynamically by CA 7 Jobflow Illustrator. In the DBPARMS file, several data sets are defined using the UCC7DBASE parameter. The ddnames for these data sets can be found by looking for the DDNAME keyword after the UCC7DBASE parameter. Look for DDNAMES UCC7JLIB, UCC7DLIB, and UCC7IDS. They should be accompanied by a keyword in the form ALLOCxxx, where xxx is either JCL or DYN. For the DBPARMS data set to be allocated dynamically, it must be a permanent data set, residing on DASD. DD DUMMY must not be specified in the CA 7 JCL. Note: For more information about the DBPARMS file, see the Systems Programmer Guide. UCC7JLIB, UCC7DLIB, UCC7IDS Specify the job data set, the dataset data set, and the index data set, which are collectively known as the CA 7 database. If coded as ALLOCDYN in the DBPARMS data set, they are allocated dynamically. If coded as ALLOCJCL in the DBPARMS data set, they are allocated dynamically if they are not present in the Jobflow Illustrator JCL, either in the batch job or schedule server task. If they are present in the JCL and dummied out, Jobflow Illustrator generates an error message and terminates. Note: DD statements DBPARMS, UCC7JLIB, UCC7DLIB, and UCC7IDS are 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 with spaces or commas. There is no space between the parameter keyword and value. Note: All of the parameters in this section can be overridden by coding them in the PARM field on the EXEC statement. The initialization parameters used by CA 7 Jobflow Illustrator have no relationship to those used by CA 7. Any names or options that match are coincidental 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. COLD Specifies that CA 7 Jobflow Illustrator should use the building parameters specified in the PARMDEF file and information from a CA 7 database to build a workflow. This is the default. CKPT Specifies that CA 7 Jobflow Illustrator should ignore the PARMDEF file and read the data set pointed to by the CHKPOINT DD. The checkpoint data is used as input to build a workflow. The CA 7 database is not read 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. CA71 Maps to what used to be known as the production copy of CA 7. This is the default. CA7n CA7n specifies the instance of CA 7 with which to connect. n can be an integer from 1 through 8. alias Defines a one- to four-character alias. This alias must correspond to an alias 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 the instance of CA 7 that the workflow will model. This parameter will usually have to be coded for a TYPE=COLD start. Note: This information is not saved to the checkpoint data set during a SAVE operation. During a TYPE=CKPT start, it is not necessary to code a LOGON 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 Jobflow Illustrator. If a batch job was run, this ID will normally be the TSO ID of the submitter. If CA 7 Jobflow Illustrator was called by a program, this field is determined by the ACEE of the address space returned by SAF. operatorid Defines 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 on to the instance of CA 7 that the workflow will model. This field may not be necessary depending on your site requirements. There is no default. The password is encrypted internally. The following is applicable only if your site requires a password to log on to CA 7: This information is not saved to the checkpoint data set during a SAVE operation. During a TYPE=CKPT start, it is not necessary to code a CA7PASS 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 the flow so that the internal tables can be built with an appropriate size to facilitate processing. SMALL Estimates that the flow contains less than 10,000 jobs. If the flow size is unknown, this default size should be used. This is the default. MEDIUM Estimates that the flow contains from 10,000 to 100,000 jobs. LARGE Estimates 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 being modeled is executing. If that copy executes on the local node, the parameter is not needed. Default: The local CAICCI node. crossnode Defines a one-to eight-character field. *AUTO* Specifies that the CAICCI interface should attempt to dynamically locate the CAICCI node where a CA 7 with a matching instance name resides. Note: For more information, see RECEIVER Parameter on page 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 the same 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 of CA 7 can be explicitly set with the XTMNAME keyword of the SVCNO statement in the CA 7 initialization file (or implicitly by the RNAME keyword). This allows each copy of CA 7 to be unique across a CAICCI network even though more than one copy can have the same instance name. Assignment of unique CAICCI receiver names allows the NODE=*AUTO* parameter to be used to dynamically target a specific copy of 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 checkpoint data 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 build the 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 chain jobs for the workflow. The remaining parameters (JOBFILTER, SCHFILTER, and SYSFILTER) are used to determine the jobs and data sets that are either triggered or requirements (prerequisites). You can code parameters in columns 1 through 71. Separate parameters with spaces or commas. There is no space between the parameter keyword and value. Values containing spaces or commas must be contained within parentheses. On a TYPE=CKPT start, the PARMDEF DD is ignored. Note: All of the parameters in this section can be overridden by coding them in 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. This can be useful when it is unclear how large the workflow would be, and the user is expecting a limited number of jobs in the output. MAXJOBS is highly useful when testing. Default: 0 (no limit on the number of jobs) Limits: 1 - 9999999 (When CA 7 Jobflow Illustrator exceeds this number of jobs, 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 the following would avoid runaway processing in case the building parameters were coded 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. mmddyy Defines the calendar date of the beginning date of the workflow. mm Defines the month. Leading zeros are required. Limits: 01 - 12 dd Defines the day. A leading zero is required if less than 10. Limits: 01 - 31 yy Defines the year. hhmm Defines the beginning time. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59
hhmm Defines the beginning time. With this parameter, the current date is used. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. 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. (mmddyy,hhmm) Defines the date and time. mmddyy Defines the calendar date of the ending date of the workflow. mm Defines the month. Leading zeros are required. Limits: 01 - 12 dd Defines the day. A leading zero is required if less than 10. Limits: 01 - 31 yy Defines the year. hhmm Defines the ending time. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 hhmm Defines the ending time. With this parameter, the current date is used. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. 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) of the workflow. This value is added to the FROM date and time to determine the ending date and time of the workflow. Default: 00800 (8 hours and no minutes) Limits: SPAN is mutually exclusive with TO. hhhmm Defines a time interval. hhh is a three-digit field, with leading zeros, if necessary. mm must be two digits. The maximum duration of the span is 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 initial extract of data from the CA 7 database or start with null tables so that flows are built entirely from ADDJOB and ADDDS commands. YES Specifies to build internal tables by extracting data from the CA 7 database. This is the default. NO Specifies to start with null tables. JOB building parameters are not allowed 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) in determining a triggered job's start time. HONOR Delays a triggered job's start time by the amount of the queue time. This is the default. IGNORE Ignores queue time when calculating start time.
Search Building Parameters

Search building parameters specify the criteria for CA 7 Jobflow Illustrator to use when searching the CA 7 database for scheduled jobs to become heads of chains 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 to become heads of chains in the workflow. Default: * (All jobs) Limits: This parameter not allowed with EXTRACT=NO. jobname Specifies a specific job name. jobname* Specifies a generic job name terminated with an asterisk. job?ame Specifies a generic job name masked in a single position. jo?name* Specifies a combination job name masked in a single position and terminated 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 this job.
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 the jobs to be heads of chains in the workflow. This parameter can be overridden by coding the (jobname,nnn) format of the JOB parameter. Default: 0 (all schedule IDs) nnn Defines a one- to three-digit number. Limits: 0 - 255 (nnn list) Specifies a list of up to 10 schedule ID numbers, enclosed in parentheses 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 heads of chains in the workflow. Default: * (All system names) systemid Defines a specific system name. This is a one- to eight-character alphanumeric 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 and separated by commas.
Filter Building Parameters

Filter building parameters specify the criteria for CA 7 Jobflow Illustrator to use when running trigger and requirement chains to determine whether to include jobs 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 names in the workflow. Default: * (All job names) jobname Defines a specific job name. jobname* Defines a generic job name terminated with an asterisk. job?ame Specifies a generic job name masked in a single position. jo?name* Specifies a combination job name masked in a single position and terminated with an asterisk. (jobname,nnn) Defines a specific job name with a specific one- to three-digit SCHID. If specified 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 schedule ID values in the workflow. Default: 0 (All schedule IDs) nnn Defines a one- to three-digit number. Limits: 0 - 255 (nnn list) Defines a list of up to 10 schedule ID numbers, enclosed in parentheses 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 system names in the workflow. Default: * (All system names) systemid Specifies a specific system name. This is a one- to eight-character alphanumeric 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 and separated by commas.
Commands (SYSIN DD Statement)

After the workflow is built and saved in internal tables, CA 7 Jobflow Illustrator looks 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 a job, add a data set, and delete a job, respectively, to/from the workflow. When one or more ad hoc commands are processed, a new workflow is generated before CA 7 Jobflow Illustrator processes a system or an output command. The ad hoc commands, combined with the SAVE system command and TYPE=CKPT start, provide the simulation, or what if capability, of simulation mode. Note: To save processing time, a new workflow is not generated after each ad hoc command. If multiple ad hoc commands follow each other, they are processed and the jobs, data sets, or both are added to the workflow as heads of chains. Jobs are deleted from the flow, one per DELJOB command. It is only when a system or output command is encountered that trigger and requirement chains 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 different checkpoint data set.
Output Command
The output command, FLOWCHART, produces workflow output in two different formats. FLOWCHART TYPE=PRINT produces a traditional flowchart with job and data set names in connected boxes, suitable for printing. A keyword option can suppress the data set boxes and produces only boxes with job names. FLOWCHART TYPE=CSV produces a file of records consisting of fields separated by commas. CSV stands for Comma-Separated Values. The file is suitable for importing into a spreadsheet program. The first record is the field names (analogous to column headings), and subsequent records are the data. Note: A CSV file produced by CA 7 Jobflow Illustrator online option has an additional 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 the line 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 CommandAdd 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 the workflow that is generated prior to the next system or output command. This command has the following format: ADDJOBJOB=jobname ,START=(mmddyy,hhmm) hhmm ,END=(mmddyy,hhmm) 1 hhmm ,SCHID=nnn
JOB=jobname Specifies a specific job name to be added to the workflow. This job becomes 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 date and time of the build parameters in the PARMDEF file. If START is omitted and END is specified, the START date and time is calculated from the END date/time. (mmddyy,hhmm) Defines the date and time. mmddyy Defines the date. mm Defines the month. Leading zeros are required. Limits: 01 - 12 dd Defines the day. A leading zero is required if less than 10. Limits: 01 - 31 yy Defines the year. hhmm Defines the time. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 hhmm Defines the time. This parameter uses the current date. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. 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 the START date and time. (mmddyy,hhmm) Defines the date and time. mmddyy Defines the date. mm Defines the month. Leading zeros are required. Limits: 01 - 12 dd Defines the day. A leading zero is required if less than 10. Limits: 01 - 31 yy Defines the year. hhmm Defines the time. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 hhmm Defines the time. This parameter uses the current date. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 SCHID=1|nnn (Optional) Specifies the one- to three-digit schedule ID of the job being added to the workflow. Default: 1 Limits: 1 - 255
ADDDS CommandAdd a Data Set

The ADDDS command adds a data set to the workflow. Its main purpose is to satisfy requirements. This command has the following format: ADDDSDSN=datasetname (current date,current time) ,CREDT=(mmddyy,hhmm) hhmm 1 ,SCHID=nnn
DSN=datasetname Defines 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 (mmddyy,hhmm) Defines the date and time. mmddyy Defines the date. mm Defines the month. Leading zeros are required. Limits: 01 - 12 dd Defines the day. A leading zero is required if less than 10. Limits: 01 - 31 yy Defines the year. hhmm Defines the time. hh Defines the hour. Limits: 00 - 23
mm Defines the minute. Limits: 00 - 59 hhmm Defines the time. This parameter uses the current date. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 SCHID=1|nnn (Optional) Specifies the one- to three-digit schedule ID of the data set being added to the workflow. Note: If you are unsure about the schedule ID of a data set, the general rule is the data set inherits the schedule ID of the job that creates it. Default: 1 Limits: 1 - 255
DELJOB CommandDelete a Job

The DELJOB command deletes a job from the workflow. Triggered and requisite jobs and data sets related to this job are deleted from the 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 trigger chain, this job is converted to a soft object, which is a placeholder with no SCHID. This command has the following format: DELJOBJOB=jobname,SCHID=nnn ,START=(mmddyy,hhmm) ,END=(mmddyy,hhmm) hhmm hhmm ,FUZZ=nnn
JOB=jobname Specifies a specific job name to delete from the workflow. Limits: The job name cannot be masked. SCHID=nnn|0 Specifies the schedule ID of the job being deleted from the workflow. nnn Specifies a one- to three-digit number. Limits: 1 - 255 0 Specifies 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. (mmddyy,hhmm) Defines the date and time. mmddyy Defines the date. mm Defines the month. Leading zeros are required. Limits: 01 - 12
dd Defines the day. A leading zero is required if less than 10. Limits: 01 - 31 yy Defines the year. hhmm Defines the time. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 hhmm Defines the time. This parameter uses the current date. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. 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. (mmddyy,hhmm) Defines the date and time. mmddyy Defines the date. mm Defines the month. Leading zeros are required. Limits: 01 - 12 dd Defines the day. A leading zero is required if less than 10. Limits: 01 - 31 yy Defines the year. hhmm Defines the time.
hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 hhmm Defines the time. This parameter uses the current date. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 FUZZ=nnn (Optional) Specifies the amount of time, plus or minus, in minutes, that the specified START/END time can vary from the job's actual time for Jobflow Illustrator 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 the parameters are coded as follows, the job's start time matches because 0900 is within 10 minutes of 0853. Without the FUZZ keyword, there would be no match because 0900 does not equal 0853. START=0900,FUZZ=10
SAVE CommandWrite to the Checkpoint Data Set

The SAVE command writes the workflow to the checkpoint data set. Performing multiple saves to the same data set overwrites previous data. Only data from the last save survives. The correct way to do multiple saves is to use the DDNAME option and write each checkpoint to a different data set. This command has the following format: SAVE SAVE DDNAME=ddname
DDNAME=ddname (Optional) Defines a one- to eight-character ddname. Default: SAVE
FLOWCHART CommandGenerate a Jobflow Illustrator

The FLOWCHART command generates a workflow from data in the internal tables and output in one of two formats: print or CSV (comma-separated value). Print format is the traditional flowchart where information is presented in boxes connected by lines that show relationships. Print format flowcharts are usually sent to SYSOUT. CSV format is usually sent to a data set. Fields in each record are separated by commas. The first record in the file contains the names of the fields. These can be used as column headings. This data set is suitable for importing into a program such as Microsoft Excel. This command has the following format: 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 and DDNAME) are designed to limit the output of the flowchart. The default command produces a flowchart containing all the objects that were built using the criteria specified by the building parameters. The preceding keywords can be used to generate a subset of the total flow. They can be omitted if a flowchart 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. PRINT Formats the flowchart for print, that is, jobs and data sets are represented in boxes connected by lines depicting relationships. For more information about the printed output see FLOWCHART TYPE=PRINT Description on page 314. This is the default. CSV Formats the flowchart as records with fields separated by commas. For more information about this format, see CSV Flowchart File Description 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) jobname Specifies a specific job name. jobname* Specifies a generic job name terminated with an asterisk. job?ame Specifies a generic job name masked in a single position.
jo?name* Specifies a combination job name masked in a single position and terminated with an asterisk. JOBFILTER=*|jobname|jobname*|job?ame|jo?name* (Optional) Defines the criteria for selecting the non-head of chain job names in the workflow. A single entry need not be enclosed in parentheses. Default: * (all job names) jobname Defines a specific job name. jobname* Defines a generic job name terminated with an asterisk. job?ame Specifies a generic job name masked in a single position. jo?name* Specifies a combination job name masked in a single position and terminated with an asterisk. SYS=*|systemid|system* (Optional) Defines the systems as selection criteria for the head of chain jobs in the flowchart. A single entry need not be enclosed in parentheses. Default: * (all system names) systemid Defines a specific system name. This is a one- to eight-character alphanumeric field. system* Defines a generic system name terminated with an asterisk. SCHID=0|nnn (Optional) Defines the one- to three-digit schedule ID value as a selection criterion for the head of chain jobs in the flowchart. A single entry need not be enclosed in parentheses. Default: 0 (all schedule IDs) Limits: 0 - 255 SYSFILTER=*|systemid|system* (Optional) Defines the criteria for selecting the non-head of chain system names in the workflow. A single entry need not be enclosed in parentheses. Default: * (all system names) systemid Defines a specific system name. This is a one- to eight-character alphanumeric field. system* Defines a generic system name terminated with an asterisk.
SCHFILTER=0|nnn (Optional) Defines the criteria for selecting the non-head of chain schedule IDs in the workflow (one- to three-digits). A single entry need not be enclosed in parentheses. Default: 0 (all schedule IDs) Limits: 0 - 255 FROM=(mmddyy,hhmm)|hhmm (Optional) Defines the earliest end date and time for jobs selected to be displayed in the flowchart. Default: FROM time specified in the PARMDEF build parameter. (mmddyy,hhmm) Defines the date and time. mmddyy Defines the date. mm Defines the month. Leading zeros are required. Limits: 01 - 12 dd Defines the day. A leading zero is required if less than 10. Limits: 1 - 31 yy Defines the year. hhmm Defines the time. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 hhmm Defines the time. This parameter uses the current date. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59
TO=(mmddyy,hhmm)|hhmm (Optional) Defines the latest end date and time for jobs selected to be displayed in the flowchart. Default: TO time specified in the PARMDEF build parameter or calculated using the from time and span. Limits: TO is mutually exclusive with SPAN. (mmddyy,hhmm) Defines the date and time. mmddyy Defines the date. mm Defines the month. Leading zeros are required. Limits: 01 - 12 dd Defines the day. A leading zero is required if less than 10. Limits: 1 - 31 yy Defines the year. hhmm Defines the time. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 hhmm Defines the time. This parameter uses the current date. hh Defines the hour. Limits: 00 - 23 mm Defines the minute. Limits: 00 - 59 SPAN=hhhmm (Optional) Defines the length of the time interval (that is, the duration) of the workflow. Default: None. If omitted, the span is calculated from the from and to times.
Limits: SPAN is mutually exclusive with TO. hhhmm hhh is a three-digit field, with leading zeros, if necessary. mm must be two digits. The maximum duration of the span is 16800, which is one week. OBJECT=ALL|JOB (Optional) Defines which objects are to be displayed in the flowchart boxes: jobs and data sets or jobs only. ALL Specifies to display both jobs and data sets in boxes on the flowchart. This is the default. JOB Specifies to display only jobs in boxes on the flowchart. An exception is made for data sets that are heads of chain, which are displayed. Connections that would involve a data set in an intermediate relationship will be shown as indirect connections. CONTYPE=ALL|TRIG (Optional) Defines whether to display requirement connections on the flowchart. ALL Displays all connections on the flowchart. This is the default. TRIG Displays only trigger and repeating connections on the flowchart. This includes job creates data set connections. LOOP=SHOW|NOSHOW (Optional) Sets display options for jobs that are part of a trigger loop. SHOW Specifies to show that a job is part of a trigger loop. This is the default. NOSHOW Specifies 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. FLOWPRT Specifies the standard ddname for FLOWCHART TYPE=PRINT. It has the attributes of SYSOUT (RECFM=FBA, LRECL=133). The LRECL can be overridden by use of the LRECL parameter. This is the default. FLOWCSV Specifies the standard ddname for FLOWCHART TYPE=CSV. It has the following DCB attributes: RECFM=VB, LRECL=1000.
ddname Defines a different ddname to use from the two listed previously. The DCB attributes must match those listed for FLOWPRT for TYPE=PRINT or for FLOWCSV for TYPE=CSV, or a system error may occur. LRECL=133|nnn (Optional) Defines the number of horizontal characters per page of the printed flowchart. This includes a printer carriage control character. This can be 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 pages of the flowchart or on every page of the flowchart. ONLY Specifies to print the heading text on only the top pages (PAGE 001.nnn) of the flowchart. This is the default. ALL Specifies to print the heading text on all pages of the flowchart. BLANKP=SHOW|NOSHOW (Optional) Describes whether to print blank pages. SHOW Specifies to print blank pages. This is the default. NOSHOW Specifies 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 printed flowcharts. If more than one option is selected, they must be enclosed in parentheses. Up to four of the listed options can be selected. If more than four are coded, an error message is generated and return code 8 is set. BEGIN Specifies that the begin date and time should be displayed. END Specifies that the end date and time should be displayed. DRCLASS Specifies that the disaster recovery class should be displayed. JOBNET Specifies that the job network name should be displayed. MAINID Specifies that the main ID (CPU on which the job can or cannot be scheduled) should be displayed. SYSTEM Specifies that the system name should be displayed. WLB Specifies that the workload balancing class should be displayed. WLP Specifies that the workload balancing priority should be displayed.
JCL Examples
JCL Examples
The following examples may help you understand the Jobflow Illustrator process.
Example 1: Cold Start

In this example, CA 7 Jobflow Illustrator starts normally with a COLD start. The default PARM of MAXJOBS=0 is overridden with an EXEC PARM of MAXJOBS=100. The internal tables are built with CA 7 database data specified using the building parameters in the PARMDEF DD statement. The table data is then saved to the data set described by the SAVE DD statement (SAVE command). Next, the workflow is printed in flowchart format to SYSOUT, as specified by the FLOWPRT DD statement (FLOWCHART TYPE=PRINT command).
//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=COLD CA7=CA74 LOGON=USER CA7PASS=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 SAVE FLOWCHART TYPE=PRINT //
JCL Examples
Example 2: Checkpoint Start and CSV Flowchart

In this example, CA 7 Jobflow Illustrator starts with a CKPT start, reading data from the checkpoint data set created in Example 1 and described by the CHKPOINT 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 set defined 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 the PARMDEF file but does not read any information from the CA 7 instance CA74 database (because of parameter EXTRACT=NO). After table initialization is accomplished, workflow data is saved to the checkpoint data set defined by DD CHKPOIN1. Then, using only the internal tables, job PAYME01 is added as a head of chain (command ADDJOB). Data set company.DAILY.PAYME01, which is a requisite of PAYME01, is added to the tables (command ADDDS). Because the subsequent command, SAVE, is a system command, a workflow is generated. Jobs and data sets in the database that are triggered and are requisites that meet the start/end/SCHID criteria are included. Next, the modified workflow is saved to the checkpoint data set defined by DD CHKPOIN2. Next, the workflow is printed to SYSOUT as specified by DD MYPRINT (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=2 EXTRACT=NO / //SYSIN DD SAVE DDNAME=CHKPOIN1 ADDJOB JOB=PAYME 1,START=( 331 7,173 ), END=( 331 7,18 ),SCHID=2 ADDDS DSN=company.DAILY.PAYME 1, CREDT=( 331 7,17 ),SCHID=2 SAVE DDNAME=CHKPOIN2 FLOWCHART 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 24 hours. The flow is expected to contain approximately 22,000 jobs. After table initialization is accomplished, job PAYME05 with SCHID=2 is deleted from the flow if it starts between 1235 and 1255. So are all jobs it triggers and all related requirements (command DELJOB). Next, CA 7 Jobflow Illustrator writes a print flowchart to a DASD data set. The flowchart 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=CA74 LOGON=USER CA7PASS=USERPASS SIZE=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 are composed of fields that are separated by commas. The records represent the workflow as it is kept in two internal tables. The five types of records are as follows: Header record, whose fields contain the field name. This is analogous to a spreadsheet 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 online option and is used internally by the online option. It is not generated when a batch job is run. The properties record, when present, is the last record in the file. Fields in each record are separated by commas. Each field has either a value enclosed in double quotes or simply a pair of double quotes. All records have the 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 column headings. 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 Unicenter Workload Control Center (UWCC).
Fields (Columns)
This section describes the fields of the CSV file. The row type describes which types of records the field applies to. Length is the length of the field value and does not include the double quotes. Rel_Number Indicates the row number of object in internal output table. Row type: JOB, DSN,XCN Length: 8 Row_Type Indicates JOB if the object being described is a job in the output table, DSN if the object being described is a data set in the output table, or XCN if this is a connection record. Row type: JOB, DSN, XCN Length: 4 XCN_Conn_Type Indicates PR if the connection type is a prerequisite, TR for trigger, RP for repeat, and ID for an indirect connection. Row type: XCN Length: 3 XCN_Conn_SubType Indicates 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_Number Indicates the number of the forward connection output entry (that is, the Rel_Number field of the connected object). Row type: XCN Length: 8 Fwd_Conn_Count Indicates this object's number of forward connections. Row type: JOB, DSN Length: 5 Job_Name Indicates the name of the job. Row type: JOB Length: 8
Schid Indicates the CA 7 schedule ID. Row type: JOB, DSN Length: 5 DS_Name Indicates the name of the data set. Row type: DSN Length: 44 DS_Number Indicates the schedule data set number. Row type: DSN Length: 10 Job_System Indicates the system name (jobset). Indicates Row type: JOB Length: 8 Job_Jobnet Indicates the job network name. Row type: JOB Length: 8 Hidden_Conn Indicates whether the job/data set has hidden connections (Y or N). Hidden connections are trigger or dependency connections to objects that are not included in the workflow because of date and time criteria or selection filters. Row type: JOB, DSN Length: 1 Soft_Flag Indicates whether this job is a soft object (Y or N). A soft object is one that does 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 the workflow, but there is no date and time schedule or trigger in the workflow to define when the soft job will run. For data sets, these are data sets that are dependency predecessors to one or more jobs in the workflow, but none of the jobs in the workflow create that data set, so there is no way to tell when that creation will occur. Row type: JOB, DSN Length: 1
Job_Head Indicates whether this job is the head of a chain (Y or N). Row type: JOB Length: 1 Job_Start_Date Indicates the target begin date in Julian format (yyyyddd). Row type: JOB Length: 7 Job_Start_Time Indicates the target begin time of day in hh:mm:ss format. Row type: JOB Length: 8 Job_End_Date Indicates the target end date in Julian format (yyyyddd). Row type: JOB Length: 7 Job_End_Time Indicates the target end time of day in hh:mm:ss format. Row type: JOB Length: 8 Job_Avg_Elapsed Indicates the job lead time or average run time in hh:mm:ss format. Row type: JOB Length: 8 Job_Mainid Indicates the CPU on which the job can or cannot be scheduled. Row type: JOB Length: 8 Job_DR_Class Indicates the job disaster recovery class. Row type: JOB Length: 8 Job_WLB_Class Indicates the job workload balancing class. Row type: JOB Length: 1
Job_Maint_Flag Indicates whether the job is a MAINT job (Y or N). Row type: JOB Length: 1 Job_Xplat_Target Reserved for future use. Row type: JOB Length: 64 Job_Xplat_Flag Indicates whether the job is an XPJOB job (Y or N). If WCC flags the job as a CA7TOUNI job, this field will also be a Y after the next cycle. Row type: JOB Length: 1 Job_Nonexec_Flag Indicates whether the job is marked as EXEC=NO (Y or N). Row type: JOB Length: 1 Job_Verify_Flag Indicates whether the job is marked as VERIFY=YES (Y or N). Row type: JOB Length: 1 Job_Locked_Flag Indicates whether the job is locked (Y or N). Row type: JOB Length: 1 Job_Hold_Flag Indicates whether the job is marked as HOLD=YES (Y or N). Row type: JOB Length: 1 Job_JCLOverride_Flag Indicates whether the job is marked as OVERRIDE=YES (Y or N). Row type: JOB Length: 1
Job_Trig_Job_Flag Indicates whether the job triggers one or more other jobs (Y or N). Row type: JOB Length: 1 Job_Trig_Loop_Flag Indicates 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 in the trigger path of a chain. For example: JOBA/001 triggers JOBB/001 triggers JOBA/001. The 2nd JOBA is a duplicate. Row type: JOB Length: 1 DS_Perm_Flag Indicates whether the data set is marked permanent (Y or N). Row type: DSN Length: 1 DS_Internal_Flag Indicates whether the data set is marked internal (Y or N). Row type: DSN Length: 1 DS_Cpost_Flag Indicates whether the data set is posted at creation time (Y or N). Row type: DSN Length: 1 DS_Auto_Flag Indicates whether the data set is AUTO type (Y or N). Row type: DSN Length: 1 DS_GDG_Flag Indicates whether the data set is a GDG (Y or N). Row type: DSN Length: 1
Manual_Add Indicates whether this object was manually added to the flow using an ADDJOB or ADDDS command (Y or N). Row type: JOB,DSN Length: 1 Job_WLB_Priority Indicates 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 then down. Page 001.002 is immediately to the right of page 001.001. Page 002.001 is 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 job name 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 be displayed are controlled by the JOBBOX keyword on the FLOWCHART command. For example, if JOBBOX=(SYSTEM,BEGIN,END,MAINID) is specified, a job might 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 of the box when appropriate: If the job is marked as maintenance only, MAINT is placed on the top line on the left. J-MAINT--------+ If the job is marked as non-executable, NOEX is placed on the top line on the right. J---------NOEX-+
If the job is marked as a cross-platform job, XPLAT is placed on the bottom line on the left. +XPLAT---------+
If the job was manually added to the flow as the result of an ADDJOB command, 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 job that is scheduled or triggered, the predecessor job is marked with SOFT on the 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. The data 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 top line on the right. D----------GDG-+ If the data set is marked to be posted at creation, POST is placed on the line above the data set number, right-justified. If the data set is marked as external, EXT is placed on the bottom line on the left. +EXT-----------+ If the data set was manually added to the flow as the result of an ADDDS command, 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 a requirement for a job that is scheduled or triggered, SOFT is placed on the bottom line on the right. +----------SOFT+
Pointers
A pointer object is shown in a flowchart when a job or data set appears more than once. The first time a job or data set is shown, it appears as a normal job or data set object, as described previously. A pointer is shown in all other places where the job or data set is referenced. A pointer for a job looks like this: J------ -------+ jobname /nnn tag>>>xxx.yyy The job's name and schedule ID are shown. The tag is a unique three-digit number to help you find where the original object is. The xxx.yyy is the page number on which you'll find the tag number. The tag number is on the connection immediately above the object. For example, if the pointer shows the following: 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 is detected. An example of a trigger loop is JOBA schedule ID 1 triggers JOBB schedule ID 1, which triggers JOBA schedule ID 1 again. Instead of a tag and page 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 is exhibited only to let the viewer know that a dependency exists. Both negative and conditional dependencies are shown. No additional information about the job 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. The connections always go down and to the right. The connection is labeled to show what type of connection it is. The character used to print the connection may also indicate the type of connection. In general, 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. If more than one type of connection is being shown, the vertical bar (|) is used. The following types of connections are shown: COND Identifies a conditional dependency. DRJ Identifies a data set required by job. DTJ Identifies a data set that triggers a job. INDJRJ Identifies a job required by job indirectly. This connection type is shown only when data sets are being excluded from the display. If JOBA creates data set X, and data set X is required by JOBB, the flowchart shows JOBA as an indirect requirement of JOBB. INDJTJ Identifies a job that triggers a job indirectly. This connection type is shown only when data sets are being excluded from the display. If JOBA creates data set X, and data set X triggers JOBB, the flowchart shows JOBA indirectly triggering JOBB. JCD Identifies a job that creates data set. JRJ Identifies a job required by job.
JTJ Identifies a job that triggers a job. NEGDEP Identifies a negative dependency. REPEAT Identifies 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 is updated, jobs PAYME03 and PAYME04 are triggered (DTJ = Data set Triggers Job). These jobs also have a data set dependency of the data set (DRJ = Data set Required by Job).
Sample FLOWCHART TYPE=CSV File (Partial)

The following is a sample of comma-separated values for the FLOWCHART TYPE=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_Targe t","Job_Xplat_Flag","Job_Nonexec_Flag","Job_Verify_Flag","Job_Locked_Flag","Job_Hold_Flag","Job_JCLOverride_Flag","Job_T rig_Job_Flag","Job_Trig_Loop_Flag","DS_Perm_Flag","DS_Internal_Flag","DS_Cpost_Flag","DS_Auto_Flag","DS_GDG_Flag","Manua l_Add","Job_WLB_Priority" "1","JOB",,,,"2","PAYME 1"," 1",,,"SYSTNAME",,"N","N","Y","2 A","N",,"N","N","N","N","N","N","N","N",,,,,,"N","1 " "1","XCN","TR",,"2" "1","XCN","TR",,"3" "2","DSN",,,,"1",," "13" "3","DSN",,,,"4",," "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 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",," "5","XCN","PR",,"16" "6","DSN",,,,"2",," "6","XCN","TR",,"7" "6","XCN","PR",,"7" "7","JOB",,,,"4","PAYME1 "," 1",,,"TEST1 ",,"N","N","N","2 ,"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 B","N" ,,"N","N","N","N","N","N","Y","N",,,,,,"N","1 " "8","XCN","RP",,"9" "8","XCN","TR",,"1 " 7 9 "," 7:59: ","2 7 9 "," 8: : "," : 1: ","ALL",," 7 9 "," 8:15: ","2 7 9 "," 8:16: "," : 1: ","ALL",,"A" 1","COMPANY.DAILY.PAYME 9","7",,,"N","N",,,,,,,,,,,,,,,,,,,,"N","Y","N","Y","N","N" 1","COMPANY.DAILY.PAYME 8","9",,,"N","N",,,,,,,,,,,,,,,,,,,,"N","Y","N","N","N","N" 7 9 "," 7:59: ","2 7 9 "," 8: : "," : 1: ","ALL",," 1","COMPANY.DAILY.PAYME 1","8",,,"N","N",,,,,,,,,,,,,,,,,,,,"N","Y","N","N","N","N""2","XCN","PR",, 1","COMPANY.DAILY.PAYME 2","6",,,"N","N",,,,,,,,,,,,,,,,,,,,"N","Y","N","Y","N","N" 7 9 "," 7:59: ","2 7 9 "," 8: : "," : 1: ","ALL",,"
Appendix A. CA7TOUNI Conversion Utility

This section contains the following topics: PHASE I . . . . . . . . . . . PHASE II . . . . . . . . . . . . . . . . . . . . Clean-Up Conversion Utility Messages Pre-Conversion Utility . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
323 332 334 335 341
The CA7TOUNI to XPJOB conversion utility lets users convert existing CA7TOUNI cross-platform jobs to XPJOB type job definitions. The conversion process consists of two phases. The first phase reads existing CA7TOUNI JCL members, extracting the information necessary to build the new XPJOB definition. The second phase takes that output as BTI input and defines the XPJOB in the CA 7 database. The conversion utility has two benefits. First, it provides a semi-automated mechanism for changing your CA7TOUNI jobs to XPJOB definitions. Second, it maintains any requirements, triggers, and schedules associated with the original CA7TOUNI job. Due to the complexity of the conversion process, the following assumptions must be true or the conversion fails: The job must have successfully executed in a CA 7 environment without QJCL updates. CA7TOUNI jobs that have run successfully should convert, assuming the remaining assumptions are met. Jobs that have not run successfully most likely have errors that would preclude their successful conversion. All CA7TOUNI jobs to convert must reside in a PDS in non-compressed format. You must move JCL that resides in a source control product (for example, CA Endevor and CA Librarian) to a PDS. Only one PDS can be processed 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 7 CA7TOUNI job definition must exist. If the same member does not exist in CA 7, the conversion fails or worse, wipes out a CA 7 job definition having the 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 parameter is specified, which sites do not want displayed. If your site has SYSIN DD data sets in their CA7TOUNI JCL, you must run the pre-conversion utility to convert these data sets to instream data. Use the output data set from the pre-conversion utility as input to the conversion utility.
A NODE parameter must exist in the CA7TOUNI job definition, either in the //PROFILE data set or in the SYSIN data. Multiple NODE parameters in either location prevent the member from being converted. A SUBFILE parameter must exist in the CA7TOUNI job definition SYSIN data. Multiple SUBFILE parameters will prevent the member from being converted. Any # cards in the CA7TOUNI JCL stream prevent the member from being converted. The # cards are allowed in the CA7TOUNI SYSIN data as long as they follow the NODE and SUBFILE parameters.
The conversion utility generates a report that shows the processing for each member. Numerous error messages may be generated that indicate conversion was not possible. However, if the assumptions listed previously are met, the conversion is expected to be successful. It is expected, but not required, that the CA7TOUNI member job consists of a single step. An input parameter is provided that lets you specify if the first step invokes a CA 11 RMS procedure. In this situation, the first step is ignored. Any steps after the CA7TOUNI step are also ignored, and a warning message is generated to that effect.
PHASE I
In Phase I, the conversion utility program, SASSX2UN, is executed in a batch job. The batch job consists of two steps. The first step executes IEBCOPY, which creates a backup copy of the PDS against which the conversion is performed. The PDS can contain CA7TOUNI JCL, conventional CA 7 job JCL or both. You do not need to separate out CA7TOUNI JCL. The second step executes program SASSX2UN. Only PDS members whose first statement begins with #7UNI are eligible for selection. All other members are bypassed. The JCL is shown in the following (see member XPJCONV in SAMPJCL).
//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=$2 RMSEXEC=RMSPROC MEMBER=AAAA MEMBER=B?CA MEMBER=DDDD //
The JCL that executes the SASSX2UN program consists of three input and three 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 also contain JCL for conventional CA 7 jobs. Only JCL whose first card starts with #7UNI will be selected for conversion. This data set must be defined to CA 7 as a CA 7 JCL library. #7UNI jobs can execute the CA7TOUNI program 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=YES NODE=TESTPLN SUBFILE=CAU9TEST #7UNI //jobcard //SUBMIT EXEC CA7TPROC,PARM='&C_L27#,&C_L2SN' //SYSPRINT DD SYSOUT= //SYSIN DD 7TRACE=YES NODE=TESTPLN SUBFILE=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 the CARPROC DD statement. If a site ran the pre-conversion utility, the final output from that job should be used here in place of the original CA 7 JCL library. SASSX2UN CARPROC Statement (Required) The CARPROC data set identifies the data set containing any defined CA7TOUNI JCL procedures and is required, even if no JCL procedures are used to execute the CA7TOUNI program. In this situation, supply an existing procedure library such as SYS2.PROCLIB or USER.PROCLIB. It is only used if a JCL procedure is found in the #7UNI member being processed.
PHASE I
SASSX2UN SYSIN Statement (Optional) The SYSIN data set contains processing keywords used by SASSX2UN. If this statement is not supplied, the following processing occurs: All CA7TOUNI members in the PDSDD data set are eligible for selection. No restore commands for backout are generated. Thus, you cannot restore your original CA7TOUNI CA 7 job definition. CA 11 RMS steps are not permitted. The first step in the CA7TOUNI JCL is assumed to invoke the CA7TOUNI program.
If the SYSIN DD statement is supplied, processing is influenced by the keyword/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 DD statement must be supplied and have PDSDDDSN keyword specified. RESTMASK Defines a 2-character value that creates the restore name of the CA7TOUNI job definition. If a RESTMASK is not provided, a backup of the CA7TOUNI job definition is not created. The member being converted will have a character in its name replaced by the mask. The first character is the replacement character, and the second character indicates 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 mask character is placed in the first blank position of the member name. For example: 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 the member name, you could end up with duplicate member names and get undesirable results during conversion. In the preceding situation, CA7Y would 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 the value used when creating the restore name.
PHASE I
Before conversion, ensure that your CA 7 database has enough space to hold backup copies of the CA7TOUNI jobs being converted. RMSEXEC Identifies the CA 11 RMS procedure used at your site. The value follows standard JCL procedure naming conventions. If specified, and the first step in the CA7TOUNI JCL contains a PROC that matches the value of this keyword, that JCL is bypassed, and the next step is assumed to contain the CA7TOUNI program or procedure. The last RMSEXEC value specified in the SYSIN DD statement is the value used to identify the CA 11 RMS procedure used at your site. MEMBER Identifies the members you want to convert. The value can be 1 to 8 characters. You can enter up to 512 MEMBER cards. Full masking is supported. 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, and a J in the fifth position are selected for processing. The CA7XJOB is not selected three times for processing, regardless of the order of these three member statements. The first match found results in the member being processed for conversion. If no MEMBER= keywords are found, all members in the input PDS are eligible for selection. PDSDDDSN Identifies the original PDSDD data set name used as input to the pre-conversion utility and is only needed if the site has to run the pre-conversion utility. If the PDSDDDSN keyword was not supplied, and a site ran the pre-conversion utility, the output BTI files produced by the conversion utility will reference the output data set generated by pre-conversion process, not the 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 RESTMASK keyword is found. The first step in the CA7TOUNI job is checked for a JCL procedure called RMSPROC. If found, the JCL procedure is bypassed, and the next step is considered the CA7TOUNI step. If the first step in the job does not execute a JCL procedure called RMSPROC, it is considered the CA7TOUNI step. Members matching the mask or member name provided are eligible for selection. The data set name referenced in the PDSDDDSN keyword will be reflected in the DELETE and SAVE BTI commands. This must reference a valid CA 7 JCLLIB.
RMSEXEC=RMSPROC MEMBER=C?ABC MEMBER=ABC MEMBER=TOUNIJOB PDSDDDSN=ABC.CA7.JOBLIB
Example 2
The following example generates a Restore command for each member selected for processing. The Restore member name has a $ in the fourth position. Because no RMSEXEC keyword is provided, the first step of the job is considered the CA7TOUNI step. All members are eligible for selection because no MEMBER keywords are provided.
RESTMASK=$4
Example 3
This example generates no Restore command because the RESTMASK keyword was not provided. The first step of the job is considered the CA7TOUNI step because no RMSEXEC keyword was provided. All members are eligible for conversion. For this situation, it is more efficient to omit the MEMBER=* entry as each member must be compared to the mask to determine whether it is eligible for selection. If this card is omitted, no mask comparison is performed (just like Example 2), members are automatically eligible 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 data set. The CA 7 commands that will convert the CA7TOUNI job to the XPJOB are written to this data set. Though you can edit the CONVCMDS data set before running it through the Batch Terminal Interface (Phase II), it is not recommended. Examples of the output are shown in the following:
/LOGON TRENT 5 DBM CONVERT,CASE 4 1,BACKUP=C$SE 4 1 XPJOB UPD,CASE 4 1, NODE=CA7NODE, EX1=(C:\PROGRA1\WINDOW3\MPLAYER2.EXE), MEMBER=CASE 4 1, SUTYPE=Y JCL DELETE,CASE 4 1,DSN=APCDAL.DEVCA7.CA31CA76.JOBLIB JCL,CASE 4 1 EDIT MIXED XSEQ I , PARM1=C:\MUSIC.MP3 SUBUSER=CA7USER $IEND SAVE SAVE,CASE 4 1,DSN=APCDAL.DEVCA7.CA31CA76.JOBLIB CLEAR DBM XNODE ADD,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 the JCL/EDIT/MIXED/XSEQ/I and $IEND/SAVE/CLEAR commands. XNODE ADD commands are present for each unique node. Ensure that your VRM database 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 noted previously can be entered by itself and succeed or fail. For example, the CONVERT and XPJOB commands could fail, but the JCL DELETE command could succeed. Thus, you are left with a CA7TOUNI job definition and no CA7TOUNI JCL (remember you do have a backup from the IEBCOPY step). Two conditions can cause the conversion to fail. The JCL member name contains the #7UNI statement and appropriate CA7TOUNI parameters but the definition in CA 7 does not indicate a CA7TOUNI job. If the assumptions identified at the beginning of this section are true, this should not occur. The Restore name provide already exists.
Regarding the second bulleted item, consider this example where the RESTMASK was set to 8$ (so the last character of the member name is changed to the mask character). CONVERT,ABCDE1,BACKUP=ABCDE$ CONVERT,ABCDE2,BACKUP=ABCDE$ Job ABCDE1 completes successfully. Job ABCDE2 fails because the backup name already exists. Job ABCDE2's JCL stream is deleted. A backup of the ABCDE2 CA7TOUNI JCL exists in the copy of the PDSDD PDS created in the first job step. Important! Ensure that duplicate backup members do not exist, or will not exist, when the CONVERT command is executed. SASSX2UN RESTCMDS Statement (Required) The RESTCMDS data set is a physical sequential output data set. The CA 7 commands that will restore the XPJOB back to the CA7TOUNI job are written to this data set. The Restore command is a single line command. RESTORE,CA7XJOB,BACKUP=CA7$JOB The Restore command is a destructive command. It wipes out an XPJOB definition created by the Convert command. If the Restore command is executed, you will also need to copy the original CA7TOUNI JCL from the backup data set (created during the conversion process) to the appropriate CA 7 JCL library. Remember, if a RESTMASK is not provided, no back-up of the CA 7 job definition will be created because no RESTORE command is generated. To restore, 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 the IEBCOPY 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 the conversion process are written to this data set. Inspect this report thoroughly before proceeding to Phase II. If your sites' CA7TOUNI job definitions meet the assumptions defined in the first part of this section, you should only see informational and, possibly, warning messages. A sample of the report is shown below. All possible messages are shown in Conversion Utility Messages on page 335.
SASSX2UN- 1 CA-7 CA7TOUNI Conversion Utility DATE: 1 /25/yy MEMBER CASE 1 1 SELECTED FOR PROCESSING MEMBER CASE 1 1 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE 1 ERROR MEMBER CASE 1 1 NO NODE KEYWORD FOUND. CANNOT CONVERT THIS M MEMBER CASE 1 6 SELECTED FOR PROCESSING MEMBER 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 MESSAGES MEMBER CASE 1 7 SELECTED FOR PROCESSING MEMBER 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 MESSAGES MEMBER CASE 1 8 SELECTED FOR PROCESSING MEMBER 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 MESSAGES MEMBER CASE 1 9 SELECTED FOR PROCESSING MEMBER 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 MESSAGES MEMBER CASE 11 SELECTED FOR PROCESSING MEMBER CASE 11 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE 1 MEMBER CASE 11 CONVERT COMMANDS SUCCESSFULLY CREATED MEMBER CASE 11 RESTORE COMMANDS SUCCESSFULLY CREATED MEMBER CASE 111 SELECTED FOR PROCESSING MEMBER CASE 111 PROFILE DSN IS CA7.SASSX2UN.PROFILE.CASE 1 MEMBER CASE 111 CONVERT COMMANDS SUCCESSFULLY CREATED MEMBER CASE 111 RESTORE COMMANDS SUCCESSFULLY CREATED Total Members................................ 7 Members Selected for Conversion.............. 7 Members Successfully Converted............... 2 Members Not Converted........................ 5
PHASE I
SASSX2UN Return Codes

The conversion utility program (SASSX2UN) returns one of the following four return codes: RC=0 Indicates that the job ran successfully, only informational messages are written to the REPORT DD statement. RC=4 Indicates that the job ran successfully but one or more members had warning messages issued. Check the warning messages in the REPORT DD statement and determine whether any action is necessary. RC=8 Indicates that the job ran successfully but one or more members had errors that prevented conversion statements from being created. Check the error messages in the REPORT DD statement and determine whether any action is necessary. RC=12 Indicates 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 they were entered. User-ID and password information extracted from the job statement, //*LOGONID card, //*JOBFROM statement, or //*PASSWORD card is written out first, followed by keyword information extracted from the PROFILE data set and then the SYSIN data stream. The JOBNO, JOBSET, MONITOR, SUBCHECK, and 7TRACE CA7TOUNI keywords are not valid for XPJOB definitions and ignored.
PHASE I
PHASE II
In Phase II, the Batch Terminal Interface (BTI) procedure is executed. This job uses the Phase I output file CONVCMDS as input. JCL to execute this procedure 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 is not a CA7TOUNI job definition, the command will fail. If the BACKUP= parameter is specified on the CONVERT command, and the backup member exists, the command will fail. Standard error processing is followed for all other commands (such as XPJOB, JCL, SAVE, CLEAR) that may be found in the deck. When the BTI job completes, thoroughly inspect the output report and resolve any 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 than 71 characters and cause your conversion to fail.
Execute the CONVERT Command Online

You can enter the CONVERT command within CA 7 from any panel. The command creates an XPJOB shell definition that cannot be executed. You must update this definition, providing the XPJOB information described in the Database Maintenance Guide, and modify the "JCL" as necessary with the CA7TOUNI parameter statements. We do not recommend using the CONVERT command in the CA 7 online environment. The following is an example of executing the CONVERT command from an online 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 found in the RESTCMDS DD data set and the BTI JCL stream, as shown in the following: //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 paste only those members you wish to restore to another data set and use that as your BTI input. Or, you can log on to your CA 7 environment and execute it as an 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 copy the CA7TOUNI JCL from the Phase I IEBCOPY back-up to the appropriate CA 7 JCL library.
Clean-Up
Clean-Up
As stated in the beginning of this section, this process maintains any requirements, triggers, and schedules associated with the original CA7TOUNI job. It also maintains PROFILE and STEPLIB data set definitions resulting from the original CA7TOUNI LOAD, or done using the DB.6 panel. These definitions are not required for the XPJOB type jobs and may be deleted using the DB.6 panel. Review your original JCL or CA7TOUNI procedure to determine the PROFILE and STEPLIB data sets.
Conversion Utility Messages

The following messages can appear in the conversion utility REPORT DD statement.
Informational Messages
MEMBER xxxxxxxx SELECTED FOR PROCESSING Reason: This message indicates the member contained the #7UNI statement and was selected for conversion processing. MEMBER xxxxxxxx CONVERT COMMANDS SUCCESSFULLY CREATED Reason: This message indicates that the member was successfully processed and that CONVERT BTI commands for this member have been placed in the CONVCMDS DD data set. MEMBER xxxxxxxx RESTORE COMMANDS SUCCESSFULLY CREATED Reason: This message indicates that the member was successfully processed and that RESTORE BTI commands for this member have been placed in the RESTCMDS DD data set. 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 the member 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 CACCENV member 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 steps and determine what action must be taken when the job is converted to an XPJOB since these 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 a SUBUSER parameter statement from any of these statements if the value is eight characters or less. *** WARNING *** - MEMBER xxxxxxxx VALUE FOR PASSWORD EXCEEDS 14 CHARACTER MAXIMUM Reason: A CA7TOUNI job had a PASSWORD= parameter on the job statement, or a //*PASSWORD statement. The conversion utility will create a SUBPASS parameter statement from either of these cards if the value is 14 characters or less. *** WARNING *** - MEMBER xxxxxxxx VALUE FOR USER=/LOGONID/JOBFROM OR PASSWORD NOT 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 either SUBUSER or SUBPASS parameter statements from these statements their value is valid. *** WARNING *** - MEMBER xxxxxxxx SUBROOT PARM FOUND. SEE XPDEF INIT DECK PARM FOR SUBROOT DETAILS Reason: A CA7TOUNI job had SUBROOT parameter. This parameter is processed differently in XPJOB definitions. For more information about this processing, see the XPDEF 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 error messages in the REPORT DD output (for the member) will explain the exact cause of the problem. *** ERROR *** - MEMBER xxxxxxxx MULTIPLE NODES FOUND IN SYSIN DATA. CANNOT CONVERT 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. CANNOT CONVERT THIS MEMBER Reason: The member listed has multiple NODE parameter entries in the PROFILE data set. The conversion utility allows for a maximum of one entry in the PROFILE data set. *** ERROR *** THIS MEMBER MEMBER xxxxxxxx # CARDS FOUND BEFORE THE NODE. CANNOT CONVERT
Reason: The member listed has # statements before the NODE parameter in the SYSIN data. # 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. CANNOT CONVER 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. CANNOT CONVERT THIS MEMBER Reason: The member listed has # statements before the SUBFILE parameter in the SYSIN data. # statements are typically used for substitution and are resolved at job submission. The utility cannot determine how to process a SUBFILE parameter that follows a # statement. *** ERROR *** - MEMBER xxxxxxxx SYSIN DSN OR PROC FOUND IN SYSIN. CANNOT CONVERT THIS MEMBER Reason: The member listed has a SYSIN data set or PROC concatenated to the SYSIN DD statement. It is assumed a SYSIN data set will contain a SUBPASS parameter the site does not want displayed so the member is not processed. Anything concatenated to the SYSIN DD * statement will cause an error. *** ERROR *** - MEMBER xxxxxxxx PROC/PGM= VALUE EXCEEDS 8 CHARACTERS. CANNOT CONVERT THIS MEMBER Reason: The member listed has a JCL error. The JCL procedure or the program name exceeded 8 characters. 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 READ PAST EOL SEARCHING PROC/PGM LINE. CANNOT CONVERT THIS MEMBER Reason: The member listed has a JCL error. 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 NO VALUE PROVIDED FOR PGM= OR PROC NAME. CANNOT CONVERT MEMBER Reason: The member listed has a JCL error. 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 PROFILE DSN EXCEEDS 44 CHARACTERS. CANNOT CONVERT THIS MEMBER Reason: The member listed has a JCL error. Data set names cannot exceed 44 characters. 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 READ PAST EOL SEARCHING //PROFILE DSN. CANNOT CONVERT MEMBER Reason: The member listed has a JCL error. 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 NO VALUE PROVIDED FOR PROFILE DSN. CANNOT CONVERT THIS MEMBER Reason: The member listed has a JCL error. No value was provided for the PROFILE data set. 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 MEMBER xxxxxxxx PROFILE DSN NOT FOUND. CANNOT CONVERT THIS
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. CANNOT CONVERT 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. CANNOT CONVERT THIS MEMBER Reason: The member listed has # statements before the SYSIN data. # cards are typically used for substitution and are resolved at job submission. The utility cannot determine how to process JCL when # statements are present.
*** ERROR *** MEMBER
MEMBER xxxxxxxx NO SUBFILE KEYWORD FOUND. CANNOT CONVERT THIS
Reason: The member listed has no SUBFILE parameter in the SYSIN DD data. XPJOB definitions require a SUBFILE. If one is not found the job cannot be converted. This message is also displayed if the first step found in the member is NOT the CA7TOUNI step and does NOT match the RMSEXEC parameter value. *** ERROR *** MEMBER MEMBER xxxxxxxx NO NODE KEYWORD FOUND. CANNOT CONVERT THIS
Reason: The member listed has no NODE parameter. XPJOB definitions require a NODE. If one is not found the job cannot be converted. *** ERROR *** - MEMBER xxxxxxxx SYSIN KEYWORD CARDS EXCEEDED MAXIMUM. CANNOT CONVERT THIS MEMBER Reason: The member listed has over 400 lines of SYSIN data. The member has exceeded the maximum allowed. *** ERROR *** - MEMBER xxxxxxxx TOO MANY KEYWORD LINES IN PROFILE DSN. CANNOT CONVERT THIS MEMBER Reason: The member listed has over 25 lines of keywords, used by CA7TOUNI, in the PROFILE 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 not execute the CA7TOUNI program. *** ERROR *** - MEMBER xxxxxxxx RESTORE NAME FOUND IN PDSDD FILE. CANNOT CONVERT MEMBER Reason: The RESTMASK keyword was supplied to the Conversion Utility. A check is performed to see if the member name generated for the back-up (using the RESTMASK value) exists in the PDSDD file. If this member already exists, the member is not converted. *** ERROR *** - MEMBER xxxxxxxx CANNOT BUILD JFCB FOR CARPROC DD. CANNOT CONVERT THIS MEMBER Reason: This member referenced a JCL procedure for CA7TOUNI. The data set referenced in the CARPROC DD statement should contain this member. There was an error trying to access this data set.
*** ERROR *** THIS MEMBER
MEMBER xxxxxxxx UNABLE TO OPEN THE CARPROC DD. CANNOT CONVERT
Reason: This member referenced a JCL procedure for CA7TOUNI. The data set referenced in the CARPROC DD statement should contain this member. There was an error 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 no continuation on a line after a previous line that ends in a + sign. The member is not converted. *** 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. The member is not converted. *** ERROR *** MEMBER xxxxxxxx yyyyyyyy EXCEEDS zzz CHARACTERS
Reason: This member had a keyword (yyyyyyyy) whose value exceeded the maximum size (zzz) allowed. The member is not converted. Note: If you receive this message for the SUBFILE keyword, you must continue to run the job as a CA7TOUNI job. SUBFILE can support lengths up to 256 bytes. The field that it 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 the keyword. The member is not converted.
Pre-Conversion Utility
The CA7TOUNI conversion utility assumes that all CA7TOUNI SYSIN DD data is in-stream. Any CA7TOUNI jobs containing one or more permanent data sets in the SYSIN DD statement are not converted. The Pre-Conversion Utility can be 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 job starting with #7UNI (all other jobs are bypassed) to a new sequential file. It dynamically allocates any permanent SYSIN DD data sets associated with the CA7TOUNI job and adds each record to the new sequential file as part of a SYSIN DD * statement. The sequential file is actually an IEBUPDTE job that contains control cards to add each CA7TOUNI job to a new PDS. After the IEBUPDTE has been run, the new PDS that can be used as input to the conversion utility. The Pre-Conversion Utility consists of three steps. Step 1 reads the PDS containing CA7TOUNI jobs and creates an IEBUPDTE job file and two other files. The report file contains information about each member that was processed. Errors that occurred processing the member can be found in this file. The output data file contains information used in Steps 2 and 3. Step 2 sorts the file. Step 3 generates the Node/JobName report. Because the output data file is a CSV file, it can be downloaded to an Excel spreadsheet or MS-Access database 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 executed with no input parameters, SUBUSER and SUBPASS information is EXCLUDED from the IEBUPDTE job (OUNIJCL). EXEC PGM=SASSX2PD,PARM='SUBUSER' Executing SASSX2PD with this parameter setting will include SUBUSER information in the OUNIJCL file. EXEC PGM=SASSX2PD,PARM='SUBUSER,SUBPASS' Executing SASSX2PD with this parameter setting will include SUBUSER and SUBPASS information in the OUNIJCL file (note SUBPASS information 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 also contain JCL for conventional CA 7 jobs. Only JCL whose first card starts with #7UNI will be selected for pre-conversion. The input file specified on this PDSDD statement must be supplied as the PDSDDDSN keyword value in the conversion utility when it is run.
Output JCL Statements

The following are the output JCL statements: SASSX2PD OUNIJCL Statement This DD statement contains an IEBUPDTE job with all the CA7TOUNI jobs that were processed (with all SYSIN DD data now in-stream). This job is submitted to create the new PDS that will be used as input to the conversion 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 5 SUBFILE=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 2 SubFile=C:\WINDOWS\+ NOTEPAD.EXE / // $$ //
SASSX2PD OREPDATA Statement This DD statement contains a list of jobs that were processed. Specific information 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 for the job. This data set is sorted in Step 2 and used to generate the CA 7 Pre-Conversion Utility Report by Node/JobName. Optionally, you can download this file to a MS-Access database or Excel spreadsheet and process as desired. A sample of the output file follows: TRENT 5 ,PRECNV JAMES 2 ,PRECNV ,PRECNV TRENT 5 ,PRECNV TRENT 5 ,PRECNV 1,USER56789 123456789 123456789 12,YES 2,user ,YES 3,user ,NO 4, ,NO 5,myUserNameLongest89 123456789 12,YES
SASSX2PD REPORT Statement This DD statement is a SYSOUT data set. All informational, warning, and error messages generated during the pre-conversion process are written to this data set. Inspect this report thoroughly before proceeding. If your sites' CA7TOUNI job definitions meet the assumptions defined in the conversion utility section, you should only see informational, and possibly, warning messages. A sample of the report is shown below. The possible messages are shown in Pre-Conversion Utility Messages on page 348.
MEMBER PRECNV13 SELECTED FOR PROCESSING MEMBER PRECNV13 SYSIN DSN IS APCDAL.DEVCA7.CL2111.TESTDATA.B1JF.PDS(T) MEMBER PRECNV13 SYSIN DSN IS APCDAL.DEVCA7.CL2111.TESTDATA.B1JF.SEQDS 1 MEMBER PRECNV13 PROCESSED SUCCESSFULLY MEMBER PRECNV14 SELECTED FOR PROCESSING ERROR MEMBER PRECNV14 SYSIN DSN IS INVALID. CANNOT PROCESS THIS MEMBER
SASSX2PR X2PROUTP Statement This DD statement is a SYSOUT data set. It contains the CA 7 Pre-Conversion Utility Report by Node/JobName. A sample of the report follows:
------------------------------------------------------------------------------SASSX2PR CA 7 Pre-Conversion Utility Report by Node/JobName NODE JOBNAME SUBUSER SUBPASS ------------------------------------------------------------------------------PRECNV 3 user NO Total Jobs Going to Node is 1 MARJA24 PRECNV 8 myuser4 YES MARJA24 PRECNV 9 myuser5 YES MARJA24 PRECNV1 user123 YES MARJA24 PRECNV17 USERNAME4 YES Total Jobs Going to Node MARJA24 is 4 USERX 6 PRECNV19 NO Total Jobs Going to Node USERX 6 is 1 JAMES 2 PRECNV 2 user YES JAMES 2 PRECNV 7 myuser3 YES JAMES 2 PRECNV11 user654 NO JAMES 2 PRECNV13 user654 NO Total Jobs Going to Node JAMES 2 is 4 TRENT 5 PRECNV 1 USER56789 123456789 123456789 12 YES TRENT 5 PRECNV 4 NO TRENT 5 PRECNV 5 myUserNameLongest89 123456789 12 YES TRENT 5 PRECNV 9 Marja24User TRENT 5 PRECNV13 myuser Total Jobs Going to Node TRENT 5 TOTAL JOBS = 15 YES YES is 5
SASSX2PD Return Codes

The Pre-Conversion Utility program (SASSX2PD) returns one of the following return codes: RC=0 Indicates that the job ran successfully. Only informational messages are written to the REPORT DD statement. RC=4 Indicates that the job ran successfully, but one or more of the PDSDD members could not be opened. Check the warning messages in the REPORT DD statement and determine whether any action is necessary. RC=8 Indicates that the job ran successfully, but one or more members had errors that prevented them from being processed. Check the error messages in the REPORT DD statement and determine whether any action is necessary. RC=12 Indicates that the job failed. No IEBUPDTE job was generated. Check the WTO 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 DD statement.
Informational Messages
MEMBER xxxxxxxx SELECTED FOR PROCESSING Reason: This message indicates the member contained the #7UNI statement and was selected for pre-conversion processing. MEMBER xxxxxxxx PROCESSED SUCCESSFULLY Reason: This message indicates the member contained the #7UNI statement and was successfully processed. MEMBER xxxxxxxx SYSIN DSN IS yyyyyyyy Reason: This message indicates the member contained a permanent SYSIN data set that 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 is not a CA7TOUNI job. If it is a CA7TOUNI job, fix the problem and rerun the Pre-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 member is 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. Action: Determine whether the data set exists and should be processed. If the member is bad, delete the member from the new PDS after the IEBUPDTE job has completed.
*** ERROR *** MEMBER xxxxxxxx SYSIN DD OPEN FAILED FOR yyyyyyyy Reason: This message indicates attempts to open SYSIN data set (yyyyyyyy) failed. Action: Determine whether the data set exists and should be processed. If the member is bad, delete the member from the new PDS after the IEBUPDTE job has completed.
Appendix B. Batch Program CA7TOUNI

This section contains the following topics: CA7TOUNI Submission . CA7TOUNI Considerations
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
352 359
Appendix B. Batch Program CA7TOUNI 351
CA7TOUNI Submission
CA7TOUNI Submission
Submission consists of CA 7 submitting a batch job that executes program CA7TOUNI to send execution data through CAICCI to the XPS SERVER on the target platform. The XPS SERVER on that platform in turn submits the job and returns CAIENF tracking data as it executes. Any output from the job will be directed to the XPS SERVER console on that platform. To use this interface, the MVS job must use JCL as described below. The JCL must begin with a #7UNI statement and it must execute CA7TOUNI. All normal scheduling 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 be returned to the ready queue with a CPU indication of 7UWT to denote it is waiting on XPS SERVER submission. If an error occurs, the job will abend and be subject to restart considerations. When execution begins on the target platform, the XPS SERVER will return tracking data and normal job flow will resume. Also, the CPU indication will change to 7UNI. CA7TOUNI has one required and one optional parameter on the EXEC statement. The required parameter is a unique number for tracking. The optional parameter is a jobset name. To facilitate supplying these parameters, we recommend that a CA-Driver procedure be used. The following is an example of such a procedure: //CA7TOUNI //STEP1 // //STEPLIB //PROFILE //SYSPRINT DPROC EXEC PGM=CA7TOUNI, PARM='&C_L27#,&C_L2SN' DD DISP=SHR,DSN=cai.ca7.caiload DD DISP=SHR,DSN=cai.ca7.xps.profile DD SYSOUT=
The CA-Driver variables &C_L27# and &C_L2SN are replaced by CA 7 job number and CA 7 system name (for the job) respectively when the job is submitted by CA 7. The PROFILE DD statement must reference a card image PDS that contains a member named CACCENV. CACCENV contains keyword entries specifying environment parameters for the Submit Function. Note: The security ID under which the Submit job executes must have READ access 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 to send the data. If the same parameter is encountered in multiple sources they will be processed as follows: EXEC parm values override SYSIN and PROFILE values SYSIN values override PROFILE values
The following describe all parameters for CA7TOUNI: DOMAIN This optional parameter can be required for some requests sent to Windows platforms. Limits: 1 to 15 alphanumeric characters Required: No Source: SYSIN or PROFILE Note: The DOMAIN variable will only be accepted from the same source as the NODE variable. That is, they either both have to come from the PROFILE data or both from the SYSIN data. If the DOMAIN variable is supplied from a source other than NODE it will be ignored and the request will be sent without a DOMAIN parameter. JOBNO This required parameter should match the CA 7 assigned job number to provide uniqueness. It must be supplied as the first positional value of PARM input on the EXEC statement. We recommend that you use a CA-Driver procedure to automatically insert the CA 7 job number in the JCL for 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 Job Management Option only supports four-digit job numbers. Only the last four digits are actually sent with the cross-platform request. If the specified job number is less than four digits it will be right-justified and zero-filled.
CA7TOUNI Submission
JOBSET When combined with the JOBNO and batch job name, this variable provides a unique identifier for the cross-platform request. Special characters should be avoided as they may not translate correctly on the target platform. If omitted, the MONITOR value will be used as JOBSET. We recommend that you use a CA-Driver procedure to insert the CA 7 system name in the JCL for this parameter. Default: MONITOR name Limits: 1 to 8 alphanumeric characters Required: No Source: EXEC parm, SYSIN, or PROFILE LINELEN This optional parameter controls the line length of the SYSIN input for the SUBFILE and PARMxx keyword parameters. Normally CA7TOUNI automatically determines if columns 73 to 80 contain line sequence numbers (LINELEN=AUTO). If column 72 contains a blank, null, or plus sign, and columns 73 to 80 are numeric, then columns 73 to 80 are considered to be line sequence numbers. Line sequence numbers are not considered part of the SUBFILE or PARMxx keyword value. The LINELEN keyword can be used to override this automatic determination and force CA7TOUNI to consider the full 80-byte record as part of the data area (LINELEN=80). Or it can force CA7TOUNI to ignore columns 73 to 80 (LINELEN=72) regardless of the contents of those columns. Default: LINELEN=AUTO Limits: AUTO, 72, and 80 are the only allowed values Required: No Source: SYSIN or PROFILE Note: This keyword can be specified multiple times. Processing for SUBFILE and PARMxx keywords is controlled by the last valid LINELEN specification processed before the current line.
CA7TOUNI Submission
MONITOR When combined with the local CAICCI node this parameter uniquely identifies the copy of CA 7 submitting this cross-platform request. The value must be exactly seven characters. CA7PROD should be avoided as this is commonly used by CA NSM Job Management Option. If only one copy of CA 7 is executing, a good choice might be CA7 followed by the SMF-ID of the originating system. If executing multiple CA 7 instances, a good choice may be CA7 followed by the instance name, such as CA7CA73. This value must match the one used by the CA 7 Cross-Platform Tracking System (XTRK). Limits: 7 alphanumeric characters Required: Yes Source: PROFILE NODE This parameter identifies the CAICCI node of the target system for this request. It must match what is defined in CAICCI on that system. Limits: 1 to 8 alphanumeric characters Required: Yes Source: SYSIN or PROFILE PARM1 thru PARM64 These optional parameters supply values to be used on the target platform. Values can be 1 to 256 characters. Special characters should be avoided as they may not translate correctly on the target platform. Embedded blanks will cause the value to be enclosed in double quotes by the XPS SERVER on 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 sign will not appear in the resulting value. Keyword checking will be suspended during a continuation operation. Limits: 1 to 256 alphanumeric characters Required: No Source: SYSIN Note: The contents of columns 73 to 80 can be included or excluded based on the processing controls currently in effect. Normally, line sequence numbers in columns 73 to 80 are ignored. For more information, see the preceding LINELEN parameter.
CA7TOUNI Submission
SUBCHECK This optional PROFILE parameter forces a security check for authorization of the currently running user to submit jobs for the ID supplied in SUBUSER. This can override the instance default that is set by CAIRIM. If the value of BSUBCHK is N, the security check is not done unless SUBCHECK overrides it. For more information about BSUBCHK, see the Security 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. A setting of NO will cause a warning message and the parameter will be ignored. SUBFILE This required SYSIN parameter identifies the script or command to be executed by the XPS SERVER. It has the same size, content and continuation considerations as the previous PARMx values. The script named must reside in a special directory identified to CA NSM Job Management Option or must indicate a fully qualified path name. For more information about Client/Server processing and the CAISCHD0004 variable, see the CA NSM Job Management Option documentation. Limits: 1 to 256 alphanumeric characters Required: Yes Source: SYSIN Note: The contents of columns 73 to 80 can be included or excluded based on the processing controls currently in effect. Normally, line sequence numbers in columns 73 to 80 are ignored. For more information, see the preceding LINELEN parameter. SUBPASS This optional parameter identifies the password to be passed with SUBUSER to the target platform. The password will be sent to the target system in an encrypted format. Some target systems may require that a password accompany the SUBUSER on cross-platform requests. Limits: 1 to 14 alphanumeric characters Required: No Source: SYSIN or PROFILE Note: The SUBPASS variable will only be accepted from the same source as the SUBUSER variable. That is, they either both have to come from the PROFILE data or both from the SYSIN data. If the SUBPASS variable is supplied from a source other than the SUBUSER it will be ignored and the request will be sent without a password.
CA7TOUNI Submission
SUBROOT This optional PROFILE parameter determines whether the special user ID of ROOT can be used for job submission. Since the user ID of ROOT has special meaning and capabilities on many non-MVS platforms, it is best not to use it when submitting work from MVS. By default, ROOT is not allowed by this interface. To submit work using ROOT as the user ID, this parameter 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 SUBUSER This optional parameter identifies the user ID for security purposes on the target platform. If omitted, the user ID of the executing MVS job will be extracted and used. A check will be done to see if the user ID ROOT is being used, in which case submission will be controlled by the setting for parameter SUBROOT. Regardless of the setting for SUBROOT, the use of ROOT as the user ID will cause a WARNING message to be issued. Since the user ID ROOT has special meaning on UNIX platforms, we recommend that ROOT not be specified. Default: Batch job user ID Limits: 1 to 32 alphanumeric characters Required: No Source: SYSIN or PROFILE SUTYPE This optional parameter determines the type of "switch user" command that will be executed if the target node is UNIX. YES Executes an 'SU-' command causing the environment setup to include execution of the '.PROFILE' for the target user. NO Executes an 'SU' command without the profile option. Default: YES Limits: YES, NO, Y and N are the only allowed values Required: No Source: SYSIN or PROFILE
CA7TOUNI Submission
XPHAO Enables the High Availability Option (HAO) for tracking CA7TOUNI jobs. The value must match the value set in the XPDEF file initialization statement XPHAO keyword of the copy of CA 7 that will submit the CA7TOUNI batch job. Default: None Limits: Must match XPDEF XPHAO keyword value Required: No Source: SYSIN or PROFILE 7TRACE This optional parameter can be used to turn on the trace facility to assist in tracking down problems. If the parameter is set to YES additional messages will be written to the SYSPRINT DD that may be helpful in pinpointing exactly when an error is encountered. Default: NO Limits: YES, NO, Y or N are only allowed values Required: No Source: SYSIN or PROFILE Examples: The following is an example of a job to list the status of CA NSM Job Management Option on on the target platform. #7UNI //TESTJOB1 JOB ...jobcard...values... //STEP1 EXEC CA7TOUNI (CA-Driver proc) //SYSIN DD node=newyork subuser=ca7user subfile=unifstat / The following is an example of a CACCENV member. monitor=ca7mvsa jobset=fromca7 Note: If the submit function encounters an error or problem that prevents the request from being sent to the target system, the submit step will abend with a User 4000 code (U4000). See the messages produced in the submit job output to determine the exact nature of the problem.
CA7TOUNI Considerations
CA7TOUNI Considerations
Similar to the Submit Function, any job whose JCL starts with #7UNI is treated as a cross-platform job. When such a job completes on MVS, it is requeued to the ready queue with a CPU indication of 7UWT. The job will stay in the ready queue until another job initiation record is received. When initiation is received the 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 records for each 7UNI job submitted. The first set represents the MVS job that submitted data to the XPS SERVER. The second set represents the job execution on the XPS SERVER platform. This second set will consist of job initiation, step termination, and job termination records only. There will be no data set records, and not all fields will be filled in for the other records. Concerning restart considerations, we recommend that 7UNI jobs not include a CA 11 restart step or have CA 7 insert such a step. Including CA 11 is unnecessary since these jobs will consist of a single step, produce no data sets and 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 to another system. Many platforms are case sensitive to their input; however unless CA 7 Mixed Case Editing is enabled, the CA 7 editor forces all data to uppercase. Therefore, edit functions of CA 7 can only be used against JCL for cross-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 edit related 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 of CA 7, such as TSO/ISPF or CA Roscoe. If the JCL must be changed after the job enters the queues, change the JCL outside of CA 7. Next, cancel and demand a new version of the job. If the job was scheduled or triggered and cannot be canceled and demanded, change the JCL outside CA 7. Use the JCL panel to FETCH it (do not use FE or EDIT). Next use the QJCL panel to REPL the request queue job's JCL thus bypassing the CA 7 editor.
Appendix C. XTRK as a STC or Job

This section contains the following topics: CA 7 Cross-Platform Tracking JCL . . . . CA 7 XPS Client Implementation Checklist
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
362 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 Tracking System (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)... //XPRINT DD SYSOUT= //XSNAP DD SYSOUT=
optional
The XCKPT DD must point to a CA 7 Cross-Platform Checkpoint file. Each copy of XTRK must have its own Checkpoint file. The DCB parameters for Checkpoint 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 have to be preformatted. The XEVENTS DD is optional. If specified, it should point to an 80-byte statement-image sequential data set, or PDS member, which contains CA 7 cross-platform external tracking rules. These rules define what events that occur on other systems should be tracked by CA 7 even though CA 7 did not submit the work that caused these events to take place. See CA 7 Cross-Platform External Tracking on page 218 for information about the format of these rules. The EXEC PARM values for XTRK are: PARM='monitor,ca 7 instance name,trace-codes' monitor This required parameter is the seven character monitor name that uniquely identifies the copy of CA 7 whose cross-platform jobs are to be tracked. It must match the MONITOR= value used by the CA 7 Cross-Platform Submit jobs to be tracked (CA7TOUNI). ca 7 instance name This optional parameter specifies the instance name of the CA 7 for which this copy of XTRK is collecting. This parameter controls which copy of CA 7 will receive the pseudo-SMF feedback generated by this copy of XTRK. The primary copy of CA 7 (called the production copy in r3.3) has an instance name of CA71. The secondary copy of CA 7 (called the test copy in r3.3) has an instance name of CA72. Other available instances are named CA73 through CA78. The values PROD or UC07 can be used instead of CA71, and the values TEST or UCT7 can be used instead of CA72. Note: The RNAME value does not affect this setting.
trace-codes These optional codes specify the level of diagnostic messages and snaps that should be generated by XTRK. There are two codes that can be specified: print/snap trace code and console message trace code. The first value controls what messages will be written to the XPRINT DD, and what records and control blocks will be written to the XSNAP DD. The second value 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 only honored for the console trace code. If entered for the print trace code it will be interpreted the same as a code of 1. NORMAL MESSAGES/WTOS. These messages indicate XTRK system startup and shutdown. They also indicate when communication with remote systems is first established, if such communication is lost, and if it is reestablished. FEEDBACK MESSAGES/WTOS. Besides the messages issued for trace code 1, messages relating to cross-platform feedback events will be issued. COMMUNICATION MESSAGES/WTOS. Besides the messages issued for trace code 2, messages relating to CCI communications with other systems will be issued. Also, messages will be issued for pseudo-SMF records generated and sent to CA 7. Also, if the XSNAP DD is available, snap dumps will be taken of the storage areas related to CCI control blocks and records, as well as pseudo-SMF records. PROGRAM PATH MESSAGES/WTOS. Besides the messages issued for trace code 3, messages relating to internal XTRK processing will be issued. Also, if the XSNAP DD is available, snap dumps will be taken of the storage areas related to XTRK control blocks, besides the communication and feedback related snaps. Note: Trace code 4 should only be used at the direction of CA Technical Support Support since it will produce a significant number of messages. 5-9 Currently trace codes 5 through 9 do not have specific definitions. If entered, they will be interpreted the same as trace code 4.
Note: Messages that indicate critical errors will always be issued as WTOs regardless 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 monitor name is 'CA7IPO1', a print trace code of '3' and a console trace code of '1', the parm 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-Platform Connections on page 203. These CAICCI connections are the same regardless of which side is acting as the XPS CLIENT or XPS SERVER. Note: This interface requires CA Common Services for z/OS. If you are communicating with a Windows platform and also have CA WCC on the same machine, you must ensure that CAICCI Remote Services and the CAICCI-PC Properties use different System Names for the Windows machine. The CAICCI Remote Services System Name is defined in file CCIRMTD.RC (local node). The CAICCI-PC Properties System Name can be 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 Program CA7TOUNI on page 351. 3. Allocate CA 7 XTRK Checkpoint files. See CA 7 SAMPJCL member XPSCKPT and CA 7 Cross-Platform Tracking JCL on page 362. Note: This may have been completed when installing or upgrading CA 7 and 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 on SYSGEN) and CA 7 Cross-Platform Tracking JCL on page 362. This procedure may appear in the PROCLIB if the CA07N020 installation job was executed. 5. Define the CA-Driver Procedure for the CA 7 XPS Submit Function. See CA 7 SAMPJCL member CA7TOUNI and Appendix B, Batch Program CA7TOUNI on page 351. If you are not familiar with CA-Driver, see Chapter 4, CA Driver Procedures, Variable Parameters, and Functions on page 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, Batch Program CA7TOUNI on page 351. The jobs should be defined and scheduled 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 the specified platform (XPS Server), and the feedback will be returned to CA 7 (XPS Client).
Appendix D. XTRK Under ICOM

This section contains the following topics: Cross-Platform Tracking ICOM PARM Values . . . . . Cross-Platform Tracking ICOM DD Statements . . . . Cross-Platform Tracking ICOM WTOR/MODIFY Replies
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
368 369 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 a subtask in the ICOM address space, add the following parameters to the SASSICOM EXEC statement. XMONITOR=monitor-name This required parameter is the seven-character monitor name that uniquely identifies each copy of CA 7 whose cross-platform jobs are to be tracked. It must match the MONITOR= value used by the CA 7 Cross-Platform Submit jobs to be tracked (CA7TOUNI). Note: This parameter is required if you want to execute the CA 7 XTRK system in the ICOM address space. If this parameter is specified then the XCKPT DD statement for the CA 7 Cross-Platform Tracking Checkpoint file must be present in the ICOM JCL. XTRC=trace-codes These optional codes specify the level of diagnostic messages and snaps that should be generated by XTRK. Two codes can be specified: print/snap trace code and console message trace code. The first value controls what messages will be written to the XPRINT DD, and what records and control blocks will be written to the XSNAP DD. The second value controls what WTOs are issued to the system console. The default trace code is 'XTRC=21'. For more information about trace code values, see CA 7 Cross-Platform Tracking JCL on page 362. Note: If used, the XMONITOR= and XTRC= keywords should be added to the end of the SASSICOM parameter list and preceded by commas to separate them 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 a sub-task in the ICOM address space the following DD statements should be added to the SASSICOM JCL. XCKPT (Required if the XMONITOR keyword is specified in the SASSICOM EXEC parameters) Points to a CA 7 Cross-Platform checkpoint file. Each copy of XTRK must have its own checkpoint file. That is, if you are running ICOM on two separate mainframe images and you want to run CA 7 XTRK, each copy 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 PDS member, which contains CA 7 cross-platform external tracking rules. These rules define what events that occur on other systems should be tracked by CA 7 even though CA 7 did not submit the work that caused these events to take place. For information about the format of these rules, see CA 7 Cross-Platform External Tracking on page 218. Note: If you are running CA 7 XTRK on multiple mainframe images, you should not specify the same external tracking rules for more than one copy of CA 7 XTRK. This could cause CA 7 to receive multiple copies of the same 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 is controlled by the first value of the XTRC= keyword in the SASSICOM EXEC parameters. XSNAP (Optional) Specifies a SYSOUT class for CA 7 Cross-Platform Tracker (XTRK) storage snap output. The type and volume of output produced is controlled by the first value of the XTRC= keyword in the SASSICOM EXEC 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 subtask of ICOM you can pass commands to the XTRK task using the CA-7.575 WTOR or a MODIFY command. Responses to these commands are issued as WTOs and 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 to XTRK issue: F CA7ICOM,XTRK=NODE For more information about specific XTRK commands, see CA 7 Cross-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 BTI (continued) overview 71 parameters 79
C
CA 7 CA 7 Job Management Smart Console Option 64 CA 1 interface 17 CA 11 ARTS Command Monitor 20 automatic CMT updating 21 RMS insertion 21 interface 19 CA APCDDS interface 22 CA APCDOC interface 22 CA Dispatch interface 24 CA Driver activating 121 branching conditional 156 unconditional 154 commands 153 comments 161 functions 147 overview 121 procedure library 125 procedure, expanding 153 reserved-name variable parameters 137 sequence numbers 136 variable parameters 130 CA Earl reporting 26 CA Easytrieve reporting 26 CA JCLCheck interface 26 CA Librarian interface 28 CA Netman interface 28 CA NSM Job Management Option 201 CA Opera interface 35 CA OPS/MVS interface 35 CA Panvalet interface 36 CA Service Desk 52 CA Workload Control Center 22 CA-Driver cross-platform scheduling 352
A
activating CA Driver 121 allocating space 175 ampersand (&) (CA Driver) 134 API requirements 40 arrays 142 ARTS command 20 asynchronous processing time (NCF) attribute testing 144
178
B
Batch Card Load program See BCLP batch commands format 74 installation process 76 batch step execution 86 BCLP ABORT 107 and NJE 184 and U7SVC facility 85 CA 7 requirements 106 control statements 109 DB 107 DBPARMS 108 description 106 ERR 107 EXITPROG 107 JCL requirements 107 using 106 BPXBATCH program 68 BTI and WLM 69 N220 job 76
Index 371
CA7TOUNI converting to XPJOB 321 CAICCI CCI interface 71 cross-platform scheduling 212 CAICCI connections 203 CAIENF events 212 CAIRIM requirement for 165, 176 resource initialization manager 166, 168 CAISMFI dynamic SMF event interceptor 168 calculating region size 174 calling U7SVC from a user program 89 Commands ARTS 20 CA Driver 153 LOGOFF 75 LOGON 74 NCF 188 communications data set and ICOM 169 file description 175 overview 170 conditional procedure expansion 153 control statements for BCLP 109 CPM 60 CPM tracker 61 CREATE (data set request statements) 115 Critical Path Monitoring 60 cross-platform scheduling and CA-Driver 352 overview 201 XPS CLIENT 207 XPS SERVER 223 cross-platform Server password requirements 229 CWORK 17
DB.1 panel (continued) Messages segment 181 Resources segment 180 DBM batch commands, format 74 DCM SAMPJCL member 35, 64 defining CA Driver procedures 125 DEND statement 128 DFLUSH command 160 DGOTO command 154 DIF command 156 disk drives supported 174 DLCTR command 159 DM3Y function 149 DM3YR function 150 DMY function 149 DMYR function 149 DNEST statement 126, 135 DOW function 150 DOW# function 150 DSET command 158 DSTEP command 154 DTADD function 148 DTDIF function 148 DTSUB function 148 dynamic initialization routines 168
E
End-of-Data Set (EODS) Statement 118 error recovery 187 events, CAIENF 212 examples Data Flow Within One CPU 166 NCF VTAM PARM 179 execution options 178 External See External Communicators External Communicators 71
D
DABORT command 160 DASD devices 174 requirements 175 data inclusion 129 data set request statements 115 Data sets 183 DATA statement (CA Driver) 128 DAY function (CA Driver) 150 DB.1 panel Execution segment 180 JCL segment 181
F
files, permanent CA 7 NCF 175 Flows 61 Forecasting print volumes with CA Dispatch format NCF communications data set 175 UDQ 175 functions for CA Driver 147 24
I
ICOM and WLM 70 communications data set 176 cross-platform tracking 367 requirements 174 implementation considerations CA 7 facilities 184 data sets 183 database 180 DB.1 panel 180 DD statements 183 EXEC statements 183 execution JCL 181 general usage 184 JES NJE capabilities 177 JES2 statements 182 JES3 statements 182 JOB statement 181 LOAD process 185 NCFNODE parameter 184 overview 177 scheduling 180 XPS CLIENT 365 XPS SERVER 234 including data 127 Interfaces CA 1 17 CA 11 19 CA APCDDS 22 CA APCDOC 22 CA Dispatch 24 CA Earl 26 CA Easytrieve 26 CA JCLCheck 26 CA Librarian 28 CA Netman 28 CA Opera 35 CA OPS/MVS 35 CA Panvalet 36 list 16 TSO/ISPF 43 UNIX System services 37 Workload Management (WLM) 69 ISPF interface 43 with CA Driver 125
J
JCL requirements for BCLP JDOM function 152 JES2 statements 182 JES3 statements 182 JOB statement 181 107
L
LDOM function 152 length attribute 145 Librarian See CA Librarian interface LINELEN 354 link editing node table 169 List function in batch commands 75 LJDOM function 152 LOAD process (SASSJJCL) 184 LOGOFF command 193 LOGON command 192 loop control 159
M
M3DY function 149 M3DYR function 150 managing workloads 69 MDY function 149 MDYR function 149 memory requirements 174 MNADD function 148 MNSUB function 148 MNT override statement 106 MODIFY command 188 MON function 150 MON# function 150 MONTH function 150 multi-access spool 170
N
N220 job 76 NCF system commands 188 components 166 Data Flow Within One CPU 166 operations CA 7 NCF functions 186 create control blocks 186 error recovery 187 establish communications 186 initialization 186
Index 373
NCF system (continued) operations (continued) loading node table 186 overview 186 scanning files 186 standard operations 187 status information 187 termination 187 overview CA 7 NCF components 166 CAIRIM 168 ICOM 169 NCF Communications Data Set 170 NCF undeliverable queue (UDQ) 170 NCF VTAM Application Program 170 node table 169 OPERATOR commands 188 purpose 164 requirements 165 SVC interface 168 unknown node table 169 requirements 165 NCF VTAM application program 170 application program functions 170 PARM 179 NCFNODE parameter 184 NEST statement 126 nested procedures 126, 135 network job entry (NJE) 164 Node Table loading 186 requirements 169 non-DBM batch commands, format 76 null value 143 number attribute 146
operator commands (continued) STOP 188, 189 TRACE 198 OPTION statement (BCLP) 111 Options for CA 7 64
P
password requirements for cross-platform scheduling 229 permanent files, CA 7 NCF 175 PF key support 48 Pre-Conversion Utility 341 procedure for CA Driver creating 125 expansion aborting 160 conditional 153 controlling loops 159 shifting during 136 nesting 126, 135 parameter substitution 130 retrieving 125 storing 125 PURGE command 169, 194
R
region size, calculating 174 Reporting CA Earl reporting 26 CA Easytrieve reporting 26 requirements CAIRIM 176 DASD 175 reserved-name variable parameters 137 resource initialization manager 166, 168 restarting jobs with CA Driver 155 retrieving procedures for CA Driver 125 return codes and SASSXXBT message table router, XPS 226
O
operating system environment operator commands format 189 LOGOFF 193 LOGON 192 MODIFY 188 overview 188 PURGE 194 response 189 SHUTDOWN 189, 190 STARTUP 191 STATUS 190, 195 174
77
S
SASSBCLP (Batch Card Load Program) using 106 using with NCF 184 SASSBSTR program overview 77 PARM values 79
SASSDPCH module 24 SASSLIBR module 28 SASSNC01 module 198 SASSNC03 module 198 SASSNC04 module 198 SASSNC12 program 175 SASSNC15 program 175 SASSPANV module 36 SASSTRLR program 184 SASSXXBT message table 77 scheduling cross-platform 201 day and time values 180 environments 69 SCHID keyword 236 Service Desk See CA Service Desk shifting during expansion 136 SHUTDOWN command, NCF and STOP command 189 description 190 terminating NCF 187 SMF interface exits 165, 168 space allocations 175 STARTUP command 191 status CA 7 NCF VTAM 196 command 187, 190, 195 information 187 STOP command 187, 189 submitting jobs with NCF 164 substring referencing 140 SVC interface 165, 168 system information &C_DATE 137 &C_DAY 137 &C_JDATE 137 &C_MONTH 137 &C_TIME 137
TSO/ISPF interface 43 type attribute 144 Typical NCF environment
167
U
U7SVC facility at remote nodes 184 overview 71 using 85 UCC7NODE table 187 UDQ See undeliverable queue (UDQ) undeliverable queue (UDQ) and PURGE command 187 and unknown node table 169 DASD requirements 175 overview 170 Unicenter CA-7 Agent 201 Unicenter Event Console 52 UNIX System Services interface 37 scheduling jobs 68 unknown node table 169
V
variable parameter arrays 142, 146 attribute testing 144 coding 132 in nested procedures 135 length attribute 145 number attribute 146 reserved-name 137 substitution 130, 134 substring referencing 140 types 144 values changing 158 defining 132 multiple 142 null 143 overriding 133 testing 144 verification of data inclusion 129 verifying JCL with CA Driver 124 Virtual Resource Management and WLM 70 Virtual terminals, installation requirements 51 VRM and WLM 70
T
termination 187 terminology 172 TIQ interface 17 TRACE command 198 trailer data 169, 170 trailer step facility and NJE 184 JCL 83 overview 81
Index 375
VTAM PARM for NCF VTAM application program 179 requirements for CA 7 under TSO/ISPF 43
W
WOM function 150 workload management (WLM) 69 management and cross-platform scheduling management and NCF 164 WOY function 151 232
X
XPJOB conversion from CA7TOUNI 321 XPS CLIENT submission 207 tracking 207 XPS Router 226 XPS Submit Monitor creating status information 223 submission 223
Y
YM3D function 149 YMD function 149 YRM3D function 150 YRMD function 149

CA7 Workload Automation RefGd

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

CA7 Workload Automation RefGd

Hochgeladen von

Copyright:

Verfügbare Formate

CA 7 Workload Automation

Interface Reference Guide

4 Interface Reference Guide

6 Interface Reference Guide

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

8 Interface Reference Guide

10 Interface Reference Guide

12 Interface Reference Guide

14 Interface Reference Guide

Chapter 2. Interfaces and Options

Chapter 2. Interfaces and Options 15

Interfaces with Other Products

Interfaces with Other Products

16 Interface Reference Guide

Interfaces with Other Products

Chapter 2. Interfaces and Options 17

Interfaces with Other Products

18 Interface Reference Guide

Interfaces with Other Products

Chapter 2. Interfaces and Options 19

Interfaces with Other Products

ARTS Command Monitor

20 Interface Reference Guide

Interfaces with Other Products

Automatic RMS Step Insertion

Automatic CMT Updating

Chapter 2. Interfaces and Options 21

Interfaces with Other Products

CA Workload Control Center (UWCC)

22 Interface Reference Guide

Interfaces with Other Products

Compare FSTRUC to a Database Flowchart

Chapter 2. Interfaces and Options 23

Interfaces with Other Products

Forecast Print Volumes

Create a Plan Data Set

24 Interface Reference Guide

Interfaces with Other Products

Chapter 2. Interfaces and Options 25

Interfaces with Other Products

26 Interface Reference Guide

Interfaces with Other Products

Chapter 2. Interfaces and Options 27

Interfaces with Other Products

28 Interface Reference Guide

Interfaces with Other Products

Chapter 2. Interfaces and Options 29

Interfaces with Other Products

CA Netman Model Transactions

30 Interface Reference Guide

Interfaces with Other Products

CA Netman Model Transactions - Continuation Rules

Chapter 2. Interfaces and Options 31

Interfaces with Other Products

CA Netman Model Transactions - Variables

32 Interface Reference Guide

Interfaces with Other Products

Variable Name &&L2PME_L2ETYR &&L2PME_L2ETDY &&L2PME_L2ETT &&L2PME_L2EM

&&L2PME_L2OVR &&L2PME_L2MNT &&L2PME_L2EX &&L2DATE &&L2OCDT &&L2OCTI &&DATE

Chapter 2. Interfaces and Options 33

Interfaces with Other Products

Variable Name &&TIME &&MFUN

34 Interface Reference Guide