Ca7 Interface Guide

CA-7
Interfaces Guide 3.3
This documentation and related computer software program (hereinafter referred to as the Documentation) is for the end user's informational purposes only and is subject to change or withdrawal by Computer Associates International, Inc. (CA) at any time. THIS DOCUMENTATION MAY NOT BE COPIED, TRANSFERRED, REPRODUCED, DISCLOSED, OR DUPLICATED, IN WHOLE OR IN PART, WITHOUT THE PRIOR WRITTEN CONSENT OF CA. THIS DOCUMENTATION IS PROPRIETARY INFORMATION OF CA AND PROTECTED BY THE COPYRIGHT LAWS OF THE UNITED STATES AND INTERNATIONAL TREATIES. 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, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE. THE USE OF ANY PRODUCT REFERENCED IN THIS DOCUMENTATION AND THIS DOCUMENTATION IS GOVERNED BY THE END USER'S APPLICABLE LICENSE AGREEMENT. The manufacturer of this documentation is Computer Associates International, Inc. Provided with Restricted Rights as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections 52.227-19(c)(1) and (2) or DFARS Section 252.227.7013(c)(1)(ii) or applicable successor provisions.
First Edition, September 2000 1988-2000 Computer Associates International, Inc. One Computer Associates Plaza, Islandia, NY 11749 All rights reserved. All trademarks, trade names, service marks, or logos referenced herein belong to their respective companies.
Contents
Chapter 1. Introduction . . . 1.1 Summary of Revisions . . . 1.1.1 Product Changes . . . 1.1.2 Documentation Changes
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-1 1-2 1-2 1-5
Chapter 2. CA-7 Interfaces and Options . . . . . . . . . . . . . . 2.1 CA-7 Interfaces with Other Products . . . . . . . . . . . . . . . 2.1.1 CA-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1.1 TIQ Command . . . . . . . . . . . . . . . . . . . . . . 2.1.2 CA-11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.2.1 ARTS Command Monitor . . . . . . . . . . . . . . . . 2.1.2.2 Automatic RMS Step Insertion . . . . . . . . . . . . . 2.1.2.3 Automatic CMT Updating . . . . . . . . . . . . . . . 2.1.3 CA-7 WorkStation . . . . . . . . . . . . . . . . . . . . . . 2.1.4 CA-APCDDS . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.5 CA-APCDOC . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.5.1 Comparing FSTRUC to a Database Flowchart . . . . 2.1.6 CA-Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.6.1 Forecasting Print Volumes . . . . . . . . . . . . . . . 2.1.6.2 Creating a Plan Data Set . . . . . . . . . . . . . . . . 2.1.7 CA-Earl . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.8 CA-Easytrieve Plus . . . . . . . . . . . . . . . . . . . . . . 2.1.9 CA-JCLCheck . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.9.1 CA-7 Considerations . . . . . . . . . . . . . . . . . . 2.1.10 CA-Librarian . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.11 CA-Netman . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.11.1 CA-7 Considerations . . . . . . . . . . . . . . . . . . 2.1.11.2 CA-Netman Considerations . . . . . . . . . . . . . . 2.1.11.3 CA-Netman Model Transactions . . . . . . . . . . . 2.1.11.4 CA-Netman Model Transactions - Continuation Rules 2.1.11.5 CA-Netman Model Transactions - Variables . . . . . 2.1.12 CA-Opera . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.13 CA-OPS/MVS II . . . . . . . . . . . . . . . . . . . . . . . 2.1.13.1 Critical Path Monitoring . . . . . . . . . . . . . . . . 2.1.14 CA-Panvalet . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.14.1 CA-Panvalet Prior to Version 14.0 . . . . . . . . . . 2.1.15 OS/390 UNIX System Services Interface . . . . . . . . . 2.1.15.1 Invoking the Interface . . . . . . . . . . . . . . . . . 2.1.15.2 Environment Variables . . . . . . . . . . . . . . . . . 2.1.16 CA-7/API Requirements . . . . . . . . . . . . . . . . . . 2.1.17 TSO/ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.17.1 VTAM Considerations . . . . . . . . . . . . . . . . . 2.1.17.2 ISPF Considerations . . . . . . . . . . . . . . . . . . 2.1.17.3 CA-7 Considerations . . . . . . . . . . . . . . . . . . 2.1.18 Unicenter TNG . . . . . . . . . . . . . . . . . . . . . . . 2.2 CA-7 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-1 2-2 . 2-3 . 2-4 . 2-5 . 2-6 . 2-7 . 2-7 . 2-8 . 2-9 . 2-9 . 2-9 2-10 2-10 2-10 2-12 2-12 2-13 2-13 2-14 2-15 2-15 2-16 2-16 2-17 2-18 2-20 2-20 2-20 2-23 2-23 2-24 2-24 2-25 2-27 2-29 2-30 2-32 2-37 2-37 2-38
Contents iii
2.2.1 CA-7/Notepad . . . . . . . . . . . . . . . . 2.2.2 CA-7/Report Balancing . . . . . . . . . . . 2.2.3 CA-7/Reports+ . . . . . . . . . . . . . . . 2.2.4 CA-7/Smart Console . . . . . . . . . . . . 2.3 Scheduling OS/390 UNIX System Services Jobs 2.3.1 Overview . . . . . . . . . . . . . . . . . . 2.3.2 Sample Invocation of BPXBATCH . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-38 2-38 2-38 2-39 2-42 2-42 2-42 3-1 3-2 . 3-3 . 3-4 . 3-5 . 3-5 . 3-6 . 3-6 . 3-7 . 3-7 . 3-8 3-10 3-13 3-14 3-14 3-15 3-16 3-17 3-17 3-18 3-18 3-19 3-20 3-21 3-22 3-23 3-23 3-24 3-24 3-25 3-26 3-26 3-27 3-27 3-28 3-30 3-34 3-37 3-38 4-1 4-2
Chapter 3. External Communicators . . . . . . . . . . . . . . . . . . . . . . 3.1 Batch Terminal Interface (BTI) . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1.1 Command Format and Sequence . . . . . . . . . . . . . . . . . . 3.1.1.2 DBM List Functions . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1.3 Non-DBM Batch Commands . . . . . . . . . . . . . . . . . . . . 3.1.1.4 Installation Process Batch Commands . . . . . . . . . . . . . . . 3.1.2 Batch Terminal Interface Execution . . . . . . . . . . . . . . . . . . . 3.1.2.1 Processing Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2.2 CA7BTI JCL Procedure . . . . . . . . . . . . . . . . . . . . . . . 3.1.2.3 Sample BTI JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2.4 JCL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Trailer Step Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 U7SVC Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1 Batch Step Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.2 Calling U7SVC From a User Program . . . . . . . . . . . . . . . . . 3.4 CA-7 CCI Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.1.1 Usage Considerations . . . . . . . . . . . . . . . . . . . . . . . . 3.4.2 CA-7 CCI Batch Interface Execution . . . . . . . . . . . . . . . . . . 3.4.2.1 CAL2X2WB JCL . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.2.2 CAL2X2WB Return Codes . . . . . . . . . . . . . . . . . . . . . 3.4.3 CA-7 CCI REXX Interface Execution . . . . . . . . . . . . . . . . . . 3.4.3.1 CA-GSS REXX Address Environment Interface Execution . . . 3.4.4 CA-7 CCI Program to Program Interface Execution . . . . . . . . . . 3.4.4.1 Calling CAL2X2WP . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.4.2 CAL2X2WP Response Buffer . . . . . . . . . . . . . . . . . . . 3.4.4.3 CAL2X2WP Return Codes . . . . . . . . . . . . . . . . . . . . . 3.4.4.4 Sample Invokation of CAL2X2WP . . . . . . . . . . . . . . . . 3.5 Batch Card Load Program (BCLP) . . . . . . . . . . . . . . . . . . . . . . 3.5.1 Using BCLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1.1 CA-7 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1.2 JCL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2 Control Statements for BCLP . . . . . . . . . . . . . . . . . . . . . . 3.5.2.1 OPTION Statement . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2.2 Data Set Request Statements CREATE, REPLACE, MODDATA 3.5.2.3 End-of-Data Set (EODS) Statement . . . . . . . . . . . . . . . . 3.5.2.4 Control Statement Examples . . . . . . . . . . . . . . . . . . . . Chapter 4. CA-Driver Procedures, Variable Parameters, and Functions 4.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . .
. . . . . . . . .
iv CA-7 3.3 Interfaces Guide
4.2 JCL Verification . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Procedure Library . . . . . . . . . . . . . . . . . . . . . . . . 4.3.1 Creating Procedures . . . . . . . . . . . . . . . . . . . . . 4.3.2 Calling Procedures . . . . . . . . . . . . . . . . . . . . . 4.3.3 Nesting Procedures . . . . . . . . . . . . . . . . . . . . . 4.3.4 Including Data . . . . . . . . . . . . . . . . . . . . . . . . 4.3.5 Verifying Data Inclusion . . . . . . . . . . . . . . . . . . 4.4 Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . 4.4.1 Coding Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.1.1 Defining Default Values 4.4.1.2 Supplying Values On The EXEC Statement . . . . . 4.4.1.3 Referencing Variable Parameters in the Procedure . 4.4.1.4 Using Variable Parameters In Nested Procedures . . 4.4.1.5 Shifting During Expansion . . . . . . . . . . . . . . 4.4.2 Reserved-Name Variable Parameters . . . . . . . . . . . 4.4.2.1 CA-Driver Reserved-Name Variable Parameters . . 4.4.3 Substrings . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.4 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.5 Null Values . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.6 Attributes of Variables . . . . . . . . . . . . . . . . . . . 4.4.6.1 The Type Attribute . . . . . . . . . . . . . . . . . . 4.4.6.2 Testing the Type Attribute . . . . . . . . . . . . . . 4.4.6.3 The Length Attribute . . . . . . . . . . . . . . . . . 4.4.6.4 Testing the Length Attribute . . . . . . . . . . . . . 4.4.6.5 The Number Attribute . . . . . . . . . . . . . . . . . 4.4.6.6 Testing the Number Attribute . . . . . . . . . . . . . 4.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.5.1 CA-Driver Functions . . . . . . . . . . . . . . . . . . . . 4.5.1.1 Arithmetic Date Functions . . . . . . . . . . . . . . 4.5.1.2 Date Conversion Functions . . . . . . . . . . . . . . 4.5.1.3 Day-Of-Month Functions . . . . . . . . . . . . . . . 4.6 Conditional Procedure Expansion . . . . . . . . . . . . . . . . 4.6.1 Defining Step Names (DSTEP) . . . . . . . . . . . . . . 4.6.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . 4.6.2 Branching (DGOTO) . . . . . . . . . . . . . . . . . . . . 4.6.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . 4.6.3 Defining Conditions (DIF) . . . . . . . . . . . . . . . . . 4.6.3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . 4.6.4 Setting Variable Parameters (DSET) . . . . . . . . . . . 4.6.5 Controlling Loops (DLCTR) . . . . . . . . . . . . . . . . 4.6.5.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . 4.6.6 Aborting Expansion (DFLUSH) . . . . . . . . . . . . . . 4.6.7 Aborting Expansion of the Current Procedure (DABORT) 4.7 Comments Inside CA-Driver Procedures . . . . . . . . . . . . 4.8 Using CA-Driver in the CA-7 Environment -- Some Examples 4.8.1 Conditional Execution Based on Schedule ID . . . . . . Chapter 5. NCF 5.1 Purpose . . 5.2 Requirements
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-3 4-4 . 4-4 . 4-4 . 4-5 . 4-6 . 4-8 . 4-9 4-11 4-11 4-12 4-13 4-14 4-15 4-16 4-16 4-19 4-21 4-22 4-23 4-23 4-23 4-24 4-24 4-25 4-25 4-26 4-27 4-27 4-28 4-31 4-32 4-33 4-33 4-33 4-33 4-35 4-35 4-37 4-39 4-39 4-39 4-39 4-40 4-41 4-41 5-1 5-2 5-3
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents v
5.3 CA-7 NCF Components . . . . . . . . . . . . . 5.3.1 CAIRIM (Resource Initialization Manager) 5.3.2 SVC Interface . . . . . . . . . . . . . . . . 5.3.3 ICOM . . . . . . . . . . . . . . . . . . . . 5.3.4 Node Table . . . . . . . . . . . . . . . . . 5.3.5 Unknown Node Table . . . . . . . . . . . 5.3.6 NCF Communications Data Set . . . . . . 5.3.7 NCF Undeliverable Queue (UDQ) . . . . . 5.3.8 NCF VTAM Application Program . . . . . 5.3.8.1 Functions . . . . . . . . . . . . . . . . 5.3.9 CA-7 NCF Test Data Generator . . . . . . 5.4 Planning and System Requirements . . . . . . . 5.4.1 General Notes . . . . . . . . . . . . . . . . 5.4.2 Resource Requirements . . . . . . . . . . . 5.4.2.1 Operating System Environment . . . . 5.4.2.2 Memory Requirements . . . . . . . . 5.4.2.3 DASD Devices . . . . . . . . . . . . . 5.4.2.4 DASD Requirements . . . . . . . . . 5.4.2.5 CAIRIM System Requirements . . . . 5.5 Implementation Considerations . . . . . . . . . 5.5.1 Execution Options . . . . . . . . . . . . . 5.5.1.1 Sample NCF VTAM PARM . . . . . 5.5.1.2 Sample NCF VTAM JCL . . . . . . . 5.5.2 CA-7 Database . . . . . . . . . . . . . . . 5.5.2.1 Scheduling . . . . . . . . . . . . . . . 5.5.2.2 DB.1 Screen . . . . . . . . . . . . . . 5.5.3 User Execution JCL . . . . . . . . . . . . 5.5.3.1 JOB Statement . . . . . . . . . . . . . 5.5.3.2 JES2 Statements . . . . . . . . . . . . 5.5.3.3 JES3 Statements . . . . . . . . . . . . 5.5.3.4 EXEC Statements . . . . . . . . . . . 5.5.3.5 DD Statements . . . . . . . . . . . . . 5.5.4 Data Sets . . . . . . . . . . . . . . . . . . 5.5.5 General Usage . . . . . . . . . . . . . . . . 5.5.5.1 NCFNODE Parameter . . . . . . . . . 5.5.5.2 CA-7 LOAD Process . . . . . . . . . 5.6 System Operations . . . . . . . . . . . . . . . . 5.6.1 Initialization . . . . . . . . . . . . . . . . . 5.6.2 Establishing Communications . . . . . . . 5.6.3 Standard Operations . . . . . . . . . . . . 5.6.3.1 Status Information . . . . . . . . . . . 5.6.4 Error Recovery . . . . . . . . . . . . . . . 5.6.5 Termination . . . . . . . . . . . . . . . . . 5.7 Operator Commands . . . . . . . . . . . . . . . 5.7.1 STOP Command . . . . . . . . . . . . . . 5.7.1.1 Syntax . . . . . . . . . . . . . . . . . 5.7.1.2 Response . . . . . . . . . . . . . . . . 5.7.2 SHUTDOWN Command . . . . . . . . . . 5.7.2.1 Syntax . . . . . . . . . . . . . . . . . 5.7.2.2 Response . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
5-4 5-6 . 5-6 . 5-7 . 5-7 . 5-7 . 5-8 . 5-8 . 5-8 . 5-8 . 5-9 5-10 5-11 5-12 5-12 5-12 5-12 5-13 5-14 5-15 5-16 5-17 5-17 5-18 5-18 5-18 5-19 5-19 5-19 5-20 5-20 5-20 5-21 5-22 5-22 5-22 5-23 5-23 5-23 5-24 5-24 5-24 5-24 5-25 5-26 5-26 5-26 5-27 5-27 5-27
vi CA-7 3.3 Interfaces Guide
5.7.3 STARTUP Command . . . . . 5.7.3.1 Syntax . . . . . . . . . . 5.7.3.2 Response . . . . . . . . . 5.7.4 LOGON Command . . . . . . 5.7.4.1 Syntax . . . . . . . . . . 5.7.4.2 Response . . . . . . . . . 5.7.5 LOGOFF Command . . . . . 5.7.5.1 Syntax . . . . . . . . . . 5.7.5.2 Response . . . . . . . . . 5.7.6 PURGE Command . . . . . . 5.7.6.1 Syntax . . . . . . . . . . 5.7.6.2 Response . . . . . . . . . 5.7.7 STATUS Command . . . . . 5.7.7.1 Syntax . . . . . . . . . . 5.7.7.2 Response . . . . . . . . . 5.7.7.3 Field Descriptions . . . . 5.7.8 TRACE Command . . . . . . 5.7.8.1 Syntax . . . . . . . . . . 5.7.9 Deactivating the Trace Facility
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-28 5-28 5-28 5-29 5-29 5-29 5-30 5-30 5-30 5-31 5-31 5-31 5-32 5-32 5-33 5-33 5-35 5-35 5-36 6-1 6-2 . 6-3 . 6-4 . 6-5 . 6-5 6-11 6-11 6-14 6-15 6-20 6-21 6-22 6-22 6-23 6-24 6-25 6-28 6-28 6-29 6-29 6-30 6-31 6-33 X-1
Chapter 6. CA-7 Cross-Platform Scheduling . . . . . . . . . 6.1 CAICCI Cross-Platform Connections . . . . . . . . . . . . . 6.1.1 Non-OS/390 CAICCI Connections . . . . . . . . . . . 6.1.2 OS/390 CAICCI Connections . . . . . . . . . . . . . . 6.2 The CA-7 XPS CLIENT . . . . . . . . . . . . . . . . . . . . 6.2.1 Submit Function . . . . . . . . . . . . . . . . . . . . . . 6.2.2 Cross-Platform Tracking . . . . . . . . . . . . . . . . . 6.2.2.1 CA-7 Cross-Platform Tracking JCL . . . . . . . . 6.2.2.2 CA-7 Cross-Platform Tracking Commands . . . . 6.2.2.3 CA-7 Cross-Platform External Tracking . . . . . . 6.2.3 CA-7 Considerations . . . . . . . . . . . . . . . . . . . 6.2.4 CA-7 XPS Client Implementation Checklist . . . . . . 6.3 The CA-7 XPS SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.1 The XPS Submit Monitor 6.3.1.1 Submission . . . . . . . . . . . . . . . . . . . . . . 6.3.1.2 Status Update . . . . . . . . . . . . . . . . . . . . 6.3.2 The Cross-Platform Scheduling Router (XPS ROUTER) 6.3.3 Cross-Platform Server Password Requirements . . . . . 6.3.3.1 Syntax Rules . . . . . . . . . . . . . . . . . . . . . 6.3.3.2 Keywords . . . . . . . . . . . . . . . . . . . . . . . 6.3.3.3 Processing . . . . . . . . . . . . . . . . . . . . . . 6.3.3.4 Examples . . . . . . . . . . . . . . . . . . . . . . . 6.3.4 Managing the Cross-Platform Workload . . . . . . . . 6.3.5 CA-7 XPS Server Implementation Checklist . . . . . . Index
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents vii
viii CA-7 3.3 Interfaces Guide
Chapter 1. Introduction
This publication contains information about several of the interfaces to 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 OS/390 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 1-1
1.1 Summary of Revisions

This topic explains changes to both CA-7 and to the documentation.
1.1.1 Product Changes

CA-7 Version 3.3 contains the following major enhancements: Parallel Sysplex Exploitation CA-7 can optionally maintain a memory structure in the Coupling Facility in which participating ICOMs record tracking data. One or more Host ICOM(s) read from the memory structure and write to the Communication data set. This can significantly reduce I/O contention and increase feedback throughput. UNIX System Services Interface The OS/390 UNIX System Services (USS) CA-7 interface allows communication with CA-7 from the USS environment. The interface can be called directly from the UNIX shell or from the IBM USS batch interface (BPXBATCH). CA-7 CCI Interface The CA-7 CCI interface allows two-way communication with CA-7 from other address spaces and environments. The interface can be engaged in a batch mode, in a REXX address environment or it can be called directly from a user program. It accepts single or stacked commands as input and returns the CA-7 output from the commands as if they had been executed in batch mode. Critical Path Monitoring Through integration with CA-OPS/MVS II, Unicenter TNG and Unicenter TNG MVS Event Manager Option (MEMO), CA-7 can support the definition and monitoring of critical job flows within the CA-7 workload. CA-OPS/MVS II provides management and administration of critical path displays. Mixed Case Support in CA-7 Editor Character translation controls can be set in the CA-7 Editor. New Editor subcommands 'UPPER' and 'MIXED' determine whether editor data is translated to uppercase or left "as is." These subcommands are enabled with a new initialization file option. If this option is not coded, then all edit data is translated to uppercase. Job Completion Tracking Precision CA-7 records job completion times in hundredths of seconds. This allows job completions to be discriminated with a high degree of precision, thus reducing the likelihood of requirement posting ambiguities where jobs complete within the same minute.
1-2 CA-7 3.3 Interfaces Guide
Display Duplicate Days for RESOLVe CA-7 can optionally display the duplicate RESOLV day(s) in new message SRC1-137. This occurs when a job is scheduled to execute the same day under two or more different Schedule IDs. With this information one can more quickly and efficiently determine the source of the scheduling conflict. VRM Device Control Virtual Resource Management (VRM) Device Control provides an alternative to Workload Balancing control of job submission based on tape drive availability. VRM resource count resources representing the number and type of storage devices used by the job are defined dynamically during CA-7 LOAD processing. Workload Balancing only permits two types of tape drives. With VRM Device Control, the number and structure of device groups is determined by the user. CA-7 Command Retrieval Command line input for CA-7 VTAM terminals is recorded in storage and may be retrieved with the /FETCH command. When the /PFnn command is used to associate /FETCH with a PF key, the CA-7 user can conveniently retrieve the last five CA-7 commands entered at an online terminal. CA-7 Base Calendar Security CA-7 security can allow clients to define CA-7 base calendar names to an external security product and secure user access to individual base calendars. REXX Address Environment Using the new CA-7 CCI interface, CA-7 allows REXX programs to pass commands to CA-7 and take action based on the output from those commands. Job 'Purge' Function The DB.1 (Job) panel provides a new function, PURGE, which deletes all CA-7 database records related to a job. In addition to the standard delete processes, the PURGE function deletes incoming trigger definitions, requirement successor definitions, and the CA-11 CMT member for the job. Suppress LATE Designation Through an Initialization File option, the PROMPTS field on the DB.1 (Job) panel can be used to indicate certain jobs should never be marked as LATE on status displays. This means operations and production control staff will not be distracted when test or non-critical jobs do not complete on time. CSA Chains Above the 16M Line CA-7 CSA SMF and Trailer chains now reside in extended CSA (above-the-line), thereby reducing utilization of this critical resource. Automated Recovery Facility (ARF) Enhancements CA-7 can optionally add a LOGON parameter to the ARF TSO SEND command to cause messages to be retained until the user logs on to TSO. Also, support for ARF has been added to the Database Transportability facility.
Prior Run Queue Expansion The maximum size of the Prior Run Queue is now approximately twice as large as in prior releases. CA-7 JCLCheck Common Component The CA-JCLCheck Common Component is provided in place of the CA-7 JCL syntax checker. Documentation Files on Tape The current CA-7 documentation files are provided in IBM Book Manager and PDF format on the product tape. Other Enhancements: SMF Purge records may optionally be sent to a test copy of CA-7. This allows detection of pre-execution JCL Errors by the test copy. The Scratch and Disk Queue Table queues can be formatted during a CA-7 ERST start which facilitates use of VIO to improve performance. The LJOB command provides a new option, LIST=RQEXCP, that lists only those requirements with a SKIP or ONLY indication. The reverse forecast commands, FRJOB and FRQJOB, have a new option, LIST=HDRS. This will limit the display to only the target job and all 'header' jobs. Database Transportability now supports a new keyword, NODSNS, for SASSDT30 which prevents the generation of data set definitions. The LQ family of commands (LREQ, LRDY, LACT, and so forth) now support a Schedule ID filter, SCHID=. The LRLOG command has a new sequence option, SEQ=REV, which causes entries to be displayed in reverse date/time sequence (most recent first). The OPTIONS initialization file statement has a new keyword DPROCCOM= to enable comment statements in CA-Driver procedures. The OPTIONS initialization file statement has a new keyword EXTSCHID= to set a default schedule ID for externally tracked jobs that are not assigned a nonzero schedule ID from the SASSEXTT table. The CA-7 CAIRIM initialization module now accepts a new reinitialization parameter (REINIT=UTABS) to reload only user defined table modules. The /DISPLAY command has a new STATUS option (/DISPLAY,ST=CA7) to describe the current copy of CA-7 (VTAM application ID and so forth).
1.1.2 Documentation Changes

The documentation for CA-7 Version 3.3 differs from previous releases as follows: The documentation set has been engineered to take advantage of the latest technology for online viewing, keyword searching, book marking, and printing. The set consists of a hard copy CA-7 Getting Started guide and Version 3.3 of CA-7 for OS/390 documentation in both IBM BookManager and Adobe Acrobat Reader format on the tape. Unicenter TNG Framework for OS/390 is composed of the services formerly known as CA90s and Unicenter TNG Framework. Reading Syntax Diagrams in the CA-7 Commands Guide explains how to read the command syntax used in all guides. Technical changes are identified by a revision bar (|) in the left margin. Revision bars are not used for editorial changes and new manuals.
Chapter 2. CA-7 Interfaces and Options

This chapter contains information on CA-7 interfaces with other products, the CA-7 product options, and discusses the requirements for CA-7 to schedule OS/390 UNIX System Services jobs.
Chapter 2. CA-7 Interfaces and Options 2-1
2.1 CA-7 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-7 WorkStation CA-APCDDS CA-APCDOC CA-Dispatch CA-Earl CA-Easytrieve Plus CA-JCLCheck CA-Librarian CA-Netman CA-Opera CA-OPS/MVS II CA-Panvalet OS/390 UNIX System Services TSO/ISPF Unicenter TNG Note: The CA-7 Security Guide contains descriptions of all security product interfaces.
2.1.1 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 CA-7 Message 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 link listed 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 "Execution" chapter of the CA-7 Systems Programmer Guide). Note: The CA-1 TIQ interface in CA-7 dynamically loads the appropriate TIQ interface module based upon the current version of CA-1 found on your system during execution. Therefore no special application statements are required.
2.1.1.1 TIQ Command

Syntax TIQ TIQ TIQU YES ,DSN=NO
Where: 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.
2.1.2 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 during the installation process as SYSMOD CL233SB (for CA-11 Version 2.0 and 2.1) or SYSMOD CL233SC (for CA-11 Version 2.2 and above). The appropriate SYSMOD should be applied during the SMP APPLY process to support the CA-7 CA-11 interface. 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 module library must be concatenated to the CA-7 STEPLIB or link listed since CA-11 modules perform part of the interface. You must add the following DD statement to the CA-7 execution JCL replacing xx with the CA-11 version number:
//CA11HELP
DD
DISP=SHR,DSN=CAI.CAICLIB(CL7xxHLP)
Refer to the CA-11 Systems Programmer Guide for more information regarding these DD statements. The data set names are established during installation of CA-11. Also, the CA-11 HELP file is distributed as a member of CA-11 GENLIB or SAMPLIB, depending on the version, and must be referenced as a member of the appropriate library.
2.1.2.1 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 may be entered. Messages produced by the CA-7 ARTS interface may be found in the CA-7 Message Guide. Those produced by CA-11 are documented in CA-11 documentation. The format of the ARTS command is as follows:
ARTS
There are no parameters 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 (refer to the "Execution" chapter of the CA-7 Systems Programmer Guide). When issuing CA-11 commands which have multiple screens of output, it is necessary to retype the first letter of the command (or a blank) before pressing Enter to view secondary screens.
2.1.2.2 Automatic RMS Step Insertion

For jobs submitted by CA-7, there is a job-level option that causes a CA-11 RMS procedure to be inserted in the job's JCL. The default procedure name inserted depends on the version 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 there is no restart data for //*UCC7RESTART, the parameter is set to P unless Load processing is needed. If there is 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 screen to Y. (See the CA-7 Database Maintenance Guide, "Jobs" chapter.) If CA-11 is not installed, the insert feature is not active regardless of the INSERT-RMS field on the DB.1 screen. 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.
2.1.2.3 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 screen SET PARM field is used, the CMT is not accessed and the PARM data is passed using the //*UCC7RESTART statement. The CA-7 commands which cause CMT updating are CANCEL, RESTART, XQ function C or F, and XRST.
2.1.3 CA-7 WorkStation

CA-7 WorkStation is an application that provides a single point of control for workloads running under CA-7 from a Windows NT workstation. This graphical presentation enhances the administration, management, and real-time monitoring of workloads. Forecasting and monitoring actions are accomplished through the use of flowcharts representing past, current, and future events. The CA-7 WorkStation interface with CA-7 requires CA-7 Version 3.2, or higher. Refer to 2.1.16, CA-7/API Requirements on page 2-27 to enable the CA-7 interface for CA-7 WorkStation.
2.1.4 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.
2.1.5 CA-APCDOC
If you have CA-APCDOC (Computer Associates 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.
2.1.5.1 Comparing 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 which 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.
2.1.6 CA-Dispatch
The interface between CA-7 and CA-Dispatch requires Version 4.1 or later of 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 2.1.6.1, Forecasting Print Volumes which follows. The CA-Dispatch to CA-7 part of the interface is discussed in the CA-Dispatch Reference Guide.
2.1.6.1 Forecasting 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. Refer to the CA-Dispatch user documentation for additional information on the forecast of print activity.
2.1.6.2 Creating 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 desired. This will place data in a data set reserved for FWLP purposes. This card-image data will identify the jobs and when they are scheduled to run. That data set must have been previously defined in the CA-7 JCL. Refer to the discussion of the FWLP command and the DDNAME keyword parameter in the CA-7 Commands Guide for further discussion of this command and its function. 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. Note: This file is generated in a format that is compatible with CA-Dispatch Version 4.1 or above. 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=loadlib-for-CA-7 //UCC7CMDS DD DISP=SHR,DSN=ca-7.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=loadlib-for-CA-7 //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) //
2.1.7 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 may be used. If a full copy of CA-Earl is not available, you can install the service from the Unicenter TNG Framework for OS/390 distribution tape. Refer to Getting Started for specific information on how to install the CA-Earl subset product. Refer to the CA-7 Reports Guide for JCL and usage considerations. The CAIMAC EARL report member, prefix CA7ER, contains record and report definitions used for the reports described in the CA-7 Reports Guide.
2.1.8 CA-Easytrieve Plus

CA-7 provides a complete set of report definitions for use with CA-Easytrieve Plus, 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 Plus. Refer to the CA-7 Reports Guide chapter on CA-Earl and CA-Easytrieve Plus reporting for information on how to produce reports from CA-Easytrieve Plus. The CA-Easytrieve Plus report definitions are saved in the CAIMAC data set.
2.1.9 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 which may prove useful in testing production job streams. The interface also includes a batch utility which uses the FJOB command to forecast a series of jobs and then the LJCK command to extract JCL for them so that 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 (Version 6.0 or later). Refer to CA-JCLCheck documentation for additional information.
2.1.9.1 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 link list library, then 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 further information on CA-JCLCheck storage requirements, consult the CA-JCLCheck documentation. The execution JCL for CA-7 must be modified to include a DD statement which 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, then the CA-JCLCheck option AUTOPROC may be specified if CA-7 is running in a JES2 environment. Refer to CA-JCLCheck documentation for further information about the AUTOPROC option. 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. Refer to the discussion of the JCLCHECK statement in the CA-7 Systems Programmer Guide for a list of valid options. Refer to CA-JCLCheck documentation for further information about these options.
2.1.10 CA-Librarian
The CA-Librarian interface is included during the installation process as SYSMOD CL233SL. During SMP APPLY processing, the CA-Librarian SYSMOD requires that you include the CA-Librarian load library in the SMP APPLY procedure for inclusion of the CA-Librarian access method modules: FAIROPN, FAIRMOD, FAIRREC, and FAIRCLS. The CA-Librarian load library should be specifed under the LIBR ddname in the SMP APPLY procedure. The SMP APPLY process generates the composite load module SASSLIBR for CA-Librarian interface support. 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 screens, 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
2.1.11 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 may 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 which uses the Machine Generated Problem Tracking feature of CA-Netman and the CA-7 batch terminal interface. Refer to CA-Netman publications for information on the use of the batch interface.

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. Refer to 2.1.11.3, CA-Netman Model Transactions on page 2-16 for further information. 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 CCI 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. Refer to CA-Netman documentation for additional information. 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 1M is recommended as a starting value. A larger increase may be required depending on the volume of CA-Netman transactions to be issued.
2.1.11.2 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 CCI listener. A listener may be requested either through a CA-Netman transaction or through the use of the CA-Netman Asynchronous Services Task (NTMASYN). Consult CA-Netman documentation for more information on implementing the CA-Netman API. Also refer to CA-Netman documentation for a discussion of security using the API. This interface requires CA-Netman Version 4.9 or higher.
2.1.11.3 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 may 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= 161 ITIM= 2127 + OCCRD= 6 9 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 00.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 refer to 2.1.11.5, CA-Netman Model Transactions - Variables on page 2-18.
2.1.11.4 CA-Netman Model Transactions - Continuation Rules

Model transactions can be continued. A continuation is indicated by the occurrence of + as the last nonblank 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.
2.1.11.5 CA-Netman Model Transactions - Variables

You may code the following variables in CA-Netman model transactions:
Table 2-1 (Page 1 of 2). CA-Netman Model Transactions Variables
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) screen 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
04 08 03 04 03 04 04 03 04 04 03 04 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
Table
2-1 (Page 2 of 2). CA-Netman Model Transactions Variables
Variable name &&L2PME_L2STDY &&L2PME_L2STT &&L2PME_L2ETYR &&L2PME_L2ETDY &&L2PME_L2ETT &&L2PME_L2EM
Length 03 04 04 03 04 04
Value CA-7 start day CA-7 start time 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 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 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 &&TIME &&MFUN
01 01 01 05 06 04 06 06 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 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.
2.1.12 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. Refer to CA-Opera documentation for details on this interface. For CA-Opera to monitor CA-7 browse data set messages, you need to add the CA-7 browse event to your CAIENF database. Refer to member L2DCM1 in the CA-7 sample JCL library to add this event.
2.1.13 CA-OPS/MVS II
CA-OPS/MVS II 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 II. Any commands issued using the CA-OPS/MVS II interface require operator security defined for the trailer terminal. Refer to CA-OPS/MVS II documentation for details on this interface. CA-7 commands can also be issued using the CA-7 CCI Interface. This facility returns the output from the CA-7 commands to the caller for evaluation. See 3.4.3.1, CA-GSS REXX Address Environment Interface Execution on page 3-22 for information on using this facility in CA-OPS MVS/II. For CA-OPS/MVS II to monitor CA-7 browse data set messages, you need to add the CA-7 browse event to your CAIENF database. Refer to member L2DCM1 in the CA-7 sample JCL library to add this event.
2.1.13.1 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) for CA-OPS/MVS II provides monitoring tools that can be used for this purpose. CPM reports on the status of jobs within key segments of the workload using job information provided by CA-7. In this way, CPM can be used to track the progress of a crucial production job stream, a "critical path". Within CA-7 a named segment of a triggered stream of jobs is known as a FLOW. The elements required for FLOW definition are: 1. The name of the FLOW. 2. The name and schedule ID of the starting job. 3. The name and schedule ID of the ending job. 4. The expected completion time of the ending job (Service Level Agreement, or SLA time).
These elements are defined in CA-7 by connecting a special VRM Corequisite resource to the starting job of the FLOW. Refer to the CA-7 Database Maintenance Guide for information on defining VRM resources. 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. Refer to the CA-7 Commands Guide for information on the FLOWL command. CA-7 uses ENF to report status information for all FLOW jobs to CA-OPS/MVS II. When CA-7 notifies CA-OPS/MVS II that a FLOW has begun, CA-OPS/MVS II will request forecast information from CA-7 to chart the "critical path" that connects the FLOWs beginning and ending jobs. CA-OPS/MVS II 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 in order to initiate a FLOW. This means that a nonexecutable job cannot start a FLOW. However, non-executable jobs can be included in a FLOW and can be defined as the ending job of a FLOW. See the CA-OPS/MVS II documentation for more information on Critical Path Monitoring features and requirements. Critical Path Monitoring Requirements: The following steps are required to activate CPM functionality for CA-7: 1. Enable CPM in the CA-7 initialization file options. 2. Enable the CA-7 CCI interface in the CA-7 initialization file options. 3. Add the CA7PARMS DD statement to the CA-OPS/MVS II OSF Servers. See the Critical Path Monitor Getting Started Guide and the CA-OPS/MVS II Installation and Customization Guide for more information on Critical Path Monitoring features and requirements. 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. Refer to the CA-7 Systems Programmer Guide for information on CA-7 initialization file options.
2. Enable the CA-7 CCI interface in the CA-7 initialization file options. The CA-7 CCI Interface is used to extract information from CA-7 for CA-OPS/MVS II to build an image of a critical path. There must be at least one CA-7 CCI terminal defined in the CA-7 initialization file. See 3.4, CA-7 CCI Interface on page 3-17 for information about the interface. See the CA-7 Systems Programmer Guide for information on GROUP, LINE, and TERM statements for CA-7 CCI terminals (DEVICE=CCI). 3. Add the CA7PARMS DD statement to the CA-OPS/MVS II OSF servers. The CA-OPS/MVS II OSF servers must have access to the CA-7 load library. If this library is not in the LNKLST or LPALIB, you must add them to the OSF server's STEPLIB DD. You may need to add a CA7PARMS DD statement to the OSF server's JCL to set parameters to be used by the CA-7 CCI 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 imbedded blanks. Lines that begin with a blank or asterisk are considered comment lines. The possible keywords are: CA7NODE= CA7SSCT= CA7USER= CA7PSWD= CA7SNAP= CA7DBUG= CAICCI NODE WHERE CA-7 RESIDES (DEFAULT=LOCAL) CA-7 SSCT (PROD OR TEST) (DEFAULT=PROD) USERID TO LOGON TO CA-7 WITH (DEFAULT=OSF SERVER USER ID) USERID PASSWORD (DEFAULT - NONE) DD NAME FOR TRACE SNAPS (DEFAULT=CA7TRACE) DEBUG/TRACE OPTIONS (DEFAULT - NONE) = SUPPRESS 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)
If you wish to use one of the snap trace options, you should add a CA7TRACE SYSOUT DD to the JCL.
2.1.14 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 screens, 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).
2.1.14.1 CA-Panvalet Prior to Version 14.0

If you are running a version of CA-Panvalet prior to Version 14.0, you will need to install a CA-7 USERMOD. Member UL2PANV in the CA-7 Sample JCL library contains the USERMOD needed to enable the CA-7 interface for older versions of CA-Panvalet. This USERMOD performs an SMP RECEIVE and APPLY to generate the composite load module SASSPANV. The CA-Panvalet load library must be included in your SMP/E procedure using the PANV DD statement prior to running the JCL to install the USERMOD. Also, you must add an APPLCTN statement to the CA-7 initialization file for the composite module created by the UL2PANV USERMOD. The format is:
APPLCTN,NAME=SASSPANV,ATTR=PERM
2.1.15 OS/390 UNIX System Services Interface

The OS/390 UNIX System Services interface provides a method of communication for requests to CA-7 from the OS/390 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 on the installation and setup of the CA-7 USS Interface modules, see UNIX System Services Interface in the CA-7 Systems Programmer Guide. For a detailed discussion on using the OS/390 UNIX Services with the shell environment, see the IBM Open Edition MVS User's Guide and the IBM Open Edition Command Reference. Refer to the following examples for invoking the CA-7 interface.
2.1.15.1 Invoking the Interface

Example: From the UNIX shell environment command prompt, you can invoke the interface as follows:
ca7oecom demandh,job=payjob1
The example above 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. Special Considerations: The OS/390 UNIX shell can be entered by issuing the TSO/E OMVS command from within TSO. If the command you wish to submit to CA-7 contains special characters, blanks, or quotes, imbed 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'
2.1.15.2 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. Setting 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.
// // S A M P L E // // A sample batch job which executes BPXBATCH to invoke // the IBM OS/39 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. // // //CA7UNIX JOB 'ACCOUNT,INFO','PROGRAMMER', // CLASS=A,MSGCLASS=X // //JS1 EXEC PGM=BPXBATCH, // PARM='sh /u/users/bin/ca7oecom demandh,job=payjob1' // //STDOUTx 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=
2.1.16 CA-7/API Requirements

The CA-7 SQL based API is used by CA-WorkStation to communicate with CA-7. If you wish to use this product with CA-7, take the following steps: 1. Merge the CA-7/API table As part of the installation of CA-7 you may have already performed this task. If not, refer to the CA-7 Getting Started guide. Merge the CA-7/API table. This task 'registers' the CA-7 product with the CA SQL based API structure. Note that this merge only needs to be done once. That is, if you have previously done this for CA-7/ViewPoint or Unicenter/STAR, you do not need to repeat it to make use of Unicenter TNG. 2. Add the CA-7 CAILIB to the Server JCL The CA-7 load library (CAILIB) must be available to the server task which communicates with CA-7. If the CA-7 CAILIB is link listed in your environment, no changes to JCL or CLISTs should be required. The CA-7 CAILIB should be added to the STEPLIB concatenation for the Server Task (started task). Refer to your related CA-7 WorkStation documentation for directions on how to identify/define the server task. 3. 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 which must be added to the CACCENV member are: CA7APPL=applid This variable identifies the VTAM APPLID for the CA-7 you wish 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 ten ACBs (CA70001 through CA70010), you should specify CA7SESS=CA70010. The interface will deduce from this that there are ten ACBs to choose from (one through ten) 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 there are enough ACBs to satisfy both ISPF and API users.
If ACBs need to be defined, refer to 2.1.17.1, VTAM Considerations on page 2-30 for detailed instructions. 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, refer to the discussions of the UCC7VTAM, LINE and TERM initialization statements in the CA-7 Systems Programmer Guide. 5. Enable Online Calendar Maintenance facility If you wish to use the facilities in CA-7 WorkStation 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 wish to enable Online Calendar Maintenance, refer to the CALENDAR initialization statement in the CA-7 Systems Programmer Guide.
2.1.17 TSO/ISPF
Computer Associates 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 may now enjoy many of the benefits that derive from TSO/ISPF (such as split-screen 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 screen by simply entering =1 in a command area and pressing Enter. One must either split the screen 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, screen data is presented as it is in any CA-7 online terminal session. The interface processes screen 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 may 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 may be requested using the !JCK edit macro. Refer to CA-JCLCheck documentation for further information on !JCK. To use the CA-7 TSO/ISPF interface, virtual terminals must be defined in the CA-7 initialization file. For more information on the installation of this interface, consult the CA-7 Getting Started guide. This discussion of the CA-7 TSO/ISPF interface installation follows in three topics: VTAM considerations ISPF considerations CA-7 considerations
2.1.17.1 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 on the VTAM application that contains the nodes used by the interface. The TSO/ISPF interface requires the use of ACF-VTAM 3.2 or higher. The CA-7 TSO/ISPF interface uses only the node name that is defined using the ACBNAME keyword on the VTAM APPL statement. There are strict conventions that are imposed by the interface which 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 may 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. Refer to 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 may 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 screen requires the use of one of these nodes dedicated for interface use. Thus, in this example, anywhere from one to four ISPF users may be allowed depending on terminal characteristics. In most instances, an ISPF user requires the use of only one CA-7 terminal session. However, there is nothing that would prevent one ISPF user from having more than one CA-7 terminal session going at one time using ISPF's split screen capability. For example, one user could split the screen into four ISPF screens, 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 there would be no nodes available for this purpose.
Unlike the node for CA-7 which 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 application(s) 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
2.1.17.2 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 CAICLIB. 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.LOADLIB) SET &CHCK = &SUBSTR(4:7,&SESSAPL) SET &NUMCHK = &DATATYPE(&CHCK) IF &NUMCHK = &STR(CHAR) THEN GOTO APPLERR CONTROL MSG LIST CONLIST SYMLIST CLRSCRN ISPEXEC CONTROL ERRORS RETURN SET &CA7ACT = PASSTHRU ISPEXEC VPUT (CA7ACT) SHARED ISPEXEC VGET (ZAPPLID) SHARED IF &ZAPPLID = CA7 THEN GOTO ENDPF 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 IN SESSAPL NAME 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.
There are also several CLISTs that 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 CAICLIB. 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 may 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 CAIISPP 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 which 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 screen 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 may 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 there is no CA-7 PF key support. Refer to 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 ISPTLIB 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 may be entered either from the "top line" or from any area considered appropriate for a CA-7 formatted screen if a formatted screen 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 screen 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 may 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 wish 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 screens, PF3 is used to return to the menu from which the current screen 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 screens will require the user to enter the screen 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 may 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 may 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 may also be specified dynamically by using an ISPF variable. A command table (CA7CMDS) is provided which 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 CAIISPT to a PDS that is in the ISPTLIB concatenation in the TSO LOGON procedure.
The following entries are in the CA7CMDS member supplied on CAIISPT:
VERB .... SUBMIT .... HELP .... RETURN .... RFIND .... RCHANGE .... UP .... DOWN .... LEFT .... RIGHT .... CURSOR
T 3
ACTION DESCRIPTION NOP &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT &CA7ACT
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 may 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 which 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 which appear in the CA7CMDS table with an action of PASSTHRU or &CA7ACT are honored by CA-7. The default command table CA7CMDS which is found in CAIISPT does not include entries for SPLIT, SWAP and END. This causes these ISPF commands to always be honored. It is recommended 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.

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 further information on installation of the TSO/ISPF interface for CA-7, refer to the CA-7 Getting Started 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 may use the CA-7 /PAGE command to page through the CA-7 pages. This means that a CA-7 screen 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 screen).
2.1.18 Unicenter TNG

CA-7 has the capability to send and receive jobs to and from platforms managed by Unicenter TNG (cross-platform scheduling). Refer to Chapter 6, CA-7 Cross-Platform Scheduling for a full discussion of these capabilities.
2.2 CA-7 Options
2.2 CA-7 Options
2.2.1 CA-7/Notepad
CA-7/Notepad provides a convenient, easy-to-use method of creating and maintaining documentation about relevant production workload procedures and information. With this operations automation tool implemented, vital information regarding the production workload is stored online and is readily available. With the production workload information centrally located, and since the tool is so easy to use, CA-7/Notepad significantly reduces the time operations staff would normally spend researching and resolving a potential problem. With CA-7/Notepad, information can be shared between CA-11/Notepad and CA-Dispatch/Notepad.
2.2.2 CA-7/Report Balancing

CA-7/Report Balancing 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-7/Report Balancing 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-7/Report Balancing adds to the flexibility of CA-7 by allowing an out-of-balance condition to directly affect the production workflow. CA-7/Report Balancing 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-7/Report Balancing requires no changes to your existing application programs.
2.2.3 CA-7/Reports+
CA-7/Reports+ is a flexible reporting option that provides presentation quality graphic reporting capabilities to CA-7 clients. CA-7/Reports+ assists production control managers, data center executives, scheduling personnel, and end users in analyzing all facets of production workload performance and management. By presenting production workload and performance data in quality graphic format, CA-7/Reports+ simplifies the task of trend analysis while helping to pinpoint problem areas.
2.2 CA-7 Options
2.2.4 CA-7/Smart Console

For CA-7/Smart Console to monitor CA-7 browse data set messages, you need to add the CA-7 browse event to your CAIENF database. Refer to member L2DCM1 in the CA-7 sample JCL library to add this event. CA-7/Smart Console's Cross System Communication provides for two major functions: CA-7/Smart Console to CA-7/Smart Console and CA-7/Smart Console Multi-System Console. CA-7/Smart Console to CA-7/Smart Console Users can define cross system actions where a message is selected by CA-7/Smart Console on one system and specific actions are performed on another system executing CA-7/Smart Console. A list of actions that can be cross system actions follows: CICSTRAN MVSCMD SENDOPER CA-7/Smart Console Multi-System Console Systems executing CA-7/Smart Console will have their console messages routed to all defined systems executing CA-7/Smart Console. Commands issued from a system executing CA-7/Smart Console can be routed to another system executing CA-7/Smart Console. 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/Smart Console for message selection. Route codes can control console message traffic. Remote operations availability. Console hardware reduction. Note: When using the CA-7/Smart Console Multi-System Console Facility, only console messages are routed between systems executing CA-7/Smart Console. CICS messages are not routed unless they are issued to the console using the SENDOPER action.
2.2 CA-7 Options
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/Smart Console 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/Smart Console 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.
2.2 CA-7 Options
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/Smart Console 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/Smart Console initializes; these messages are not selected realtime. CA-7/Smart Console processes them as if the messages were occurring at CA-7/Smart Console 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/Smart Console address space is active, CA-7/Smart Console does not respond to them; however, CA-7/Smart Console 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/Smart Console 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 4-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/Smart Console interfaces with CAIRIM to determine product licensing authorization.
2.3 Scheduling OS/390 UNIX System Services Jobs
2.3 Scheduling OS/390 UNIX System Services Jobs
2.3.1 Overview
The OS/390 environment provides a UNIX implementation referred to as UNIX System Services. These services allow UNIX users to operate from within the OS/390 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. Refer to the IBM documentation, OS/390 OpenEdition User's Guide, for a detailed discussion of the BPXBATCH utility.
2.3.2 Sample Invocation of BPXBATCH
// // S A M P L E // // Sample batch JCL which executes BPXBATCH to invoke the IBM // OS/39 UNIX shell and then executes a shell command under // UNIX System Services. // // //JOBNAME JOB 'ACCOUNT,INFO','PROGRAMMER',CLASS=A,MSGCLASS=X // //JS1 EXEC PGM=BPXBATCH,,PARM='sh /bin/ls' // //STDOUTx 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=
Chapter 3. External Communicators

External communicators enable the processing of work which is under CA-7 control, based on events which 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 CCI interface combines aspects of the BTI and U7SVC facilities. It uses the Computer Associates 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, and/or extract information from the command output for future processing. The CA-7 CCI interface can be executed in a batch mode, called from a REXX CLIST or environment, or called directly from another program. 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.
Chapter 3. External Communicators 3-1
3.1 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 screen and other menu-type screens. 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. Refer to the CA-7 Systems Programmer Guide, "User Exits and Modifications," for a discussion of the batch terminal interface error message table (SASSXXBT).
3.1.1.1 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: /LOGON /LOGONopid ,password
Where: opid Specifies the required operator identification. password Specifies an optional password (site dependent). 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 screen 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 nonblank character in column 72 and the next statement must begin in column 1. In the following, please 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
1,OPT=C
To log off, the format is: /LOGOFF /LOGOFF
3.1.1.2 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 screen 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.
3.1.1.3 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
3.1.1.4 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 CA-7 specialist or systems programmer who installed CA-7 for the data set name.
3.1.2 Batch Terminal Interface Execution

3.1.2.1 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 possible return codes are: Return code 0 Explanation The SASSBSTR program was able to successfully complete its functions without detecting an error. SASSBSTR does NOT validate that the SYSIN commands were processed successfully by CA-7. SASSBSTR detected an error condition that prevented successful completion of its tasks. Usually, a WTO or message in the SYPRINT 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 A security violation occurred which prevented successful execution of SASSBSTR.
Usage of the SASSXXBT message table may generate additional return code values. Refer to the CA-7 Systems Programmer Guide for additional information about SASSXXBT. 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 cancelled one until a recycle of CA-7 or the use of the above procedure.
3.1.2.2 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=,PG=SASSBSTR //BTERM EXEC PGM=&PG, // PARM='&ID,POOL=(&POOL),DSNPFX=&DSNPFX,&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=
3.1.2.3 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) ..... ..... / //
3.1.2.4 JCL Parameters

The PARM values for SASSBSTR are shown in the following format:
PARM=(n,POOL=(x-y,b,c),DSNPFX='batch dsn prefix.',NOMCHK,NOWAIT)
Where: 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 5 seconds for a total of 1 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. NOMCHK Used to suppress 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. Refer to the CA-7 Systems Programmer Guide, "User Exits and Modifications," for a description of the SASSXXBT message table. 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 wait 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.
3.2 Trailer Step Facility

CA-7 trailer steps are special purpose job steps which may 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 which performs the operation requested in trailer step JCL. You may use the trailer step to perform any of the commands belonging to the queue maintenance application as defined by SPO0 security. Refer to Figure 3-1 for an illustration of trailer step data flow.
Figure
3-1. Trailer Step Data Flow
You may 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 which creates the data sets. This is due to the possibility of a restart which 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 which 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 may be defined. Refer to 3-12 for a trailer step JCL sample. A JCL procedure similar to this is provided during installation and should be used to ease maintenance and version upgrades. Check with your systems programmer or CA-7 specialist for the correct procedure name.
//CA 7TRLR EXEC PGM=SASSTRLR,PARM= //STEPLIB DD DSN=CA-7.loadlib,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 ## //
(See NOTE)
Figure
3-2. Trailer Step JCL Sample
Note: You can specify an optional PARM value on the EXEC statement. The PARM value may be either ACT or 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 error messages and abends. When the PARM value of INACT is used, the data is held in CSA to be processed when ICOM is started. Additionally, if the trailer step is to send commands to a test copy of CA-7, a PARM value of TEST=YES must be specified. Return code 0 4 Explanation PARM value supplied. 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. Invalid PARM, INACT assumed. Various error conditions, denoted with a WTO which describes the error. Refer to the CA-7 Message Guide for an explanation of the various WTOs.
Refer to the CA-7 Security Guide for the discussion of SASSTRLR and the /LOGON statement. Refer to the CA-7 Systems Programmer Guide for information on the use of SASSTRLR with a test copy of CA-7. 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 may 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.
3.3 U7SVC Facility
3.3 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 may 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.
3.3 U7SVC Facility
3.3.1 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. The format of the PARM or data record consists of one or more entries separated by semicolons. Each entry is a CA-7 batch command or a data set creation statement. (Each entry may begin and end with one or more blanks.)
3.3.1.1 Syntax
To indicate that the creation of a data set has completed, a statement in the following format is required: D D=dsname,, vvvvvv xxx ,tttttttt
Where: dsname Specifies the data set name. Size/Type: Required: 1 to 44 alphanumeric characters Yes
vvvvvv 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. Size/Type: Required: xxx 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. Size/Type: Default: Required: 1 to 3 numeric characters from 1 to 255 1 No 1 to 6 alphanumeric characters No
tttttttt Indicates a positional parameter specifying the logical terminal or station name to be notified of the data set creation. Size/Type: Default: Required: 1 to 8 alphanumeric characters MASTER No
3.3 U7SVC Facility
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.)
3.3.1.2 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 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. Refer to the CA-7 Security Guide for more details on security interfaces. The U7SVC facility uses the same blocking technique noted for the trailer step facility on Trailer Step JCL Sample on page 3-12.
3.3 U7SVC Facility
3.3.2 Calling 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, REGS=R1 , IDENTIFY BASE REGISTER LINK=OS, REQUEST OS LINKAGE 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) DC C'TEST=YES;' (REQUIRED IF SENDING TO TEST COPY) COMMANDS DC C'/LOGON;DEMANDH,JOB=CA 7TEST;/LOGOFF' PARML EQU -COMMANDS END
X X X
3.4 CA-7 CCI Interface
3.4.1 Overview
The CA-7 CCI interface uses the Computer Associates 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 CCI interface environment executes. CAICCI is a Computer Associates common component which 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 TCPIP 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 CCI interface establishes communication with the CA-7 CCI receiver in the CA-7 address space. This receiver is created when there are one or more CA-7 CCI Terminals (DEVICE=CCI) defined in the CA-7 initialization file. Refer to the CA-7 Systems Programmer Guide for information on the CA-7 initialization file options. The CA-7 CCI 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. Refer to 3.1, Batch Terminal Interface (BTI) on page 3-2 for specific information about CA-7 batch formats.
3.4.1.1 Usage Considerations

1. CAICCI must be active on both the MVS image where the CA-7 address space is executing and where the CA-7 CCI interface environment is executing. There must be a CAICCI connection between these systems. 2. The CA-7 address space must be active. 3. There must be one or more CA-7 CCI Terminals (DEVICE=CCI) defined and active in the CA-7 address space. 4. 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 CCI interface is executing must be a valid CA-7 operator. 5. There is NO requirement for shared DASD between the MVS image where the CA-7 CCI interface executes and the image where CA-7 itself executes. 6. There is NO requirement that CA7ICOM executes on the MVS image where the CA-7 CCI interface executes.
3.4.2 CA-7 CCI Batch Interface Execution

The CA-7 CCI 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 CCI 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.
3.4.2.1 CAL2X2WB JCL

The following JCL can be used to execute the CA-7 CCI batch interface:
//jobname JOB (user job parms) //JS1 EXEC PGM=CAL2X2WB,PARM='optional.parms' //STEPLIB DD DISP=SHR,DSN=cai.ca7.loadlib //SYSPRINT DD SYSOUT= //ERRORS DD SYSOUT= //SYSIN DD ..... (CA-7 commands go here) ..... //
The optional parameters which can be specified on the EXEC statement are:
PARM='ca-7 cci node,ca-7 ssct name,options,cmdin ddname,cmdout ddname,errors ddname'
Where: CA-7 CCI NODE 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). CA-7 SSCT NAME The subsystem name of the CA-7 you wish to communicate with. The primary copy of CA-7 (production copy) has an SSCT name of 'UC07'. The secondary copy of CA-7 (test copy) has an SSCT name of 'UCT7'. The default is to communicate with the primary (production) copy of CA-7. The values PROD and TEST can be used instead of UC07 and UCT7. OPTIONS The 1-4 character option string: TRACE OPTION If set to 'Y' it turns on diagnostic WTOs for the CA-7 CCI 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 The ddname of the source for CA-7 commands. The default is SYSIN.
CMDOUT DDNAME The ddname for the CA-7 command output. The default is SYSPRINT. ERRORS DDNAME 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.
3.4.2.2 CAL2X2WB Return Codes

Module CAL2X2WB issues WTO CAL2C509I when processing completes which lists the return code and condition code for the process. The possible return and condition codes from CAL2X2WB are as follows: Return code 0 8 Explanation The CAL2X2WB program was able to successfully complete its functions without detecting an error. Processing error: CC=1 CC=2 CC=8 CC=9 CC=10 16 No valid CA-7 commands were read from SYSIN. No command output responses were received from CA-7. Non-zero return code from CA-7 CCI interface module (CAL2X2W0). See message CAL2C596E. Error attempting to GETMAIN storage. See message CAL2C594E. Error attempting to LOAD a needed module. See message CAL2C595E.
Parameter list error: CC=1 CC=2 CC=3 CC=4 Invalid parameter list. See message CAL2C590E. Invalid parameter value. See message CAL2C591E. Required DD statement missing or invalid. See message CAL2C592E. DCB open error. See message CAL2W593E.
Note: Usage of the SASSXXBT error message table may generate additional return code values. See the CA-7 Systems Programmer Guide for additional information about SASSXXBT.
3.4.3 CA-7 CCI REXX Interface Execution

The CA-7 CCI 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 CAICLIB 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 = sub-system name of CA-7 to communicate with / (default= production CA-7 (prod)). To communicate / with secondary copy of CA-7 specify 'test'. / 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 CLIST 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 = 'prod' / ca7_debug = 'N; ' / /
address CA7 command say 'rc =' rc x = queued() say 'queued() =' x do i = 1 to x pull line line2 = SUBSTR(line,2) say line2 end return
strip carriage control char
3.4.3.1 CA-GSS REXX Address Environment Interface Execution

OPS/REXX (the REXX implementation used by CA-OPS/MVS II) 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 CAICLIB 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 pull line say line end return
/ / / / / / / / / / / / / / /
3.4.4 CA-7 CCI Program to Program Interface Execution

The CA-7 CCI 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 which contains the command responses from CA-7. The calling program can then parse the responses and take other appropriate actions based on the results.
3.4.4.1 Calling CAL2X2WP

To invoke the CA-7 CCI 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: Offset +0 Value 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. Length of the string of CA-7 batch commands. This parameter is required. Address of an 8 byte field where the address and length of the CA-7 response buffer is placed. The first 4 bytes will contain the address, and the second 4 bytes will contain the length of the buffer. If the caller wants the response buffer to be in storage above the 16Mb line, the first byte of the 8 byte field should contain the value X'80'. Otherwise, the buffer storage is GETMAINed below the 16Mb line. This parameter is required. IT IS THE CALLER'S RESPONSIBLITY TO FREEMAIN THE RESPONSE BUFFER STORAGE. +12 Pointer to a 64 byte field which contains the CAICCI node name where the CA-7 address space executes. The default is the local node. This parameter is optional. Pointer to the 4 character SSCT name of the CA-7 to communicate with. The value PROD can be used to indicate the production (primary) CA-7. The value TEST can be used to indicate the test (secondary) copy of CA-7. The default is PROD. This parameter is optional. Pointer to a 4 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 semicolon (;). The third and fourth characters are reserved for future use. This parameter is optional.
+4 +8
+16
+20
3.4.4.2 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 nulls. 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 NON-ZERO 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 16Mb line (LOC=ANY GETMAIN option). IT IS THE CALLER'S RESPONSIBLITY TO FREE THE RESPONSE BUFFER STORAGE.
3.4.4.3 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: Return code 0 4 8 Explanation The CAL2X2WP program was able to successfully complete its functions without detecting an error. No responses from CA-7 received. Processing error: CC=9 CC=10 12 Error attempting to GETMAIN storage. Error attempting to LOAD a needed module.
Error return from CAL2X2W0 (non-abend) CC= AL2(CAL2X2W0 rc),AL2(CAL2X2W0 cc)
16
Parameter list error: CC=1 CC=2 Invalid parameter list. Invalid parameter value.
20
Error return from CAL2X2W0 (abend) CC= Sxxx or Uxxx which is the printable abend code.
3.4.4.4 Sample Invokation 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 DS DC DC
CMDLIST DC CMDLISTL EQU END
C'/LOGON USERX;DEMAND,JOB=TESTJOB;/LOGOFF' (L'CMDLIST) X2WPSAMP
3.5 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.
3.5.1 Using 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 may not 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 screen which is defined in the CA-7 Database Maintenance Guide or the #MNT special purpose override statement. For further information on the #MNT statement, refer to the "JCL Management" chapter of the CA-7 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 may 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 CA-7 Message Guide. Note: BCLP cannot process data sets on SMS managed volumes.
3.5.1.1 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.
3.5.1.2 JCL Requirements

PARMs: PARM information on the BCLP execute statement may consist of one or more of the following parameters. If more than one is entered, they must be separated by commas. EXITPROG=xxxxxxxx Describes the name of the user exit routine which is to receive control immediately after each statement is read (including the OPTION statement). This exit program name may 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. TEST=YES Indicates that data set creation information is to be sent to a test copy of CA-7 rather than the production copy. 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 CA-7 Systems Programmer Guide. UCC7JLIB Specifies the job data set. See the DBPARMS DD discussion in the CA-7 Systems Programmer Guide. UCC7DLIB Specifies the dataset data set. See the DBPARMS DD discussion in the CA-7 Systems Programmer Guide.
DBPARMS Used to define parameters in the database. Refer to the CA-7 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 which is to temporarily contain card images for a data set. Enough space must be allocated to contain the largest data set to be processed. U7xxxxxx 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 EXITPROG PARM.
//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
DD DD DD DD DD CREATE DSN=A.B.C,VOL=111111
PGM=SASSBCLP,PARM=('EXITPROG=PX1') DSN=CA-7.loadlib,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
REPLACE DSN=X.Y.Z,VOL=222222
3.5.2 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 may 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 may be entered in two ways. A comment may 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.
3.5.2.1 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 may omit this statement. Options specified in the statement may be overridden at the data set level. Syntax OPTION UCC7 OPTION MASTER ,LTERM=xxxxxxxx YES NO ,DETLIST=NO ,VOLROT=YES YES 312 ,REQSAT=NO ,BLKSIZE=nnnnn SASSBCX1 1 ,EXITPROG=xxxxxxxx ,MAXJOBS=nnn 1 SYSRES ,SCHID=nnn ,CVOL=xxxxxx
Where: LTERM 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: Required: MASTER No
MASTER Specifies the master terminal is to receive the data set completion message. xxxxxxxx Specifies the logical terminal name to receive the completion message. Size/Type: 1 to 8 alphanumeric characters
DETLIST Specifies whether a detail list of all statements entered is to be produced. Default: Required: YES No
YES Specifies a list of all statements is to be produced. NO Specifies only control statements and messages are to be listed. VOLROT Indicates whether, on a specific volume request, an insufficient space condition results in a search of other volumes for the space. Default: Required: NO Indicates an insufficient space condition resulting in an error. YES Specifies a search of U7xxxxxx 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 Specifies whether a successful operation on a data set should result in either a requirement being satisfied or a job being triggered. Default: Required: YES No NO No
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 Designates the block size to be used when creating data sets. This keyword may also be used to assign a default block size for all data sets or for a single data set. Size/Type: Default: Required: 2 to 5 numeric characters from 80 to 32720 3120 No
3120 Specifies the block size of 3120.
nnnnn Specifies the block size. The block size specified must be divisible by 80 and may not be larger than the track size of the receiving device or 32720, whichever is smaller. EXITPROG Designates the name of the user exit routine to receive control after each statement is read. This may 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 CA-7 Systems Programmer Guide. Size/Type: Default: Required: 1 to 8 alphanumeric characters SASSBCX1 No
SASSBCX1 If EXITPROG keyword is omitted (and is not present in the PARM information on the EXEC statement), SASSBCX1 is the default. xxxxxxxx Specifies the name of the user exit routine. MAXJOBS 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 which contains more job names than the maximum, the data set request is bypassed. Size/Type: Default: Required: 10 Specifies 10 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 Specifies which schedule ID created the data set. This may be done on a data set basis or for the whole job. Size/Type: Default: Required: 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. 1 to 3 numeric characters from 1 to 255 1 No 1 to 3 numeric characters from 1 to 255 10 No
CVOL 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. Size/Type: Default: Required: 1 to 6 alphanumeric characters SYSRES No
SYSRES Specifies the system resident device as the volume containing the system catalog. xxxxxx Specifies the volume containing the system catalog.
3.5.2.2 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. Syntax CREATE REPLACE MODDATA UCC7CREATE,DSN=xx...xx REPLACE 312 MODDATA ,BLKSIZE=nnnnn NO YES ,CATALOG=YES ,DETLIST=NO ,JOBS=xxxxxxxx ,LTERM=xxxxxxxx YES 1 ,VOL=xxxxxx ,REQSAT=NO ,SCHID=xxx YES ,EXITPROG=xxxxxxxx ,VOLROT=NO ,CVOL=xxxxxx
Where: 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 may 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. Size/Type: Required: 1 to 44 alphanumeric characters Yes
BLKSIZE Describes the output block size to be used for this data set. The rules for BLKSIZE are described in the BLKSIZE keyword of the 3.5.2.1, OPTION Statement on page 3-30. CATALOG Indicates whether the data set is to be cataloged after a successful operation. Default: Required: 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 Specifies whether a detail list of all statements entered is to be produced. Default: Required: YES No NO No
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 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 10 jobs may 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 may be continued. If continued, the last job name on a statement must be followed by a comma. The next job name may start anywhere on the next statement. The right parenthesis must appear immediately after the last job name. Size/Type: Required: 1 to 8 alphanumeric characters No
LTERM Overrides the default logical terminal and follows the rules described in the LTERM keyword of the 3.5.2.1, OPTION Statement on page 3-30. If present, this keyword overrides the default only for this data set. Size/Type: Required: 1 to 8 alphanumeric characters No
REQSAT Described in the OPTION statement. If present, it overrides the default only for this data set. SCHID Specifies which schedule ID created the data set. It overrides the default schedule ID. SCHID is described in the 3.5.2.1, OPTION Statement on page 3-30. VOL 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 U7xxxxxx 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, then 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 U7xxxxxx 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 request, the U7xxxxxx JCL statements must have a volume specified or the first U7xxxxxx must be named U7VOLSER. VOLROT Described in the 3.5.2.1, OPTION Statement on page 3-30. If present, it overrides the default only for this data set. EXITPROG Described in the 3.5.2.1, OPTION Statement on page 3-30. 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 which may optionally follow the data statements. CVOL Described in the 3.5.2.1, OPTION Statement on page 3-30. If present, it overrides the default only for this data set request.
3.5.2.3 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. Syntax EODS UCC7 EODS
A null data set is created if no data statements follow the control statement. You may use this to indicate no transaction input is available for today's run of a given job.
3.5.2.4 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 U7xxxxxx DD statement. Example 2: Same as Example 1, with the addition that JOB Z must have run since the last creation (refer to 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 U7xxxxxx 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 (refer to 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 U7xxxxxx 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 U7xxxxxx DD statement.
Chapter 4. CA-Driver Procedures, Variable Parameters, and Functions

This chapter 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 JCL statement in a job at the job's submission time. 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
When one 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 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. The allocation of CA-Driver procedure libraries is normally determined by the CARPROC DD statement. However, this allocation may be altered for JCL in any defined CA-7 JCL library. If the definition of the CA-7 JCL 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 JCL from that JCL library. For additional information on associating a CA-Driver procedure library with a CA-7 JCL library, refer to the discussion of the DPROC keyword on the JCL initialization file statement in the CA-7 Systems Programmer Guide or the discussion of the the DPROC keyword on the /JCL command in the CA-7 Commands Guide.
Chapter 4. CA-Driver Procedures, Variable Parameters, and Functions 4-1
4.1 Usage Notes

1. Because the JCL is modified by CA-Driver at job submission, JCL changes will not be reflected in the job's queue JCL. 2. If the SASSXX02 user exit is being used, it will receive the JCL statements after they have been manipulated by CA-Driver. If the user exit inserts or modifies JCL, the changed statements are not inspected by CA-Driver. 3. If the SASSXX05 user exit is being used, it receives the JCL statements as the job enters the queues (prior to submission). Therefore, any statements inserted or changed are available to CA-Driver. 4. All scheduled overrides (such as #JI and #XO) are applied prior to CA-Driver invocation. 5. The job card cannot be in a CA-Driver PROC. 6. CA-Driver and MVS SP4: Due to a conflict with the MVS IF and SET statements, all CA-Driver statements now use a prefix of D, as in DIF and DSET. If MVS is running below SP4, then the old statements (IF, SET) are also supported. Starting with MVS SP4, the old statements are ignored. The statements that have changed are: Old syntax ABORT FLUSH GOTO IF LCTR NEST SET STEP New syntax DABORT DFLUSH DGOTO DIF DLCTR DNEST DSET DSTEP
Computer Associates strongly recommends use of the new syntax.
4.2 JCL Verification
4.2 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 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, 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 JCL appropriately. Refer to the CA-7 Commands Guide for information on the LJCK command. You can find details on the use of JCLL and other CA-7 editor subcommands in the "Edit Facility" chapter of the CA-7 Database Maintenance Guide.
4.3 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.
4.3.1 Creating 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 1-8 alphanumeric characters, beginning with an alpha or national character.
//procname
DPROC
Use ISPF or any other editor to code procedures.
4.3.2 Calling Procedures

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
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
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=335 =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 which is submitted to JES. 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.
4.3.3 Nesting 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
This sample shows both the LVTOC procedure and the LVTOCS procedure which 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=335 =VSIAUX,FORMAT
When the LVTOC procedure is retrieved, it calls the LVTOCS procedure which 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=335 =VSIAUX,FORMAT
4.3.4 Including 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.
This is useful for job streams that process data which change each time the job is run and for those jobs which 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 statement(s) 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=335 =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.
4.3.5 Verifying 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 which 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 1-8 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 which signals the end of the data inclusion statements.
//LIST //CALL LISTVTOC // //
JOB ,JOHN.DOE,CLASS=A EXEC PROC=LVTOC VOL=335 =VSIAUX,FORMAT DEND LVTOCX
4.4 Variable Parameters

A procedure in the CA-Driver library may contain up to 64 symbolic parameters. A default value may 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 statement which calls the procedure. (If no default value is defined, a value must be supplied on the EXEC 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. (See 4.4.1, Coding Variable Parameters on page 4-11 for specific coding requirements.)
//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 statement or on a DSET statement. the default value if no value is supplied on the EXEC statement. This example shows the LVTOC procedure with two parameters, each with a default value.
//LVTOC //LIST1 //VOL //SYSPRINT //SYSIN LISTVTOC
DPROC VOL=335 ,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
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=335 =VSIAUX,FORMAT
If this procedure is called with a value for the VOL parameter only:
//CALL
EXEC
PROC=LVTOC,VOL=333
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=333 =VSIAUX,FORMAT
4.4.1 Coding Variable Parameters

Up to 64 variable parameters may 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.
4.4.1.1 Defining Default Values

A default value of up to 64 characters may 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.
4.4.1.2 Supplying 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 statement. (If values are given in both places, the value on the EXEC statement overrides the defined default value.) Values supplied on the calling EXEC 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 //CALL //CALL //CALL
EXEC EXEC EXEC EXEC
PROC=LVTOC,VAR1=NO PROC=LVTOC,VAR2='D E F' PROC=LVTOC,VAR3=/MARY'S/ PROC=LVTOC,VAR4='REPLACEMENT VALUE'
Multiple variable parameters may be listed one after the other, separated by commas. 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. 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'
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
4.4.1.3 Referencing 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'
4.4.1.4 Using Variable Parameters In Nested Procedures

Variable parameters may 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
// //LVTOCS
DPROC VAR1=YES . . . DNEST LVTOCS,VAR2=&VAR1 DPROC VAR2=
The calling procedure defines VAR1, and the nested procedure defines VAR2.
4.4.1.5 Shifting During Expansion

During variable parameter substitution, the substitution character string may 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 may 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: Computer Associates does 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.
4.4.2 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 begins with &C_ to avoid conflicts with variable names defined on the DPROC statement.
4.4.2.1 CA-Driver Reserved-Name Variable Parameters

The following table lists the reserved-name variable parameters that are offered by CA-Driver: Parameter &C_DATE &C_JDATE &C_TIME &C_DAY &C_MONTH Example This example procedure uses four of the CA-Driver reserved-name variable parameters. Contents Current system date in mm/dd/yy format Current system Julian date in yyddd format Current system time in hhmmss format Current day of the week (MONDAY, TUESDAY, ...) Current month name (JANUARY, FEBRUARY, ...)
//TIMER DPROC // IT IS &C_TIME ON &C_DAY IN &C_MONTH AND THE DATE IS &C_DATE
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/
Information for a specific run of a CA-7 scheduled job may be referenced through the use of variables described in the following table: Parameter &C_L2JN &C_L2UID &C_L2MID &C_L2SN &C_L2QN &C_L27# &C_L2LT &C_L2RO &C_L2CC &C_L2PRY &C_L2CLS &C_L2SID &C_L2#T1 &C_L2#T2 &C_L2EM &C_L2DOD &C_L2DOT &C_L2DLD &C_L2DLT Contents Name of CA-7 scheduled job UID of CA-7 scheduled job MAINID value for CA-7 scheduled job SYSTEM name of CA-7 scheduled job Name of queue where CA-7 scheduled job resides Value is REQUEST on LJCK displays. CA-7 job number for CA-7 scheduled job Value is 00001 on LJCK displays. LTERM value for CA-7 scheduled job RO value for job level COND-CODE test Value for job level COND-CODE test PRIORITY value for CA-7 scheduled job CLASS value for CA-7 scheduled job SCHEDULE-ID value for CA-7 scheduled job Value supplied from SCHID keyword on LJCK displays. Number of TAPE1 tape drives for CA-7 scheduled job Number of TAPE2 tape drives for CA-7 scheduled job Entry mode for CA-7 scheduled job, such as DEMAND or RUN. Value is SSCAN on LJCK displays. Due-out date for CA-7 scheduled job (YYDDD) Due-out time for CA-7 scheduled job (HHMM) Deadline date for CA-7 scheduled job (YYDDD) 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.
4.4.3 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)
Where: 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/00 &VAR4(&VAR2,&VAR3) 31 Substring reference Substring value
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 in order 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)
4.4.4 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.)
4.4.5 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 may be a null value. A null value may 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.
4.4.6 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
4.4.6.1 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
4.4.6.2 Testing 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.
4.4.6.3 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
4.4.6.4 Testing 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)
4.4.6.5 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 6.
4.4.6.6 Testing 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
4.5 Functions
4.5 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 may be absolute constants or may 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 which 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.
4.5 Functions
4.5.1 CA-Driver Functions

4.5.1.1 Arithmetic Date Functions
The following arithmetic date functions are offered by CA-Driver. All leap-year, month end, and year end adjustments are automatically handled by CA-Driver. 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 may be a positive numeric constant or a variable containing a positive numeric value. Example: If &C_JDATE=99366, DTADD(4,&C_JDATE)=00004 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 may be a positive numeric constant or a variable containing a positive numeric value. Example: If &C_JDATE=00005, DTSUB(8,&C_JDATE)=99363 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=00040, DTDIF(00045,&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 may be a positive numeric constant or a variable containing a positive numeric value. Example: If &C_JDATE=00023, MNADD(2,&C_JDATE)=00082 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 may be a positive numeric constant or a variable containing a positive numeric value. Example: If &C_JDATE=00039, MNSUB(1,&C_JDATE)=00008
4.5 Functions
4.5.1.2 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=00032, DMY(&C_JDATE)=010200 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=00032, MDY(&C_JDATE)=020100 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=00032, YMD(&C_JDATE)=000201 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=00032, DMYR(&C_JDATE)=01022000 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=00032, MDYR(&C_JDATE)=02012000 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=00032, YRMD(&C_JDATE)=20000201 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=00032, DM3Y(&C_JDATE)=01FEB00 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=00032, M3DY(&C_JDATE)=FEB0100 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=00032, YM3D(&C_JDATE)=00FEB01
4.5 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=00032, DM3YR(&C_JDATE)=01FEB2000
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=00032, M3DYR(&C_JDATE)=FEB012000
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=00032, YRM3D(&C_JDATE)=2000FEB01
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=00032, 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=00032, 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=00032, 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=00032, 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=00032, 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=00032, DOW#(&C_JDATE)=02
4.5 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=01096, 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=01096, 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=01096, 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=01096, WOY(&C_JDATE)=15
4.5 Functions
4.5.1.3 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 which 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,00025)=30 Example 2: LDOM(2,00045)=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,00025)=00002 Example 2: JDOM(2,00045)=00033 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,00025)=00030 Example 2: LJDOM(2,00045)=00058
4.6 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 operand(s)
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.
4.6.1 Defining 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 may be one to eight alphanumeric characters. A maximum of 256 names may be defined in each procedure.
4.6.1.1 Examples
//ONE //DAILYRUN //STEP1 //1
DSTEP DSTEP DSTEP DSTEP
4.6.2 Branching (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
4.6.2.1 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 which 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.
4.6.3 Defining 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 which allows it to be referenced in other DIF or DGOTO statements. A variable parameter which 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 =, <, > may be used instead of EQ, LT and GT. A character string against which to test the variable parameter. It may 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
4.6.3.1 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 STEP // 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
4.6.4 Setting 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 may 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 may 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
4.6.5 Controlling 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
The number you specify (n) is the maximum number of times any one step may be branched to. If any step is referenced n+1 times, an error message is produced and procedure expansion is terminated.
4.6.5.1 Examples
// // //
DLCTR DLCTR DLCTR
4 9 999
4.6.6 Aborting 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.
4.6.7 Aborting 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
4.7 Comments Inside CA-Driver Procedures
4.7 Comments Inside CA-Driver Procedures

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 which 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 may 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.
4.8 Using CA-Driver in the CA-7 Environment -- Some Examples
4.8 Using CA-Driver in the CA-7 Environment -- Some Examples
4.8.1 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
Chapter 5. NCF
This chapter 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 5-1
5.1 Purpose
5.1 Purpose
It is often desirable, for maximizing use and effectiveness of computer resources, to route CPU jobs (and their products) to some other data center(s) 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 which 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 may execute at any site within a network of sites just as if the site were a local CPU. NCF ensures that the CA-7 which 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.
5.2 Requirements
5.2 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 MVS with JES2 or JES3, at a minimum of one site Support for ICOM, under MVS, at all sites Generation of SMF record types 4, 5, 14, 15, 20 and 26 (or type 30 equivalents) at all sites A VTAM environment which supports the Multisystem Networking Facility (MSNF) at all sites NJE jobs do not necessarily require special CA-7 database definitions.
Chapter 5. NCF 5-3
5.3 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 Refer to Figure 5-1 and Figure 5-2 on page 5-5 for an illustration of the data flow between these components within a single CPU and a typical NCF environment (however, there are many variations available to the user).
Figure
5-1. CA-7 NCF Data Flow Within One CPU
Figure
5-2. One Typical NCF Environment
Chapter 5. NCF 5-5
5.3.1 CAIRIM (Resource Initialization Manager)

CA-7 NCF uses Computer Associates' 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 Unicenter TNG Framework for OS/390 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.
5.3.2 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 Reader Date 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 which 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 which should be retained locally and that data which 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 which 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.
5.3.3 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.
5.3.4 Node Table

This table defines nodes in the network for the NCF VTAM task. Up to 222 nodes may 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 VTAM and NCF Node Table Definitions appendix of the CA-7 Getting Started 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 VTAM and NCF Node Table Definitions appendix of the CA-7 Getting Started guide.
5.3.5 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 may 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 5-7
5.3.6 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.
5.3.7 NCF Undeliverable Queue (UDQ)

The UDQ contains data for nodes which do not have an active link, or which are not defined in the node table. Any data which 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.
5.3.8 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.
5.3.8.1 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
5.3.9 CA-7 NCF Test Data Generator

A test program is supplied which 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 may be used to identify a node table to be used for this test. This node table name does not have to be UCC7NODE, but may 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 may 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 which 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 which 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 Computer Associates support personnel. 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 5-9
5.4 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 CA-7 Getting Started guide. The information in this topic is provided to allow you to effectively plan the installation of CA-7 NCF. Installation requirements for sites which are not running CA-7 are slightly different from those for sites which are running CA-7.
5.4.1 General Notes

Terminology: The following terminology is used throughout this chapter and the CA-7 Getting Started 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. Used to refer to all the sites connected by NCF. A site that runs CA-7 and NCF. A site that runs NCF but not CA-7. A node in an NJE network. Consists of one or more CPUs running with or without shared spool.
NCF Complex NCF1 NCF2 site
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 to installing NCF at the NCF2 site(s). All CA-7s executing in the NCF Complex must be at least Version 3.0 or later. Also, only production copies of CA-7 can use NCF for tracking jobs. NCF cannot use a test copy of CA-7. All of the CPUs in the NCF Complex must have the CA-7 SVC and CA-7 SMF interface exits installed at Version 3.0 or later. 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. 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 to be 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 5-11
5.4.2 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.
5.4.2.1 Operating System Environment

CA-7 NCF requires MVS/XA, MVS/ESA, or OS/390 and ACF/VTAM. 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, Computer Associates Resource Initialization Manager, must be on each CPU as well.
5.4.2.2 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 = 180K + (4K * (# of nodes)) Memory requirements of ICOM remain about the same, approximately 20K.
5.4.2.3 DASD Devices

CA-7 NCF supports the following disk drives: 3330 3350 3375 3380 3390 9345
5.4.2.4 DASD Requirements

Permanent files for CA-7 NCF: 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. Refer to the CA-7 install job N030 for sample JCL. Undeliverable queue (UDQ): The UDQ contains CA-7 formatted SMF and trailer data which 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 which 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:
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 may be transmitted. Experience may show that more space is required for a particular site. This data set must be formatted using the SASSNC15. Refer to the CA-7 install job N030 for sample JCL.
Chapter 5. NCF 5-13
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:
Space required for the ICOM communications data set at NCF2 sites should be about 100-150 blocks (about five tracks on 3380 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. Refer to the CA-7 Systems Programmer Guide Chapter 3 for additional information regarding the formatting of the communications data set.
5.4.2.5 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 Computer Associates product. Refer to the CA-7 Getting Started guide for detailed system requirements for CAIRIM.
5.5 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 which allows CA-7 to submit jobs which, through JES NJE routing, may 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 may 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 which are critical to the success of this processing. These considerations are discussed in this topic.
Chapter 5. NCF 5-15
5.5.1 Execution Options

An option may 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 PARM= 3 'TIME=tttttttt'
Where: TIME Is the duration of the WAIT which 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 may be omitted. tttttttt Is the user-specified time limit in one hundredths of a second. Leading zeros may be omitted.
5.5.1.1 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
'
5.5.1.2 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 //UCC7NCFD DD //UCC7NCFU DD //
user job statement specifications user specifications PGM=NCF,PARM='TIME=3 ' DISP=SHR,DSN=cai.ca7.cailib SYSOUT= SYSOUT= SYSOUT= 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 5-17
5.5.2 CA-7 Database

CA-7 NCF provides support for CA-7 jobs that execute at a remote NJE node. Actual execution may 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 screen are important for NJE jobs.
5.5.2.1 Scheduling
All CA-7 scheduling considerations are the same for NJE jobs as for jobs which 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 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.
5.5.2.2 DB.1 Screen

Fields on the DB.1 screen are used for NJE jobs with only a few special considerations. The GENERAL, JCL, REQUIREMENTS, and MESSAGES segments of the DB.1 screen 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 which 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 screen apply to resources which must be available at the remote node.
5.5.3 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 screen 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 screen (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.
5.5.3.1 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 which 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 may require an additional column of the job statement. Refer to Chapter 3 of the CA-7 Systems Programmer Guide.
5.5.3.2 JES2 Statements

Jobs may be routed to a remote node for execution, through JES2, through one of the following control statements: /*ROUTE /*XEQ Refer to 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 which caused the job to be transmitted.
Chapter 5. NCF 5-19
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.
5.5.3.3 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.
5.5.3.4 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 responsibility. Cataloged procedures used in NJE jobs must also be located at the site where conversion and interpretation of the cataloged procedures occur.
5.5.3.5 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 3800 FLASH and MODIFY modules 3800 CHARS tables MVS subsystem names
5.5.4 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 may 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 5-21
5.5.5 General Usage

Several CA-7 facilities routinely used at local nodes may 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 may be demanded, requirements may be posted, and so forth, by executing these programs at the execution node. Activities which 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 may execute at any node in the network based on the routing which is specified in JES control statements within the JCL for the jobs.
5.5.5.1 NCFNODE Parameter

When executing SASSTRLR, SASSBCLP or U7SVC, the EXEC statement may 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 which 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. (Refer to the node table assembly discussion in the VTAM and NCF Node Table Definitions appendix of the CA-7 Getting Started guide for further details on node names.)
5.5.5.2 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 screen, 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.
5.6 System Operations
5.6.1 Initialization
The only recurring initialization task required of the user once the system has been installed is to ensure that ACF/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. See the VTAM and NCF Node Table Definitions appendix of the CA-7 Getting Started guide for a discussion of the programs provided to satisfy this requirement.
5.6.2 Establishing 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. Refer to 5.7.4, LOGON Command on page 5-29 for information.
Chapter 5. NCF 5-23
5.6.3 Standard Operations

5.6.3.1 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 may be displayed for one node or all of the nodes. Refer to 5.7.7, STATUS Command on page 5-32 for more information.
5.6.4 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, it may be desirable to purge its data to prevent the UDQ from being filled. Refer to 5.7.6, PURGE Command on page 5-31 for more information.
5.6.5 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. Refer to 5.7.2, SHUTDOWN Command on page 5-27 and 5.7.1, STOP Command on page 5-26 for more information.
5.7 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, may be used interchangeably with MODIFY. The maximum acceptable length for the command [operand] is 36 characters. Any command which is not syntactically and logically correct will be rejected with the message: CA-7.NC1 1 UNKNOWN COMMAND IGNORED
Chapter 5. NCF 5-25
5.7.1 STOP Command

Use the STOP command to immediately detach the subtask and terminate the NCF job. You should issue a SHUTDOWN command prior to a STOP command to complete all pending processes.
5.7.1.1 Syntax
STOP STOP jobname
Where: jobname Is the OS job or task name of the NCF VTAM application to be terminated.
5.7.1.2 Response
Upon successful completion of the command, the following message is issued: IEF4 4I jobname - ENDED - TIME = hh.mm.ss
5.7.2 SHUTDOWN Command

Use the SHUTDOWN command to post all node processors to complete their pending processes and to log off. It 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.
5.7.2.1 Syntax
SHUTDOWN MODIFY jobname,SHUTDOWN
Where: jobname Is the OS job or task name of the NCF VTAM application to be terminated.
5.7.2.2 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 node(s). Refer to 5.7.7, STATUS Command on page 5-32 for details.
Chapter 5. NCF 5-27
5.7.3 STARTUP Command

Use the STARTUP command after a SHUTDOWN to reestablish communications. It rebuilds all control blocks, opens the ACB and logs on all nodes.
5.7.3.1 Syntax
STARTUP MODIFY jobname,STARTUP
Where: jobname Is the OS job or task name of the NCF VTAM application to be attached.
5.7.3.2 Response
The following message will appear for each node (xxxxxxxx) that was logged on successfully: CA-7.NC3 2 SESSION ESTABLISHED WITH NODE (xxxxxxxx)
5.7.4 LOGON Command

Use of 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.
5.7.4.1 Syntax
LOGON MODIFY jobname,LOGON nodename
Where: jobname Is the OS job or task name of the NCF VTAM application. nodename Is the node with which communication is being established.
5.7.4.2 Response
Upon successful completion of this command, the following message is issued: CA-7.NC3 2 SESSION ESTABLISHED WITH NODE (xxxxxxxx)
Chapter 5. NCF 5-29
5.7.5 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.
5.7.5.1 Syntax
LOGOFF MODIFY jobname,LOGOFF nodename
Where: jobname Is the OS job or task name of the NCF VTAM application. nodename Is the node specified to log off.
5.7.5.2 Response
Upon successful completion of this command, the following message is issued: CA-7.N3 3 LOGOFF REQUEST COMPLETE FOR NODE=xxxxxxxx
5.7.6 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.
5.7.6.1 Syntax
PURGE MODIFY jobname,PURGE nodename
Where: jobname Is the OS job or task name of the NCF VTAM application. nodename Is the node to be purged.
5.7.6.2 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 may 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.
Chapter 5. NCF 5-31
5.7.7 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 which 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.
5.7.7.1 Syntax
All nodes: To display the status of all nodes: STATUS MODIFY jobname,STATUS
Where: jobname Is the OS job or task name of the NCF VTAM application. Single node: To display the status of a single node: STATUS MODIFY jobname,STATUS nodename
Where: nodename Is the single node for which status is to be displayed.
5.7.7.2 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
5.7.7.3 Field Descriptions

The following are descriptions of the individual data items displayed for each node: Item NODE ID STATUS Description The VTAM APPL ACBNAME of the node whose status information is displayed. Each unknown node name will be printed on a separate line. The node ID in hexadecimal. The status of each node: ACTIVE INACTIVE Communication is established with this node. 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 which initiated the communications link is the PLU. RECV SENT UNDL The number of blocks received from the node specified. The number of blocks sent to the specified node. The number of blocks on the undeliverable queue (UDQ) which 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. The number of blocks on the UDQ which contained data for the node that was purged.
PURG
NCF QUEUE The percentage of blocks used in the NCF communications data set compared to total blocks available.
Chapter 5. NCF 5-33
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.
5.7.8 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 the CA-7 NCF technical support staff for problem resolution.
5.7.8.1 Syntax
To activate the trace facility: TRACE MODIFY jobname,TRACE=SNAP n (n,mm,mm,...,mm)
Where: jobname Is 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 may 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.
Chapter 5. NCF 5-35
5.7.9 Deactivating the Trace Facility

To deactivate the previously activated trace facility, the following command is used: TRACE MODIFY jobname,TRACE=OFF
Where: jobname Has the same meaning as in the previous TRACE command entered to activate the tracing facility.
Chapter 6. CA-7 Cross-Platform Scheduling

A CA scheduling solution may request work to be run on its behalf by another CA scheduling solution on a different platform. For example, the Unicenter TNG Workload Manager on a UNIX platform may request that CA-7 schedule MVS jobs on its behalf. The CA scheduling solutions which can participate in cross-platform scheduling are: CA-7, CA-Scheduler, CA-Jobtrac, Unicenter TNG, and CA-7 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 above example, Unicenter TNG is the XPS CLIENT and CA-7 is the XPS SERVER. The workload may 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. This chapter discusses the requirements that allow CA-7 to participate in the crossplatform scheduling environment. All forms of cross-platform scheduling require communications between systems using Computer Associates 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: 6.2, The CA-7 XPS CLIENT on page 6-5 and 6.3, The CA-7 XPS SERVER on page 6-22.
Chapter 6. CA-7 Cross-Platform Scheduling 6-1
6.1 CAICCI Cross-Platform Connections

The OS/390 system and the system running Unicenter TNG or CA-7 Agent must be connected by CAICCI (Computer Associates Common Communications Interface). Specifically, Cross-Platform Scheduling uses the TCPIP/Gateway protocol of CAICCI. The connection may be defined on the OS/390 side, the non-OS/390 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 OS/390 systems that are active the majority of the time and many non-OS/390 systems, some of which may be shut down frequently. In this case, it makes sense to make the CAICCI connection definitions on the non-OS/390 system.
6.1.1 Non-OS/390 CAICCI Connections

CAICCI connections are defined in the following files, depending on the platform: Platform Unix Windows NT Windows NT Product Unicenter TNG or CA-7 Agent Unicenter TNG CA-7 Agent File $caiglbl0000/cci/config/<machine-name>/ccirmtd.prf where <machine-name> is the CCI name of the machine. \TNG\CAIUSER\CCIRMTD.RC \CA\CAIUSER\CCIRMTD.RC
The format of the CCIRMTD file is the same on all non-OS/390 platforms. The first line must be a LOCAL statement and may 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 OS/390, 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. This is recommended. PORT specifies the TCP/IP port number to use. The default is 1721, which is the default port for Unicenter TNG and CA-7 Agent. The default port on OS/390 is 7000 and may be changed on the PROTOCOL(TCPIPGW....) statement. ALIAS is only valid on the LOCAL statement. If the "cciname" is longer than 8 characters, a 1- to 8-character alias must be used to accommodate CAICCI on OS/390 systems. Other CAICCI systems refer to 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.
6.1.2 OS/390 CAICCI Connections

CAICCI protocol and connection definitions on OS/390 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-OS/390 platforms. The types of TCP/IP Gateway protocols are TCPIPGW, TCPIP3GW, and TCPIPSGW. Refer to the CAICCI User Guide for specific information on these protocols. 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 re-establish 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 OS/390, the node name is not case sensitive. The NODE and CONNECT statements may also be issued from a console by prefixing the command with "ENF'. For example:
ENF CONNECT(NODEX)
6.2 The CA-7 XPS CLIENT

The XPS CLIENT for CA-7 sends scheduling requests to a CA scheduling solution (XPS SERVER) which may 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. The submission function is provided by program CA7TOUNI. The tracking function is provided by the CA-7 Cross-Platform Tracking System (XTRK).
6.2.1 Submit Function

Submission consists of CA-7 submitting a batch job which 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, it is recommended that a CA-Driver procedure be used. The following is an example of such a procedure.
//CA7TOUNI //STEP1 // //PROFILE //STEPLIB //SYSPRINT
DPROC EXEC PGM=CA7TOUNI, PARM='&C_L27#,&C_L2SN' DD DISP=SHR,DSN=ca-7.xps.profile DD DISP=SHR,DSN=ca-7.cailib 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 which 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. The following is an example of JCL which 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 may be required for some requests sent to CA-Unicenter TNG on NT platforms. Size/Type: Required: Source: 1 to 15 alphanumeric characters No 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. It is recommended that you use a CA-Driver procedure to automatically insert the CA-7 job number in the JCL for this parameter. Size/Type: Required: Source: 1 to 5 numeric characters Yes EXEC parm
Note: Even though JOBNO can be up to 5 digits CA-Unicenter only supports 4 digit job numbers. Only the last 4 digits are actually sent with the crossplatform request. If the specified job number is less than 4 digits it will be right justified and zero filled. 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. It is recommended that you use a CA-Driver procedure to insert the CA-7 system name in the JCL for this parameter. Size/Type: Required: Source: Default: 1 to 8 alphanumeric characters No EXEC parm, SYSIN, or PROFILE MONITOR name
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 7 characters. CA7PROD should be avoided as that is commonly used by Unicenter TNG and CA-7 for VAX. A good choice might be CA7 followed by the SMF-ID of the originating system. This value must match the one used by the CA-7 CrossPlatform Tracking System (XTRK). Size/Type: Required: Source: 7 alphanumeric characters Yes 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. Size/Type: Required: Source: 1 to 8 alphanumeric characters Yes SYSIN or PROFILE
PARM1 thru PARM64 These optional parameters supply values to be used on the target platform. Values may 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. Size/Type: Required: Source: 1 to 256 alphanumeric characters No SYSIN
SUBCHECK This optional PROFILE parameter can force a security check for authorization of the currently running user to submit jobs for the ID supplied in SUBUSER. Normally such checking is controlled by a flag set in the ICMDSECT module (BSUBCHK). This parameter can be used to force submit checking even if the ICMDSECT setting is off. Size/Type: Required: Source: YES and Y are the only allowed values No 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 PARMx values above. The script named must reside in a special directory identified to Unicenter TNG or must indicate a fully qualified path name. Refer to the Unicenter TNG documentation regarding Client/Server processing and the CAISCHD0004 variable. Size/Type: Required: Source: 1 to 256 alphanumeric characters Yes SYSIN
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. Size/Type: Required: Source: 1 to 14 alphanumeric characters No 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.
SUBROOT This optional PROFILE parameter determines whether the special user ID of ROOT may 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 will not be allowed by this interface. In order to submit work using ROOT as the user ID, this parameter must be present with a value of "YES" or "Y". Size/Type: Required: Source: Default: YES, NO, Y and N are the only allowed values No PROFILE NO
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, it is recommended that ROOT not be specified. Size/Type: Required: Source: Default: 1 to 32 alphanumeric characters No SYSIN or PROFILE Batch job user ID
SUTYPE This optional parameter determines the type of "switch user' command that will be executed if the target node is UNIX. If the parameter is YES (default), then an 'SU-' command will be executed causing the environment setup to include execution of the '.PROFILE' for the target user. If the parameter is NO, then an 'SU' command will be executed without the profile option. Size/Type: Required: Source: Default: YES, NO, Y and N are the only allowed values No SYSIN or PROFILE YES
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 which may be helpful in pinpointing exactly when an error is encountered. Size/Type: Required: Source: Default: YES, NO, Y or N are only allowed values No SYSIN or PROFILE NO
Examples: The following is an example of a job to list the status of Unicenter TNG 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). Refer to the messages produced in the submit job output to determine the exact nature of the problem.
6.2.2 Cross-Platform Tracking

Tracking consists of the XPS SERVER returning feedback records for CA-7 submitted jobs to the system which sent the request. These records are transmitted using CAICCI and represent job initiation, job termination, and job failure events. The CA-7 Cross-Platform Tracking System (XTRK) running as a started task, batch job, or as a subtask under ICOM on the OS/390 system where the CA-7 Cross-Platform Submit job executed receives these events and converts them into 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 running on each system where CA-7 CrossPlatform Submit (CA7TOUNI) jobs can execute. CA-7 ICOM must also be executing on these systems. Also, events such as job execution and file creation/update which occur on non-OS/390 platforms can be tracked even though CA-7 did not request that work (Cross-Platform External Tracking). Unicenter TNG or CA-7 Agent must be executing at the remote node for this tracking to occur. For specific information on running CA-7 XTRK as a subtask in the CA-7 ICOM address space, see Cross-Platform Tracking under ICOM in Chapter 6 of the CA-7 Systems Programmer Guide.
6.2.2.1 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=...ca-7..cailib... //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 pre-formatted.
The XEVENTS DD is optional. If specified, it should point 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. Refer to 6.2.2.3, CA-7 Cross-Platform External Tracking on page 6-15 for information on the format of these rules. The EXEC PARM values for XTRK are:
PARM='monitor,ca-7-subsystem,trace-codes'
monitor This required parameter is the 7 character monitor name which 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-subsystem This optional parameter specifies the 4 character subsystem 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 production copy of CA-7 uses subsystem UC07 (this is the default), and the test or secondary copy of CA-7 uses subsystem UCT7. The values PROD and TEST can be substituted for UC07 and UCT7. 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 '11'. 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 Technical 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 which 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 '2' and a console trace code of '1', the parm value on the EXEC statement would be:
PARM='CA7IPO1,PROD,21'
6.2.2.2 CA-7 Cross-Platform Tracking Commands

The CA-7 Cross-Platform Tracker (XTRK) accepts MODIFY and STOP operator commands. XTRK MODIFY commands are:
Table 6-1 (Page 1 of 2). XTRK Modify Commands
Command ADDNODE(nnnnnnn) BLDXEVT
Explanation Add a CAICCI node (nnnnnnnn) to the XTRK Node Table. XTRK will attempt to establish communications with that node. Rebuild 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. Delete a CAICCI node (nnnnnnnn) from the XTRK Node Table. XTRK will no longer attempt to communicate with that node. List Node(s) 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*). Refer to messages CAL2X155I and CAL2X156I. List Node(s) from the XTRK Node Table indicating the CAICCI node name and the Unicenter TNG or CA-7 Agent 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*). Refer to message CAL2X154I. List Node(s) 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*). Refer to messages CAL2X155I and CAL2X156I. 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. Forces a storage snap to be written to the XSNAP DD (if available and open). The options are: SVT TAB XEVT ALL XTRK System Vector Table XTRK Node Table Block(s) XTRK External Event Table entries all of the above
DELNODE(nnnnnnn) NODE
NODEN
NODEX
PING
SNAP(..option..)
STOP
Causes XTRK to perform normal shutdown processing. This can also be done using the operator STOP command (P CA7XTRK).
Table
6-1 (Page 2 of 2). XTRK Modify Commands
Command TRC(pc)
Explanation 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 List Rules from the XTRK External Tracking Event table. Refer to 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 which apply to that node argument. For example: XEVT(AIX*).
6.2.2.3 CA-7 Cross-Platform External Tracking

The CA-7 Cross-Platform Tracker (XTRK) can request notification of job events and file create/updates from Unicenter TNG or CA-7 Agent. For jobs to be tracked, they must be under the control of Unicenter TNG. However, the creation or update of files can be detected by Unicenter TNG or CA-7 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 card-image data set or PDS member which 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 which 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 which match the format of OS/390 CA-7 External Tracking. The CA-7 address space treats these pseudo-SMF records in the same manner as other external tracking records. Refer to the CA-7 Systems Programmer Guide for information on setting up CA-7 to process external tracking.
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( may 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. Lines may be continued at any point (inside or outside a keyword) by ending the line with " -" (a blank followed by a dash). The line will be continued with the first non-blank character on the next line. Comments may be coded by placing an asterisk (*) in column 1. Keyword TYPE( Function 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 Unicenter TNG. JNO( is REQUIRED for TYPE(JOB) events. It is ignored for other types. For event TYPE(JOB), the jobset name of the job to be tracked as defined to Unicenter TNG. JOBSET( is REQUIRED for TYPE(JOB) events. It is ignored for other types.
JOBSET(
Keyword MVSNAME(
Function For event TYPE(JOB), the job name which conforms to MVS standards to be used by CA-7 to track this job. For event TYPE(DSN), the fully qualified data set name which conforms to MVS standards to be used by CA-7 to track this file. MVSNAME( is REQUIRED for TYPE(JOB) and TYPE(DSN) events. For event TYPE(JOB), the name of the job to be tracked as defined to Unicenter TNG. For event TYPE(DSN), the fully qualified name of the file to be tracked. 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. The CAICCI node name at which Unicenter TNG or CA-7 Agent should watch for this event. For TYPE(CONNECT) it is the node name which 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. 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. Refer to the Unicenter TNG documentation for more information on these methods. STAT( is optional for EVENT(DSN) events and ignored for all other events.
NAME(
NODE(
STAT(
The XTRK command XEVT may be used to display the current External Events. The XTRK command BLDXEVT may be used to re-build the table of External Events. Refer to 6.2.2.2, CA-7 Cross-Platform Tracking Commands on page 6-14 for more information on these commands.
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) )
Unicenter TNG will send XTRK feedback when TNG 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 Unicenter TNG system that XTRK connects with, whose CAICCI Node name begins with the characters 'AIX', will be asked to send XTRK feedback when TNG 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 which will capture tracking for this job regardless of which AIX machine it runs on.
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 Unicenter TNG or the CA-7 Agent on 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 OS/390 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). It is recommended to have 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 CrossPlatform jobs are submitted to. If you wish 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 which explicitly references that node. If the only rules which 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 on enabling CA-7 external tracking, see Tracking External Tasks in the CA-7 Systems Programmer Guide.
6.2.3 CA-7 Considerations

As noted above for the Submit Function, any job whose JCL starts with #7UNI will be 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 which 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, it is recommended 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 may be included in the JCL as SYSIN data, certain special considerations are applied to jobs flagged for submittal to another system. Many Unicenter TNG and CA-7 Agent 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 may 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 screen) FE function QM.5 (QJCL screen) FE and FETCH functions QM.1-X (XQ screen) 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 of CA-7. Use the JCL screen to FETCH it (do not use FE or EDIT). Next use the QJCL screen to REPL the request queue job's JCL thus bypassing the CA-7 editor.
6.2.4 CA-7 XPS Client Implementation Checklist

1. Define CAICCI connections among systems. Refer to 6.1, CAICCI Cross-Platform Connections on page 6-2. These CAICCI connections are the same regardless of which side is acting as the XPS CLIENT or XPS SERVER. Note: This interface requires CA90s (service level C0 or later) or Unicenter TNG Framework for OS/390, Unicenter TNG, and CA-7 Agent. It is NOT compatible with earlier versions of CA90s or Unicenter. If you are communicating with Unicenter TNG or the CA-7 Agent on a Windows/NT platform and also have CA-7 WorkStation on the same machine, you must ensure that CAICCI Remote Services and the CAICCI-PC Properties use different System Names for the Windows/NT 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. Refer to CA-7 SAMPJCL member XPSPROF and to 6.2.1, Submit Function on page 6-5. 3. Allocate CA-7 XTRK Checkpoint file(s). Refer to CA-7 SAMPJCL member XPSCKPT and to 6.2.2.1, CA-7 Cross-Platform Tracking JCL on page 6-11. 4. Define and start CA-7 Cross-Platform Tracking Task(s) (XTRK). Refer to CA-7 SAMPJCL member CA7XTRK and to 6.2.2.1, CA-7 Cross-Platform Tracking JCL on page 6-11. 5. Define the CA-Driver Procedure for the CA-7 XPS Submit Function. Refer to CA-7 SAMPJCL member CA7TOUNI and to 6.2.1, Submit Function on page 6-5. If you are not familiar with CA-Driver, refer to Chapter 4, CA-Driver Procedures, Variable Parameters, and Functions on page 4-1. 6. Define the CA-7 cross-platform jobs and JCL for the Submit Function. Refer to CA-7 SAMPJCL member CA7XSUB and to 6.2.1, Submit Function on page 6-5. 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. Refer to 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).
6.3 The CA-7 XPS SERVER

The CA-7 XPS SERVER receives scheduling requests from a CA scheduling solution which may 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.
6.3.1 The XPS Submit Monitor

The XPS SUBMIT MONITOR is the function which 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.
6.3.1.1 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 which 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 statement in the CA-7 initialization file determines the scheduling command that is issued when a cross-platform scheduling request is received. Refer to 6.3.4, Managing the Cross-Platform Workload on page 6-31 and to the discussion of the XPSSCHD keyword on the SVCNO initialization file statement in the CA-7 Systems Programmer Guide for additional information on this important parameter. 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. Refer to the CA-7 Security Guide for additional information. 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 Unicenter TNG 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.
6.3.1.2 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 initialization file statement affects the way job completion status updates are reported to the XPS CLIENT. If the default of XPSSCHD=RUNREF is used, then a CAIENF record for job completion is created immediately when the job terminates. If XPSSCHD=DEMAND or XPSSCHD=RUN is coded then the job completion status update will not be 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.
6.3.2 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 may be more than one CA scheduling solution executing. For example, there may be both production and test copies of CA-7 executing on the same MVS image. The cross-platform scheduling router enables both copies 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 which originated the request. Cross-platform scheduling communication is performed by using the Computer Associates Common Communications Facility (CAICCI). A copy of CAICCI runs on each system where Computer Associates 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-tohost connection). Each copy of CAICCI has a unique identifier known as the node name. On each system, Computer Associates 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 which it is connected to. There are several unique CAICCI application names which are used only for cross-platform scheduling. The combination of the node name and the unique CAICCI application names enable Computer Associates scheduling solutions to route requests for work and the feedback from that work. Besides the unique node and CAICCI application names each Computer Associates scheduling solution which participates in cross-platform scheduling has a seven-character identifier known as a monitor name. In an MVS environment, each Computer Associates scheduling solution must have a monitor name that is unique in the local MVS environment. Thus, on a system where there are both production and test copies of CA-7 at the same node, they must have different monitor names in order for cross-platform scheduling to work properly for both copies. The CAICCI application names used by cross-platform scheduling are based on the functions they perform. The CAICCI application which receives requests for work has a fixed name which 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) which 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 which 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. 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 7-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 7-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 that node. These applications appear only on MVS and are controlled by each CA scheduling solution participating in crossplatform scheduling.
6.3.3 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 which are not 'trusted' you can write rules so that any request from them which contains a user ID must also carry a password that can be validated by the cross-platform server. Requests received from these systems which 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 re-initialized.
6.3.3.1 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.
6.3.3.2 Keywords
NODE=caicci-node-name This keyword identifies the 1 to 8 character CAICCI node name that a CrossPlatform request can be received from. It must be specified as a specific name or an asterisk (*) which indicates all nodes. If not specified the default is NODE=* indicating all nodes. MONITOR=monitor-name This keyword identifies the 7 character scheduling system monitor name that a CrossPlatform request can be received from. It must be specified as a specific name or an asterisk (*) which indicates all monitor names. In cases where a given node may have multiple scheduling systems (such as production and test copies 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 This keyword identifies the 1 to 8 character user ID that may be passed with a crossplatform request. It must be specified as a specific name or an asterisk (*) which indicates all user IDs. If not specified the default is ID=* indicating all user IDs. PSWD=YES/NO This keyword indicates whether a cross-platform request which 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.
6.3.3.3 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 rule(s) which require a password will take precedence over those which do not. If no match is found in the table then the request will be allowed to proceed without a password.
6.3.3.4 Examples
NODE=A 4IENF,MONITOR=CA7PROD,ID= ,PSWD=YES
The above rule indicates that any request from CAICCI node A04IENF, scheduling system CA7PROD must have a password if it contains an explicit user ID.
NODE= ,ID=MASTER,PSWD=YES
The above rule indicates that any request which 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 above 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 above rules. The second rule will take precedence since a specific ID match will take precedence over a specific NODE match. A password WILL NOT be required.
NODE=A 4IENF,MONITOR= ,ID= ,PSWD=YES NODE= ,MONITOR=CA7PROD,ID= ,PSWD=NO
If a request is received from CAICCI node A04IENF, scheduling system CA7PROD with any user ID it will partially match on both of the above rules. In this case the matches have equal weight (NODE or MONITOR specific, ID generic). In the case of a tie the rule which requires a password will take precedence over one which does not. A password WILL be required.
6.3.4 Managing 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 which may 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: 1. Using a special variant of the RUN command referred to as RUNREF 2. the DEMAND command, or 3. the RUN command. CA-7 determines how the job will enter the request queue based on the value of the XPSSCHD keyword on the SVCNO 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, Unicenter TNG). The primary responsibility for workload control belongs to the XPS CLIENT. Jobs scheduled using this option will NOT honor requirements defined in CA-7, they will NOT be 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. A greater degree of workload control over cross-platform jobs may 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, since 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 SVCNO initialization file statement is used to declare a global option which applies to all jobs requested from XPS CLIENTs. This parameter may be overridden for selected jobs by coding this keyword in the 'Filename' field (Job Detail - Submission - Filename) in Unicenter TNG. Refer to Step 6 in 6.3.5, CA-7 XPS Server Implementation Checklist on page 6-33.
6.3.5 CA-7 XPS Server Implementation Checklist

1. Define CAICCI connections among systems. Refer to 6.1, CAICCI Cross-Platform Connections on page 6-2. These CAICCI connections are the same regardless of which side is acting as the XPS CLIENT or XPS SERVER. This interface requires CA90s (service level C0 or later) or Unicenter TNG Framework for OS/390 and Unicenter TNG. It is NOT compatible with earlier versions of CA90s or Unicenter. If you are communicating with Unicenter TNG on a Windows/NT platform and also have CA-7 WorkStation on the same machine, you must ensure that CAICCI Remote Services and the CAICCI-PC Properties use different System Names for the Windows/NT 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. Define CAIENF Cross-Platform Scheduling Feedback Event (CAXPSFBK). Refer to CA-7 SAMPJCL member L2DCM2. This job will define the CAXPSFBK CAIENF event and data elements. If CAIENF is active when the L2DCM2 job is run it will need to be shut down and restarted to make the CAXPSFBK event available. 3. Add cross-platform scheduling keywords to the CA-7 initialization file. Select the appropriate values for cross-platform scheduling on the SVCNO initialization file statement: a. Specify MONITOR=YES. This indicates that CA-7 XPS SERVER functions should be activated. b. The XPS ROUTER will execute on only one copy of CA-7 at any given CAICCI node. The XPS ROUTER will be started on the production copy of CA-7 by default if MONITOR=YES is coded. If cross-platform scheduling is to be used only with a test copy of CA-7 then ROUTER=YES must be coded on the SVCNO statement for the test copy in order to start the XPS ROUTER under the test copy of CA-7. c. Determine the appropriate value for the XPSSCHD parameter based upon 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 then consider either DEMAND or RUN values for XPSSCHD. At least one internal terminal must be defined for use by cross-platform scheduling. Refer to the CA-7 Systems Programmer Guide for additional information on terminals with DEVICE=TRXDV. Refer to the CA-7 Systems Programmer Guide for information on the initialization options for CA-7 XPS SERVER functions. CA-7 will need to be shut down and restarted for these options to take effect.
4. Define cross-platform scheduling password requirement rules. If you wish 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). Refer to 6.3.3, Cross-Platform Server Password Requirements on page 6-28 for information on coding the password requirement rules. 5. In Unicenter TNG, define a Station for the system where CA-7 executes. Refer to the Unicenter TNG documentation for the specific procedures to define a Station. 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 Unicenter TNG. Refer to the Unicenter TNG documentation for the specific procedures to define Jobsets and Jobs. a. Use the 'Station' defined above in the Job definition (Job Detail - Main Panel). b. Specify the MVS jobname that is defined to CA-7 in the 'Filename' field (Job Detail - Submission - Filename). c. If you have more than one copy of CA-7 at the target MVS system and you wish to route this job to the secondary copy, add the keyword ',MONITOR=monitor-name' after the MVS jobname in the 'Filename' field. For example, if you wish to execute job TESTJOB1 on the test copy of CA-7 whose monitor name is 'TESTCA7', specify a Filename of 'TESTJOB1,MONITOR=TESTCA7'. d. The value of the XPSSCHD keyword on the SVCNO 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 jobname in the 'Filename' field. For example, if job TESTJOB1 is to be DEMANDed on the test copy of CA-7 but the XPSSCHD value in CA-7 is RUNREF, then specify the following in Filename: 'TESTJOB1,MONITOR=TESTCA7,XPSSCHD=DEMAND'. e. If you wish 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 DetailSubmission-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, then a password will not be required.
7. Define the MVS jobs to CA-7. The jobs which 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 Unicenter TNG jobs. Refer to CA-7 documentation for information on defining a job in CA-7. The Automated Recovery Facility (ARF) CANNOT be used with cross-platform jobs. 8. Schedule/Demand the Unicenter TNG Jobset. Refer to the Unicenter TNG documentation for the specific procedures to schedule Jobsets/Jobs. 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).
Index
Special Characters
& (ampersand) (CA-Driver) 4-13 &C_DATE parameter 4-16 &C_DAY parameter 4-16 &C_JDATE parameter 4-16 &C_MONTH parameter 4-16 &C_TIME parameter 4-16 #statements See alphabetical listing
C
CA-1 interface 2-3 CA-11 ARTS Command Monitor 2-6 automatic CMT updating 2-7 RMS insertion 2-7 interface 2-5 CA-7 Agent 6-1 CA-7 facilities Batch Card Load Program (SASSBCLP) 5-22 LOAD process (SASSJJCL) 5-22 trailer step (SASSTRLR) 5-22 U7SVC utility 5-22 CA-7 submitted jobs 5-2 CA-7 WorkStation 2-8 CA-7/API requirements 2-27 CA-7/Notepad 2-38 CA-7/Report Balancing 2-38 CA-7/Reports+ 2-38 CA-7/Smart Console 2-39 CA-APCDDS interface 2-9 CA-APCDOC interface 2-9 CA-Dispatch interface 2-10 CA-Driver activating 4-1 branching conditional 4-35 unconditional 4-33 commands 4-32 comments 4-40 cross-platform scheduling 6-5 functions 4-26 overview 4-1 procedure library 4-4 procedure, expanding 4-32 reserved-name variable parameters 4-16 sequence numbers 4-15 variable parameters 4-9 CA-Earl reporting 2-12 CA-Easytrieve Plus reporting 2-12 CA-JCLCheck interface 2-13 CA-Librarian interface 2-14 CA-Netman interface 2-15 CA-Opera interface 2-20 CA-OPS/MVS II interface 2-20
A
Activating CA-Driver 4-1 Allocating space 5-13 Ampersand (&) (CA-Driver) 4-13 Arrays 4-21 ARTS command 2-6 Asynchronous processing time (NCF) Attribute testing 4-23
5-16
B
Batch Card Load program See BCLP Batch commands format 3-3 installation process 3-5 Batch step execution 3-14 BCLP ABORT 3-27 and U7SVC facility 3-13 CA-7 requirements 3-26 control statements 3-28 DB 3-27 DBPARMS 3-28 description 3-26 ERR 3-27 EXITPROG 3-27 JCL requirements 3-27 using 3-26 BPXBATCH program 2-42 BTI N220 job 3-5 overview 3-1 parameters 3-8
Index X-1
CA-Panvalet interface 2-23 CAICCI CCI interface 3-1 cross-platform scheduling 6-11 CAICCI connections 6-2 CAIENF events 6-11 CAIRIM requirement for 5-3, 5-14 resource initialization manager 5-4, 5-6 CAISMFI dynamic SMF event interceptor 5-6 Calculating region size 5-12 Calling U7SVC from a user program 3-16 CL233SB SYSMOD 2-5 CL233SC SYSMOD 2-5 Commands ARTS 2-6 CA-Driver 4-32 LOGOFF 3-4 LOGON 3-3 NCF 5-25 Communications data set and ICOM 5-7 file description 5-13 overview 5-8 Conditional procedure expansion 4-32 Control statements for BCLP 3-28 CPM 2-20 CREATE (data set request statements) 3-34 Critical Path Monitoring 2-20 Cross-platform scheduling and CA-Driver 6-5 Overview 6-1 XPS CLIENT 6-5 XPS SERVER 6-22 Cross-platform Server password requirements 6-28 CWORK 2-3
DB.1 screen (continued) Resources segment 5-18 DBM batch commands, format 3-3 DCM SAMPJCL member 2-20, 2-39 Defining CA-Driver procedures 4-4 DEND statement 4-7 DFLUSH command 4-39 DGOTO command 4-33 DIF command 4-35 Disk drives supported 5-12 DLCTR command 4-39 DM3Y function 4-28 DM3YR function 4-29 DMY function 4-28 DMYR function 4-28 DOW function 4-29 DOW# function 4-29 DSET command 4-37 DSTEP command 4-33 DTADD function 4-27 DTDIF function 4-27 DTSUB function 4-27 Dynamic initialization routines 5-6
E
End-of-Data Set (EODS) Statement 3-37 Enhancements 1-1 Error recovery 5-24 Events, CAIENF 6-11 Examples Data Flow Within One CPU 5-4 NCF VTAM PARM 5-17 Execution options 5-16 External See External Communicators External Communicators 3-1
D
DABORT command 4-39 DASD devices 5-12 requirements 5-13 Data inclusion 4-8 Data set request statements 3-34 Data sets 5-21 DATA statement (CA-Driver) 4-7 DAY function (CA-Driver) 4-29 DB.1 screen Execution segment 5-18 JCL segment 5-19 Messages segment 5-19
F
Files, permanent CA-7 NCF 5-13 Flows 2-21 Forecasting print volumes with CA-Dispatch Format NCF communications data set 5-13 UDQ 5-13 Functions for CA-Driver 4-26 2-10
I
ICOM communications data set 5-14
X-2 CA-7 3.3 Interfaces Guide
ICOM (continued) requirements 5-12 Implementation considerations CA-7 facilities 5-22 data sets 5-21 database 5-18 DB.1 screen 5-18 DD statements 5-20 EXEC statements 5-20 execution JCL 5-19 general usage 5-22 JES NJE capabilities 5-15 JES2 statements 5-19 JES3 statements 5-20 JOB statement 5-19 LOAD process 5-22 NCFNODE parameter 5-22 overview 5-15 scheduling 5-18 XPS CLIENT 6-21 XPS SERVER 6-33 Including data 4-6 Interfaces CA-1 2-3 CA-11 2-5 CA-APCDDS 2-9 CA-APCDOC 2-9 CA-Dispatch 2-10 CA-Earl 2-12 CA-Easytrieve Plus 2-12 CA-JCLCheck 2-13 CA-Librarian 2-14 CA-Netman 2-15 CA-Opera 2-20 CA-OPS/MVS II 2-20 CA-Panvalet 2-23 list 2-2 OS/390 UNIX System services TSO/ISPF 2-29 ISPF interface 2-29 with CA-Driver 4-4
L
LDOM function 4-31 Length attribute 4-24 Librarian See CA-Librarian interface Link editing node table 5-7 List function in batch commands LJDOM function 4-31 LOGOFF command 5-30 LOGON command 5-29 Loop control 4-39
3-4
M
M3DY function 4-28 M3DYR function 4-29 MDY function 4-28 MDYR function 4-28 Memory requirements 5-12 MNADD function 4-27 MNSUB function 4-27 MNT override statement 3-26 MODIFY command 5-25 MON function 4-29 MON# function 4-29 MONTH function 4-29 Multi-access spool 5-8 MVS dynamic initialization component
5-6
N
N220 job 3-5 NCF system commands 5-25 components 5-4 Data Flow Within One CPU 5-4 operations CA-7 NCF functions 5-23 create control blocks 5-23 error recovery 5-24 establish communications 5-23 initialization 5-23 loading node table 5-23 overview 5-23 scanning files 5-23 standard operations 5-24 status information 5-24 termination 5-24 overview CA-7 NCF components 5-4 CAIRIM 5-6 ICOM 5-7
2-24
J
JCL requirements for BCLP JDOM function 4-31 JES2 statements 5-19 JES3 statements 5-20 JOB statement 5-19 3-27
Index X-3
NCF system (continued) overview (continued) NCF Communications Data Set 5-8 NCF undeliverable queue (UDQ) 5-8 NCF VTAM Application Program 5-8 node table 5-7 OPERATOR commands 5-25 purpose 5-2 requirements 5-3 SVC interface 5-6 unknown node table 5-7 requirements 5-3 NCF VTAM application program 5-8 application program functions 5-8 PARM 5-17 NCFNODE parameter 5-22 NEST statement 4-5 Nested procedures 4-5, 4-14 Network job entry (NJE) 5-2 Node Table loading 5-23 requirements 5-7 Non-DBM batch commands, format 3-5 Null value 4-22 Number attribute 4-25
PF key support 2-34 Procedure for CA-Driver creating 4-4 expansion aborting 4-39 conditional 4-32 controlling loops 4-39 shifting during 4-15 nesting 4-5, 4-14 parameter substitution 4-9 retrieving 4-4 storing 4-4 PURGE command 5-7, 5-31
R
Region size, calculating 5-12 Reporting CA-Earl reporting 2-12 CA-Easytrieve Plus reporting 2-12 Requirements CAIRIM 5-14 DASD 5-13 Reserved-name variable parameters 4-16 Resource initialization manager 5-4, 5-6 Restarting jobs with CA-Driver 4-34 Retrieving procedures for CA-Driver 4-4 Return codes and SASSXXBT message table Router, XPS 6-25
O
Operating system environment 5-12 Operator commands format 5-26 LOGOFF 5-30 LOGON 5-29 MODIFY 5-25 overview 5-25 PURGE 5-31 response 5-26 SHUTDOWN 5-26, 5-27 STARTUP 5-28 STATUS 5-27, 5-32 STOP 5-25, 5-26 TRACE 5-35 OPTION statement (BCLP) 3-30 Options for CA-7 2-38 OS/390 UNIX System services interface
3-6
S
SASSBCLP (Batch Card Load Program) using 3-26 using with NCF 5-22 SASSBSTR program overview 3-6 PARM values 3-8 SASSDPCH module 2-10 SASSLIBR module 2-14 SASSNC01 module 5-35 SASSNC03 module 5-35 SASSNC04 module 5-35 SASSNC12 program 5-13 SASSNC15 program 5-13 SASSPANV module 2-23 SASSTRLR program 5-22 SASSXXBT message table 3-6 Scheduling cross-platform 6-1 day and time values 5-18
2-24
P
Password requirements for cross-platform scheduling Permanent files, CA-7 NCF 5-13 6-28
Shifting during expansion 4-15 SHUTDOWN command, NCF and STOP command 5-26 description 5-27 terminating NCF 5-24 SMF interface exits 5-3, 5-6 Space allocations 5-13 Startup command 5-28 Status CA-7 NCF VTAM 5-33 command 5-24, 5-27, 5-32 information 5-24 STOP command 5-24, 5-26 Substring referencing 4-19 Summary of enhancements 1-1 SVC interface 5-3, 5-6 System information &C_DATE 4-16 &C_DAY 4-16 &C_JDATE 4-16 &C_MONTH 4-16 &C_TIME 4-16
Unicenter TNG 2-37, 6-1 UNIX System Services scheduling jobs 2-42 Unknown node table 5-7
V
Variable parameter arrays 4-21, 4-25 attribute testing 4-23 coding 4-11 in nested procedures 4-14 length attribute 4-24 number attribute 4-25 reserved-name 4-16 substitution 4-9, 4-13 substring referencing 4-19 types 4-23 values changing 4-37 defining 4-11 multiple 4-21 null 4-22 overriding 4-12 testing 4-23 Verification of data inclusion 4-8 Verifying JCL with CA-Driver 4-3 Virtual terminals, installation requirements 2-37 VTAM PARM for NCF VTAM application program 5-17 requirements for CA-7 under TSO/ISPF 2-29
T
Termination 5-24 Terminology 5-11 TIQ interface 2-3 TRACE command 5-35 Trailer data 5-7, 5-8 Trailer step facility figure 3-10 JCL 3-12 overview 3-10 TSO/ISPF interface 2-29 Type attribute 4-23 Typical NCF environment 5-5
W
WOM function Workload management management WOY function 4-29 and cross-platform scheduling and NCF 5-2 4-30 6-31
U
U7SVC facility at remote nodes 5-22 overview 3-1 using 3-13 UCC7NODE table 5-24 UDQ See Undeliverable queue (UDQ) Undeliverable queue (UDQ) and PURGE command 5-24 and unknown node table 5-7 DASD requirements 5-13 overview 5-8
X
XPS CLIENT submission 6-5 tracking 6-5 XPS Router 6-25 XPS Submit Monitor creating status information submission 6-22
6-22
Index X-5
Y
YM3D function 4-28 YMD function 4-28 YRM3D function 4-29 YRMD function 4-28

Ca7 Interface Guide

Transféré par

Informations du document

Description originale:

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Ca7 Interface Guide

Transféré par

Droits d'auteur :

Formats disponibles

CA-7

Interfaces Guide 3.3

1-1 1-2 1-2 1-5

iv CA-7 3.3 Interfaces Guide

vi CA-7 3.3 Interfaces Guide

viii CA-7 3.3 Interfaces Guide

Chapter 1. Introduction 1-1

1.1 Summary of Revisions

1.1 Summary of Revisions

1.1.1 Product Changes

1-2 CA-7 3.3 Interfaces Guide

1.1 Summary of Revisions

Chapter 1. Introduction 1-3

1.1 Summary of Revisions

1-4 CA-7 3.3 Interfaces Guide

1.1 Summary of Revisions

1.1.2 Documentation Changes

Chapter 1. Introduction 1-5

1-6 CA-7 3.3 Interfaces Guide

Chapter 2. CA-7 Interfaces and Options

Chapter 2. CA-7 Interfaces and Options 2-1

2.1 CA-7 Interfaces with Other Products

2.1 CA-7 Interfaces with Other Products

2-2 CA-7 3.3 Interfaces Guide

2.1 CA-7 Interfaces with Other Products

Chapter 2. CA-7 Interfaces and Options 2-3

2.1 CA-7 Interfaces with Other Products

2.1.1.1 TIQ Command

2-4 CA-7 3.3 Interfaces Guide

2.1 CA-7 Interfaces with Other Products

Chapter 2. CA-7 Interfaces and Options 2-5

2.1 CA-7 Interfaces with Other Products

2.1.2.1 ARTS Command Monitor

2-6 CA-7 3.3 Interfaces Guide

2.1 CA-7 Interfaces with Other Products

2.1.2.2 Automatic RMS Step Insertion

2.1.2.3 Automatic CMT Updating

Chapter 2. CA-7 Interfaces and Options 2-7

2.1 CA-7 Interfaces with Other Products

2.1.3 CA-7 WorkStation

2-8 CA-7 3.3 Interfaces Guide

2.1 CA-7 Interfaces with Other Products

2.1.5.1 Comparing FSTRUC to a Database Flowchart

Chapter 2. CA-7 Interfaces and Options 2-9

2.1 CA-7 Interfaces with Other Products

2.1.6.1 Forecasting Print Volumes

2.1.6.2 Creating a Plan Data Set

2-10 CA-7 3.3 Interfaces Guide

2.1 CA-7 Interfaces with Other Products

Chapter 2. CA-7 Interfaces and Options 2-11

2.1 CA-7 Interfaces with Other Products

2.1.8 CA-Easytrieve Plus

2-12 CA-7 3.3 Interfaces Guide

2.1 CA-7 Interfaces with Other Products

2.1.9.1 CA-7 Considerations

Chapter 2. CA-7 Interfaces and Options 2-13

2.1 CA-7 Interfaces with Other Products

2-14 CA-7 3.3 Interfaces Guide

2.1 CA-7 Interfaces with Other Products

2.1.11.1 CA-7 Considerations

Chapter 2. CA-7 Interfaces and Options 2-15

2.1 CA-7 Interfaces with Other Products

2.1.11.2 CA-Netman Considerations