Ca7 Interface Guide

CA-7®Interfaces Guide

3.3

This documentation and related computer software program (hereinafter referred to as the “Documentation”) is forthe end user's informational purposes only and is subject to change or withdrawal by Computer Associates Interna-tional, Inc. (“CA”) at any time.

THIS DOCUMENTATION MAY NOT BE COPIED, TRANSFERRED, REPRODUCED, DISCLOSED, ORDUPLICATED, IN WHOLE OR IN PART, WITHOUT THE PRIOR WRITTEN CONSENT OF CA. THIS DOC-UMENTATION IS PROPRIETARY INFORMATION OF CA AND PROTECTED BY THE COPYRIGHT LAWSOF 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 WARRAN-TIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. INNO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS ORDAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUTLIMITATION, LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA ISEXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE.

THE USE OF ANY PRODUCT REFERENCED IN THIS DOCUMENTATION AND THIS DOCUMENTATIONIS 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 11749All rights reserved.

All trademarks, trade names, service marks, or logos referenced herein belong to their respective companies.

Contents

Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11.1 Summary of Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

1.1.1 Product Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.1.2 Documentation Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Chapter 2. CA-7 Interfaces and Options . . . . . . . . . . . . . . . . . . . . . . . 2-12.1 CA-7 Interfaces with Other Products . . . . . . . . . . . . . . . . . . . . . . . . 2-2

2.1.1 CA-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32.1.1.1 TIQ Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

2.1.2 CA-11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52.1.2.1 ARTS Command Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 2-62.1.2.2 Automatic RMS Step Insertion . . . . . . . . . . . . . . . . . . . . . . 2-72.1.2.3 Automatic CMT Updating . . . . . . . . . . . . . . . . . . . . . . . . 2-7

2.1.3 CA-7 WorkStation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82.1.4 CA-APCDDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92.1.5 CA-APCDOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9

2.1.5.1 Comparing FSTRUC to a Database Flowchart . . . . . . . . . . . . . 2-92.1.6 CA-Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10

2.1.6.1 Forecasting Print Volumes . . . . . . . . . . . . . . . . . . . . . . . 2-102.1.6.2 Creating a Plan Data Set . . . . . . . . . . . . . . . . . . . . . . . . 2-10

2.1.7 CA-Earl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-122.1.8 CA-Easytrieve Plus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-122.1.9 CA-JCLCheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

2.1.9.1 CA-7 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 2-132.1.10 CA-Librarian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-142.1.11 CA-Netman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15

2.1.11.1 CA-7 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152.1.11.2 CA-Netman Considerations . . . . . . . . . . . . . . . . . . . . . . 2-162.1.11.3 CA-Netman Model Transactions . . . . . . . . . . . . . . . . . . . 2-162.1.11.4 CA-Netman Model Transactions - Continuation Rules . . . . . . . 2-172.1.11.5 CA-Netman Model Transactions - Variables . . . . . . . . . . . . . 2-18

2.1.12 CA-Opera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-202.1.13 CA-OPS/MVS II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20

2.1.13.1 Critical Path Monitoring . . . . . . . . . . . . . . . . . . . . . . . . 2-202.1.14 CA-Panvalet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23

2.1.14.1 CA-Panvalet Prior to Version 14.0 . . . . . . . . . . . . . . . . . . 2-232.1.15 OS/390 UNIX System Services Interface . . . . . . . . . . . . . . . . . 2-24

2.1.15.1 Invoking the Interface . . . . . . . . . . . . . . . . . . . . . . . . . 2-242.1.15.2 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . 2-25

2.1.16 CA-7/API Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 2-272.1.17 TSO/ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29

2.1.17.1 VTAM Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 2-302.1.17.2 ISPF Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 2-322.1.17.3 CA-7 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37

2.1.18 Unicenter TNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-372.2 CA-7 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38

Contents iii

2.2.1 CA-7/Notepad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-382.2.2 CA-7/Report Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-382.2.3 CA-7/Reports+ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-382.2.4 CA-7/Smart Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39

2.3 Scheduling OS/390 UNIX System Services Jobs . . . . . . . . . . . . . . . . 2-422.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-422.3.2 Sample Invocation of BPXBATCH . . . . . . . . . . . . . . . . . . . . . 2-42

Chapter 3. External Communicators . . . . . . . . . . . . . . . . . . . . . . . . . 3-13.1 Batch Terminal Interface (BTI) . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

3.1.1.1 Command Format and Sequence . . . . . . . . . . . . . . . . . . . . . 3-33.1.1.2 DBM List Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43.1.1.3 Non-DBM Batch Commands . . . . . . . . . . . . . . . . . . . . . . . 3-53.1.1.4 Installation Process Batch Commands . . . . . . . . . . . . . . . . . . 3-5

3.1.2 Batch Terminal Interface Execution . . . . . . . . . . . . . . . . . . . . . . 3-63.1.2.1 Processing Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-63.1.2.2 CA7BTI JCL Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . 3-73.1.2.3 Sample BTI JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-73.1.2.4 JCL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

3.2 Trailer Step Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-103.3 U7SVC Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13

3.3.1 Batch Step Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-143.3.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-143.3.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15

3.3.2 Calling U7SVC From a User Program . . . . . . . . . . . . . . . . . . . 3-163.4 CA-7 CCI Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17

3.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-173.4.1.1 Usage Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18

3.4.2 CA-7 CCI Batch Interface Execution . . . . . . . . . . . . . . . . . . . . 3-183.4.2.1 CAL2X2WB JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-193.4.2.2 CAL2X2WB Return Codes . . . . . . . . . . . . . . . . . . . . . . . 3-20

3.4.3 CA-7 CCI REXX Interface Execution . . . . . . . . . . . . . . . . . . . . 3-213.4.3.1 CA-GSS REXX Address Environment Interface Execution . . . . . 3-22

3.4.4 CA-7 CCI Program to Program Interface Execution . . . . . . . . . . . . 3-233.4.4.1 Calling CAL2X2WP . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-233.4.4.2 CAL2X2WP Response Buffer . . . . . . . . . . . . . . . . . . . . . 3-243.4.4.3 CAL2X2WP Return Codes . . . . . . . . . . . . . . . . . . . . . . . 3-243.4.4.4 Sample Invokation of CAL2X2WP . . . . . . . . . . . . . . . . . . 3-25

3.5 Batch Card Load Program (BCLP) . . . . . . . . . . . . . . . . . . . . . . . . 3-263.5.1 Using BCLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26

3.5.1.1 CA-7 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-273.5.1.2 JCL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27

3.5.2 Control Statements for BCLP . . . . . . . . . . . . . . . . . . . . . . . . 3-283.5.2.1 OPTION Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-303.5.2.2 Data Set Request Statements CREATE, REPLACE, MODDATA . . 3-343.5.2.3 End-of-Data Set (EODS) Statement . . . . . . . . . . . . . . . . . . 3-373.5.2.4 Control Statement Examples . . . . . . . . . . . . . . . . . . . . . . 3-38

Chapter 4. CA-Driver Procedures, Variable Parameters, and Functions . . . . 4-14.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

iv CA-7 3.3 Interfaces Guide

4.2 JCL Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34.3 Procedure Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

4.3.1 Creating Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-44.3.2 Calling Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-44.3.3 Nesting Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-54.3.4 Including Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64.3.5 Verifying Data Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

4.4 Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-94.4.1 Coding Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

4.4.1.1 Defining Default Values . . . . . . . . . . . . . . . . . . . . . . . . 4-114.4.1.2 Supplying Values On The EXEC Statement . . . . . . . . . . . . . . 4-124.4.1.3 Referencing Variable Parameters in the Procedure . . . . . . . . . . 4-134.4.1.4 Using Variable Parameters In Nested Procedures . . . . . . . . . . . 4-144.4.1.5 Shifting During Expansion . . . . . . . . . . . . . . . . . . . . . . . 4-15

4.4.2 Reserved-Name Variable Parameters . . . . . . . . . . . . . . . . . . . . 4-164.4.2.1 CA-Driver Reserved-Name Variable Parameters . . . . . . . . . . . 4-16

4.4.3 Substrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-194.4.4 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-214.4.5 Null Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-224.4.6 Attributes of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23

4.4.6.1 The Type Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-234.4.6.2 Testing the Type Attribute . . . . . . . . . . . . . . . . . . . . . . . 4-234.4.6.3 The Length Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . 4-244.4.6.4 Testing the Length Attribute . . . . . . . . . . . . . . . . . . . . . . 4-244.4.6.5 The Number Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . 4-254.4.6.6 Testing the Number Attribute . . . . . . . . . . . . . . . . . . . . . . 4-25

4.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-264.5.1 CA-Driver Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27

4.5.1.1 Arithmetic Date Functions . . . . . . . . . . . . . . . . . . . . . . . 4-274.5.1.2 Date Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . 4-284.5.1.3 Day-Of-Month Functions . . . . . . . . . . . . . . . . . . . . . . . . 4-31

4.6 Conditional Procedure Expansion . . . . . . . . . . . . . . . . . . . . . . . . . 4-324.6.1 Defining Step Names (DSTEP) . . . . . . . . . . . . . . . . . . . . . . . 4-33

4.6.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-334.6.2 Branching (DGOTO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33

4.6.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-334.6.3 Defining Conditions (DIF) . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35

4.6.3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-354.6.4 Setting Variable Parameters (DSET) . . . . . . . . . . . . . . . . . . . . 4-374.6.5 Controlling Loops (DLCTR) . . . . . . . . . . . . . . . . . . . . . . . . . 4-39

4.6.5.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-394.6.6 Aborting Expansion (DFLUSH) . . . . . . . . . . . . . . . . . . . . . . . 4-394.6.7 Aborting Expansion of the Current Procedure (DABORT) . . . . . . . . 4-39

4.7 Comments Inside CA-Driver Procedures . . . . . . . . . . . . . . . . . . . . . 4-404.8 Using CA-Driver in the CA-7 Environment -- Some Examples . . . . . . . . 4-41

4.8.1 Conditional Execution Based on Schedule ID . . . . . . . . . . . . . . . 4-41

Chapter 5. NCF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

Contents v

5.3 CA-7 NCF Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-45.3.1 CAIRIM (Resource Initialization Manager) . . . . . . . . . . . . . . . . . . 5-65.3.2 SVC Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-65.3.3 ICOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-75.3.4 Node Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-75.3.5 Unknown Node Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-75.3.6 NCF Communications Data Set . . . . . . . . . . . . . . . . . . . . . . . . 5-85.3.7 NCF Undeliverable Queue (UDQ) . . . . . . . . . . . . . . . . . . . . . . . 5-85.3.8 NCF VTAM Application Program . . . . . . . . . . . . . . . . . . . . . . . 5-8

5.3.8.1 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-85.3.9 CA-7 NCF Test Data Generator . . . . . . . . . . . . . . . . . . . . . . . . 5-9

5.4 Planning and System Requirements . . . . . . . . . . . . . . . . . . . . . . . . 5-105.4.1 General Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-115.4.2 Resource Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

5.4.2.1 Operating System Environment . . . . . . . . . . . . . . . . . . . . . 5-125.4.2.2 Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 5-125.4.2.3 DASD Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-125.4.2.4 DASD Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 5-135.4.2.5 CAIRIM System Requirements . . . . . . . . . . . . . . . . . . . . . 5-14

5.5 Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 5-155.5.1 Execution Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16

5.5.1.1 Sample NCF VTAM PARM . . . . . . . . . . . . . . . . . . . . . . 5-175.5.1.2 Sample NCF VTAM JCL . . . . . . . . . . . . . . . . . . . . . . . . 5-17

5.5.2 CA-7 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-185.5.2.1 Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-185.5.2.2 DB.1 Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18

5.5.3 User Execution JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-195.5.3.1 JOB Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-195.5.3.2 JES2 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-195.5.3.3 JES3 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-205.5.3.4 EXEC Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-205.5.3.5 DD Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20

5.5.4 Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-215.5.5 General Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22

5.5.5.1 NCFNODE Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 5-225.5.5.2 CA-7 LOAD Process . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22

5.6 System Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-235.6.1 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-235.6.2 Establishing Communications . . . . . . . . . . . . . . . . . . . . . . . . 5-235.6.3 Standard Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24

5.6.3.1 Status Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-245.6.4 Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-245.6.5 Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24

5.7 Operator Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-255.7.1 STOP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26

5.7.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-265.7.1.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26

5.7.2 SHUTDOWN Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-275.7.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-275.7.2.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27

vi CA-7 3.3 Interfaces Guide

5.7.3 STARTUP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-285.7.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-285.7.3.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28

5.7.4 LOGON Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-295.7.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-295.7.4.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29

5.7.5 LOGOFF Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-305.7.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-305.7.5.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30

5.7.6 PURGE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-315.7.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-315.7.6.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31

5.7.7 STATUS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-325.7.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-325.7.7.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-335.7.7.3 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33

5.7.8 TRACE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-355.7.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35

5.7.9 Deactivating the Trace Facility . . . . . . . . . . . . . . . . . . . . . . . 5-36

Chapter 6. CA-7 Cross-Platform Scheduling . . . . . . . . . . . . . . . . . . . . 6-16.1 CAICCI Cross-Platform Connections . . . . . . . . . . . . . . . . . . . . . . . . 6-2

6.1.1 Non-OS/390 CAICCI Connections . . . . . . . . . . . . . . . . . . . . . . 6-36.1.2 OS/390 CAICCI Connections . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

6.2 The CA-7 XPS CLIENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56.2.1 Submit Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56.2.2 Cross-Platform Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11

6.2.2.1 CA-7 Cross-Platform Tracking JCL . . . . . . . . . . . . . . . . . . 6-116.2.2.2 CA-7 Cross-Platform Tracking Commands . . . . . . . . . . . . . . 6-146.2.2.3 CA-7 Cross-Platform External Tracking . . . . . . . . . . . . . . . . 6-15

6.2.3 CA-7 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-206.2.4 CA-7 XPS Client Implementation Checklist . . . . . . . . . . . . . . . . 6-21

6.3 The CA-7 XPS SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-226.3.1 The XPS Submit Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22

6.3.1.1 Submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-236.3.1.2 Status Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24

6.3.2 The Cross-Platform Scheduling Router (XPS ROUTER) . . . . . . . . . 6-256.3.3 Cross-Platform Server Password Requirements . . . . . . . . . . . . . . . 6-28

6.3.3.1 Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-286.3.3.2 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-296.3.3.3 Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-296.3.3.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30

6.3.4 Managing the Cross-Platform Workload . . . . . . . . . . . . . . . . . . 6-316.3.5 CA-7 XPS Server Implementation Checklist . . . . . . . . . . . . . . . . 6-33

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1

Contents vii

viii CA-7 3.3 Interfaces Guide

Chapter 1. Introduction

This publication contains information about several of the interfaces to CA-7. Includedare interfaces with other products, external communicators, CA-Driver, the Network Com-munications Facility (NCF) component of CA-7, cross-platform scheduling, and OS/390UNIX System Services scheduling. It is designed for use by both the operator and datacenter 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 whichparticipating ICOMs record tracking data. One or more Host ICOM(s) read from thememory structure and write to the Communication data set. This can significantlyreduce I/O contention and increase feedback throughput.

� UNIX System Services Interface

The OS/390 UNIX System Services (USS) CA-7 interface allows communicationwith CA-7 from the USS environment. The interface can be called directly from theUNIX 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 otheraddress spaces and environments. The interface can be engaged in a batch mode, ina REXX address environment or it can be called directly from a user program. Itaccepts single or stacked commands as input and returns the CA-7 output from thecommands as if they had been executed in batch mode.

� Critical Path Monitoring

Through integration with CA-OPS/MVS II, Unicenter TNG and Unicenter TNGMVS Event Manager Option (MEMO), CA-7 can support the definition and moni-toring of critical job flows within the CA-7 workload. CA-OPS/MVS II providesmanagement 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 subcom-mands 'UPPER' and 'MIXED' determine whether editor data is translated to uppercaseor left "as is."

These subcommands are enabled with a new initialization file option. If this optionis 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 com-pletions to be discriminated with a high degree of precision, thus reducing the likeli-hood of requirement posting ambiguities where jobs complete within the sameminute.

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 messageSRC1-137. This occurs when a job is scheduled to execute the same day under twoor more different Schedule IDs. With this information one can more quickly andefficiently determine the source of the scheduling conflict.

� VRM Device Control

Virtual Resource Management (VRM) Device Control provides an alternative toWorkload Balancing control of job submission based on tape drive availability.VRM resource count resources representing the number and type of storage devicesused by the job are defined dynamically during CA-7 LOAD processing.

Workload Balancing only permits two types of tape drives. With VRM DeviceControl, 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 beretrieved 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-7commands 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 externalsecurity 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 commandsto 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 data-base records related to a job. In addition to the standard delete processes, thePURGE function deletes incoming trigger definitions, requirement successor defi-nitions, 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) panelcan be used to indicate certain jobs should never be marked as LATE on status dis-plays. This means operations and production control staff will not be distractedwhen 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 tocause messages to be retained until the user logs on to TSO. Also, support for ARFhas 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 inprior releases.

� CA-7 JCLCheck Common Component

The CA-JCLCheck Common Component is provided in place of the CA-7 JCLsyntax checker.

� Documentation Files on Tape

The current CA-7 documentation files are provided in IBM Book Manager and PDFformat on the product tape.

� Other Enhancements:

– SMF Purge records may optionally be sent to a test copy of CA-7. This allowsdetection of pre-execution JCL Errors by the test copy.

– The Scratch and Disk Queue Table queues can be formatted during a CA-7ERST start which facilitates use of VIO to improve performance.

– The LJOB command provides a new option, LIST=RQEXCP, that lists onlythose 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, forSASSDT30 which prevents the generation of data set definitions.

– The LQ family of commands (LREQ, LRDY, LACT, and so forth) now supporta Schedule ID filter, SCHID=.

– The LRLOG command has a new sequence option, SEQ=REV, which causesentries to be displayed in reverse date/time sequence (most recent first).

– The OPTIONS initialization file statement has a new keyword DPROCCOM= toenable comment statements in CA-Driver procedures.

– The OPTIONS initialization file statement has a new keyword EXTSCHID= toset a default schedule ID for externally tracked jobs that are not assigned a non-zero schedule ID from the SASSEXTT table.

– The CA-7 CAIRIM initialization module now accepts a new reinitializationparameter (REINIT=UTABS) to reload only user defined table modules.

– The /DISPLAY command has a new STATUS option (/DISPLAY,ST=CA7) todescribe 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 technologyfor online viewing, keyword searching, book marking, and printing. The set consistsof a hard copy CA-7 Getting Started guide and Version 3.3 of CA-7 for OS/390 doc-umentation in both IBM BookManager and Adobe Acrobat Reader format on thetape.

� Unicenter TNG Framework for OS/390 is composed of the services formerly knownas CA90s and Unicenter TNG Framework.

� Reading Syntax Diagrams in the CA-7 Commands Guide explains how to read thecommand syntax used in all guides.

Technical changes are identified by a revision bar (|) in the left margin. Revision barsare 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-7product options, and discusses the requirements for CA-7 to schedule OS/390 UNIXSystem 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. Combinedwith 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. TIQallows 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 theinitialization file can be used to cause an automatic cancel from TIQ mode after a speci-fied 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 notdefined to the CA-1 Security module, a message appears and a different CA-1 passwordmust be entered.

Messages produced by the CA-7 TIQ interface are in the CA-7 Message Guide. Thoseproduced 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 listedto use this feature.

When the TIQ interface is used, the CWORK value for CA-7 should be increased by 10for each concurrent TIQ session through CA-7 (see the "Execution" chapter of the CA-7Systems Programmer Guide).

Note: The CA-1 TIQ interface in CA-7 dynamically loads the appropriate TIQ interfacemodule based upon the current version of CA-1 found on your system duringexecution. Therefore no special application statements are required.



2.1.1.1 TIQ Command

Syntax

TIQ

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

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

Where:

UIndicates updating is to occur.

DSNIndicates whether the data set name is to be verified before CA-1 will allow updatingof 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 allowingautomatic RMS step insertion, and by providing automatic CMT updating when jobs arerestarted, 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 andabove). The appropriate SYSMOD should be applied during the SMP APPLY process tosupport the CA-7 CA-11 interface.

Add the following statements to the initialization file before the APPLCTN statement forSASSPROG:

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 listedsince CA-11 modules perform part of the interface. You must add the following DDstatement 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 DDstatements. The data set names are established during installation of CA-11. Also, theCA-11 HELP file is distributed as a member of CA-11 GENLIB or SAMPLIB, dependingon 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 allowsuse of online tracking and maintenance of restart/rerun information as described in CA-11documentation. The ARTS interface is very similar to the TIQ interface. The monitormode is entered and can be limited by the MONLIM value from the TERM statement inthe initialization file.

The CA-7 OPID is passed to CA-11 as a password. If it is not defined to the CA-11Security 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 MessageGuide. 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-7should be increased by a count of 20 for each concurrent ARTS session through CA-7. IfCA-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, sinceCWORK reduces the external storage available to other CA-7 interfaces, it may be betterto increase region size (refer to the "Execution" chapter of the CA-7 Systems ProgrammerGuide).

When issuing CA-11 commands which have multiple screens of output, it is necessary toretype the first letter of the command (or a blank) before pressing Enter to view sec-ondary 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 proce-dure to be inserted in the job's JCL. The default procedure name inserted depends on theversion level of CA-7. You can change the procedure name by using the PROCRMSparameter of the RESTART statement in the initialization file. (You can find a sampleRMS 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, therestart data is passed as the parameter.

� If there is no restart data for //*UCC7RESTART, the parameter is set to P unlessLoad 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 RESTARTstatement in the initialization file.

To request automatic RMS step insertion for a job, set the INSERT-RMS field on theDB.1 screen to Y. (See the CA-7 Database Maintenance Guide, "Jobs" chapter.) IfCA-11 is not installed, the insert feature is not active regardless of the INSERT-RMSfield on the DB.1 screen.

Note: If IBM OS Restart (job statement RESTART parameter) is used, then it is pos-sible that the RMS step inserted by CA-7 will be bypassed. This could result invarious 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 throughCA-7, the CMT is updated automatically. If CA-7 NCF is installed, then, for jobs exe-cuted at nonlocal NCF nodes, CMT updating cannot occur and the restart data is passedby the //*UCC7RESTART statement.

When a job is resubmitted, force completed, or canceled, the interface attempts to clearthe CMT flags. When a job is restarted, the interface posts the restart data to the CMTthen sets the restart data to P. If the QM.4 screen SET PARM field is used, the CMT isnot accessed and the PARM data is passed using the //*UCC7RESTART statement.

The CA-7 commands which cause CMT updating are CANCEL, RESTART, XQ functionC or F, and XRST.



2.1.3 CA-7 WorkStation

CA-7 WorkStation is an application that provides a single point of control for workloadsrunning under CA-7 from a Windows NT workstation. This graphical presentationenhances the administration, management, and real-time monitoring of workloads. Fore-casting and monitoring actions are accomplished through the use of flowcharts repres-enting 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 forCA-7 WorkStation.



2.1.4 CA-APCDDS

CA-APCDDS automates the manual, often neglected task of data verification, therebyincreasing the accuracy and consistency of your output while reducing reruns andimproving auditability.

CA-APCDDS is a rule-based menu-driven system that provides comprehensive data ver-ification routines to catch errors in a timely fashion -- before mistakes are propagatedthroughout the system. CA-APCDDS adds to the flexibility of CA-7 by allowing anout-of-balance condition to directly affect the production workflow. CA-APCDDS hasthe 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 forexecution. Implementation of CA-APCDDS requires no changes to your existing applica-tion 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 jobflowcharts from the CA-7 database. These flowcharts can be based on the current work-load or forecasted for a future date. Users with CA-7 can use the DOCCHART compo-nent to print flowcharts of jobs showing the job schedules, successor relationships, andother 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 byreading an FSTRUC report. If the user chooses the FSTRUC option, the CA-7 FSTRUCcommand should be issued first, placing the output into a sequential file, whichDOCCHART then reads. The differences between creating a CA-7 flowchart fromFSTRUC output and creating one from the database include:

� The database flowchart shows job and data set requirements, which FSTRUC doesnot.

� The database flowchart shows a starting point and continues on until it reaches theend, whereas FSTRUC just shows one job at a time.

� The database flowchart is not time sensitive. It shows the relationship between jobsregardless of the time it is run. It gives an undistorted view of triggers and require-ments, and database relationships.

� The database flowchart runs independently of CA-7 and does not require CA-7address 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 databaseflowchart does not.

� Since the database flowchart issues its own reads to the database, it can run againstany copy of the database (current, old, or restored). A user can compare the databasetoday 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 ofCA-Dispatch.

This interface consists of two parts where data is communicated either from CA-7 toCA-Dispatch or from CA-Dispatch to CA-7. The CA-7 to CA-Dispatch part of the inter-face is discussed in 2.1.6.1, “Forecasting Print Volumes” which follows. TheCA-Dispatch to CA-7 part of the interface is discussed in the CA-Dispatch ReferenceGuide.

2.1.6.1 Forecasting Print Volumes

When CA-Dispatch is used for managing printed output, the forecasting of print volumesby CA-Dispatch may be desirable for planning activities associated with handling theactual 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 forecastof 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 abatch 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 datawill 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 thediscussion of the FWLP command and the DDNAME keyword parameter in theCA-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 planrecords in the format required by CA-Dispatch.

Note: This file is generated in a format that is compatible with CA-DispatchVersion 4.1 or above.

3. Using the output file from SASSDPCH, produce the forecast of print volumes asdescribed in the CA-Dispatch user documentation.



Alternatively, the data set created in Step 1 could be modified or created manually by theuser prior to Step 2. The following is a sample of the JCL needed to produce a plan filefor 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 generatedduring installation and a copy of CA-Earl. If a full copy of CA-Earl is installed, it maybe used. If a full copy of CA-Earl is not available, you can install the service from theUnicenter TNG Framework for OS/390 distribution tape. Refer to Getting Started forspecific information on how to install the CA-Earl subset product. Refer to the CA-7Reports Guide for JCL and usage considerations.

The CAIMAC EARL report member, prefix CA7ER, contains record and report defi-nitions 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, ifthat product is in use at your site. A standard set of reports can be produced using eitherthe CA-7 log history file or output from the CA-7 database backup utility as input toCA-Easytrieve Plus. Refer to the CA-7 Reports Guide chapter on CA-Earl andCA-Easytrieve Plus reporting for information on how to produce reports fromCA-Easytrieve Plus. The CA-Easytrieve Plus report definitions are saved in theCAIMAC data set.



2.1.9 CA-JCLCheck

The CA-7 interface for CA-JCLCheck supports enhanced validation of JCL in the CA-7editor and on the LJCK command. It also supports batch validation of JCL for a streamof 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 arereported in a meaningful context. Also, the interface supports checking for the existenceof 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 aseries of jobs and then the LJCK command to extract JCL for them so that JCLCheck canvalidate the JCL for the stream as a whole. This utility is requested from an ISPF panelthat is provided with CA-JCLCheck (Version 6.0 or later). Refer to CA-JCLCheck doc-umentation for additional information.

2.1.9.1 CA-7 Considerations

The interface is requested through the JCLCHECK statement in the CA-7 initializationfile. An OS LOAD macro is used during CA-7 initialization to locate the JCLCHECKload module. The address returned by the LOAD macro is used for all subsequentaccesses of CA-JCLCheck by CA-7. If the JCLCHECK module is not resident or in alink list library, then concatenate the library containing the JCLCHECK load module tothe CA-7 STEPLIB.

The storage requirement for CA-7 may increase significantly if the CA-7 CA-JCLCheckinterface is used. A CWORK increment of 250 is proposed as a starting value.However, this should be considered a tentative recommendation as the storage requiredmay vary according to several factors such as the number of concurrent interface usersand the number of input statements to be parsed. For further information onCA-JCLCheck storage requirements, consult the CA-JCLCheck documentation.

The execution JCL for CA-7 must be modified to include a DD statement which points tothe libraries on which cataloged procedures reside. The name of the DD statement mustbe SYSPROC. If this DD statement is not found, then the CA-JCLCheck optionAUTOPROC may be specified if CA-7 is running in a JES2 environment. Refer toCA-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 ProgrammerGuide for a list of valid options. Refer to CA-JCLCheck documentation for further infor-mation about these options.



2.1.10 CA-Librarian

The CA-Librarian interface is included during the installation process as SYSMODCL233SL. During SMP APPLY processing, the CA-Librarian SYSMOD requires thatyou include the CA-Librarian load library in the SMP APPLY procedure for inclusion ofthe CA-Librarian access method modules: FAIROPN, FAIRMOD, FAIRREC, andFAIRCLS. The CA-Librarian load library should be specifed under the LIBR ddname inthe SMP APPLY procedure. The SMP APPLY process generates the composite loadmodule 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-Librariandata 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 asnnn on the DD statement (leading zeros are required on the DD statement). Access isread-only using JCL screens, list commands or job scheduling functions such asDEMAND, RUN, and so forth.

Normal access expands "include" references, but a list option is available to suppressexpansion 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 completionsusing the realtime CA-Netman interface. When CA-7 detects a job completion, one ormore CA-Netman API transactions are issued based on information about the job fromthe CA-7 status queues.

In the standard implementation, the realtime interface may be used to OPEN or UPDATEproblems in CA-Netman for CA-7 jobs that end abnormally and CLOSE CA-Netmanproblems for those restarted CA-7 jobs when they complete normally.

A batch interface between CA-7 and CA-Netman is also available which uses theMachine Generated Problem Tracking feature of CA-Netman and the CA-7 batch terminalinterface. Refer to CA-Netman publications for information on the use of the batch inter-face.


The realtime interface will be initialized if the NETMAN statement is present in theCA-7 initialization file. This statement is used to set CA-Netman API control values andparameters 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 areused to build the CA-Netman API transactions that are issued when a CA-7 job com-pletes. Refer to 2.1.11.3, “CA-Netman Model Transactions” on page 2-16 for furtherinformation.

The realtime CA-Netman interface uses CA-Netman API deferred processing so that APItransactions created by the interface will be retained in the event that the CA-NetmanCCI receiver is inactive. This requires the presence of a CA-Netman API deferredrequest data set. Any CA-Netman API request issued by the interface will be written tothis file for subsequent processing with the NTM920 utility. The data set must bedefined as RECFM=FB and LRECL=80 and must be identified in the CA-7 procedurewith the ddname NTMADFR. Refer to CA-Netman documentation for additional infor-mation.

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 thistask is ready to accept CA-7 job completions, a message is issued indicating successfulinitialization of the CA-Netman interface.

The storage requirement for CA-7 may increase significantly if the CA-Netman interfaceis used. An increase in region size of 1M is recommended as a starting value. A largerincrease may be required depending on the volume of CA-Netman transactions to beissued.



2.1.11.2 CA-Netman Considerations

If the realtime CA-Netman interface is indicated, a task in the CA-7 address space will becreated to asynchronously accept CA-7 job completion data, build CA-Netman trans-actions based on the schema in the model CA-Netman transaction file and issue APIrequests to send those transactions to CA-Netman.

The CA-Netman API requires the presence of an active CA-Netman CCI listener. Alistener may be requested either through a CA-Netman transaction or through the use ofthe CA-Netman Asynchronous Services Task (NTMASYN). Consult CA-Netman doc-umentation for more information on implementing the CA-Netman API.

Also refer to CA-Netman documentation for a discussion of security using the API. Thisinterface 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 exe-cution JCL by a NETMAN DD statement. Each time the CA-Netman interface isinvoked, CA-Netman commands built from the model transactions will be issued. Forexample, 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 MGPTtransaction conforming to the above format.

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

CA-Netman transactions are issued in the order that they appear in the model transactionfile 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 aboveexample the following CA-Netman API transaction could be generated when job ABC123completes:

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. Inthis example suppose that job ABC123 abended with a S-0C4 on 00.161 at 10:30 atnight. Note the use of the incident time keyword (ITIM). The CA-7 job number isinserted instead of a true incident time. In this way, the problem can be referenced byincident date and CA-7 job number.

For a list of variable names and their values refer to 2.1.11.5, “CA-Netman Model Trans-actions - 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 thenext line. The length of a CA-Netman transaction built by this interface cannot exceed1000 bytes. The number of continuations for CA-Netman model transactions is limitedby 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 Length Value

&&L2NTM_DBASENM 16 The value of the DBASENM keyword on the CA-Netman SystemInformation (SYST) screen

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

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

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

&&L2PME_L2JOB 05 CA-7 assigned job number

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

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

&&L2PME_L2RSN 08 Restart step name

&&L2PME_L2CC 06 Completion code:

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

&&L2PME_L2RC 04 Restart count

&&L2PME_L2CPUT 08 CPU time

&&L2PME_L2JCLI 03 CA-7 JCL ID for the job

&&L2PME_L2DOYR 04 CA-7 due-out year

&&L2PME_L2DODY 03 CA-7 due-out day

&&L2PME_L2DOT 04 CA-7 due-out time

&&L2PME_L2DLYR 04 CA-7 deadline year

&&L2PME_L2DLDY 03 CA-7 deadline day

&&L2PME_L2DLT 04 CA-7 deadline time

&&L2PME_L2SMYR 04 CA-7 submit year

&&L2PME_L2SMDY 03 CA-7 submit day

&&L2PME_L2SMT 04 CA-7 submit time

&&L2PME_L2STYR 04 CA-7 start year



Table 2-1 (Page 2 of 2). CA-Netman Model Transactions Variables

Variable name Length Value

&&L2PME_L2STDY 03 CA-7 start day

&&L2PME_L2STT 04 CA-7 start time

&&L2PME_L2ETYR 04 CA-7 end year

&&L2PME_L2ETDY 03 CA-7 end day

&&L2PME_L2ETT 04 CA-7 end time

&&L2PME_L2EM 04 The entry mode of the job:

ADEM job entered by DEMAND command in ARF recoveryADST data set triggered in ARF recoveryAEXT externally tracked job in ARF recoveryAJBT job triggered in ARF recoveryANWT network triggered in ARF recoveryAPS job entered by Personal Scheduling in ARF recoveryARFJ ARF recovery jobARUN job entered by RUN command in ARF recoveryASSC job entered by Schedule Scan in ARF recoveryDEMD job entered by DEMAND commandDSTR data set triggeredEXTL externally tracked jobJBTR job triggeredNWTR network triggeredPSCH job entered by Personal SchedulingRUN job entered by RUN commandSSCN job entered by Schedule ScanXDEM cross-platform scheduled using XPSSCHD=DEMANDXPS cross-platform scheduled using XPSSCHD=RUNREFXRUN cross-platform scheduled using XPSSCHD=RUN

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

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

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

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

&&L2OCDT 06 Occurrence date: format is MMYYDD

&&L2OCTI 04 Occurrence time: format is HHMM

&&DATE 06 System date: format is CYYDDD

&&TIME 06 System time: format is HHMMSS

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



2.1.12 CA-Opera

CA-Opera provides an interface to CA-7 using the U7SVC facility. This interface allowsCA-7 commands to be issued based on events recognized by CA-Opera. Any commandsissued using the CA-Opera interface require operator security defined for the trailer ter-minal. 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-7browse event to your CAIENF database. Refer to member L2DCM1 in the CA-7 sampleJCL 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 interfaceallows 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 securitydefined for the trailer terminal. Refer to CA-OPS/MVS II documentation for details onthis interface.

CA-7 commands can also be issued using the CA-7 CCI Interface. This facility returnsthe output from the CA-7 commands to the caller for evaluation. See 3.4.3.1, “CA-GSSREXX Address Environment Interface Execution” on page 3-22 for information on usingthis facility in CA-OPS MVS/II.

For CA-OPS/MVS II to monitor CA-7 browse data set messages, you need to add theCA-7 browse event to your CAIENF database. Refer to member L2DCM1 in the CA-7sample 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 toolsthat 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 infor-mation provided by CA-7. In this way, CPM can be used to track the progress of acrucial production job stream, a "critical path".

Within CA-7 a named segment of a triggered stream of jobs is known as a FLOW. Theelements 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 SLAtime).



These elements are defined in CA-7 by connecting a special VRM Corequisite resource tothe starting job of the FLOW. Refer to the CA-7 Database Maintenance Guide for infor-mation on defining VRM resources.

A FLOW initiates when VRM resources are attached to the starting job and terminateswhen its ending job completes successfully. CA-7 considers an active FLOW to includethe beginning job and all of its job and dataset triggered descendants up to and includingthe ending job. The CA-7 command FLOWL can be used to display active FLOWs inCA-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 willrequest forecast information from CA-7 to chart the "critical path" that connects theFLOWs beginning and ending jobs. CA-OPS/MVS II then uses the CA-7 ongoing statusinformation to monitor the progress of the critical path.

FLOW initiation occurs at job submission as part of the VRM resource evaluationprocess. This implies a restriction on defining the starting job in a FLOW. A job mustbe eligible to use VRM resources in order to initiate a FLOW. This means that a non-executable job cannot start a FLOW. However, non-executable jobs can be included in aFLOW and can be defined as the ending job of a FLOW.

See the CA-OPS/MVS II documentation for more information on Critical Path Moni-toring features and requirements.

Critical Path Monitoring Requirements: The following steps are required to acti-vate 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 Installationand Customization Guide for more information on Critical Path Monitoring features andrequirements.

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 onthe OPTIONS statement in the CA-7 initialization file. When active, this interfaceprovides services that can be used to define those portions of the triggered workloadthat require special management attention using CPM. These services are used todefine the limits of a key segment of the triggering stream and to assign a name tothe segment for subsequent references in the CPM environment. Refer to the CA-7Systems 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/MVSII to build an image of a critical path. There must be at least one CA-7 CCI terminaldefined in the CA-7 initialization file. See 3.4, “CA-7 CCI Interface” on page 3-17for information about the interface. See the CA-7 Systems Programmer Guide forinformation 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 thislibrary is not in the LNKLST or LPALIB, you must add them to the OSF server'sSTEPLIB DD. You may need to add a CA7PARMS DD statement to the OSF serv-er's JCL to set parameters to be used by the CA-7 CCI interface to gather informa-tion about active flows. If specified, The CA7PARMS DD must point to an 80 bytecard- image data set or PDS member.

CA7PARMS keywords must start in column 1 with no imbedded blanks. Lines thatbegin with a blank or asterisk are considered comment lines. The possible keywordsare:

CA7NODE= CAICCI NODE WHERE CA-7 RESIDES (DEFAULT=LOCAL)

CA7SSCT= CA-7 SSCT (PROD OR TEST) (DEFAULT=PROD)

CA7USER= USERID TO LOGON TO CA-7 WITH (DEFAULT=OSF SERVER USER ID)

CA7PSWD= USERID PASSWORD (DEFAULT - NONE)

CA7SNAP= DD NAME FOR TRACE SNAPS (DEFAULT=CA7TRACE)

CA7DBUG= 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 CA7TRACESYSOUT DD to the JCL.



2.1.14 CA-Panvalet

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

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

The following JCL statement must also be added to the CA-7 initialization file for eachCA-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 asnnn on the DD statement (leading zeros are required on the DD statement). Access isread-only using JCL screens, list commands or job scheduling functions such asDEMAND, RUN, and so forth.

Normal access expands "include" references, but a list option is available to suppress theexpansion when doing an LLIB command.

If a new version of CA-Panvalet is installed, CA-7 needs to be recycled (a WARM startis 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 toinstall a CA-7 USERMOD. Member UL2PANV in the CA-7 Sample JCL library con-tains the USERMOD needed to enable the CA-7 interface for older versions ofCA-Panvalet. This USERMOD performs an SMP RECEIVE and APPLY to generate thecomposite load module SASSPANV. The CA-Panvalet load library must be included inyour SMP/E procedure using the PANV DD statement prior to running the JCL to installthe USERMOD.

Also, you must add an APPLCTN statement to the CA-7 initialization file for the com-posite 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 forrequests to CA-7 from the OS/390 UNIX System Services environment. The interfacecan be called directly from the UNIX shell or from the MVS batch interface UnixSystems Services MVS BPXBATCH. This includes user applications, shell scripts, andthe command prompt. The request can be any valid CA-7 command that is normallypassed to U7SVC and must be syntactically correct.

For information on the installation and setup of the CA-7 USS Interface modules, seeUNIX 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 Refer-ence. 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 theinterface as follows:

ca7oecom demandh,job=payjob1

The example above invokes the CA-7 UNIX Services interface executable CA7OECOMand passes the command on to CA-7 through U7SVC. In this case, a DEMANDHcommand for job PAYJOB1 is requested. A return code is supplied to indicate the statusof the request to U7SVC.

Special Considerations: The OS/390 UNIX shell can be entered by issuing theTSO/E OMVS command from within TSO.

If the command you wish to submit to CA-7 contains special characters, blanks, orquotes, imbed the entire command in single quotes. This prevents the shell from evalu-ating 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 thelocation of the interface executable CA7OECOM. This variable is required to be setprior to execution of the interface.

Example Path

/users/applications/ca7/bin

CA7TRACE: This environment variable is used for diagnostic purposes. When set to avalue of "ON", the interface module CA7OECOM will issue diagnostic messages duringexecution to assist in problem determination.

Setting Environment Variables: Environment variables can be set from within theshell by using the UNIX "export" command. If you are using the MVS Batch interfaceUnix Systems Services MVS BPXBATCH, you can set the environment variables in afile pointed to by ddname STDENV.

Examples: To set the CA7DIR variable in the UNIX environment from the commandprompt, 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 variableto the value as follows:

CA7DIR=/users/applications/ca7/bin



Special Considerations: The UNIX environment is case sensitive. The CA7DIRenvironment variable name must be specified in uppercase. The path name itself can bemixed 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',


//:

//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. Ifyou 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 'regis-ters' 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 previouslydone this for CA-7/ViewPoint or Unicenter/STAR, you do not need to repeat it tomake 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 commu-nicates with CA-7. If the CA-7 CAILIB is link listed in your environment, nochanges to JCL or CLISTs should be required.

The CA-7 CAILIB should be added to the STEPLIB concatenation for the ServerTask (started task). Refer to your related CA-7 WorkStation documentation fordirections 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 setused by the CA-7/API. This is pointed to by the PROFILE DD in the Server startedtask.

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 com-municate with. This can be found on the APPL= keyword of the UCC7VTAM state-ment in the CA-7 initialization file. For example, if your APPLID for CA-7 isPRODCA7 then specify CA7APPL=PRODCA7.

Note: The CA-7/API can communicate with any CA-7 that is defined to the VTAMsystem where the API is executing. If you have cross-domain definitions to aCA-7 on a remote system, the CA-7/API executing locally can communicatewith that CA-7.

CA7SESS=high-acb-name

This variable identifies the set of VTAM ACB names that can be used by theCA-7/API locally to establish communications with CA-7. For example, if you haveten ACBs (CA70001 through CA70010), you should specify CA7SESS=CA70010.The interface will deduce from this that there are ten ACBs to choose from (onethrough 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 thatinterface can also be used by the CA-7/API. If so, check to ensure there are enoughACBs to satisfy both ISPF and API users.



If ACBs need to be defined, refer to 2.1.17.1, “VTAM Considerations” on page 2-30for 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 whichit is communicating. If you do not have Virtual Terminals defined, or if you need toincrease the number of Virtual Terminals, refer to the discussions of theUCC7VTAM, LINE and TERM initialization statements in the CA-7 Systems Pro-grammer Guide.

5. Enable Online Calendar Maintenance facility

If you wish to use the facilities in CA-7 WorkStation to maintain your CA-7 basecalendars, 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 onlinewithout the need for batch assemblies.

If you wish to enable Online Calendar Maintenance, refer to the CALENDAR initial-ization 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 widerange of CA-7 functions. With the interface, the CA-7 user may now enjoy many of thebenefits 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 avail-able from a CA-7 terminal session under ISPF. For example, one cannot go to the ISPFBROWSE screen by simply entering =1 in a command area and pressing Enter. Onemust 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 aCLIST. Programs executed under the CLIST acquire a CA-7 virtual terminal and aVTAM LU-LU session is set up between ISPF(SLU) and CA-7(PLU). With the excep-tion 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 theappropriate ISPF Dialog Manager services. Interface modules issue VTAM SEND andRECEIVE macros to handle the data traffic with CA-7.

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

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

The JCL syntax checking facility that is used by the native CA-7 Editor is NOTavailable in the ISPF environment. JCL validation through CA-JCLCheck may berequested using the !JCK edit macro. Refer to CA-JCLCheck documentation forfurther information on !JCK.

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

For more information on the installation of this interface, consult the CA-7 Getting Startedguide.

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 sessionbetween CA-7 and ISPF. The following discussion provides information on the VTAMapplication that contains the nodes used by the interface. The TSO/ISPF interfacerequires the use of ACF-VTAM 3.2 or higher.

The CA-7 TSO/ISPF interface uses only the node name that is defined using theACBNAME keyword on the VTAM APPL statement. There are strict conventions thatare imposed by the interface which must be observed when coding the value for thiskeyword. The application minor node name that is created by the label on the APPLstatement is not referenced by the interface directly. This name is used by VTAM andmust be unique within the network.

The ACBNAME values must be exactly seven bytes long. The first three characters maybe chosen by the user, subject to VTAM naming conventions. The last four charactersmust be numeric and numbered consecutively from 0001 to nnnn, where nnnn representsthe 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 ses-sions begin with the characters CA7. If the maximum number of concurrent interfaceuses is 4, then 4 nodes must be defined for this purpose. Refer to the following exampleof a VTAMLST member defining the nodes for such an installation.

CA7ISPF VBUILD TYPE=APPL

CA71???1 APPL ACBNAME=CA7???1




:

A sample VTAMLST member is included in the CA7ISPF member of MACLIB. Thismay be edited to reflect the specific needs of your installation. This should then becopied 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 ofthese nodes dedicated for interface use. Thus, in this example, anywhere from one tofour 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 isnothing that would prevent one ISPF user from having more than one CA-7 terminalsession going at one time using ISPF's split screen capability. For example, one usercould split the screen into four ISPF screens, and from each screen maintain a CA-7terminal session. This would imply four concurrent uses of the interface or four CA-7terminal sessions going on at once. In this example, any attempt to use the interfaceduring this time from another terminal would fail since there would be no nodes availablefor this purpose.



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

A VTAM application similar to the one just described must be defined in each VTAMdomain where TSO/ISPF sessions with CA-7 are to be supported. For CLIST compat-ibility, the ACBNAME values should be the same across domains, only the node namesthat are created by the labels on the VTAM APPL statements need be changed fornetwork uniqueness. In the following example, the CA7ISPF member could be used as amodel for an application definition in another domain of the network.

CA7ISPF2 VBUILD TYPE=APPL





When the install is complete, make sure to activate the application(s) where the interfacenodes are defined. In this example, issue a VARY command on the MVS console tomake 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 ofCAICLIB. This CLIST must be edited to reflect changes appropriate for your installa-tion. It should then be copied to a library that is part of the SYSPROC concatenation inthe 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 theUCC7VTAM statement in the CA-7 initialization file. The value on the SESSAPLkeyword should be the ACBNAME with the highest value. In this example, CA70004would 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 iscalled 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-7environment. Another edit macro CA7ED0 is supplied and is required for internal use bythe interface. These CLISTs are also supplied on CAICLIB. These must also be copiedto a CLIST library that is included in the SYSPROC concatenation in the TSO LOGONprocedure.

The following load modules are required. They are used to handle the VTAM link withCA-7, invoke Dialog Manager services and perform other interface functions. Thesemodules 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-7production load library to a smaller load library that is accessed by TSO users. In thisway, use of the interface does not entail allocation of the CA-7 load library. The librarycontaining 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 doc-umentation panel which is invoked when the ISPF HELP command is issued. CA7P000is the panel required for processing option 1 from the CA-7 menu. This panel is used forall online terminal screen handling. These panel definitions should be copied to a librarythat is part of the ISPPLIB concatenation in the TSO LOGON procedure.



Although a CA-7 online terminal session may be acquired by simply executingCA7PDRVR, ISR@PRIM should be modified to issue the CA7PDRVR command withNEWAPPL (CA7). If CA7PDRVR is invoked in this way, an ISPF application namedCA7 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 PFkey support. Refer to the sample ISR@PRIM provided in CAI.SAMPJCL for an exampleof 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 primarymenu, then ISPF searches for a user profile named CA7PROF, an edit profile namedCA7EDIT, and a command table named CA7CMDS. The CA7CMDS member ofISPTLIB is provided as part of the installation. CA7PROF and CA7EDIT are built byISPF dynamically. ISPF retrieves all profile information from CA7PROF while the CA7application is in control, thus allowing the user the capability of defining ISPF PF keysettings that are unique to the CA7 application.

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

PF?1 - HELP PF13 - HELP

PF?2 - SPLIT PF14 - SPLIT

PF?3 - END PF15 - END

PF?4 - RETURN PF16 - RETURN

PF?5 - RFIND PF17 - RFIND

PF?6 - RCHANGE PF18 - RCHANGE

PF?7 - UP PF19 - UP

PF?8 - DOWN PF2? - DOWN

PF?9 - SWAP PF21 - SWAP

PF1? - LEFT PF22 - LEFT

PF11 - RIGHT PF23 - RIGHT

PF12 - CURSOR PF24 - CURSOR

In a CA-7 terminal session under ISPF there is no ISPF command input area, unless theISPF editor is invoked. All input is interpreted as CA-7 terminal input and is treated assuch. CA-7 input may be entered either from the "top line" or from any area consideredappropriate 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 com-mands can be entered only through the PF key, since all screen input is taken to be CA-7terminal input.



CA-7 allows assignment of CA-7 commands to PF keys as does ISPF. In a CA-7 ter-minal session under ISPF, a PF key interrupt may be used for ISPF command input orCA-7 command input but not both. Since it is desirable to use PF keys for both types ofcommand input, most users may wish to specify that certain PF keys provide ISPFcommand input, and that other PF keys are treated like CA-7 PF keys. When using CA-7formatted input screens, PF3 is used to return to the menu from which the current screencould be selected. (PF15 is not accepted as an equivalent function.) Assigning PF3 toany ISPF command will prevent that key from being used by CA-7 in any way; transfersbetween 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 thatshould be taken when this command is input. Such a table is known as an applicationcommands table and may be modified using ISPF option 3.9. The table exists as amember of a PDS in the ISPTLIB concatenation in the TSO LOGON procedure. Thename of the member (also the name of the table) is xxxxCMDS, where xxxx is the nameof the ISPF application in control when the command was entered. If an ISPF commandis entered from a CA-7 terminal session under ISPF, then the application in control wouldbe CA7. Thus, the table that ISPF would search is CA7CMDS. If an entry is found inthe table that matches the command entered, then ISPF takes the action specified on thattable 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 wereno table entry for it. If NOP is specified, then the command associated with it is deacti-vated for that application. If PASSTHRU is specified, then the command with its PF keyinterrupt is passed to the application in effect, which in this case is the CA-7 TSO/ISPFinterface. 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 defaultPF key settings for the CA7 application previously listed. Use of this table with thedefault PF key settings allows all PF keys except PF02, PF03, PF09, PF14, PF15, andPF21 to be given their CA-7 interpretation in a CA-7 terminal session unless the ISPFeditor is invoked. If the ISPF editor is invoked, then all PF keys are taken as providingISPF 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. TheCA7CMDS member should be copied from CAIISPT to a PDS that is in the ISPTLIBconcatenation in the TSO LOGON procedure.



The following entries are in the CA7CMDS member supplied on CAIISPT:

VERB T ACTION

DESCRIPTION

.... SUBMIT 3 NOP

.... HELP ? &CA7ACT

.... RETURN ? &CA7ACT

.... RFIND ? &CA7ACT

.... RCHANGE ? &CA7ACT

.... UP ? &CA7ACT

.... DOWN ? &CA7ACT

.... LEFT ? &CA7ACT

.... RIGHT ? &CA7ACT

.... CURSOR ? &CA7ACT

The ACTION NOP on the entry for SUBMIT causes the ISPF SUBMIT command to bedeactivated for the CA7 application. This prevents users from using the ISPF SUBMITcommand to submit jobs while in the ISPF editor in a CA-7 terminal session. This isstrongly recommended since jobs submitted through the ISPF SUBMIT command are nottracked by CA-7.

Use of the &CA7ACT variable on the other table entries allows the interface programsand CLISTs to set the action dynamically, so that the action may be changed when theneed arises. If the ISPF editor is invoked from a CA-7 terminal session, then the valueof &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 terminalsession where the ISPF editor is not currently being used. Suppose also, that the PF01key is associated with the ISPF HELP command under the CA7 application. ISPFsearches the CA7CMDS table for an entry for the ISPF HELP command. The entry isfound 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 pro-grams which send the PF01 interrupt to CA7. CA7 sees the interrupt and processes thecommand (if any) associated with that PF key.



If, however, the ISPF editor has been invoked from a CA-7 terminal session, then thesituation is different. Prior to entering the ISPF editor, the interface programs set thevalue of &CA7ACT to blanks. Thus, the action associated with the ISPF HELPcommand in the CA7CMDS table has been set to blanks. This causes the ISPF HELPcommand to be processed normally when PF01 is pressed.

Most of the default PF key settings provided for the CA7 application equate with ISPFcommands that have no significance in a CA-7 terminal session unless the ISPF editor isinvoked.

Great care should be exercised when modifying the ISPF PF key settings or the commandtable for the CA7 application. Only those PF keys that are associated with ISPF com-mands which appear in the CA7CMDS table with an action of PASSTHRU or&CA7ACT are honored by CA-7. The default command table CA7CMDS which isfound in CAIISPT does not include entries for SPLIT, SWAP and END. This causesthese 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 commandinput that must be entered from the CA-7 terminal session. If such command input isalways to be handled by ISPF or TSO then do not create entries for these commands inCA7CMDS.


Virtual terminal definitions are required. The number of virtual terminals defined shouldbe greater than or equal to the number of nodes defined for CA-7 TSO/ISPF communi-cation.

For further information on installation of the TSO/ISPF interface for CA-7, refer to theCA-7 Getting Started guide.

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

2.1.18 Unicenter TNG

CA-7 has the capability to send and receive jobs to and from platforms managed byUnicenter TNG (cross-platform scheduling). Refer to Chapter 6, “CA-7 Cross-PlatformScheduling” 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 maintainingdocumentation about relevant production workload procedures and information. With thisoperations automation tool implemented, vital information regarding the production work-load is stored online and is readily available. With the production workload informationcentrally located, and since the tool is so easy to use, CA-7/Notepad significantly reducesthe time operations staff would normally spend researching and resolving a potentialproblem.

With CA-7/Notepad, information can be shared between CA-11/Notepad andCA-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 andimproving auditability.

CA-7/Report Balancing is a rule-based menu-driven system that provides comprehensivedata verification routines to catch errors in a timely fashion -- before mistakes are propa-gated throughout the system. CA-7/Report Balancing adds to the flexibility of CA-7 byallowing 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 toan out-of-balance condition. No longer is it necessary to manually balance a report andthen manually demand jobs for execution. Implementation of CA-7/Report Balancingrequires 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 graphicreporting capabilities to CA-7 clients.

CA-7/Reports+ assists production control managers, data center executives, schedulingpersonnel, and end users in analyzing all facets of production workload performance andmanagement. By presenting production workload and performance data in quality graphicformat, CA-7/Reports+ simplifies the task of trend analysis while helping to pinpointproblem 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 theCA-7 browse event to your CAIENF database. Refer to member L2DCM1 in the CA-7sample 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-SystemConsole.

� CA-7/Smart Console to CA-7/Smart Console

Users can define cross system actions where a message is selected by CA-7/SmartConsole on one system and specific actions are performed on another system exe-cuting 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 toall defined systems executing CA-7/Smart Console. Commands issued from a systemexecuting CA-7/Smart Console can be routed to another system executingCA-7/Smart Console. The command output is returned to the console that issued thecommand. The principle of integrated services will be used to communicate betweensystems. The use of CA Common Communication Interface (CAICCI) insulates CAproducts 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 formessage 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, onlyconsole messages are routed between systems executing CA-7/Smart Console.CICS messages are not routed unless they are issued to the console using theSENDOPER action.


2.2 CA-7 Options

� Simulate Mode

– This feature functions at the action record level. By defining an action record inthe SIMULATE state, you instruct the action processor not to actually performthe 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 onthe CA-7/Smart Console system parameters. The inclusion of an action record inthe simulate state within a list of actions has no effect on any of the otheractions; they are still processed normally. You can set one, some, or all of theactions in a list to the simulate state.

� Selection Processing

– This selection process will allow messages to be selected only a specifiednumber of times within a time frame. After this maximum has been reached, theselection record can be suspended for a specific time period.

– This selection process will allow messages to be selected only after a specifiednumber of occurrences. After this frequency has been reached, the selectionrecord can be suspended for a specific time period.

– You can specify substitution variables as scan text. Substitution variables workwith the SETEVENT action. When the SETEVENT action occurs, all the vari-ables for that message are saved. By entering the Event ID in the token fieldand the actual variable name in the SCAN TEXT field, the selection processorwill resolve the variable and perform the SCAN using the data that variable con-tains.

– The selection processor allows specification of up to eight SCAN TEXT quali-fications.

– Selection processing supports lowercase characters as your SCAN TEXT data.Be aware that, SCAN TEXT data defaults to lowercase when specifying the datain the CA-7/Smart Console Dialog.

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

– A selection field, SUBSYSTEM, qualifies what is being processed. Validparameters for this field are: WTO, CMD, and CICS. The default is WTO,which is used to define console messages. CMD is used for selection of oper-ator commands. CICS is used for the selection of internal CICS messages thatare typically written to the MSGUSR DCB. Use these messages to detect ter-minal and printer errors, transaction abends, and other information relevant to aCICS address space.

Use the SUBSYSTEM field with the JOBNAME field to select CICS messagesfrom specific address spaces.


2.2 CA-7 Options

– The selection processor allows for selection of the MVS Nucleus InitializationProgram (NIP) messages. NIP messages are produced from the time the systemoperator selects the LOAD function at the system console to the time that theoperating system is initialized. System initialization is considered the point intime when the system log becomes available. To select NIP messages,CA-7/Smart Console must be initialized before the Job Entry Subsystem (JES) isstarted. Keep in mind that the NIP messages have already occurred by the timeCA-7/Smart Console initializes; these messages are not selected realtime.CA-7/Smart Console processes them as if the messages were occurring atCA-7/Smart Console initialization time. This provides the ability to determinethat an IPL has occurred or perform action processing based on the producedNIP messages. Since the NIP messages occur before the CA-7/Smart Consoleaddress 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 ofdates on which the selection record will be active.

– Day/Time Qualification is available. This will allow you to specify a certain dayor days and also specific time ranges on those days within which the selectionrecord 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 automat-ically 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/ESASP4.

� Automatic Time Commands

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

� Licensing Management Program (LMP)

– CA-7/Smart Console interfaces with CAIRIM to determine product licensingauthorization.


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 SystemServices. These services allow UNIX users to operate from within the OS/390 environ-ment without having to learn the MVS system internals while using most of the standardUNIX facilities such as shell commands, shell scripts, and binary executables. ThisUNIX shell runs as an MVS system task and can be accessed from any MVS batch jobthrough a program called BPXBATCH.

The BPXBATCH program is invoked from MVS batch and executes shell scripts or exe-cutables on the UNIX file system. Since this is standard MVS batch JCL, CA-7 canschedule these tasks just like any other MVS batch job.

Refer to the IBM documentation, OS/390 OpenEdition User's Guide, for a detailed dis-cussion 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',


//:

//STDERR DD PATH='/u/users/work/mystd.err',


//:

//STDENV DD DSN=USER.PDS(ENVARS),DISP=SHR

//:



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 thecreation of the data file as a prerequisite task and is triggered when the data file isreceived from the RJE site. Such activities are handled by CA-7 facilities such as batchterminal interface, trailer step, U7SVC, and batch card load program (BCLP).

The batch terminal interface facility (BTI) is used to perform mainly database functionswithin a batch job instead of through an online terminal. Many of the same commandsthat are available online can be performed through a batch terminal when a CA-7 onlineterminal is unavailable or impractical.

Trailer steps communicate queue posting commands to CA-7 for some action that hastaken place. On receiving this communication, CA-7 automatically initiates all tasksdefined as dependent on that posting action.

The U7SVC program combines the BCLP and trailer step functions. U7SVC can beexecuted as a step, in the same manner as a trailer step, or it can be called from anotherprogram to send commands to CA-7 or post a data set creation. Through U7SVC, theuser can post to CA-7 the creation of a noncard-image data set or request commands notsupported by the trailer step.

The CA-7 CCI interface combines aspects of the BTI and U7SVC facilities. It uses theComputer Associates Common Communication Interface (CAICCI) to send batch com-mands to CA-7 on the same or another MVS image. It also receives back the CA-7output from those commands so that the caller can evaluate the success of the commandstring, and/or extract information from the command output for future processing. TheCA-7 CCI interface can be executed in a batch mode, called from a REXX CLIST orenvironment, or called directly from another program.

BCLP is used to transfer batches of card-image data to disk or tape. Once the data filesare created, work under CA-7 control can use those files. On creation of the file, com-pletion information is posted to the CA-7 log data set and all dependent processing tasksare 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 centralcomputer 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. Ofcourse, work that begins with any task external to CA-7 can still realize the advantages ofautomated 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 onlineterminal. You can perform many of the same commands available online in this mannerif no CA-7 online terminal is available, if hardcopy output is desired from the commandsperformed, or if more than 255 pages of output could be produced. Each batch terminalis actually a pair of disk data sets, one input and one output. These data sets must bedefined in the online CA-7 JCL.

When using a batch terminal, ICOM does not have to be active on the CPU whereSASSBSTR is running; but the batch terminal must have access to the Communicationsdata set. However, when using the trailer step, U7SVC or BCLP facilities, ICOM mustbe active on the CPU where it runs.

Commands must follow the same sequence as if using a CA-7 online terminal. Queuemaintenance commands, such as XQ or XUPD, are not available in batch mode, and theDB.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 inthe output data set.

� Retrieves the output and writes it to a SYSOUT data set. The BTI output can bechecked against a user-defined table of messages to detect error or warning condi-tions. Refer to the CA-7 Systems Programmer Guide, "User Exits and Modifica-tions," 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 batchterminal interface input data set. They must begin in column 1 of the record.

To log on, the format is:

/LOGON

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

Where:

opidSpecifies the required operator identification.

passwordSpecifies 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 securityID for the user who submitted the BTI job.

The format of the DBM batch commands consists of placing the equivalent screen topline command by itself in the first statement. In the second and following statements arethe 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 valueentered. There must be a nonblank character in column 72 and the next statement mustbegin in column 1.

In the following, please notice that function is a positional parameter and must appearwhere 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??1,OPT=C

DBM

LJOB,JOB=ACCTPAY,LIST=RQMT

/LOGOFF

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 targetand does not actually provide an image of the equivalent online formatted screen con-taining 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 thejob.



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 com-mands, there is a significant difference:

� For non-DBM commands, the batch statement format is the same as the online topline 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 manycommands in BTI format. These commands perform database maintenance (DBM) func-tions and some inquiry functions.

These commands provide a good example of how to use the BTI facility effectively. Theuser can benefit from reviewing that data and understanding better how this facility canbe used to accomplish many user needs.

Note: The N220 job itself should not be run while CA-7 is active online, as the N220job is an execution of CA-7 in batch mode. The same commands, however, canbe used with the Batch Terminal Interface program. The batch commands for jobN220 reside in member N220DECK in the JCLLIB from installation. Check withyour CA-7 specialist or systems programmer who installed CA-7 for the data setname.



3.1.2 Batch Terminal Interface Execution

3.1.2.1 Processing Flow

The batch terminal interface program (SASSBSTR) controls the BTI processing flow. Itperforms the following functions:

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

� Copies SYSIN data to the BATCHIN data set.

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

� Awaits completion of the processing by CA-7.

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

If the user-defined batch error message table module SASSXXBT is available, eachline of output is compared against entries in the table. If matched, a message iswritten to the ERRORS DD (if available). Also, the matching table entry return codeis saved if it is higher than any previously saved return code.

The possible return codes are:

Usage of the SASSXXBT message table may generate additional return code values.Refer to the CA-7 Systems Programmer Guide for additional information aboutSASSXXBT.

You should never cancel a BTI job while it is executing. This kind of cancel does notinterrupt the execution of the CA-7 commands that the BTI has given to CA-7 to processon the specified (or pooled) batch terminal. All of these commands have to completebefore CA-7 can make the batch terminal available for another BTI execution.

Return code Explanation

0 The SASSBSTR program was able to successfully complete itsfunctions without detecting an error. SASSBSTR does NOT vali-date that the SYSIN commands were processed successfully byCA-7.

8 SASSBSTR detected an error condition that prevented successfulcompletion of its tasks. Usually, a WTO or message in theSYPRINT is issued indicating the error condition.

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

16 A security violation occurred which prevented successful exe-cution of SASSBSTR.



If you do a cancel, the only way to possibly recover (reuse) that batch terminal is to runanother BTI specifying the appropriate ID number. This causes CA-7 to produce theCA-7.252 WTOR, and a reply of RESET allows the BTI to proceed. However, if theprevious BTI commands have not yet completed, the current BTI still fails. Also, no BTIusing pooling is able to use the same ID again of the cancelled one until a recycle ofCA-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 touse 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:

nCan be 0 or specific BTI terminal. A value of 0 (zero) indicates that Dynamic BTIManagement should be used. (The program automatically locates and uses an avail-able BTI terminal.) A specific BTI terminal number (1-8) indicates that the programshould use that specific batch terminal. If that terminal is already in use by anotherjob, the current job checks every 5 seconds for a total of 1 minute to see if theterminal becomes available. If the terminal is still unavailable, a CA-7.252 WTOR isissued so that you decide whether you want this job to wait for the terminal tobecome available or cancel this job. Remember that if a specific BTI terminalnumber 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 thepool 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 listof 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 specificjobs. If these terminal numbers are excluded from the pool, Dynamic BTI Manage-ment never allocates them, thus they should always be available for BTI executionsthat reference them specifically.

If all batch terminals in the pool are busy, the BTI program enters a cycle where itlooks for an available batch terminal every five seconds. This continues for fiveminutes. If no batch terminals have become available during that time, WTORCA-7.253 is issued. If there is a system problem, the operator can reply CANCEL toterminate the BTI job with a return code of 8. If a reply of WAIT is issued, the BTIprogram continues its wait/check cycle indefinitely. If several BTI jobs are waitingon any available batch terminal, there is no serialization in the order in which theyobtain a terminal.



DSNPFX='batch.dsn.prefix.'Specifies an alternate data set name prefix for the BATCHIN and BATCHOUT datasets. The BTI program dynamically allocates the BATCHIN and BATCHOUT filesassociated with a specific batch terminal. Normally, the BTI program constructs thedata set names for these files using the data set name prefix from the CA-7 commu-nication data set (UCC7CMDS DD). The suffix BATCHI#n/BATCHO#n isappended to the prefix to construct the full data set names (where n is the associatedbatch terminal number).

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

NOMCHKUsed to suppress BTI output message checking against the SASSXXBT messagetable. If this parameter is not specified and a user-coded SASSXXBT table moduleis available, the message checking is done. Refer to the CA-7 Systems ProgrammerGuide, "User Exits and Modifications," for a description of the SASSXXBT messagetable.

NOWAITIf this parameter is specified, BTI terminates with an RC=8 if CA-7 is not activewhen the BTI job starts. If this parameter is not specified and the CA-7 addressspace is not active when the BTI process starts, it issues a WTOR (CA-7.255) andwait for CA-7. When CA-7 becomes active, BTI processing continues without anyintervention.

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 causethe processing of CA-7 commands at strategic points within the processing. Jobs exe-cuting 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 notaffect the operational function of the job but causes activity within CA-7. A CA-7 appli-cation is executed which performs the operation requested in trailer step JCL. You mayuse the trailer step to perform any of the commands belonging to the queue maintenanceapplication as defined by SPO0 security. Refer to Figure 3-1 for an illustration of trailerstep 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 adata set requirement. Normally, CA-7 does not post data set requirements for jobs in therequest queue until normal completion of the job which creates the data sets. This is dueto the possibility of a restart which would again create the data set. A trailer step couldbe inserted after the step that creates the data set (before other steps of the job) to postrequirements 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 jobdependency could be established even though the online system is not a CA-7 job. Thefinal step of the online system could post these jobs with a trailer step to satisfy thisrequirement.

The /MSG command is also allowed in the trailer step. You can send messages to logicalterminals by this process.

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

The /WLB command is allowed in the trailer step. You can turn workload balancing ONor OFF and can adjust certain resources.

Once the trailer terminal is used, it cannot be logged off. This means that a /LOGOFFcommand is ignored other than to terminate a block of input data as noted later in thischapter.

To use the trailer step facility, a trailer terminal must be defined in the initialization fileand ICOM must be active on the CPU where the trailer step is to run. Only one trailerterminal may be defined. Refer to 3-12 for a trailer step JCL sample. A JCL proceduresimilar to this is provided during installation and should be used to ease maintenance andversion upgrades. Check with your systems programmer or CA-7 specialist for thecorrect procedure name.



//CA?7TRLR EXEC PGM=SASSTRLR,PARM= (See NOTE)

//STEPLIB DD DSN=CA-7.loadlib,DISP=SHR

//SYSOUT DD SYSOUT=A


//SYSIN DD DATA,DLM=##

/LOGON operator-ID

CA-7 queue posting commands go here

/MSG,LT=station,M=message

##

//:

Figure 3-2. Trailer Step JCL Sample

Note: You can specify an optional PARM value on the EXEC statement. The PARMvalue may be either ACT or INACT. ACT indicates that ICOM must be active orthe data is not sent. If ACT is specified and ICOM is not active, the programissues error messages and abends. When the PARM value of INACT is used, thedata is held in CSA to be processed when ICOM is started. Additionally, if thetrailer step is to send commands to a test copy of CA-7, a PARM value ofTEST=YES must be specified.

Refer to the CA-7 Security Guide for the discussion of SASSTRLR and the /LOGONstatement. Refer to the CA-7 Systems Programmer Guide for information on the use ofSASSTRLR with a test copy of CA-7.

To prevent command interleaving among multiple tasks on the same CPU and tasksamong 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 toavoid 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 DDstatement. The attribute should be BLKSIZE=80.


0 PARM value supplied.

4 PARM defaulted to INACT and/or an invalid command wasfound in the input. If an invalid command is found, the followingWTO is issued: CA-7.TRLR-10 COMMAND NOT IN SPO0APPLICATION.

8 Invalid PARM, INACT assumed. Various error conditions,denoted with a WTO which describes the error. Refer to theCA-7 Message Guide for an explanation of the various WTOs.


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 trailerprogram (SASSTRLR) uses the SVC to issue various posting commands. A program isprovided to allow the user flexibility in the use of the SVC. The name of this program isU7SVC 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 setmay have been created in a previous step of a job that is running external to CA-7. Thecreated data set need not be fixed blocked with a record length of 80, as is the case withBCLP.

The program also allows the user to issue CA-7 batch commands. All commands that areauthorized for the trailer terminal may also be issued. Thus, the U7SVC program is notlimited 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 shouldnot be specified by the SASSXDSN exit table, or possible double postings (anddouble 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 leastone is required. The ddname for the DD * input data is CA7DATA. Each commandmust be on one line and cannot be continued. The format of the PARM or data recordconsists of one or more entries separated by semicolons. Each entry is a CA-7 batchcommand or a data set creation statement. (Each entry may begin and end with one ormore blanks.)

3.3.1.1 Syntax

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

D

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

Where:

dsnameSpecifies the data set name.

Size/Type: 1 to 44 alphanumeric charactersRequired: Yes

vvvvvvIndicates a positional parameter specifying the volume serial number where the dataset was created. Not needed if the data set has been cataloged. If not specified, acomma must be used to denote its absence.

Size/Type: 1 to 6 alphanumeric charactersRequired: No

xxxIndicates a positional parameter specifying the schedule ID to be used for the data setcreation. If not specified, a comma must be used to denote its absence.

Size/Type: 1 to 3 numeric characters from 1 to 255Default: 1Required: No

ttttttttIndicates a positional parameter specifying the logical terminal or station name to benotified of the data set creation.

Size/Type: 1 to 8 alphanumeric charactersDefault: MASTERRequired: No


3.3 U7SVC Facility

Note: When external security is present, a resource check is made for all data set cre-ation requests. Since CA-7 treats these requests as if the data set was reallycreated, it can cause posting or triggering to occur. Therefore, a security resourcecheck 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 proce-dure is written to a user-specified PROCLIB during the execution of the N020 installationjob.

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

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

Example 2: This example indicates a logon, demand scheduling of job TEST, postingcreation of data set CA7.TEST2, demand scheduling of jobs TEST2 and TEST3 and alogoff. All could have been provided in the CA7DATA data set if so desired. Eachcould 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 therelative GDG number format. The relative GDG number is converted to the cor-responding 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 abso-lute generation number. The absolute zero generation number can also be speci-fied, for example D=A.B.G0000V00. This format is not converted, but it isrecognized as a GDG data set.

If queue maintenance commands (other than D commands) are entered through theU7SVC 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 commandsand end with a /LOGOFF.

Note: When external security is being used, a password may be required. Refer to theCA-7 Security Guide for more details on security interfaces.

The U7SVC facility uses the same blocking technique noted for the trailer step facility onTrailer 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 theprogram being executed. A standard parameter list is passed in register 1. One or morecommands may be passed for each call.

U7SVC can be called by using the LINK macro. Register 1 must contain the address ofthe parameter list. The parameter list must be on a halfword boundary where the first 2bytes 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 PARMkeyword included with it.

U7SVC can modify the parameter list that is passed to it. If a user program is calling theU7SVC multiple times during a single execution, then the parameter list needs to be rein-itialized by the user program between calls.

The following is a sample program to call U7SVC.

ZSVCTEST TITLE '-- SAMPLE PROGRAM TO CALL U7SVC'

ZSVCTEST START

SASSVRSN VRSN=TST, X

REGS=R1?, IDENTIFY BASE REGISTER X

LINK=OS, REQUEST OS LINKAGE X

EQU=YES REQUEST REGISTER EQUATES

LA R1,PARMA POINT TO PARAMETER ADDRESS

LINK EP=U7SVC,ERRET=OOPS

B #UCC7RET RETURN TO CALLER

OOPS DS ?H

WTO 'U7SVC NOT LINKED'

LA R15,16 SET ERROR CODE

B #UCC7RET RETURN TO CALLER

PARMA DC A(PARMS)

PARMS DC Y(PARML)

: DC C'TEST=YES;' (REQUIRED IF SENDING TO TEST COPY)

COMMANDS DC C'/LOGON;DEMANDH,JOB=CA?7TEST;/LOGOFF'

PARML EQU :-COMMANDS

END


3.4 CA-7 CCI Interface


3.4.1 Overview

The CA-7 CCI interface uses the Computer Associates Common Communications Inter-face (CAICCI) to send batch commands to, and receive command output from the CA-7address space. The interface can be executed from batch, from a REXX address environ-ment, or in a program-to-program mode. Because the interface uses CAICCI, there is norequirement for shared DASD between the MVS images where CA-7 executes and wherethe CA-7 CCI interface environment executes.

CAICCI is a Computer Associates common component which allows CA applications tocommunicate with each other without dealing with the specifics of a particular communi-cation protocol. The actual transfer of data may be in the form of cross-memory, VTAMto VTAM connection, or some form of TCPIP connection. However, the applicationcode is not dependent on any particular protocol. CAICCI is a sub-component of theCAIENF (Event Notification Facility) common component.

The CA-7 CCI interface establishes communication with the CA-7 CCI receiver in theCA-7 address space. This receiver is created when there are one or more CA-7 CCITerminals (DEVICE=CCI) defined in the CA-7 initialization file. Refer to the CA-7Systems 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 outputfrom these commands is also returned in the CA-7 batch format. Refer to 3.1, “BatchTerminal Interface (BTI)” on page 3-2 for specific information about CA-7 batchformats.



3.4.1.1 Usage Considerations

1. CAICCI must be active on both the MVS image where the CA-7 address space isexecuting and where the CA-7 CCI interface environment is executing. There mustbe 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 activein 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 executingmust be a valid CA-7 operator.

5. There is NO requirement for shared DASD between the MVS image where the CA-7CCI interface executes and the image where CA-7 itself executes.

6. There is NO requirement that CA7ICOM executes on the MVS image where theCA-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 sendcommands 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 toSYSPRINT.

If the user-defined batch error message table module SASSXXBT is available, eachline of output is compared against entries in the table. If matched, a message iswritten to the ERRORS DD (if available). Also, the matching table entry return codeis 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


//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 NODEThe CAICCI node name where the CA-7 address space is executing. The default isto attempt to communicate with a CA-7 executing at the same CAICCI node wherethe batch job is executing (local node).

CA-7 SSCT NAMEThe subsystem name of the CA-7 you wish to communicate with. The primary copyof CA-7 (production copy) has an SSCT name of 'UC07'. The secondary copy ofCA-7 (test copy) has an SSCT name of 'UCT7'. The default is to communicate withthe primary (production) copy of CA-7. The values PROD and TEST can be usedinstead of UC07 and UCT7.

OPTIONSThe 1-4 character option string:

TRACE OPTIONIf 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 SEPARATORThe character used to separate commands when they are read from SYSIN andstacked into a command block. The default command separator character is asemicolon (;).

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

CMDIN DDNAMEThe ddname of the source for CA-7 commands. The default is SYSIN.



CMDOUT DDNAMEThe ddname for the CA-7 command output. The default is SYSPRINT.

ERRORS DDNAMEThe ddname for messages produced when a CA-7 command output line matches anentry 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 tableis 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 liststhe return code and condition code for the process. The possible return and conditioncodes from CAL2X2WB are as follows:

Note: Usage of the SASSXXBT error message table may generate additional return codevalues. See the CA-7 Systems Programmer Guide for additional information aboutSASSXXBT.


0 The CAL2X2WB program was able to successfully complete itsfunctions without detecting an error.

8 Processing error:

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

CC=2 No command output responses were received fromCA-7.

CC=8 Non-zero return code from CA-7 CCI interfacemodule (CAL2X2W0). See message CAL2C596E.

CC=9 Error attempting to GETMAIN storage. Seemessage CAL2C594E.

CC=10 Error attempting to LOAD a needed module. Seemessage CAL2C595E.

16 Parameter list error:

CC=1 Invalid parameter list. See message CAL2C590E.

CC=2 Invalid parameter value. See message CAL2C591E.

CC=3 Required DD statement missing or invalid. Seemessage CAL2C592E.

CC=4 DCB open error. See message CAL2W593E.



3.4.3 CA-7 CCI REXX Interface Execution

The CA-7 CCI REXX interface programs (CAL2X2WA and CAL2X2WR) provide thecapability to send commands to CA-7 and receive the output from those commands in aREXX environment. Program CAL2X2WA establishes the REXX CA-7 Address envi-ronment, and program CAL2X2WR processes the command handling.

CA-7 provides a REXX example in the CAICLIB installation library. The sample EXECis 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) /: strip carriage control char :/

say line2

end

return



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 toexecute 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. Copythis EXEC to a data set in your SYSEXEC concatenation. The sample EXEC isCA7OPSRX.

/:--------------------------------------------------------------:/

/: :/

/: 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 fromanother 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 thecommand responses from CA-7. The calling program can then parse the responses andtake 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 beavailable to the program being executed. A standard parameter list is passed in register1. The format of the parameter list is:

Offset Value

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

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

+ 8 Address of an 8 byte field where the address and length of the CA-7 responsebuffer is placed. The first 4 bytes will contain the address, and the second 4bytes will contain the length of the buffer. If the caller wants the responsebuffer to be in storage above the 16Mb line, the first byte of the 8 byte fieldshould contain the value X'80'. Otherwise, the buffer storage is GETMAINedbelow the 16Mb line. This parameter is required.

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

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

+16 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.

+20 Pointer to a 4 character Options field. The first character indicates whetherdiagnostic trace messages are to be generated (value of Y). The default is tonot produce trace messages. The second character can specify the commandstring separator character. Any non-blank non-null character can be used as acommand separator. The default separator is semicolon (;). The third andfourth characters are reserved for future use. This parameter is optional.



3.4.4.2 CAL2X2WP Response Buffer

The response buffer returned by CAL2X2WP contains all of the output lines receivedfrom CA-7 in response to the command string provided. If no responses were receivedfrom CA-7 because of an error, no response buffer is created, and the address/length fieldsupplied by the caller is nulls. If an error was encountered after CAL2X2WP beganreceiving responses from CA-7, a response buffer is still created, and the address andlength are set in the caller's address/length field. IT IS POSSIBLE TO RECEIVE ANON-ZERO RETURN CODE FROM CAL2X2WP AND STILL HAVE A RESPONSEBUFFER.

CA-7 responses in the response buffer are fixed length records. Each record is 133 bytesin length. If you wish to calculate the number of lines in the buffer, simply divide theoverall length by 133. Each response is blank-padded and begins with a carriage controlcharacter.

It is the caller's responsibility to FREEMAIN the response buffer once it is no longerneeded. The buffer is obtained from subpool 0. If the first byte of the caller's 8-byteaddress/length field contains X'80' on entry to CAL2X2WP, the response buffer isobtained from storage above the 16Mb line (LOC=ANY GETMAIN option). IT IS THECALLER'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 conditioncode is in register 0. The possible return and condition codes from CAL2X2WP are:


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

4 No responses from CA-7 received.

8 Processing error:

CC=9 Error attempting to GETMAIN storage.

CC=10 Error attempting to LOAD a needed module.

12 Error return from CAL2X2W0 (non-abend)

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

16 Parameter list error:

CC=1 Invalid parameter list.

CC=2 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 R1,X2WPPARM : R1 -> PARM LIST

LINK EP=CAL2X2WP : CALL CA-7 CCI PGM-PGM

:

CLC BUFFADR,=A(?) : ANY CA-7 RESPONSES ?

BE #UCC7RET : NO - EXIT WITH RC

L R2,BUFFADR : R2 -> RESPONSES

L R3,BUFFLEN : R3 = BUFFER LENGTH

LA R3,?(R2,R3) : R3 -> END OF RESPONSES

LOOP DS ?H

CLC SPO7??,?(R2) : GOOD DEMAND RESPONSE ?

BE GOOD : YES - EXIT LOOP

LA R2,133(,R2) : R2 -> NEXT LINE

CR R2,R3 : REACHED END ?

BL LOOP : NO - CYCLE

WTO 'X2WPSAMP : JOB DEMAND NOT SUCCESSFUL '

B #UCC7RET : BRANCH TO PROGRAM EXIT

:

GOOD DS ?H

WTO 'X2WOSAMP : JOB DEMANDED SUCCESSFULLY '

B #UCC7RET : BRANCH TO PROGRAM EXIT

:

SPO7?? DC CL1?' SPO7-?? ' : GOOD DEMAND MSG PREFIX

:

X2WPPARM DS ?F : CA-7 CCI IFACE PARM LIST

DC A(CMDLIST) : ADDRESS OF COMMAND STRING

DC A(CMDLISTL) : LENGTH OF COMMAND STRING

DC A(BUFFSET) : BUFFER ADDRESS/LENGTH FIELD

DC X'8?',AL3(?) : END OF PARMLIST

:

BUFFSET DS ?D : SPOT FOR BUFFER ADDR/LENGTH

BUFFADR DC A(?) : ADDR OF CA-7 RESPONSE BUFFER

BUFFLEN DC F'?' : LENG OF CA-7 RESPONSE BUFFER

:

CMDLIST DC C'/LOGON USERX;DEMAND,JOB=TESTJOB;/LOGOFF'

CMDLISTL EQU (L'CMDLIST)

:

END X2WPSAMP


3.5 Batch Card Load Program (BCLP)


The Batch Card Load program (BCLP) loads card-image data to sequential data setsrequired for CA-7 jobs. Through BCLP, sequential data sets may be created, replaced ormodified. When BCLP is executed, CA-7 is notified by ICOM of successful data setmanipulation through the communications data set. In this way, the database indexentries 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 thenscans the request queue for jobs that use this data set as an input requirement. Jobstriggered 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. Thesedata 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 markedas a maintenance job to prevent the posting of SMF records. To mark BCLP as a main-tenance job, use the DB.1 screen which is defined in the CA-7 Database MaintenanceGuide 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 Mainte-nance Guide.

If the job is not marked as a maintenance job, then message SMF0-17 is issued (unlesssuppressed with SASSMSGS) and the Type 99 record (DSN creation) is ignored. Thiscould cause improper scheduling if the data set request included the SCHID keyword.

BCLP dynamically allocates space required for each data set. This is accomplished byspooling card images to a work data set and calculating the number of disk tracksrequired to store the data.

Generation data groups may be handled through BCLP; however, the following differ-ences 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 tocreate 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 ofthe 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 data-base unless REQSAT=NO is used.

To post requirements as available, ICOM must be active. If ICOM is not active, require-ments 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 ormore of the following parameters. If more than one is entered, they must be separated bycommas.

EXITPROG=xxxxxxxxDescribes the name of the user exit routine which is to receive control immediatelyafter each statement is read (including the OPTION statement). This exit programname 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 setonly). If EXITPROG is omitted, SASSBCX1 is assumed.

ERR=ABORTIndicates 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=YESIndicates that data set creation information is to be sent to a test copy of CA-7 ratherthan the production copy.

DD Statements: The following DD statements are required:

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

SYSUDUMPUsed for a dump under certain error conditions.

UCC7IDSSpecifies the index data set. See the DBPARMS DD discussion in the CA-7 SystemsProgrammer Guide.

UCC7JLIBSpecifies the job data set. See the DBPARMS DD discussion in the CA-7 SystemsProgrammer Guide.

UCC7DLIBSpecifies the dataset data set. See the DBPARMS DD discussion in the CA-7Systems Programmer Guide.



DBPARMSUsed to define parameters in the database. Refer to the CA-7 Systems ProgrammerGuide for a description of this data set. The same values used in the UCC7DBASEstatements when the database was last loaded must also be used here to ensurecorrect access to the database.

UCC7WORKAllocates 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.

U7xxxxxxOne 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 theDD statement. If it does not match, a warning message is generated. Volumes arelocated by VOL=SER, not by ddname.

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

SYSINSource of input control statements and data.

BCLP JCL: The following is a sample of BCLP JCL with EXITPROG PARM.

//ST1 EXEC PGM=SASSBCLP,PARM=('EXITPROG=PX1')

//STEPLIB DD DSN=CA-7.loadlib,DISP=SHR

//SYSPRINT DD SYSOUT=A


//UCC7IDS DD DSN=user-defined-index-data-set,DISP=SHR

//UCC7JLIB DD DSN=user-defined-job-data-set,DISP=SHR

//UCC7DLIB DD DSN=user-defined-dataset-data-set,DISP=SHR

//DBPARMS DD DSN=user-defined-location-of-DBPARMS,DISP=SHR

//UCC7WORK DD VOL=SER=111111,UNIT=SYSDA,

// DISP=(NEW,DELETE),SPACE=(TRK,(1?,1?))

//U7VOLSER DD UNIT=SYSDA,SPACE=(TRK,?)

//U7111111 DD VOL=SER=111111,UNIT=SYSDA,DISP=SHR



//SYSIN DD :

:UCC7 CREATE DSN=A.B.C,VOL=111111

statement1

:UCC7 REPLACE DSN=X.Y.Z,VOL=222222

statement1

statement2

:UCC7 EODS

/:

3.5.2 Control Statements for BCLP

Control statements for the Batch Card Load Program must contain an identifier, an opera-tion, and optionally one or more keyword operands. The identifier and operation fieldsare separated by one or more blanks. The operation field and the first keyword parameterare 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 eachcontrol statement, including continuation statements.

� Operation Field

The operation field must be separated from the identifier by one or more blanks. Ifmultiple statements are used for the same operation, the operation field must appearon the first statement.

� Keyword Parameters

The operation field and the first keyword parameter are separated by one or moreblanks. Keyword parameters may appear in any order. For a continuation, the lastkeyword on a statement to be continued must be followed by a comma. The nextkeyword parameter and its operand (with the exception of JOBS) must appear on thenext statement. On continuation statements, the identifier (*UCC7) and the firstkeyword parameter must be separated by at least one blank.

� Comments

Comments may be entered in two ways. A comment may be entered beyond the lastkeyword of a statement. It must be separated from the keyword and its operand byone or more blanks. If an entire statement is to contain comments, the first characterof the comments must be an asterisk (*). Even if the entire statement is to contain acomment, the identifier (*UCC7) must be present.

Examples:

:UCC7 operation1 keyword1=x,keyword2=y

:UCC7 operation2

:UCC7 keyword=x, THIS VALUE IS

:UCC7 :REQUIRED ON MONDAYS

:UCC7 keyword=y,keyword=z,

:UCC7 keyword=zz

The possible operation field values are:

OPTION CREATE REPLACE MODDATA EODS

Examples are provided following the keyword formats and options.



3.5.2.1 OPTION Statement

Use the OPTION statement to set up default parameters for the execution of BCLP. Ifthe OPTION statement is used, it must be first. If standard defaults are sufficient, youmay omit this statement. Options specified in the statement may be overridden at thedata 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:

LTERMWhen CA-7 has completed updating the database index entries and input requirementposting, a data set completion message is generated. The LTERM keyword desig-nates the logical terminal to receive the data set completion message. This messageis generated when CA-7 has updated its database index entries and appropriaterequirements are posted as satisfied. This action, and the associated message, are notproduced unless REQSAT=YES was either specified or taken as a default. Also, themessage is not produced for data sets that are defined as PERM (permanent) inCA-7. If LTERM is specified, it must match a logical terminal name (STANIDS) inthe CA-7 initialization file. If this keyword is omitted, MASTER is assumed.

Default: MASTERRequired: No

MASTERSpecifies the master terminal is to receive the data set completion message.

xxxxxxxxSpecifies the logical terminal name to receive the completion message.

Size/Type: 1 to 8 alphanumeric characters



DETLISTSpecifies whether a detail list of all statements entered is to be produced.

Default: YESRequired: No

YESSpecifies a list of all statements is to be produced.

NOSpecifies only control statements and messages are to be listed.

VOLROTIndicates whether, on a specific volume request, an insufficient space conditionresults in a search of other volumes for the space.

Default: NORequired: No

NOIndicates an insufficient space condition resulting in an error.

YESSpecifies a search of U7xxxxxx volumes, in DD statement sequence, is made forsufficient data set space. Rotation begins with the first volume and proceeds asif it were a nonspecific request.

REQSATSpecifies whether a successful operation on a data set should result in either arequirement being satisfied or a job being triggered.


YESIndicates that CA-7 is notified of the successful operation with a Type 99 recordgenerated by BCLP.

NOIndicates that the operation is performed but a Type 99 record is not generatedand CA-7 is not notified.

BLKSIZEDesignates 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 fora single data set.


3120Specifies the block size of 3120.



nnnnnSpecifies the block size. The block size specified must be divisible by 80 andmay not be larger than the track size of the receiving device or 32720, whicheveris smaller.

EXITPROGDesignates the name of the user exit routine to receive control after each statement isread. This may be done for all statements in the job (specified in the PARM field ofthe EXEC statement), for all control statements (except OPTION) and data state-ments (specified on the OPTION statement), or only for the data statements of aspecific data set request. The various options available to the exit program are dis-cussed in the CA-7 Systems Programmer Guide.

Size/Type: 1 to 8 alphanumeric charactersDefault: SASSBCX1Required: No

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

xxxxxxxxSpecifies the name of the user exit routine.

MAXJOBSSpecifies the maximum number of job names to appear in any JOBS parameter on adata set request statement. If a data set request is encountered which contains morejob names than the maximum, the data set request is bypassed.


10Specifies 10 job names are to appear in JOBS parameter on a data set requeststatement.

nnnSpecifies the number of job names to appear in JOBS parameter on a data setrequest statement.

SCHIDSpecifies which schedule ID created the data set. This may be done on a data setbasis or for the whole job.


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

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



CVOLSpecifies 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 fora data set.

Size/Type: 1 to 6 alphanumeric charactersDefault: SYSRESRequired: No

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

xxxxxxSpecifies 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. Adata set statement always immediately precedes the first data statement for the data setbeing acted on.

Syntax

CREATE REPLACE MODDATA

��──:UCC7─ ──┬ ┬─CREATE── ──,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:

CREATECreates a new data set. The data set must not already exist on the volume. If thedata set is cataloged and the data set still exists on the volume pointed to by thecatalog, the VOL keyword must be specified. In this case, CATALOG=YES resultsin an update of the catalog, but the original data set is not scratched. IfVOLROT=YES is specified and the data set is found during volume rotation, anerror occurs and the data set request is bypassed.

REPLACEReplaces an existing data set. The data set specified in the DSN keyword must existon the volume pointed to by the catalog, or if VOL has been specified, on thatvolume. If VOLROT=YES was specified and there is not enough space on thevolume originally containing the data set, another volume is assigned and the catalogis updated.

MODDATAAdds data to an existing data set if it exists, or creates a new data set if it does notexist. If the data set does exist, the keyword VOLROT has no meaning. Whencreating a new data set, the rules described under the CREATE option apply.



DSNDescribes the name of the data set operated on. The name must be a valid OS dataset name. GDG may be described either by a relative number (+1) or by an absolutegeneration number. The data set name must be defined in the CA-7 database.

Size/Type: 1 to 44 alphanumeric charactersRequired: Yes

BLKSIZEDescribes the output block size to be used for this data set. The rules for BLKSIZEare described in the BLKSIZE keyword of the 3.5.2.1, “OPTION Statement” onpage 3-30.

CATALOGIndicates whether the data set is to be cataloged after a successful operation.

Default: NORequired: No

NOSpecifies that the system catalog is not modified.

YESSpecifies that the data set is to be cataloged.

May also be used to catalog a data set being created, replaced, or modified.

DETLISTSpecifies whether a detail list of all statements entered is to be produced.


YESSpecifies a detail list of all statements entered is to be produced.

NOSpecifies that only control statements and messages are to be listed.

JOBSIndicates that a data set request is to occur only if the specified job or jobs have runsince the last data set update. A maximum of 10 jobs may be entered with thiskeyword unless MAXJOBS has been entered on the OPTION statement to increasethe maximum number. If more than one job is entered, the group of job names mustbe enclosed in parentheses. The JOBS keyword is the only keyword whose operandmay be continued. If continued, the last job name on a statement must be followedby a comma. The next job name may start anywhere on the next statement. Theright parenthesis must appear immediately after the last job name.




LTERMOverrides the default logical terminal and follows the rules described in the LTERMkeyword of the 3.5.2.1, “OPTION Statement” on page 3-30. If present, this keywordoverrides the default only for this data set.


REQSATDescribed in the OPTION statement. If present, it overrides the default only for thisdata set.

SCHIDSpecifies which schedule ID created the data set. It overrides the default scheduleID. SCHID is described in the 3.5.2.1, “OPTION Statement” on page 3-30.

VOLIndicates the volume to be used for this data set. The keyword overrides the catalogif the data set is cataloged. If a volume is entered it must be described with aU7xxxxxx DD statement. If VOLROT=YES is specified and there is insufficientspace 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 anattempt to locate the data set. If the data set is located both in the system catalogand on the volume pointed to by the system catalog, the data set is replaced or addedto 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 fora MODDATA, data is added to the data set. If the data set is not found for aMODDATA, the data set is created.

Nonspecific Requests. If a CREATE request is encountered or if a MODDATAdata set is not found, and the VOL parameter is not present, the data set is assignedto the first U7xxxxxx volume. If there is insufficient space on that volume, anattempt is made to obtain space on subsequent volumes. Volumes are assigned in thesame sequence as their respective DD statements in the job stream.

Note: For nonspecific request, the U7xxxxxx JCL statements must have a volumespecified or the first U7xxxxxx must be named U7VOLSER.

VOLROTDescribed in the 3.5.2.1, “OPTION Statement” on page 3-30. If present, it overridesthe default only for this data set.

EXITPROGDescribed in the 3.5.2.1, “OPTION Statement” on page 3-30. If present, it overridesthe default only for this data set request. The user exit program specified here isused only for data statements and the EODS control statement which may optionallyfollow the data statements.

CVOLDescribed in the 3.5.2.1, “OPTION Statement” on page 3-30. If present, it overridesthe 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. Ifthe EODS statement is omitted, an EODS is generated if another control statement isencountered. If EODS is entered, it must be followed by another data set request controlstatement or end-of-file.

Syntax

EODS

��──:UCC7 EODS────────────────────────────────────────────────────�

A null data set is created if no data statements follow the control statement. You mayuse 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 requirementfor JOB Z. The data set is to be cataloged after creation. The BCLP control statementswould appear as follows.

:UCC7 CREATE DSN=A,VOL=111111,CATALOG=YES

statement1

statement2

:UCC7 EODS

Note: Since the default of REQSAT is YES, the keyword is not required.

All keywords not entered will default.

The EODS statement is optional.

Volume 111111 must be defined by a U7xxxxxx DD statement.

Example 2: Same as Example 1, with the addition that JOB Z must have run since thelast creation (refer to JOBS description for restrictions discussed earlier in this chapter).

:UCC7 CREATE DSN=A,VOL=111111,CATALOG=YES,

:UCC7 JOBS=Z

statement1

statement2

:UCC7 EODS

Example 3: Replace cataloged data set A.

:UCC7 REPLACE DSN=A

statement3

statement4

statement5

Note: Since the data set was cataloged, VOL and CATALOG are not required.

An EODS statement is generated.

The volume on which the data set is cataloged must be defined by a U7xxxxxxDD statement.



Example 4: Add data to the end of a cataloged data set B. JOBS X, Y, and Z musthave run since the last update of data set B (refer to JOBS description for restrictionsdiscussed earlier in this chapter).

:UCC7 MODDATA DSN=B,JOBS=(X,Y,Z)

statement M

statement N

.

.

.

.

statement Z

:UCC7 EODS

Note: If data set B does not exist on the volume, the MODDATA is changed toCREATE.

The volume on which the data set does (or will) exist must be defined by aU7xxxxxx DD statement.

Example 5: Replace data set C. Data set C is not presently cataloged, but is to becataloged after this run.

:UCC7 REPLACE DSN=C,VOL=111111,CATALOG=YES

statement A

statement B

statement C

Note: Volume 111111 must be defined with a U7xxxxxx DD statement.


Chapter 4. CA-Driver Procedures, VariableParameters, and Functions

This chapter describes how to store JCL, variables, and data in the CA-Driver procedurelibrary, 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 areretrieved

� 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 exe-cution JCL. CA-7 calls CA-Driver for each JCL statement in a job at the job's sub-mission time. CA-Driver scans the JCL statements looking for either of the followingcontrol statements embedded in the job stream.

// EXEC procname

or

// EXEC PROC=procname

When one is encountered, CA-Driver searches all allocated CA-Driver procedure librarieslooking for a matching procname (procedure name). If that procedure name is found in aprocedure library, CA-Driver expands the procedure and passes back a set of expandedstatements to the job stream one statement at a time instead of passing back the // EXECprocname or // EXEC PROC=procname statement. If the procedure name is NOT foundin a CA-Driver procedure library, the statement is passed back to the job streamunchanged. Thus, CA-Driver procedure calls can be embedded anywhere in the jobstream.

The allocation of CA-Driver procedure libraries is normally determined by theCARPROC DD statement. However, this allocation may be altered for JCL in anydefined CA-7 JCL library. If the definition of the CA-7 JCL library includes a referenceto a CA-Driver procedure library, that procedure library is searched prior to the librariesin the CARPROC concatenation when CA-Driver is invoked for JCL from that JCLlibrary. For additional information on associating a CA-Driver procedure library with aCA-7 JCL library, refer to the discussion of the DPROC keyword on the JCL initializa-tion file statement in the CA-7 Systems Programmer Guide or the discussion of the theDPROC 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 notbe reflected in the job's queue JCL.

2. If the SASSXX02 user exit is being used, it will receive the JCL statements afterthey 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 jobenters the queues (prior to submission). Therefore, any statements inserted orchanged are available to CA-Driver.

4. All scheduled overrides (such as #JI and #XO) are applied prior to CA-Driver invo-cation.

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 statementsnow use a prefix of D, as in DIF and DSET. If MVS is running below SP4, then theold statements (IF, SET) are also supported. Starting with MVS SP4, the old state-ments are ignored.

The statements that have changed are:

Computer Associates strongly recommends use of the new syntax.

Old syntax New syntax

ABORT DABORT

FLUSH DFLUSH

GOTO DGOTO

IF DIF

LCTR DLCTR

NEST DNEST

SET DSET

STEP DSTEP


4.2 JCL Verification

4.2 JCL Verification

The CA-7 interface with CA-Driver is invoked at job submission time. It is also invokedwhen 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 commandenvironment. For example, the value of &C_L2JN will be the job name defined in theCA-7 database if evaluated in LJCK processing. If CA-Driver is invoked using the JCLLeditor subcommand, the value of &C_L2JN is the character string UNKNOWN becausethe job name is unavailable when the command is entered. Use these commands toverify that CA-Driver is modifying JCL appropriately. Refer to the CA-7 CommandsGuide for information on the LJCK command. You can find details on the use of JCLLand other CA-7 editor subcommands in the "Edit Facility" chapter of the CA-7 DatabaseMaintenance Guide.


4.3 Procedure Library


The CA-Driver procedure library is a standard OS partitioned data set. Therefore, youcan 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 asthe first statement in the procedure. The contents of the procedure consist of all thestatements following the DPROC statement. When a procedure is called (retrieved fromthe 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 state-ment. This name must be 1-8 alphanumeric characters, beginning with an alpha ornational 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 EXECstatement 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 JOB ,JOHN.DOE,CLASS=A

//LIST1 EXEC PQM=IEHLIST

//VOL DD UNIT=SYSDA,VOL=SER=VSIAUX,DISP=SHR

//SYSPRINT DD SYSOUT=V

//SYSIN DD :

//CALL EXEC PROC=LVTOC

//



CA-Driver replaces the EXEC statement with the contents of the procedure and submitsthis expanded job stream to JES for execution.

//LIST JOB ,JOHN.DOS,CLASS=A

//LIST1 EXEC PGM=IEHLIST



//SYSIN DD :

LISTVTOC 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 theexpanded job stream which is submitted to JES.

� If there is no member of the CA-Driver procedure library by the name specified onthe EXEC statement, the search passes to the OS procedure library. (This is whatwould happen if the EXEC statement misspelled LVTOC as LVTIC.)

� If CA-Driver detects any error conditions during its expansion, a DERR statementwith an appropriate error message passes to JES. This is then flagged as an invalidstatement 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. Whenthe 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 (espe-cially data tables) as separate procedures. These procedures can then be retrieved, asneeded, by nesting them in other procedures. If one of these separate procedures needsmodification, you only need to make the changes to that one procedure. When the proce-dure is called by another procedure, the updated version is automatically retrieved; so theexpanded 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 isnested in the LVTOC procedure.

//LVTOC DPROC




//SYSIN DD :

// DNEST LVTOCS

//LVTOCS DPROC


When the LVTOC procedure is retrieved, it calls the LVTOCS procedure which is nestedin it. Therefore, this sample job stream calls both procedures.

//LIST JOB ,JOHN.DOS,CLASS=A


//

The EXEC statement is replaced by the contents of both procedures and this job stream issubmitted to JES for execution.





//SYSIN DD :


//

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 andfor 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 youwant expansion to stop.

// DATA

CA-Driver will replace the DATA statement with the statement(s) that follow the EXECstatement in the input job stream. When CA-Driver reaches a DEND statement, it returnsto the procedure and continues expansion.

For example, we could have designed procedure LVTOC so that the LISTVTOC state-ment 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 thesame point.

//LVTOC DPROC




//SYSIN DD :

// DATA

Then we include the LISTVTOC statement on the input job stream followed by a DENDstatement.




// DEND

//

When the procedure is expanded, the LISTVTOC statement replaces the DATA state-ment.

You can use any number of DATA statements in a procedure. Each DATA statementdirects CA-Driver back to the job stream until a DEND statement is found. Therefore, ifa job procedure contains three DATA statements, the job stream submitted for processingmust contain three DEND statements. Variable parameters must be within the DPROCand 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 appropriateplaces, you can use a verification name on each DATA statement and the same name onthe DEND statement which terminates that data.

// DATA LVTOCX

// DEND LVTOCX

If the name on the DATA statement and the name on the DEND statement are not thesame, CA-Driver flags the condition as an error. The verification name must be 1-8alphanumeric characters, beginning with an alpha character, and does not have to relate tothe name of the procedure.

This example shows the same procedure with a data verification name.

//LVTOC DPROC


//VOL DD UNIT=SYSDA,VOL=SER,VSIAUX,DISP=SHR


//SYSIN DD :

// DATA LVTOCX

The same verification name is coded on the DEND statement which signals the end ofthe data inclusion statements.




// DEND LVTOCX

//


4.4 Variable Parameters


A procedure in the CA-Driver library may contain up to 64 symbolic parameters. Adefault value may be defined for each parameter when the procedure is created. Whenthe procedure is expanded, each parameter is replaced by its default value or by a valueon the EXEC statement which calls the procedure. (If no default value is defined, avalue 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 procedureis created, with or without a default value. (See 4.4.1, “Coding Variable Parameters” onpage 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 ofthe procedure. When the procedure is expanded, CA-Driver replaces each occurrence ofthe 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 defaultvalue.

//LVTOC DPROC VOL=335?,ID=VSIAUX




//SYSIN DD DD :

LISTVTOC VOL=&VOL=&ID,FORMAT

If this procedure is called with no supplied values:




It is expanded with the default values inserted in the body of the procedure in place of&VOL and &ID.




//SYSIN DD :


//

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.




//SYSIN DD :


//



4.4.1 Coding Variable Parameters

Up to 64 variable parameters may be defined for each procedure. Each parameter mustbe named on the DPROC statement when the procedure is defined. The name must befrom one to seven alphanumeric characters (A-Z,0-9), beginning with an alphabetic char-acter. The underscore character (_) is also acceptable except in the first character posi-tion. However, we recommend that you do not use the underscore character in a variablename defined on the DPROC statement so that you avoid conflicts with reserved-namevariable 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 quotesor other special character delimiters like apostrophes or slashes. (The followingcannot be delimiters: spaces, commas, periods, ampersands, plus or minus signs.)

� If the value contains only alphanumeric characters, delimiters are optional.

Examples:

//LVTOC DPROC VAR1=YES

//LVTOC DRPOC VAR2='A B C'

//LVTOC DPROC VAR3=/JOHN'S/

//LVTOC DPROC VAR4=

In the first example, the default value for VAR1 is YES. Since this consists only ofalphanumeric characters, no quotes or other delimiters are needed. In the secondexample, VAR2 has a default value of A B C. Since this contains spaces, it must beenclosed in quotes or other delimiters. In the third example, the default value for VAR3is JOHN'S. Since this character string contains a quote, a special character other than aquote must be used as a delimiter. In this example, a slash (/) is used. In the fourthexample, 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 givenon the calling EXEC statement. (If values are given in both places, the value on theEXEC statement overrides the defined default value.)

Values supplied on the calling EXEC statement are coded the same way as defaultvalues:

� If the value contains other than alphanumeric characters, delimiters are required.

� If the value contains only alphanumeric characters, delimiters are optional.

Examples:

//CALL EXEC PROC=LVTOC,VAR1=NO

//CALL EXEC PROC=LVTOC,VAR2='D E F'

//CALL EXEC PROC=LVTOC,VAR3=/MARY'S/

//CALL EXEC PROC=LVTOC,VAR4='REPLACEMENT VALUE'

Multiple variable parameters may be listed one after the other, separated by commas. Tocontinue an EXEC statement to the next line, end the first line with a completed param-eter, including the separation comma. Code the second line with slashes in columns 1and 2, and the additional parameters beginning in column 16 or before.

Examples:

//CALL EXEC PROC=LVTOC,VAR1=NO,VAR2='D E F',VAR3=/MARY'S/

//CALL EXEC PROC=LVTOC,VAR1=NO,VAR2='D E F',VAR3=/MARY'S/,

// VAR4='REPLACEMENT VALUE'

All variable parameters must be given a value before they are used. If a value is notspecified 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 ofthe procedure. (Never use an ampersand on the DPROC or EXEC statements.) It is theampersand that signals CA-Driver to replace the variable parameter with a value. Forexample, assume the default value FILE has been defined for the variable parameterVAR1.

This statement in the procedure will be expanded as:

//&VAR1 DD DSN=DATA.SET //FILE DD DSN=DATA.SET

//SYSUT1 DD DSN=DATA.&VAR1 //SYSUT1 DD DSN=DATA.FILE

If the variable parameter is followed immediately by an alphanumeric character, it mustbe terminated by a period in the procedure. If the variable parameter is to be followed bya period after replacement, it must appear in the procedure followed by two periods. Forexample:

This statement in the procedure will be expanded as:

//SYSUT1 DD DSN=&VAR1.DATA //SYSUT1 DD DSN=FILEDATA

//SYSUT1 DD DSN=&VAR1..DATA //SYSUT1 DD DSN=FILE.DATA

A variable parameter is NOT preceded by an ampersand when it is the object of a DSETstatement (that is, a value is being assigned to it), or the FIRST object of a DIF state-ment.

// DSET VAR1=&VAR2 will assign VAR1 the contents of VAR2

// DSET VAR1=VAR2 will assign VAR1 the string 'VAR2'

// DIF VAR1 EQ &VAR2 GOTO STEP will compare the contents of VAR1 and VAR2

// DIF VAR1 EQ VAR2 GOTO STEP will compare the contents of VAR1

with the string 'VAR2'



4.4.1.4 Using Variable Parameters In Nested Procedures

Variable parameters may be passed from a calling procedure to a nested procedure. Todo this, the variable parameter must be defined in each procedure using either the sameparameter name or different parameter names. For example, a nested procedure beingpassed a parameter from a calling procedure could be created as:

//LVTOC DPROC VAR1=YES

.

.

.

// DNEST LVTOCS,VAR2=&VAR1

//LVTOCS DPROC VAR2=

The calling procedure defines VAR1, and the nested procedure defines VAR2.



4.4.1.5 Shifting During Expansion

During variable parameter substitution, the substitution character string may be shorter orlonger than the parameter name. CA-Driver shifts the character string during procedureexpansion according to these guidelines:

� If the replacement character string is shorter than the variable parameter (includingthe ampersand and concatenation character, if present), the character string will beshifted left the number of bytes that the replacement character string is shorter thanthe variable parameter. This shift will continue until a string of two or more spacesis encountered, at which point the shift will terminate. As a result, these spaces willbe increased by the number of bytes that the variable parameter exceeds the replace-ment character string.

� If the replacement character string is longer than the variable parameter, all followingbytes will be shifted right by the number of bytes that the replacement characterstring is longer than the variable parameter. This shift will continue until a string ofspaces long enough to contain the number of characters shifted, plus one blank, isencountered 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 ormore character strings may also be shifted right if the number of spaces betweenthem is sufficient to contain the number of characters shifted and still leave onespace.

In these examples, the variable parameter &F has a replacement value of FILE and&DATASET has a replacement value of DSN.

Original stmt: //&F DD DSN=PAYROLL.MASTER COMMENT

Expanded stmt: //FILE DD DSN=PAYROLL.MASTER COMMENT

Original stmt: //INP DD DSN=&DATASET..XYZ COMMENT

Expanded stmt: //INP DD DSN=DSN.XYZ COMMENT

Original stmt: //INP DD DSN=MASTER.&F..INPUT COMMENT

Expanded stmt: //INP DD DSN=MASTER.FILE.INPUT COMMENT

Note: Computer Associates does not recommend the use of sequence numbers or extra-neous data such as comments on lines containing variables in CA-DriverDPROCs. 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 referenceanywhere that a variable parameter can be referenced in a CA-Driver procedure. Valuesare automatically assigned by CA-Driver when the reserved-name variable parameter isreferenced during procedure expansion. These reserved-name variable parameters cannotbe defined in a DPROC statement, and assigned values cannot be changed using theDSET statement. All reserved-name variable parameters begins with &C_ to avoid con-flicts 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 byCA-Driver:

Example

This example procedure uses four of the CA-Driver reserved-name variable parameters.

Parameter Contents

&C_DATE Current system date in mm/dd/yy format

&C_JDATE Current system Julian date in yyddd format

&C_TIME Current system time in hhmmss format

&C_DAY Current day of the week (MONDAY, TUESDAY, ...)

&C_MONTH 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 useof variables described in the following table:

Note: All values for the CA-7 reserved-name variables are derived from JQREC for theCA-7 submitted job, unless CA-Driver is invoked from LJCK in which case somevalues are determined from database information.

Parameter Contents

&C_L2JN Name of CA-7 scheduled job

&C_L2UID UID of CA-7 scheduled job

&C_L2MID MAINID value for CA-7 scheduled job

&C_L2SN SYSTEM name of CA-7 scheduled job

&C_L2QN Name of queue where CA-7 scheduled job residesValue is REQUEST on LJCK displays.

&C_L27# CA-7 job number for CA-7 scheduled jobValue is 00001 on LJCK displays.

&C_L2LT LTERM value for CA-7 scheduled job

&C_L2RO RO value for job level COND-CODE test

&C_L2CC Value for job level COND-CODE test

&C_L2PRY PRIORITY value for CA-7 scheduled job

&C_L2CLS CLASS value for CA-7 scheduled job

&C_L2SID SCHEDULE-ID value for CA-7 scheduled jobValue supplied from SCHID keyword on LJCK displays.

&C_L2#T1 Number of TAPE1 tape drives for CA-7 scheduled job

&C_L2#T2 Number of TAPE2 tape drives for CA-7 scheduled job

&C_L2EM Entry mode for CA-7 scheduled job, such as DEMAND or RUN.Value is SSCAN on LJCK displays.

&C_L2DOD Due-out date for CA-7 scheduled job (YYDDD)

&C_L2DOT Due-out time for CA-7 scheduled job (HHMM)

&C_L2DLD Deadline date for CA-7 scheduled job (YYDDD)

&C_L2DLT Deadline time for CA-7 scheduled job (HHMM)



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 theJCL 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 entirevalue. To do this, specify two numbers in parentheses following the parameter name.

&parmname(n,m)

Where:

nIs the location within the value of the start of the substring.

mIs the length of the substring (one or more bytes).

These examples show how the two numbers identify the substring that is being refer-enced.

Substrings can also be identified by variable parameters that represent numbers. This isillustrated below.

Parameter Value Substring reference Substring value

&VAR1 HOWDY &VAR1(1,2) HO

&VAR1 89 &VAR1(2,1) 9

Parameter Value Substring reference Substring value

&VAR2 4

&VAR3 2

&VAR4 12/31/00 &VAR4(&VAR2,&VAR3) 31



These sample control statements show how procedure expansion can be based on the con-tents of a substring, rather than on the entire parameter value:

This control statement References a substring in order to

// DIF C_DATE(1,2) NE 01 GOTOMONTHERR

Test only the month portion of the datevalue (1st and 2nd positions)

// DIF C_DATE(3,1) NE '/' GOTOERROR

Check for a slash in the date (3rd posi-tion)

// DSET VAR1=&C_DATE(7,2) Set VAR1 equal to year portion of datevalue (7th and 8th positions)

// DIF VAR1(&VAR2,&VAR3) EQ 9GOTO OK1

Test only part of VAR1 (VAR2 andVAR3 represent numbers)



4.4.4 Arrays

A variable parameter can be assigned multiple values or array elements. To indicate thata parameter has an array of values, give the total number of values in parentheses fol-lowing the parameter name on the DPROC statement. For example, VAR(4) indicatesthat a parameter has four values. When this procedure is expanded, each of these fourvalues 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 sepa-rated by commas in the order of the array elements. To omit a default value, code acomma 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 whichhave default values.

� A parameter named Y, which consists of three elements in an array, each of whichhas 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 ofwhich has a default value (TESTJOB).

To supply array values on the calling EXEC statement, list the values, enclosed in paren-theses 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 ele-ments would retain their default values. (These default values must be defined when theprocedure is created.)



4.4.5 Null Values

You must supply a value for every variable parameter listed on the DPROC statement orelse the procedure cannot be expanded. However, this value may be a null value. A nullvalue may be used either as the default value when the procedure is created or as theoverride value when the procedure is called. To specify a null value on either theDPROC 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 Yparameter. The value for the third element is a null value. (If the default value werereally 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, thestatement 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 issupplied. For example, assume that the parameter Y was defined with a null defaultvalue. No override value is supplied when the procedure is called. When the procedureis expanded, each occurrence of Y is replaced with a null character string; therefore, Y iseffectively removed from the expanded statement as these examples show.

This statement in the procedure: will be expanded like this:

//SYSUT1 DD DSN=&Y.FILE.DATA //SYSUT1 DD DSN=FILE.DATA

//SYSUT1 DD DSN=FILE&Y //SYSUT1 DD DSN=FILE

A null value is different from having no value associated with a variable parameter. If aparameter has no default or override value, an error message is issued indicating that theprocedure cannot be expanded.



4.4.6 Attributes of Variables

Every variable parameter has two attributes: type and length. Variable parameter arraysalso have a third attribute: number. Each of these attributes can be tested during condi-tional expansion using the following format:

To test for Specify

Type T'parmname

Length L'parmname

Number 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. (Thetype is determined by the actual replacement value, not by the defined value or how thevalue was stated.)

If the replacement value is The type is

A character format C

A positive integer N

A negative integer M

Omitted (not the same as a null value) O

4.4.6.2 Testing the Type Attribute

To test a variable parameter for type, prefix it with T'.

// DIF T'VAR1 EQ C GOTO CHARVALU

// DIF T'VAR2 EQ N GOTO ISNUMERC

Since variable parameters that are used in array indexing and segment subscripting mustbe positive integers (type N), it is a good idea to test the type attribute of a variableparameter 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 bytesin the replacement value.

If the replacement value is The length is

CA-Driver 9

X 1

0049 4

(null) 0

27 2

4.4.6.4 Testing the Length Attribute

To test a variable parameter for length, prefix it with L'.

// DIF L'VAR3 EQ ? GOTO NOVALUE (zero length - null value)

// DIF L'VAR4 GT 4 GOTO TOOLARGE



4.4.6.5 The Number Attribute

The number attribute gives the number of elements in a variable parameter array thathave values assigned to them, regardless of whether the value was assigned by default oron the DPROC statement. For example, assume the procedure XYZ was created with thefollowing statement:

//XYZ DPROC Q(8)=(A,B,C,,,,J)

If it is retrieved with an EXEC statement containing no override values, the number attri-bute 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 thefourth 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 N'VAR6 LT 1 GOTO NOVALUES

// DIF N'VAR7 EQ 5 GOTO DONEALL


4.5 Functions

4.5 Functions

CA-Driver also recognizes a set of predefined functions. A CA-Driver function has areserved 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 parameterscontaining valid values that the function expects. In either case, parameters values mustbe 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 avariable 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 variableVAR1. (All month end and leap-year adjustment is automatically handled by theDTADD 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 JCLstaging and manual manipulation. Because all of the functions have parameters whichaccept or default to CA-Driver variable parameters, the power of the functions and thevariable parameters can be combined.

The functions perform more than simple arithmetic operations because they take intoaccount transitions between months, years, and periods so that they return the expectedvalues.


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, monthend, and year end adjustments are automatically handled by CA-Driver.

Function and parame-ters

Explanation

DTADD(n,&var) Adds "n" to variable "&var." The variable &var must contain a valid Julian date inthe yyddd format. n represents a number of days to be added to &var and may bea 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 Juliandate 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 positivenumeric value.

Example: If &C_JDATE=00005, DTSUB(8,&C_JDATE)=99363

DTDIF(&var1,&var2) Subtracts variable "&var2" from variable "&var1." The variables &var1 and &var2must 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 inthe yyddd format. n represents a number of months to be added to &var and maybe 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 Juliandate 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 positivenumeric 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, monthend, and year end adjustments are automatically handled by CA-Driver.

Function and parameters Explanation

DMY(&var) Converts variable "&var" into ddmmyy format. The variable &var mustcontain 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 mustcontain 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 mustcontain 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 mustcontain 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 mustcontain 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 mustcontain 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 mustcontain 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 mustcontain 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 mustcontain a valid Julian date in the yyddd format.

Example: If &C_JDATE=00032, YM3D(&C_JDATE)=00FEB01


4.5 Functions


DM3YR(&var) Converts variable "&var" into ddmonccyy format. The variable &var mustcontain 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 mustcontain 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 mustcontain 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 yydddformat.

Example: If &C_JDATE=00032, DAY(&C_JDATE)=MONDAY

MONTH(&var) Converts variable "&var" into the month name (JANUARY, FEBRUARY, andso on). The variable &var must contain a valid Julian date in the yydddformat.

Example: If &C_JDATE=00032, MONTH(&C_JDATE)=FEBRUARY

MON(&var) Converts variable "&var" into a three character abbreviation of the monthname (JAN, FEB, and so on). The variable &var must contain a valid Juliandate 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). Thevariable &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 theweek name (SUN, MON, and so on). The variable &var must contain a validJulian 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 soon). The two-digit numbering begins with Sunday (01). The variable &varmust contain a valid Julian date in the yyddd format.

Example: If &C_JDATE=00032, DOW#(&C_JDATE)=02


4.5 Functions


WOM(&var) Converts variable "&var" into a two digit week of the month (01, 02, 03, andso on). The variable &var must contain a valid Julian date in the yydddformat. 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 soon). 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, andso on). The variable &var must contain a valid Julian date in the yydddformat. Since the weeks are defined from Sunday to Saturday, the first weekmay 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 soon). 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 onlycontain 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 returndates or portions of dates by counting a specified number of days forward from thebeginning 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 areuseful for coding procedures that require a date which is always a certain number of daysfrom the beginning or end of the month such as a billing date that is constantly on the10th day of the month.

Function and parame-ters

Explanation

LDOM(n,yyddd) Returns the day-of-month number by counting n days backwards from the end ofthe month of the Julian date (yyddd) specified. Counting begins at 1 on the lastday of the month. (n=1 returns the last day of the month.) If yyddd is not speci-fied, the default is the current &C_JDATE value. n should be in the range of 1-31.

Example 1: LDOM(2,00025)=30Example 2: LDOM(2,00045)=27

JDOM(n,yyddd) Returns a Julian date by counting n days from the beginning of the month of thethe Julian date (yyddd) specified. Counting begins at 1 on the first day of themonth. (n=1 returns a Julian date representing the first day of a month.) If yydddis not specified, the default is the current &C_JDATE value. n should be in therange of 1-31.

Example 1: JDOM(2,00025)=00002Example 2: JDOM(2,00045)=00033

LJDOM(n,yyddd) Returns a Julian date by counting n days backward from the end of the month ofthe Julian date (yyddd) specified. Counting begins at 1 on the last day of themonth. (n=1 returns a Julian date representing the last day of a month.) If yydddis not specified, the default is the current &C_JDATE value. n should be in therange of 1-31.

Example 1: LJDOM(2,00025)=00030Example 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 valuessupplied on the EXEC statement.

These commands are available to program conditional procedure expansion.

Code the commands in control statements like the following:

To Use thiscommand

Assign a name to a control statement DSTEP

Branch to a step DGOTO

Define conditions for branching DIF

Set variable parameters DSET

Control looping DLCTR

Flush all calling procedures DFLUSH

Abort current procedure DABORT

//name command operand(s)

name is an optional user-defined value given to a control statement so that it can bereferenced 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 controlstatement 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 bedefined in each procedure.

4.6.1.1 Examples

//ONE DSTEP

//DAILYRUN DSTEP

//STEP1 DSTEP

//1 DSTEP

4.6.2 Branching (DGOTO)

Use the DGOTO command to stop procedure expansion, branch forward or backward toanother control statement, and continue expansion at that point.

//name1 DGOTO name2

4.6.2.1 Examples

//name DGOTO ONE

//name DGOTO DAILYRUN

//name DGOTO STEP1

//name DGOTO 1



The following example demonstrates how to use DSTEP and DGOTO statements torestart an abended job stream at step three instead of step one. To do this, the procedureis defined with a variable parameter called RESTART which has a default value ofSTEP01.

//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


// DD ...

// DD ...

//STEP?3 DSTEP

//: STEP STEP?3


// DD ...

If a restart is necessary, an overriding value is supplied for the RESTART parameterspecifying 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 selectionstop 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 DIFcontrol 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 state-ment.

At this point Specify this value

name1 An optional name for this control statement which allows it tobe referenced in other DIF or DGOTO statements.

parmname A variable parameter which was defined on the DPROC state-ment when the procedure was cataloged.

operator The relationship between the parameter and the value as oneof these operators: LT, GT, EQ, NE, GE, or LE. Thesymbols =, <, > may be used instead of EQ, LT and GT.

value A character string against which to test the variable parameter.It may be from 1-64 characters in length and must be delim-ited by quotes or some other special character if it containsother than all alphanumeric characters. (If this characterstring is a different length than the value of the parameter, thelength of the parameter value is used.) This can also be avariable.

name2 The name of another control statement that is to be branchedto if these conditions are met.

4.6.3.1 Examples

// DIF VAR1 EQ YES GOTO STEP1

// DIF VAR2 NE 'DAILY RUN' GOTO MONTHLY

// DIF VAR3 LE 99 GOTO TESTOK

// DIF SIZE GT 12? GOTO TOOLARGE



The following example demonstrates how conditional procedure expansion selects dif-ferent job steps from a large procedure, depending on the day of the week. The reservedvariable C_DAY is used to inform the procedure of the day of the week. The procedureis 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


// 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


// 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 conditionalexpansion. Code the name of the parameter and the new value in this format with nospaces after the parameter name.

//name DSET parmname=value

The value may be one of these:

� An integer, either positive or negative.

// DSET VAR1=4 (positive value is assumed)

// DSET VAR=+22 (positive value may be explicit)

// DSET VAR=-3 (negative value must be explicit)

� The result of an arithmetic expression using integer values and arithmetic operators(+, -, *, /).

// DSET VAR1=4-2

// DSET VAR1=8+7

// DSET VAR1=4:3

// DSET VAR1=8/4

� A character string.

// DSET VAR1=NO

// DSET VAR1='A CHARACTER STRING'

� The value of another variable parameter.

// DSET VAR1=&VAR2



� The result of an arithmetic expression using two variable parameters or one variableparameter and an integer. (Variable parameters used in arithmetic expressions musthave numeric values associated with them, rather than character values. The resultsof all arithmetic operations are truncated to provide only integer results.)

// DSET VAR1=&VAR1+1

// DSET VAR1=&VAR1+&VAR2

// DSET VAR1=&VAR2-&VAR3

// DSET VAR1=&VAR2:&VAR3

// DSET VAR1=&VAR2/2



4.6.5 Controlling Loops (DLCTR)

As a result of backward step branching during procedure expansion, procedure expansioncan enter a loop. CA-Driver automatically terminates procedure expansion when any stepname is referenced more than 16 times. To override the default value of 16 step refer-ences, use the DLCTR command and specify a number.

//name DLCTR n

The number you specify (n) is the maximum number of times any one step may bebranched to. If any step is referenced n+1 times, an error message is produced and pro-cedure expansion is terminated.

4.6.5.1 Examples

// DLCTR 4

// DLCTR 9?

// DLCTR 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 theremainder 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. Callingprocedures 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 procedureand 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 insideCA-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 notappear in any displays where the procedure is expanded.

The DPROCCOM keyword on the OPTIONS statement in the CA-7 initialization filecontrols the use of comments inside CA-Driver procedures. The default isDPROCCOM=NO. All CA-Driver procedure statements beginning with '//*' are subjectto 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 beginwith a character string other than '//*' then that string may be coded as a value on theDPROCCOM keyword. The value must not exceed eight bytes and should not includeblanks 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 -- SomeExamples

4.8.1 Conditional Execution Based on Schedule ID

You can use the &C_L2SID reserved name variable parameter to modify a parameter fora job. For example, by convention schedule ID 001 indicates that the job should run witha parameter of MONTHLY, schedule ID 002 is associated with a parameter ofWEEKLY. 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 DPROC RUNTYPE=,VAR(4)=(MONTHLY,WEEKLY,DAILY,OTHER),HOLDSEL=

// DSET HOLDSEL=&C_L2SID

// DIF HOLDSEL LE 3 GOTO DOIT

// DSET HOLDSEL=4

//DOIT DSTEP

// DSET RUNTYPE=&VAR(&HOLDSEL)

//STEPNAME EXEC PGM=USERPGM,PARM=&RUNTYPE


Chapter 5. NCF

This chapter defines the purpose and basic requirements for CA-7 NCF (Network Com-munications Facility) and describes the primary components of the system. Functionaldescriptions 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 routeCPU jobs (and their products) to some other data center(s) for processing, printing, andso forth. Generally these data centers are widely dispersed geographically. They may belocated very close to each other, however. In any case, routing of jobs is performed byJES over a communications link between the data centers. This is accomplished with JEScontrol statements included within the JCL for the job.

IBM provides a Network Job Entry (NJE) facility within JES to handle the routing ofjobs to be processed at another data center. NJE also routes any print or punch output towhatever location the user wishes to perform that function. Printing and punching of joboutput 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 asscheduling, prerequisite verification, job submission, and so forth, based on SMF data. Inan NJE environment, as in all environments, SMF data is only produced at the locationwhere job execution occurs. CA-7 may or may not be installed at that location. SMFdata must, however, be returned to the CA-7 which originally submitted the job if CA-7is to be able to track the job.

CA-7 NCF, an optional component of CA-7, provides the software required to allow theuser to fully use all workload management facilities of CA-7, whether some jobs areprocessed on an NJE basis.

With NCF, jobs submitted by CA-7 may execute at any site within a network of sites justas if the site were a local CPU. NCF ensures that the CA-7 which submitted a jobreceives 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. TheJCL for any such job must, however, contain the JES statements necessary to cause JESto route the job to the desired location after it has been submitted by CA-7. When exe-cution does occur, CA-7 performs its functions related to the job just as if the job exe-cuted in an initiator on a local CPU. This transparency to both CA-7 and the productionuser 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 CPUwhere these jobs are to execute. CAIRIM plus the CA-7 SMF interface exits and SVCinterface 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) atall 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 flowbetween 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 thateliminate the need for preinstalled user SVCs, SMF interface exits, subsystems, and otherinstallation requirements commonly encountered when installing systems software. Theseroutines are grouped under the service code S910, which is one of the Unicenter TNGFramework for OS/390 Common Services.

CA-7 uses the CAISMFI Dynamic SMF Event Interceptor (which is a subcomponent ofCAIRIM), so SMF recording must be active in the system for any SMF event or datahandling product routines. The CAIRIM SMF Interceptor component does not requireany 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 origi-nating node ID. The CA-7 UJV SMF interface exit preserves this ID in either the ReaderDate or SMF User ID fields depending on which location the user designates, inICMDSECT, for this purpose.

The CA-7 SVC, when called by the CA-7 SMF interface exits, uses this node ID toidentify the CA-7 location which submitted the job and to which all SMF data for the jobshould be returned. The originating CA-7 node ID is used to distinguish between datawhich should be retained locally and that data which should be routed back to CA-7 atsome other node.

The CA-7 SVC interface obtains data from the CA-7 SMF interface exits and the CA-7trailer or U7SVC programs and transfers this data across address spaces for subsequentprocessing by ICOM. The SVC interface and SMF interface exits must be installed at allsites for NCF processing to occur.

Although the execution location must generate the necessary SMF record types to satisfyCA-7 requirements, the data need not be also written to the SMF MANX/Y data setsunless the user so desires. This data which occurs at the execution site is available at theoriginating CA-7 site for logging into the CA-7 log data set in standard CA-7 log recordformat.



5.3.3 ICOM

All ICOMs that run in an NCF environment must have the NCF modules available (forexample, STEPLIB) and an extra DD statement pointing to the NCF communications dataset. This is an extension of the standard CA-7 ICOM program. It must be installed ateach node. It processes data for local and remote records by extracting data from theSVC interface and writing local records to the CA-7 communications data set and remoterecords to the NCF communications data set.

Data received through VTAM at an originating node is routed through the SVC interfaceand 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 mayexist in any one network. Each NCF node corresponds to a JES NJE node on aone-to-one basis. UCC7NODE is the required name for the node table. Generation ofthe node table is accomplished with the UNCNOD macro as discussed in the VTAM andNCF 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 uniqueVTAM identifier (ACBNAME) as specified in a VTAM APPL definition. Each site musthave its own table.

For a successful communications link to be established between the NCF VTAM tasks atany two nodes in the network, a validation of the two node tables is automatically per-formed at "bind" time. A discussion of this validation procedure is included in theVTAM 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, anentry is created in the unknown node table dynamically by the NCF VTAM task. AnySMF or trailer data for such nodes are written to the undeliverable queue besides creatingan entry to this table.

Unless the user changes the node table while jobs are executing at a remote node in thenetwork, no unknown nodes should ever occur.

If the unknown node table becomes full, a warning message is issued and any new unde-liverable data is dropped.

Data in the undeliverable queue for an unknown node may be purged with the PURGEcommand. Any reoccurrence of data for this unknown node is also written to the unde-liverable 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 collectionat each node in the network. It contains SMF and CA-7 trailer data for jobs submittedfrom a remote node. This file must exist for NCF processing to occur. This data set hasa 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 notdefined in the node table. Any data which cannot be transmitted due to communicationinterruptions 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 newdata is lost. A progressive series of warning messages are issued beginning when the filethreshold (80 percent) is reached and continuing until the percentage used drops belowthe threshold value.

5.3.8 NCF VTAM Application Program

The NCF VTAM application program receives and transmits CA-7 NCF data betweennodes in the network. This program receives control once VTAM and the NCF VTAMapplication 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 toNCF 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 byICOM 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. Fortesting purposes, the EXEC statement for the NCF VTAM task should be changed toinclude two additional PARM values. The PARM value TEST indicates that the installa-tion test is being performed. Another PARM value, TABLE=member may be used toidentify a node table to be used for this test. This node table name does not have to beUCC7NODE, but may be if desired. The coded PARM value for this test would besimilar to the following example:

PARM=('TIME=3???',TEST,'TABLE=UCC7NODB')

Note: The installation test parameters TEST and TABLE are not valid for use in anormal production environment.

To test the establishment of a session between two or more NCF nodes, The TEST andTABLE parameters may be used to execute two or more nodes on a single machine. TheVTAM APPL definitions must be correctly coded to allow a local-LU to local-LUsession.

To test data transmission between two nodes, a data generator program is supplied whichcan be executed with the following JCL:

// EXEC PGM=SASSNCDG,PARM='TABLE=xxxxxxxx'

//STEPLIB DD DISP=SHR,DSN=user load library

//UCC7NCFD DD DISP=SHR,DSN=user defined NCF communications data set

//SYSIN DD DUMMY,BLKSIZE=8?

The TABLE parameter should specify the same table used by the NCF VTAM applica-tion program which is to transmit the data. Sample data is generated, according to thistable, for transmission to all remote nodes. The SYSIN DD statement is required andshould always be coded as shown in the JCL above unless otherwise directed by Com-puter 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 shouldreinitialize the ICOM communications data set (COMMDS), the NCF communi-cations data set (COMNCF), and the NCF undeliverable queue (UNDQUE). Thiswill 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 NCFis incorporated in the CA-7 Getting Started guide. The information in this topic is pro-vided to allow you to effectively plan the installation of CA-7 NCF. Installation require-ments for sites which are not running CA-7 are slightly different from those for siteswhich are running CA-7.



5.4.1 General Notes

Terminology: The following terminology is used throughout this chapter and the CA-7Getting Started guide and helps distinguish between environments.

NCF Network Communication Facility, a component of CA-7. Also refersto the VTAM application program used to pass certain CA-7 data fromsite to site.

NCF Complex Used to refer to all the sites connected by NCF.

NCF1 A site that runs CA-7 and NCF.

NCF2 A site that runs NCF but not CA-7.

site A node in an NJE network. Consists of one or more CPUs runningwith or without shared spool.

Installation: The following general considerations apply to installation:

� CA-7 must be installed in at least one of the sites in the NCF complex.

� If both CA-7 and NCF are to be installed at a site, first install CA-7 and NCF at theNCF1 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 cannotuse a test copy of CA-7.

� All of the CPUs in the NCF Complex must have the CA-7 SVC and CA-7 SMFinterface exits installed at Version 3.0 or later. ICOM must be run on each CPU inthe 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. Thetime 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 locatedand 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 wherethe jobs are to be run. Also, all sites to which CA-7 submits CA-11 controlled jobsmust use the same procedure name for RMS. The RMS procedure name must be inthe 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 andthe 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 sitethat does run NCF (NCF1 or NCF2) if a LOAD step is included in the JCL. Thisresults in a U0110 abend in the LOAD step. If there is no LOAD step, the job runsbut 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 oper-ating 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, ICOMmust 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 allCPUs that can execute CA-7 controlled jobs. CAIRIM, Computer Associates ResourceInitialization 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 ofnodes in the node table. The following formula should be used to calculate the virtualregion 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 twodata sets used by NCF itself and one data set used by ICOM. Following is a descriptionof the permanent files.

NCF communications data set: The NCF communications data set contains CA-7 for-matted SMF and trailer data to be transmitted to remote nodes. In a multi-CPU site, thisdata set must reside on a shared DASD device. Each CPU in the complex must executea copy of ICOM, each of which shares this data set.

The NCF communications data set is a formatted physical sequential data set with thefollowing characteristics:

DCB=(RECFM=F,BLKSIZE=1?24,LRECL=1?24)

The space required by the NCF communications data set depends on the amount of NCFactivity. A minimum allocation of 900 blocks is recommended.

This data set must be formatted using the SASSNC12 program. Refer to the CA-7 installjob N030 for sample JCL.

Undeliverable queue (UDQ): The UDQ contains CA-7 formatted SMF and trailer datawhich could not be transmitted because communication with a node was interrupted orcould not be established. It also contains data for any nodes encountered during proc-essing which have not been defined in the node table. Unless the user changes the nodetable while NJE jobs are in the JES queue, either locally or remote, no unknown nodeIDs should occur.

The undeliverable queue is a formatted physical sequential data set with the followingcharacteristics:


The space required by the UDQ depends on the amount of NCF activity. No less thanone cylinder is recommended. At least 600 blocks of space should be allocated for eachnode to which data may be transmitted. Experience may show that more space isrequired for a particular site.

This data set must be formatted using the SASSNC15. Refer to the CA-7 install jobN030 for sample JCL.

Chapter 5. NCF 5-13


ICOM communications data set: The ICOM communications data set contains CA-7formatted SMF and trailer data to be processed by the local CA-7. This data set mustreside on a shared DASD device for multi-CPU sites. For NCF1 sites, this data set isallocated and initialized during CA-7 installation.

The ICOM communications data set is a formatted physical sequential data set with thefollowing characteristics:


Space required for the ICOM communications data set at NCF2 sites should be about100-150 blocks (about five tracks on 3380 devices). At NCF1 sites, space is determinedduring 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 ICOMlooping. Refer to the CA-7 Systems Programmer Guide Chapter 3 for additional informa-tion 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-7NCF will execute. This service may have already been installed with another ComputerAssociates 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 aCA-7 environment not only requires the installation of the necessary software at the proc-essing sites, but also requires some production considerations for implementing jobs underCA-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 andmonitor the jobs as if they were executing locally. Even without the support of CA-7NCF, jobs routed to a remote site or node through JES can execute at the desired destina-tion node. CA-7 at the local site or node would, however, be unable to track the jobsautomatically through SMF feedback since all SMF data for the job would occur only atthe remote node at which execution occurred. Using the NCF component software, pro-duction processing may occur at any remote node as if the remote processor and initiatorwere a local initiator.

However, there are implementation considerations for the production user which are crit-ical 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. Thisoption is specified in the JCL PARM field of the EXEC statement for the NCF VTAMapplication program. The option is specified as follows:

PARM

��─ ──PARM= ──┬ ┬─────────────────────── ─────────────────────────────� │ │┌ ┐─????3???─

└ ┘──'TIME= ──┴ ┴─tttttttt─ '

Where:

TIMEIs the duration of the WAIT which is issued by the NCF VTAM application programwhen an attempt to enqueue the NCF communications data set fails. You may needto adjust this parameter to minimize data set contention, especially in an MAS envi-ronment.

This time limit is also used to synchronize the initial LOGON processing during NCFstartup. If all remote nodes have not attempted to LOGON when the limit isreached, a warning message (CA7.NC203) is issued and the remaining LOGONs areallowed to complete asynchronously while normal processing commences. Thisparameter is optional.

00003000Is the default time limit (30 seconds) in one hundredths of a second. Leadingzeros may be omitted.

ttttttttIs the user-specified time limit in one hundredths of a second. Leading zerosmay be omitted.



5.5.1.1 Sample NCF VTAM PARM

The following is a coded example of the PARM for the NCF VTAM applicationprogram:

//NCF EXEC PGM=NCF,PARM='TIME=????25??'

5.5.1.2 Sample NCF VTAM JCL

Following is an example of the JCL for the NCF VTAM task.

//jobname JOB :user job statement specifications:

/:JOBPARM :user specifications:

//:

//NODE1 EXEC PGM=NCF,PARM='TIME=3???'

//STEPLIB DD DISP=SHR,DSN=cai.ca7.cailib


//UCC7SNAP DD SYSOUT=:

//SYSABEND DD SYSOUT=:

//UCC7NCFD DD DISP=SHR,DSN=user defined communications data set

//UCC7NCFU DD DISP=OLD,DSN=user defined NCF undeliverable queue

//:

The UCC7SNAP DD statement cannot have FREE=CLOSE specified.

Chapter 5. NCF 5-17


5.5.2 CA-7 Database

CA-7 NCF provides support for CA-7 jobs that execute at a remote NJE node. Actualexecution may occur at any location within the network of CPUs. The execution locationis essentially transparent to the production control person. However, CA-7 database con-siderations 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 executelocally. 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 aremote site. It is a user responsibility to ensure that the remote node is prepared toprocess the job when it arrives.

Note: The day and time values specified in defining the schedules for the jobs are thevalues used by the CA-7 into which they are defined. For example, consider asituation where site A is in New York and site B is in Los Angeles. Job X is tobe run at site A and is due out at 10:00 AM, New York time. If the job isdefined in the CA-7 database at site B, then the due-out time for the job shouldbe 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 screenare used as they would be without NCF.

All of the fields in the EXECUTION segment have the same meaning except that theMAINID field for an NJE job should, when used, specify a CPU from which JES cantransmit the job to the proper remote node (after CA-7 submits the job to JES). It is stillthe user's responsibility to ensure that the job contains the JCL necessary to cause JES todo 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 insertsthe step which executes CA-11. In these cases, CA-11 must be installed at the locationwhere the job executes.

Fields in the RESOURCES segment of the DB.1 screen apply to resources which must beavailable 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-7initially submits the job to JES. The JCL segment of the DB.1 screen must define wherethe JCL can be found.

Care must be taken also to ensure that any LTERM value specified in the MESSAGESsegment of the DB.1 screen (or in the JCL statement in the initialization file) causesmessages 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 includesthe 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 indica-tors which CA-7 manages. Position 69 must always contain a blank (to prevent JCLerrors) and positions 70 and 71 contain indicator bytes set by CA-7 for execution controlpurposes. These reserved positions in the JOB statement must be reserved in all CA-7controlled 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 state-ments were reserved. To avoid problems when NCF is installed, the user must ensurethat 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 thefollowing control statements:

/*ROUTE/*XEQ

Refer to the IBM publications for a discussion of these statements. When used, thesestatements are located in the local execution JCL library immediately after the JOB state-ment. Once the job is submitted to JES by CA-7, these statements direct JES2 to routethe job to the proper NJE node.

JES2/NJE also supports the /*XMIT control statement. This statement is only docu-mented in the JES2 manual. When used, the name of the job transmitted to the remotenode 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 posi-tioned 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 ofjobs 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 theexecution node as opposed to the submission node. Existence of the programs at theexecution node is a user responsibility.

Cataloged procedures used in NJE jobs must also be located at the site where conversionand interpretation of the cataloged procedures occur.

5.5.3.5 DD Statements

Data definition (DD) statements, besides referencing a data set located at the executionsite, 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 ensurethat production data sets are located at the execution node and, if applicable, are cata-loged correctly. Some production data sets may always be maintained at one site whileothers may be required at more than one site. The user must ensure that the correctversion 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 executionnode.

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 NJEnodes as long as the load modules have been installed at the remote site. These facilitiesinclude:

� 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. Jobsmay be demanded, requirements may be posted, and so forth, by executing these pro-grams at the execution node. Activities which are to be performed by CA-7 as a result ofthe execution of these programs are controlled by CA-7, wherever it resides, based on thefeedback provided by NCF support. Jobs demanded or released by these facilities mayexecute at any node in the network based on the routing which is specified in JES controlstatements within the JCL for the jobs.

5.5.5.1 NCFNODE Parameter

When executing SASSTRLR, SASSBCLP or U7SVC, the EXEC statement may be codedwith a node name in the PARM parameter. This causes the event posting data to berouted to CA-7 residing at the node name specified. If this parameter is not coded, thefeedback 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 nodename must exist in the NCF node table as defined with the NODNAME parameter of theUNCNOD macro. (Refer to the node table assembly discussion in the VTAM and NCFNode Table Definitions appendix of the CA-7 Getting Started guide for further details onnode names.)

5.5.5.2 CA-7 LOAD Process

The LOAD process is performed at the execution site. Data from this process is automat-ically returned to the originating CA-7 site for updating of the CA-7 database. Job char-acteristics in the database reflect the resource and data set information from the executionenvironment. This includes the RESOURCE data on the DB.1 screen, information on theCA-7 cross-reference reports, and all other references to data sets and resources withinCA-7.

Data set requirements and triggers are supported no matter where the job executes. Thedata 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 beeninstalled 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 reini-tialized prior to execution of NCF. See the VTAM and NCF Node Table Definitionsappendix of the CA-7 Getting Started guide for a discussion of the programs provided tosatisfy this requirement.

5.6.2 Establishing Communications

When the system is started, it automatically establishes communications with VTAM andthen 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 becomeactive, 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 nodesspecified in the node table and any unknown nodes encountered during processing. Itindicates whether they are active or inactive and displays activity counts. Status may bedisplayed 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 theUCC7NODE table, is put in the undeliverable queue (UDQ). Data for these unknownnodes remains on the UDQ until communication can be established or until the data ispurged using the PURGE command. If communication is not established with that nodein the near future, it may be desirable to purge its data to prevent the UDQ from beingfilled.

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 commandfollowed by the STOP command. This allows all pending processes to complete andprovide 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 untila positive response has been received. However, duplicate data can be sent because thedata 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” onpage 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 commandwith the exception of the MVS STOP command. The other commands discussed in thistopic require that a MODIFY taskname precede the command text in the followingformat:

��─ ──MODIFY taskname ──,command ──┬ ┬───────── ───────────────────────� └ ┘ ─operand─

The short form of the MODIFY command, F, may be used interchangeably withMODIFY.

The maximum acceptable length for the command [operand] is 36 characters.

Any command which is not syntactically and logically correct will be rejected with themessage:

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 allpending processes.

5.7.1.1 Syntax

STOP

��─ ──STOP jobname ─────────────────────────────────────────────────�

Where:

jobnameIs 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 pendingprocesses and to log off. It terminates communication with VTAM by closing the ACBand freeing all control blocks. The only valid commands after a SHUTDOWN areSTARTUP or STOP. The SHUTDOWN command also issues a STATUS command.

5.7.2.1 Syntax

SHUTDOWN

��─ ──MODIFY jobname,SHUTDOWN ──────────────────────────────────────�

Where:

jobnameIs 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 ofthe 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. Itrebuilds all control blocks, opens the ACB and logs on all nodes.

5.7.3.1 Syntax

STARTUP

��─ ──MODIFY jobname,STARTUP ───────────────────────────────────────�

Where:

jobnameIs 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 onsuccessfully:

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 speci-fied. This is usually done after that node has been logged off. Once the link has beenestablished, any undeliverable data in the UDQ will be sent.

5.7.4.1 Syntax

LOGON

��─ ──MODIFY jobname,LOGON nodename ────────────────────────────────�

Where:

jobnameIs the OS job or task name of the NCF VTAM application.

nodenameIs 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 hascompleted any pending processes, the LOGOFF command will be executed, communi-cations will be terminated and all future data will go to the undeliverable queue until thenode is again logged on. This command can be issued at any node.

5.7.5.1 Syntax

LOGOFF

��─ ──MODIFY jobname,LOGOFF nodename ───────────────────────────────�

Where:


nodenameIs 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 nodespecified in the command. The entire undeliverable queue must be read and processingof the communications data set is suspended until this is completed. Multiple nodes canbe purged only by entering multiple commands.

5.7.6.1 Syntax

PURGE

��─ ──MODIFY jobname,PURGE nodename ────────────────────────────────�

Where:


nodenameIs 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 theSMF data, a PURGE command may require several minutes to completedepending on the volume of records.

This command deletes records that CA-7 uses for tracking jobs. This can resultin some jobs staying in the ready or active queues.

Chapter 5. NCF 5-31


5.7.7 STATUS Command

The STATUS command displays the status of a single node or all nodes. The nodesdisplayed will be those in the UCC7NODE table plus any unknown nodes which wereencountered during processing. The percentage of blocks used in both the NCF commu-nications data set and undeliverable queue is also displayed. Record counts reflect thevolume 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:


Single node:

To display the status of a single node:

STATUS

��─ ──MODIFY jobname,STATUS nodename ───────────────────────────────�

Where:

nodenameIs 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.

b c--------------------- CA-7 NCF VTAM STATUS ----------------------

__NODE__ (ID) _STATUS_ _LUTYP_ _RECV_ _SENT_ _UNDL_ _PURG_

ADL?1?1 (?2) INACTIVE ????57 ????57 ?????? ??????

ACH?2?1 (?3) ACTIVE PLU ???485 ???485 ?????? ??????

nodename (?4) UNKNOWN ?????? ?????? ???146 ??????

NCF QUEUE ..41% USED UND QUEUE ..23% USED

e f

5.7.7.3 Field Descriptions

The following are descriptions of the individual data items displayed for each node:

Item Description

NODE The VTAM APPL ACBNAME of the node whose status information is dis-played. Each unknown node name will be printed on a separate line.

ID The node ID in hexadecimal.

STATUS The status of each node:

ACTIVE Communication is established with this node.

INACTIVE Communication is not established with this node.

UNKNOWN This node is not in the UCC7NODE table but data wasreceived and is either being held on the undeliverable queue orwas purged.

LUTYPE If a node is active, it is either a primary logical unit (PLU) or secondarylogical unit (SLU). The node which initiated the communications link is thePLU.

RECV The number of blocks received from the node specified.

SENT The number of blocks sent to the specified node.

UNDL The number of blocks on the undeliverable queue (UDQ) which contain datafor this node. The physical blocks on the UDQ can contain data for multiplenodes. Therefore, the total of the UNDL counts on the STATUS commanddoes not necessarily correlate to the physical blocks used on the UDQ.

PURG The number of blocks on the UDQ which contained data for the node thatwas purged.

NCF QUEUEThe percentage of blocks used in the NCF communications data set comparedto total blocks available.

Chapter 5. NCF 5-33


UND QUEUEThe percentage of blocks used in the UDQ compared to total blocks avail-able. When the UND QUEUE % USED first exceeds 80 percent, 85 percent,and 90 percent, a warning message will be issued. The warning message willbe 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 NCFtracing facility. This facility can provide SNAP dumps or WTOs to assist in isolatingproblems.

Note: Due to the extreme volumes of WTO and SNAP output produced, this facilityshould only be used when requested by the CA-7 NCF technical support staff forproblem resolution.

5.7.8.1 Syntax

To activate the trace facility:

TRACE

��─ ──MODIFY jobname,TRACE= ──┬ ┬─SNAP───────────── ──────────────────� ├ ┤─n────────────────

└ ┘──(n,mm,mm,...,mm)

Where:

jobnameIs the OS job or task name of the VTAM subtask.

TRACE= SNAP|n|(n,mm,mm,...,mm)Activates the trace facility.

SNAPIndicates that SNAP dumps are to be taken.

nIndicates the level number of WTOs desired. When coded by itself, WTOs willbe produced by all modules.

Level numbers (n) for WTOs are 1, 4 and 7 and are the only valid values forWTOs. Level 1 provides the most general WTOs. Levels 4 and 7 provide pro-gressively more detailed WTOs. Level 7 provides the most detailed WTOs. Aspecial level number of 127 may be used to request PCB SNAP dumps eachtime a PCB is dispatched. A PCB (Program Control Block) is an NCF internaldata area used in controlling all processing.

(n,mm,mm,...,mm)Indicates that the specified level of WTOs (n) is desired only from the modulesspecified as mm in the list. The parentheses must be coded as shown. Thespecification for n is the same as previously indicated. As an example,(7,01,03,04) indicates that the most detailed WTOs are desired from modulesSASSNC01, 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:

jobnameHas the same meaning as in the previous TRACE command entered to activate thetracing facility.


Chapter 6. CA-7 Cross-Platform Scheduling

A CA scheduling solution may request work to be run on its behalf by another CA sched-uling solution on a different platform. For example, the Unicenter TNG WorkloadManager 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 MVSjob or UNIX script, and so on) as the XPS CLIENT. The XPS SERVER is the CAscheduling solution controlling execution of the work requested by the XPS CLIENT. Inthe 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 initiatework 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 alsoact as the XPS SERVER by submitting and tracking work in response to requests fromXPS CLIENTs.

This chapter discusses the requirements that allow CA-7 to participate in the cross-platform scheduling environment. All forms of cross-platform scheduling require commu-nications between systems using Computer Associates Common Communication Interface(CAICCI). The other requirements necessary for CA-7 to run as an XPS CLIENT aredistinct 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 con-nected by CAICCI (Computer Associates Common Communications Interface). Specif-ically, Cross-Platform Scheduling uses the TCPIP/Gateway protocol of CAICCI. Theconnection 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 ofconnections, and/or the system that is recycled most often. A typical site probably has asmall number of OS/390 systems that are active the majority of the time and manynon-OS/390 systems, some of which may be shut down frequently. In this case, it makessense 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 Product File

Unix Unicenter TNGor CA-7 Agent

$caiglbl0000/cci/config/<machine-name>/ccirmtd.prfwhere <machine-name> is the CCI name of the machine.

Windows NT Unicenter TNG \TNG\CAIUSER\CCIRMTD.RC

Windows NT CA-7 Agent \CA\CAIUSER\CCIRMTD.RC

The format of the CCIRMTD file is the same on all non-OS/390 platforms. The first linemust be a LOCAL statement and may be followed by any number of REMOTE state-ments.

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 beresolved into a TCP/IP address. A TCP/IP PING command on this value should be suc-cessful.

"cciname" is the name that CAICCI will use for this node. This value may or may notbe the same as the ip-address. The name must match the CAICCI name defined at theremote node. For OS/390, the CAICCI name is defined by the SYSID parameter in theCAICCI parameters.

If STARTUP is specified, the connection is attempted as soon as CAICCI starts. This isrecommended.

PORT specifies the TCP/IP port number to use. The default is 1721, which is the defaultport for Unicenter TNG and CA-7 Agent. The default port on OS/390 is 7000 and maybe changed on the PROTOCOL(TCPIPGW....) statement.

ALIAS is only valid on the LOCAL statement. If the "cciname" is longer than 8 charac-ters, 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 isbroken, 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-platformscheduling communication. This is necessary even if the individual node connnectionsare defined on the non-OS/390 platforms. The types of TCP/IP Gateway protocols areTCPIPGW, TCPIP3GW, and TCPIPSGW. Refer to the CAICCI User Guide for specificinformation 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 beresolved into a TCP/IP address. A TSO PING command on this value should be suc-cessful.

"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 theconnection.

"cciname" is the name that CAICCI will use for this node. This value may or may notbe the same as the ip-address. The name must match the CAICCI name defined at theremote node (or the ALIAS= if specified). On OS/390, the node name is not case sensi-tive.

The NODE and CONNECT statements may also be issued from a console by prefixingthe 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 (XPSSERVER) which may be running on a remote platform and receives status feedback (jobinitiation and job termination information) from the XPS SERVER.

The XPS CLIENT for CA-7 performs two functions: submission and tracking. The sub-mission function is provided by program CA7TOUNI. The tracking function is providedby 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 CA7TOUNIto send execution data through CAICCI to the XPS SERVER on the target platform. TheXPS SERVER on that platform in turn submits the job and returns CAIENF tracking dataas it executes. Any output from the job will be directed to the XPS SERVER console onthat platform.

To use this interface, the MVS job must use JCL as described below. The JCL mustbegin with a #7UNI statement and it must execute CA7TOUNI. All normal schedulingfeatures are available for the job. It can have schedules, predecessors, triggers andresources.

When the job is submitted to MVS, it will execute and complete, but it will be returnedto the ready queue with a CPU indication of 7UWT to denote it is waiting on XPSSERVER submission. If an error occurs, the job will abend and be subject to restartconsiderations. When execution begins on the target platform, the XPS SERVER willreturn tracking data and normal job flow will resume. Also, the CPU indication willchange to 7UNI.

CA7TOUNI has one required and one optional parameter on the EXEC statement. Therequired parameter is a unique number for tracking. The optional parameter is a jobsetname. To facilitate supplying these parameters, it is recommended that a CA-Driver pro-cedure be used. The following is an example of such a procedure.

//CA7TOUNI DPROC

//STEP1 EXEC PGM=CA7TOUNI,

// PARM='&C_L27#,&C_L2SN'

//PROFILE DD DISP=SHR,DSN=ca-7.xps.profile

//STEPLIB DD DISP=SHR,DSN=ca-7.cailib


The CA-Driver variables &C_L27# and &C_L2SN are replaced by CA-7 job number andCA-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 membernamed CACCENV. CACCENV contains keyword entries specifying environment param-eters for the Submit Function.

Note: The security-id under which the Submit job executes must have READ access tothe 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 asfollows:

� EXEC parm values override SYSIN and PROFILE values

� SYSIN values override PROFILE values

The following describe all parameters for CA7TOUNI:

DOMAINThis optional parameter may be required for some requests sent to CA-UnicenterTNG on NT platforms.

Size/Type: 1 to 15 alphanumeric charactersRequired: NoSource: SYSIN or PROFILE

Note: The DOMAIN variable will only be accepted from the same source as theNODE variable. That is, they either both have to come from the PROFILEdata or both from the SYSIN data. If the DOMAIN variable is supplied froma source other than NODE it will be ignored and the request will be sentwithout a DOMAIN parameter.

JOBNOThis required parameter should match the CA-7 assigned job number to provideuniqueness. It must be supplied as the first positional value of PARM input on theEXEC statement. It is recommended that you use a CA-Driver procedure to auto-matically insert the CA-7 job number in the JCL for this parameter.

Size/Type: 1 to 5 numeric charactersRequired: YesSource: EXEC parm



Note: Even though JOBNO can be up to 5 digits CA-Unicenter only supports 4digit job numbers. Only the last 4 digits are actually sent with the cross-platform request. If the specified job number is less than 4 digits it will beright justified and zero filled.

JOBSETWhen combined with the JOBNO and batch job name, this variable provides aunique identifier for the cross-platform request. Special characters should be avoidedas they may not translate correctly on the target platform. If omitted, theMONITOR value will be used as JOBSET. It is recommended that you use aCA-Driver procedure to insert the CA-7 system name in the JCL for this parameter.

Size/Type: 1 to 8 alphanumeric charactersRequired: NoSource: EXEC parm, SYSIN, or PROFILEDefault: MONITOR name

MONITORWhen combined with the local CAICCI node this parameter uniquely identifies thecopy of CA-7 submitting this cross-platform request. The value must be exactly 7characters. CA7PROD should be avoided as that is commonly used by UnicenterTNG and CA-7 for VAX. A good choice might be CA7 followed by the SMF-ID ofthe originating system. This value must match the one used by the CA-7 Cross-Platform Tracking System (XTRK).

Size/Type: 7 alphanumeric charactersRequired: YesSource: PROFILE

NODEThis parameter identifies the CAICCI node of the target system for this request. Itmust match what is defined in CAICCI on that system.

Size/Type: 1 to 8 alphanumeric charactersRequired: YesSource: SYSIN or PROFILE

PARM1 thru PARM64These optional parameters supply values to be used on the target platform. Valuesmay be 1 to 256 characters. Special characters should be avoided as they may nottranslate correctly on the target platform. Embedded blanks will cause the value tobe enclosed in double quotes by the XPS SERVER on the target platform. SinceJCL is limited to 80 characters per record, continuation may be required. To con-tinue a record, end it with a plus sign (+) and continue in column 1 of the nextstatement. The ending plus sign will not appear in the resulting value. Keywordchecking will be suspended during a continuation operation.

Size/Type: 1 to 256 alphanumeric charactersRequired: NoSource: SYSIN



SUBCHECKThis optional PROFILE parameter can force a security check for authorization of thecurrently running user to submit jobs for the ID supplied in SUBUSER. Normallysuch 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 settingis off.

Size/Type: YES and Y are the only allowed valuesRequired: NoSource: PROFILE

Note: This parameter cannot be used to turn off submit checking. A setting of NOwill cause a warning message and the parameter will be ignored.

SUBFILEThis required SYSIN parameter identifies the script or command to be executed bythe XPS SERVER. It has the same size, content and continuation considerations asthe PARMx values above. The script named must reside in a special directory iden-tified to Unicenter TNG or must indicate a fully qualified path name. Refer to theUnicenter TNG documentation regarding Client/Server processing and theCAISCHD0004 variable.

Size/Type: 1 to 256 alphanumeric charactersRequired: YesSource: SYSIN

SUBPASSThis optional parameter identifies the password to be passed with SUBUSER to thetarget platform. The password will be sent to the target system in an encryptedformat. Some target systems may require that a password accompany the SUBUSERon cross-platform requests.

Size/Type: 1 to 14 alphanumeric charactersRequired: NoSource: SYSIN or PROFILE

Note: The SUBPASS variable will only be accepted from the same source as theSUBUSER variable. That is, they either both have to come from thePROFILE data or both from the SYSIN data. If the SUBPASS variable issupplied from a source other than the SUBUSER it will be ignored and therequest will be sent without a password.



SUBROOTThis optional PROFILE parameter determines whether the special user ID of ROOTmay be used for job submission. Since the user ID of ROOT has special meaningand capabilities on many non-MVS platforms, it is best not to use it when submittingwork from MVS. By default, ROOT will not be allowed by this interface. In orderto submit work using ROOT as the user ID, this parameter must be present with avalue of "YES" or "Y".

Size/Type: YES, NO, Y and N are the only allowed valuesRequired: NoSource: PROFILEDefault: NO

SUBUSERThis optional parameter identifies the user ID for security purposes on the target plat-form. 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 casesubmission will be controlled by the setting for parameter SUBROOT. Regardless ofthe setting for SUBROOT, the use of ROOT as the user ID will cause a WARNINGmessage to be issued. Since the user ID ROOT has special meaning on UNIX plat-forms, it is recommended that ROOT not be specified.

Size/Type: 1 to 32 alphanumeric charactersRequired: NoSource: SYSIN or PROFILEDefault: Batch job user ID

SUTYPEThis optional parameter determines the type of "switch user' command that will beexecuted 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 willbe executed without the profile option.

Size/Type: YES, NO, Y and N are the only allowed valuesRequired: NoSource: SYSIN or PROFILEDefault: YES

7TRACEThis optional parameter can be used to turn on the trace facility to assist in trackingdown problems. If the parameter is set to YES additional messages will be writtento the SYSPRINT DD which may be helpful in pinpointing exactly when an error isencountered.

Size/Type: YES, NO, Y or N are only allowed valuesRequired: NoSource: SYSIN or PROFILEDefault: NO



Examples: The following is an example of a job to list the status of Unicenter TNG onthe 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 requestfrom being sent to the target system, the submit step will abend with a User 4000code (U4000). Refer to the messages produced in the submit job output to deter-mine the exact nature of the problem.



6.2.2 Cross-Platform Tracking

Tracking consists of the XPS SERVER returning feedback records for CA-7 submittedjobs to the system which sent the request. These records are transmitted using CAICCIand 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-PlatformSubmit job executed receives these events and converts them into SMF like feedbackrecognized by CA-7. CA-7 then processes this information like any other job to deter-mine when it becomes active, completes, or fails.

There should be one copy of CA-7 XTRK running on each system where CA-7 Cross-Platform Submit (CA7TOUNI) jobs can execute. CA-7 ICOM must also be executing onthese systems.

Also, events such as job execution and file creation/update which occur on non-OS/390platforms can be tracked even though CA-7 did not request that work (Cross-PlatformExternal Tracking). Unicenter TNG or CA-7 Agent must be executing at the remote nodefor this tracking to occur.

For specific information on running CA-7 XTRK as a subtask in the CA-7 ICOM addressspace, see Cross-Platform Tracking under ICOM in Chapter 6 of the CA-7 Systems Pro-grammer 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)... ::optional::

//XPRINT DD SYSOUT=:

//XSNAP DD SYSOUT=:

The XCKPT DD must point to a CA-7 Cross-Platform Checkpoint file. Each copy ofXTRK 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 bepre-formatted.



The XEVENTS DD is optional. If specified, it should point to an 80-byte card-imagesequential data set, or PDS member, which contains CA-7 cross-platform externaltracking rules. These rules define what events that occur on other systems should betracked by CA-7 even though CA-7 did not submit the work that caused these events totake place. Refer to 6.2.2.3, “CA-7 Cross-Platform External Tracking” on page 6-15 forinformation on the format of these rules.

The EXEC PARM values for XTRK are:

PARM='monitor,ca-7-subsystem,trace-codes'

monitorThis required parameter is the 7 character monitor name which uniquely identifies thecopy of CA-7 whose cross-platform jobs are to be tracked. It must match theMONITOR= value used by the CA-7 Cross-Platform Submit jobs to be tracked(CA7TOUNI).

ca-7-subsystemThis optional parameter specifies the 4 character subsystem name of the CA-7 forwhich this copy of XTRK is collecting. This parameter controls which copy of CA-7will receive the pseudo-SMF feedback generated by this copy of XTRK. The pro-duction copy of CA-7 uses subsystem UC07 (this is the default), and the test or sec-ondary copy of CA-7 uses subsystem UCT7. The values PROD and TEST can besubstituted for UC07 and UCT7.

trace-codesThese optional codes specify the level of diagnostic messages and snaps that shouldbe generated by XTRK. There are two codes that can be specified: print/snap tracecode and console message trace code. The first value controls what messages will bewritten to the XPRINT DD, and what records and control blocks will be written tothe XSNAP DD. The second value controls what WTOs are issued to the systemconsole.

The default trace codes are '11'. Possible trace codes are:

0 QUIET MODE - Only severe error WTOs. This value is only honoredfor the console trace code. If entered for the print trace code it will beinterpreted the same as a code of 1.

1 NORMAL MESSAGES/WTOS. These messages indicate XTRK systemstartup and shutdown. They also indicate when communication withremote systems is first established, if such communication is lost, and ifit is reestablished.

2 FEEDBACK MESSAGES/WTOS. Besides the messages issued for tracecode 1, messages relating to cross-platform feedback events will beissued.



3 COMMUNICATION MESSAGES/WTOS. Besides the messages issuedfor trace code 2, messages relating to CCI communications with othersystems will be issued. Also, messages will be issued for pseudo-SMFrecords generated and sent to CA-7. Also, if the XSNAP DD is avail-able, snap dumps will be taken of the storage areas related to CCIcontrol blocks and records, as well as pseudo-SMF records.

4 PROGRAM PATH MESSAGES/WTOS. Besides the messages issuedfor trace code 3, messages relating to internal XTRK processing will beissued. Also, if the XSNAP DD is available, snap dumps will be takenof the storage areas related to XTRK control blocks, besides the commu-nication and feedback related snaps.

Note: Trace code 4 should only be used at the direction of TechnicalSupport since it will produce a significant number of messages.

5-9 Currently trace codes 5 through 9 do not have specific definitions. Ifentered, they will be interpreted the same as trace code 4.

Note: Messages which indicate critical errors will always be issued as WTOsregardless of the trace code settings. Also, all error and warning messages(message-ids ending with E or W) will always be written to the trace print (ifavailable) regardless of the current trace code settings.

PARM Example: To start XTRK for a production CA-7 system whose monitor nameis 'CA7IPO1', a print trace code of '2' and a console trace code of '1', the parm value onthe 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 com-mands. XTRK MODIFY commands are:

Table 6-1 (Page 1 of 2). XTRK Modify Commands

Command Explanation

ADDNODE(nnnnnnn) Add a CAICCI node (nnnnnnnn) to the XTRK Node Table. XTRK will attemptto establish communications with that node.

BLDXEVT Rebuild the Cross-Platform External Tracking table from the rules defined in theXEVENTS DD. If the rebuild is successful XTRK will attempt to re-synchronize with each remote node to pass the new set of external tracking rules.

DELNODE(nnnnnnn) Delete a CAICCI node (nnnnnnnn) from the XTRK Node Table. XTRK will nolonger attempt to communicate with that node.

NODE List Node(s) from the XTRK Node Table indicating the current status, lastactivity and checkpoint dates and times. The default is to list all nodes. A fullor partially qualified argument can be specified to limit the display. Forexample: NODE(AIX*). Refer to messages CAL2X155I and CAL2X156I.

NODEN List Node(s) from the XTRK Node Table indicating the CAICCI node name andthe Unicenter TNG or CA-7 Agent node name. This display can be useful if youare using CAICCI Alias names. The default is to list all nodes. A full or par-tially qualified argument of the CAICCI node name can be specified to limit thedisplay. For example: NODEN(AIX*). Refer to message CAL2X154I.

NODEX List Node(s) from the XTRK Node Table indicating the current status, lastactivity and checkpoint dates and times, and the internal status flags. The defaultis to list all nodes. A full or partially qualified argument can be specified tolimit the display. For example: NODEX(AIX*). Refer to messages CAL2X155Iand CAL2X156I.

PING Forces the XTRK Tracking Manager to send a CAICCI record to each node inthe XTRK Node Table to confirm a connection, or attempt to initiate a con-nection. Normally this process is done on a timer basis.

SNAP(..option..) Forces a storage snap to be written to the XSNAP DD (if available and open).The options are:

SVT XTRK System Vector Table

TAB XTRK Node Table Block(s)

XEVT XTRK External Event Table entries

ALL all of the above

STOP Causes XTRK to perform normal shutdown processing. This can also be doneusing the operator STOP command (P CA7XTRK).



Table 6-1 (Page 2 of 2). XTRK Modify Commands

Command Explanation

TRC(pc) Without any operands it causes a display of current XTRK trace settings (seemessage CAL2X159I). With operands:

TRC(pc) Resets the current trace code settings. For example: TRC(21) setsthe print trace code to 2 and the console trace code to 1. Both codesmust 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 messagesCAL2X185I and CAL2X186I. The default is to list all event rules. A full orpartially qualified CAICCI node argument can be specified to limit the display toonly 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 filecreate/updates from Unicenter TNG or CA-7 Agent. For jobs to be tracked, they must beunder the control of Unicenter TNG. However, the creation or update of files can bedetected by Unicenter TNG or CA-7 Agent even if it is done by a task outside of theircontrol.

When XTRK starts, it checks for an XEVENTS DD statement. If present, it should pointto a 80-byte card-image data set or PDS member which contains the event rules for CA-7Cross-Platform External Tracking. When XTRK establishes communication with aremote system, it passes to that system the rules which apply to it. When a matching jobinitiation, termination, or file create/close occurs on that system, the feedback record forthat 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 forCA-7 which match the format of OS/390 CA-7 External Tracking. The CA-7 addressspace treats these pseudo-SMF records in the same manner as other external trackingrecords. Refer to the CA-7 Systems Programmer Guide for information on setting upCA-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 mean-ingful for all types of events. Unless otherwise specified, case does not matter. All datamust be between columns 1 and 72. Lines may be continued at any point (inside oroutside a keyword) by ending the line with " -" (a blank followed by a dash). The linewill be continued with the first non-blank character on the next line. Comments may becoded by placing an asterisk (*) in column 1.

Keyword Function

TYPE( 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 termi-nation events should be tracked.

TYPE(DSN)Indicates that matching file creation/ update eventsshould be tracked.

TYPE(CONNECT)Indicates that XTRK should always attempt toestablish contact with the CAICCI node specifiedin the NODE( parameter.

JNO( For event TYPE(JOB), the four digit job number of the job tobe tracked as defined to Unicenter TNG.JNO( is REQUIRED for TYPE(JOB) events. It is ignored forother types.

JOBSET( For event TYPE(JOB), the jobset name of the job to be trackedas defined to Unicenter TNG.JOBSET( is REQUIRED for TYPE(JOB) events. It is ignoredfor other types.



The XTRK command XEVT may be used to display the current External Events. TheXTRK command BLDXEVT may be used to re-build the table of External Events. Referto 6.2.2.2, “CA-7 Cross-Platform Tracking Commands” on page 6-14 for more informa-tion on these commands.

Keyword Function

MVSNAME( For event TYPE(JOB), the job name which conforms to MVSstandards to be used by CA-7 to track this job.For event TYPE(DSN), the fully qualified data set name whichconforms to MVS standards to be used by CA-7 to track thisfile.MVSNAME( is REQUIRED for TYPE(JOB) and TYPE(DSN)events.

NAME( For event TYPE(JOB), the name of the job to be tracked asdefined to Unicenter TNG.For event TYPE(DSN), the fully qualified name of the file tobe tracked. The value of NAME( is case-sensitive when usedfor a job name, and it may be case-sensitive when used as afile name, depending on the target platform.NAME( is REQUIRED for TYPE(JOB) and TYPE(DSN)events.

NODE( The CAICCI node name at which Unicenter TNG or CA-7Agent should watch for this event. For TYPE(CONNECT) itis the node name which XTRK should always establish contactwith.NODE( is REQUIRED for all events.NODE( must be fully qualified for TYPE(CONNECT) events.NODE( can be fully qualified, partially qualified or fullygeneric for TYPE(JOB) or TYPE(DSN) events.

STAT( For EVENT(DSN), STAT( indicates which method should beused on Unix machines to determine when the file has beenupdated. STAT(N), the default, uses hooks in the Unix kerneland is the fastest and most reliable method. STAT(Y) uses aUnix statistics utility to determine when the file has beenupdated. Refer to the Unicenter TNG documentation for moreinformation on these methods.STAT( is optional for EVENT(DSN) events and ignored for allother events.



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 thecreation/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. XTRKwill 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 namebegins 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 willtrack it as a CA-7 external job with the name AIXJOB1. This definition allows you toset up one rule which will capture tracking for this job regardless of which AIX machineit runs on.



XEVENTS Example 4

EVENT( TYPE(CONNECT) NODE(AIX??1) )



These rules ensure that XTRK will attempt to communicate with Unicenter TNG or theCA-7 Agent on each of these systems (AIX001, AIX002, AIX003). Normally, XTRKcommunication will only take place if CA-7 submits a cross-platform job to that remotesystem. If you simply want to listen for cross-platform external tracking events at anode, the TYPE(CONNECT) rule ensures that XTRK will attempt to establish communi-cation 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 rulesfor both copies. If you do, each XTRK could receive feedback for the same remote jobor file event. Depending on the timing of XTRK, ICOM, and CA-7 processing, thiscould result in duplicate triggers (at worst), or unnecessary overhead in the CA-7 addressspace (at best). It is recommended to have one copy of XTRK handle the Cross-PlatformExternal Tracking for CA-7.

Using TYPE(CONNECT) Event Rules: Normally the CA-7 Cross-Platform TrackingSystem (XTRK) only communicates with those remote systems where CA-7 Cross-Platform jobs are submitted to. If you wish to use CA-7 Cross-Platform ExternalTracking for remote systems that do not receive any CA-7 cross-platform work, you needto define at least one XEVENTS rule which explicitly references that node. If the onlyrules 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 beavailable to the CA-7 address space. The External Job/STC Filter Table module,SASSEXTL, is NOT required for cross-platform external tracking. For information onenabling CA-7 external tracking, see Tracking External Tasks in the CA-7 Systems Pro-grammer Guide.



6.2.3 CA-7 Considerations

As noted above for the Submit Function, any job whose JCL starts with #7UNI will betreated as a cross-platform job. When such a job completes on MVS, it is requeued tothe ready queue with a CPU indication of 7UWT. The job will stay in the ready queueuntil another job initiation record is received. When initiation is received the CPU indi-cation 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 each7UNI job submitted. The first set represents the MVS job which submitted data to theXPS SERVER. The second set represents the job execution on the XPS SERVER plat-form. This second set will consist of job initiation, step termination, and job terminationrecords only. There will be no data set records, and not all fields will be filled in for theother records.

Concerning restart considerations, it is recommended that 7UNI jobs not include a CA-11restart step or have CA-7 insert such a step. Including CA-11 is unnecessary since thesejobs will consist of a single step, produce no data sets and must be totally rerun ifrestarted.

Since commands and parameters may be included in the JCL as SYSIN data, certainspecial considerations are applied to jobs flagged for submittal to another system. ManyUnicenter TNG and CA-7 Agent platforms are case sensitive to their input; howeverunless 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 ifINITCASE=Y is specified in the CA-7 initialization file.

Note: If CA-7 Mixed Case Editing is not enabled, the following JCL edit related fea-tures 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 ofCA-7, such as TSO/ISPF or CA-ROSCOE. If the JCL must be changed after thejob enters the queues, change the JCL outside of CA-7. Next, cancel and demanda new version of the job. If the job was scheduled or triggered and cannot becanceled and demanded, change the JCL outside of CA-7. Use the JCL screen toFETCH it (do not use FE or EDIT). Next use the QJCL screen to REPL therequest 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-PlatformConnections” on page 6-2.

These CAICCI connections are the same regardless of which side is acting as theXPS CLIENT or XPS SERVER.

Note: This interface requires CA90s (service level C0 or later) or Unicenter TNGFramework for OS/390, Unicenter TNG, and CA-7 Agent. It is NOT com-patible with earlier versions of CA90s or Unicenter.

If you are communicating with Unicenter TNG or the CA-7 Agent on aWindows/NT platform and also have CA-7 WorkStation on the samemachine, you must ensure that CAICCI Remote Services and the CAICCI-PCProperties use different System Names for the Windows/NT machine. TheCAICCI Remote Services System Name is defined in file CCIRMTD.RC(local node). The CAICCI-PC Properties System Name can be accessedthrough 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” onpage 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-PlatformTracking 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-PlatformTracking 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” onpage 6-5. If you are not familiar with CA-Driver, refer to Chapter 4, “CA-DriverProcedures, 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” onpage 6-5. The jobs should be defined and scheduled like any other CA-7 job, onlythe 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 specifiedplatform (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 solutionwhich may be running on a remote platform. It responds by servicing the requests (jobsubmission), and returning appropriate feedback to the XPS CLIENT. In this way, theXPS CLIENT is notified of job initiation and termination.

The CA-7 XPS SERVER comprises two distinct functions: the XPS SUBMIT MONITORand the XPS ROUTER. The programs that make up the XPS ROUTER functionnormally run as subtasks in the CA-7 address space. The XPS SUBMIT MONITORfunction 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 requestfrom the XPS CLIENT, schedules the job in CA-7 and sends status feedback to the XPSCLIENT through the XPS ROUTER.

The XPS SUBMIT MONITOR is responsible for two activities: submission of CA-7 jobsand 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 XPSSUBMIT MONITOR using CAICCI. The SUBMIT MONITOR builds a terminalcommand based on parameters provided in the scheduling request or from options codedin the CA-7 initialization file. The submit MONITOR then uses an internal terminal toissue a command which causes the job to be scheduled. The definition of an internalterminal is marked by the specification of DEVICE=TRXDV. If CA-7 is to be an XPSSERVER, at least one internal terminal must be defined.

The value of the XPSSCHD keyword on the SVCNO statement in the CA-7 initializationfile determines the scheduling command that is issued when a cross-platform schedulingrequest is received. Refer to 6.3.4, “Managing the Cross-Platform Workload” onpage 6-31 and to the discussion of the XPSSCHD keyword on the SVCNO initializationfile statement in the CA-7 Systems Programmer Guide for additional information on thisimportant parameter.

The XPS SUBMIT MONITOR respects CA-7 terminal security. A USERID is requiredfor the logon to the internal terminal used for the scheduling request. This USERID willdetermine the security in effect for the request. If no USERID is supplied on the sched-uling request from the XPS CLIENT then the value of the XPSSID keyword on theSECURITY statement will be used for the logon to the internal terminal. If no USERIDis supplied and if no value is coded for the XPSSID keyword then the schedulingrequests 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 anXPS 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 PRIORto scheduling. If the job is not defined to CA-7, the scheduling request from the XPSCLIENT will fail.

The command that is used by the XPS SERVER to schedule the job is recorded in theCA-7 Log. If an XPS CLIENT scheduling request fails, the terminal command as well asthe 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 CLIENTin the form of CAIENF events. The CAIENF event that is used for this purpose isnamed 'CAXPSFBK'. CA-7 will create CAXPSFBK records to signal status changessuch as job initiation, job termination and job failure. These CAIENF events will becaptured by the XPS ROUTER and forwarded to the XPS CLIENT.

If the command used to schedule the job fails for any reason (for example, /LOGONfailure, job not defined, and so on), CA-7 creates a CAIENF record reporting the failureto be sent to the XPS CLIENT.

A CAIENF record reporting job initiation is created when CA-7 receives the job initiationrecord from SMF.

The value of the XPSSCHD keyword on the SVCNO initialization file statement affectsthe way job completion status updates are reported to the XPS CLIENT. If the default ofXPSSCHD=RUNREF is used, then a CAIENF record for job completion is created imme-diately when the job terminates. If XPSSCHD=DEMAND or XPSSCHD=RUN is codedthen the job completion status update will not be reported until the job exits the requestqueue.

If a job requested by an XPS CLIENT is canceled in CA-7 prior to job submission, thenCA-7 will create a CAIENF record indicating that the job failed. If, however, the job hasalready run at least once, then a CAIENF record indicating job termination will becreated.



6.3.2 The Cross-Platform Scheduling Router (XPS ROUTER)

To communicate with other CA scheduling solutions each system must present a singlepoint of communication. The cross-platform scheduling router (XPS ROUTER) is thissingle point of communication on MVS systems. On a given MVS system there may bemore than one CA scheduling solution executing. For example, there may be both pro-duction and test copies of CA-7 executing on the same MVS image. The cross-platformscheduling 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 workfrom other systems. It then routes each request to the appropriate CA scheduling solutionon that system. The feedback information (job initiation, termination, failure) generatedby the CA scheduling solution is used to create CAIENF cross-platform feedback events(CAXPSFBK). The cross-platform scheduling router intercepts these events and sendsthe feedback to the original requester. Logging this information in CAIENF also preventsthe loss of feedback data if communications problems interrupt the links among plat-forms. When the link is reestablished, the cross-platform scheduling router can retrievethe logged feedback events from CAIENF and send them to the system which originatedthe request.

Cross-platform scheduling communication is performed by using the Computer AssociatesCommon Communications Facility (CAICCI). A copy of CAICCI runs on each systemwhere Computer Associates solutions require it. The copies of CAICCI on each systemcommunicate with each other using various protocols based on CAICCI control parame-ters. The gateway communication protocol is used for cross-platform scheduling (host-to-host connection).

Each copy of CAICCI has a unique identifier known as the node name. On each system,Computer Associates solutions register with the local copy of CAICCI as a CAICCIapplication. The local CAICCI then makes those applications known to the copies ofCAICCI on other systems which it is connected to. There are several unique CAICCIapplication names which are used only for cross-platform scheduling. The combinationof the node name and the unique CAICCI application names enable Computer Associatesscheduling solutions to route requests for work and the feedback from that work.

Besides the unique node and CAICCI application names each Computer Associatesscheduling solution which participates in cross-platform scheduling has a seven-characteridentifier known as a monitor name. In an MVS environment, each Computer Associatesscheduling solution must have a monitor name that is unique in the local MVS environ-ment. Thus, on a system where there are both production and test copies of CA-7 at thesame node, they must have different monitor names in order for cross-platform schedulingto work properly for both copies.

The CAICCI application names used by cross-platform scheduling are based on the func-tions they perform. The CAICCI application which receives requests for work has afixed name which is common to all systems, and there can only be one copy at a CAICCInode. Other CAICCI applications that participate in cross-platform scheduling have acommon format where the monitor name makes them unique in the local CAICCI envi-ronment.



The CAICCI application names used in cross-platform scheduling are:

� SUBMITC Server

This CAICCI application name receives requests for work from CA Scheduling sol-utions on other systems. The SUBMITC Server routes the request to the appropriateCA scheduling solution at that node (monitor-name Server).

There can only be one copy of the SUBMITC Server on a given node regardless ofhow many CA Scheduling solutions are executing at that node. On MVS, this appli-cation is controlled by the cross-platform scheduling router. On non-MVS platformsthere can only be one CA Scheduling solution so the SUBMITC Server is controlleddirectly by that solution.

� CAU9SET Setup Manager

This CAICCI application name controls the Checkpoint Synchronization process withother systems. The Setup Manager initiates the Synchronization process and sendsfeedback (job initiation, termination, failure information) which was previouslylogged 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 howmany CA Scheduling solutions are executing at that node. On MVS, this applicationis controlled by the cross-platform scheduling router.

� CAU9CTK Track Task

This CAICCI application name sends the real-time feedback (job initiation, termi-nation, and failure information) to the remote system which requested a piece ofwork.

There can only be one copy of the Track Task on a given node regardless of howmany CA Scheduling solutions are executing at that node. On MVS, this applicationis 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 thework is to be executed. The CAICCI application name consists of the seven char-acter 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 areCA Scheduling solutions executing at that node. On MVS, these applications arecontrolled 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 remotesystem. The feedback is sent either by the SetUp Manager or Track Task at thesystem where the job was actually run. The CAICCI application name consists ofthe 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 areCA Scheduling solutions executing at that node. On MVS, these applications arecontrolled 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. TheseCAICCI applications receive requests for work from the SUBMITC Server applica-tion running at the local node. The CAICCI application name consists of the7-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 CAScheduling solutions executing at that that node. These applications appear only onMVS and are controlled by each CA scheduling solution participating in cross-platform scheduling.



6.3.3 Cross-Platform Server Password Requirements

The password requirement rules for the cross-platform server on MVS define when apassword must accompany an explicit user ID in a cross-platform request. Using theserules you can discriminate between trusted and non-trusted systems when receivingrequests. That is, if you are confident that requests from a given system have alreadygone through security checks to ensure that the user ID passed with the request should behonored, you can specify a rule so that the cross-platform router will accept the user IDwithout a password. For other systems which are not 'trusted' you can write rules so thatany request from them which contains a user ID must also carry a password that can bevalidated by the cross-platform server. Requests received from these systems which havea 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 userID/password combination itself. That process will be done by the XPS Server schedulingsystem based upon it's own security processing (internal or external).

Password Requirement Rules are defined in a data set pointed to by the XPSPSWD DDstatement in the Cross-Platform Scheduling Router (XPS) environment. This data set is asequential file consisting of fixed 80 byte records (physical sequential or a member of aPDS). The records can be blocked or unblocked. If the XPSPSWD DD statement is notpresent, or contains no valid rules, the default processing is to accept all requests withoutchecking for the presence of passwords.

When the Cross-Platform Scheduling Router (XPS) goes through initialization processingit will attempt to locate and parse the Password Requirement Rules. If found, these ruleswill 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 through71. 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-nameThis keyword identifies the 1 to 8 character CAICCI node name that a Cross-Platform request can be received from. It must be specified as a specific name or anasterisk (*) which indicates all nodes. If not specified the default is NODE=* indi-cating all nodes.

MONITOR=monitor-nameThis keyword identifies the 7 character scheduling system monitor name that a Cross-Platform request can be received from. It must be specified as a specific name or anasterisk (*) which indicates all monitor names. In cases where a given node mayhave multiple scheduling systems (such as production and test copies of CA-7), theNODE and MONITOR combination will uniquely identify a specific schedulingsystem. If not specified the default is MONITOR=* indicating all monitor names.

ID=user-idThis keyword identifies the 1 to 8 character user ID that may be passed with a cross-platform request. It must be specified as a specific name or an asterisk (*) whichindicates all user IDs. If not specified the default is ID=* indicating all user IDs.

PSWD=YES/NOThis keyword indicates whether a cross-platform request which matches theNODE/MONITOR/ID parameters of the rule must have a password to accompany theuser ID in the request. A value of YES (or Y) indicates that such requests must havea password. A value of NO (or N) indicates that passwords are optional for suchrequests. 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 todetermine 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 bemade.

2. If the request contains both a user ID and a password, a password requirement checkwill not be made.

3. If the request contains a user ID but no password, a password requirement check willbe made.

The XPS Router will attempt to find the 'best match' between the current request and thePassword Requirement Rule Table based upon the NODE, MONITOR and user ID. Amatch with a rule that specifies a specific NODE, MONITOR and/or ID will take preced-ence over a generic rule. If multiple rules equally match a request then the rule(s) whichrequire a password will take precedence over those which do not. If no match is found inthe 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, schedulingsystem 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 musthave 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 ofTESTUSER 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 itwill partially match on both of the above rules. The second rule will take precedencesince a specific ID match will take precedence over a specific NODE match. A passwordWILL 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 withany user ID it will partially match on both of the above rules. In this case the matcheshave equal weight (NODE or MONITOR specific, ID generic). In the case of a tie therule which requires a password will take precedence over one which does not. A pass-word WILL be required.



6.3.4 Managing the Cross-Platform Workload

The distributed nature of cross-platform scheduling emphasizes the need to consider thequestion of managing the cross-platform workload.

There are two approaches to scheduling which may be distinguished in terms of thedegree of control granted the XPS CLIENT versus the degree of control granted the XPSSERVER.

The manager-agent model may be useful in making this distinction. The schedulingmanager is the focal point of control for the workload. The scheduling manager requestswork and monitors status for purposes of workload control (evaluating requirements, trig-gering other work). The scheduling agent initiates work at the request of the managerand 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 XPSCLIENT 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 theXPSSCHD keyword on the SVCNO initialization file statement. Values includeRUNREF, DEMAND and RUN.

By default, cross-platform jobs enter CA-7 using the RUNREF option. This assigns therole of scheduling manager to the XPS CLIENT, the requester of the job on another plat-form (for example, Unicenter TNG). The primary responsibility for workload controlbelongs to the XPS CLIENT. Jobs scheduled using this option will NOT honor require-ments defined in CA-7, they will NOT be considered requirements for other CA-7 jobsand they will NOT trigger other CA-7 jobs at completion. This variant of the RUNcommand differs from the standard RUN command in that it will not allow a CA-7restart. A job scheduled using this command is considered "complete" at either normal orabnormal termination. An entry for the job will appear in the CA-7 RUNLOG, howeverno 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-7using the XPSSCHD=DEMAND or XPSSCHD=RUN options. If either of these optionsis used, then additional management functions become the responsibility of CA-7.

XPSSCHD=RUN confers additional responsibility on CA-7 for monitoring and control ofrestart and rerun conditions. However, since the RUN command is used to schedule thejob, CA-7 requirement and trigger definitions will be ignored.



XPSSCHD=DEMAND confers even more management responsibility on CA-7. Becausethe DEMAND command is used to schedule the job, CA-7 requirement and trigger defi-nitions 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 todeclare 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 toStep 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-PlatformConnections” on page 6-2.

These CAICCI connections are the same regardless of which side is acting as theXPS CLIENT or XPS SERVER.

This interface requires CA90s (service level C0 or later) or Unicenter TNG Frame-work for OS/390 and Unicenter TNG. It is NOT compatible with earlier versions ofCA90s or Unicenter.

If you are communicating with Unicenter TNG on a Windows/NT platform and alsohave CA-7 WorkStation on the same machine, you must ensure that CAICCI RemoteServices and the CAICCI-PC Properties use different System Names for theWindows/NT machine. The CAICCI Remote Services System Name is defined infile CCIRMTD.RC (local node). The CAICCI-PC Properties System Name can beaccessed 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 CAXPSFBKCAIENF event and data elements. If CAIENF is active when the L2DCM2 job isrun it will need to be shut down and restarted to make the CAXPSFBK event avail-able.

3. Add cross-platform scheduling keywords to the CA-7 initialization file.

Select the appropriate values for cross-platform scheduling on the SVCNO initializa-tion file statement:

a. Specify MONITOR=YES. This indicates that CA-7 XPS SERVER functionsshould be activated.

b. The XPS ROUTER will execute on only one copy of CA-7 at any givenCAICCI node. The XPS ROUTER will be started on the production copy ofCA-7 by default if MONITOR=YES is coded. If cross-platform scheduling is tobe used only with a test copy of CA-7 then ROUTER=YES must be coded onthe SVCNO statement for the test copy in order to start the XPS ROUTER underthe test copy of CA-7.

c. Determine the appropriate value for the XPSSCHD parameter based upon theneeds of your environment. Remember that the default value gives the greatestdegree of workload control to the XPS CLIENT and limited control to CA-7. Ifa greater degree of control over cross-platform jobs should be given to CA-7then 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 terminalswith DEVICE=TRXDV.

Refer to the CA-7 Systems Programmer Guide for information on the initializationoptions for CA-7 XPS SERVER functions. CA-7 will need to be shut down andrestarted 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 adata set or PDS member to hold the rules. Add an XPSPSWD DD statement to theCA-7 JCL where the XPS ROUTER will execute (see step 3 b above). Refer to6.3.3, “Cross-Platform Server Password Requirements” on page 6-28 for informationon 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 aStation. 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 defineJobsets 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 (JobDetail - Submission - Filename).

c. If you have more than one copy of CA-7 at the target MVS system and youwish to route this job to the secondary copy, add the keyword',MONITOR=monitor-name' after the MVS jobname in the 'Filename' field. Forexample, if you wish to execute job TESTJOB1 on the test copy of CA-7 whosemonitor name is 'TESTCA7', specify a Filename of'TESTJOB1,MONITOR=TESTCA7'.

d. The value of the XPSSCHD keyword on the SVCNO initialization file statementspecifies how a job requested by an XPS CLIENT is to be scheduled. This is aglobal value and applies to all jobs requested by XPS CLIENTs. To overridethis value for a specific job add the keyword ',XPSSCHD=xpsschd-value' afterthe MVS jobname in the 'Filename' field. For example, if job TESTJOB1 is tobe DEMANDed on the test copy of CA-7 but the XPSSCHD value in CA-7 isRUNREF, 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 jobinto the CA-7 system, specify it in the 'Run as User', 'User' field (Job Detail-Submission-Run as User). Otherwise, the CA-7 user ID will default according tothe XPSSID= option on the SECURITY statement in the CA-7 initialization file.A password may or may not be required depending on the MVS PasswordRequirement Table described in Step 4, above. If no Password RequirementTable 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 theCA-7 database. These are the MVS jobs identified in the 'Filename' field of theUnicenter TNG jobs. Refer to CA-7 documentation for information on defining a jobin 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 scheduleJobsets/Jobs.

When the cross-platform jobs are submitted the request will be routed to CA-7 on thespecified MVS system (XPS SERVER), and the feedback from CA-7 will bereturned 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

AActivating CA-Driver 4-1Allocating space 5-13Ampersand (&) (CA-Driver) 4-13Arrays 4-21ARTS command 2-6Asynchronous processing time (NCF) 5-16Attribute testing 4-23

BBatch Card Load program

See BCLPBatch commands

format 3-3installation process 3-5

Batch step execution 3-14BCLP

ABORT 3-27and U7SVC facility 3-13CA-7 requirements 3-26control statements 3-28DB 3-27DBPARMS 3-28description 3-26ERR 3-27EXITPROG 3-27JCL requirements 3-27using 3-26

BPXBATCH program 2-42BTI

N220 job 3-5overview 3-1parameters 3-8

CCA-1 interface 2-3CA-11

ARTS Command Monitor 2-6automatic

CMT updating 2-7RMS insertion 2-7

interface 2-5CA-7 Agent 6-1CA-7 facilities

Batch Card Load Program (SASSBCLP) 5-22LOAD process (SASSJJCL) 5-22trailer step (SASSTRLR) 5-22U7SVC utility 5-22

CA-7 submitted jobs 5-2CA-7 WorkStation 2-8CA-7/API requirements 2-27CA-7/Notepad 2-38CA-7/Report Balancing 2-38CA-7/Reports+ 2-38CA-7/Smart Console 2-39CA-APCDDS interface 2-9CA-APCDOC interface 2-9CA-Dispatch interface 2-10CA-Driver

activating 4-1branching

conditional 4-35unconditional 4-33

commands 4-32comments 4-40cross-platform scheduling 6-5functions 4-26overview 4-1procedure library 4-4procedure, expanding 4-32reserved-name variable parameters 4-16sequence numbers 4-15variable parameters 4-9

CA-Earl reporting 2-12CA-Easytrieve Plus reporting 2-12CA-JCLCheck interface 2-13CA-Librarian interface 2-14CA-Netman interface 2-15CA-Opera interface 2-20CA-OPS/MVS II interface 2-20

Index X-1

CA-Panvalet interface 2-23CAICCI

CCI interface 3-1cross-platform scheduling 6-11

CAICCI connections 6-2CAIENF events 6-11CAIRIM

requirement for 5-3, 5-14resource initialization manager 5-4, 5-6

CAISMFI dynamic SMF event interceptor 5-6Calculating region size 5-12Calling U7SVC from a user program 3-16CL233SB SYSMOD 2-5CL233SC SYSMOD 2-5Commands

ARTS 2-6CA-Driver 4-32LOGOFF 3-4LOGON 3-3NCF 5-25

Communications data setand ICOM 5-7file description 5-13overview 5-8

Conditional procedure expansion 4-32Control statements for BCLP 3-28CPM 2-20CREATE (data set request statements) 3-34Critical Path Monitoring 2-20Cross-platform scheduling

and CA-Driver 6-5Overview 6-1XPS CLIENT 6-5XPS SERVER 6-22

Cross-platform Server password requirements 6-28CWORK 2-3

DDABORT command 4-39DASD

devices 5-12requirements 5-13

Data inclusion 4-8Data set request statements 3-34Data sets 5-21DATA statement (CA-Driver) 4-7DAY function (CA-Driver) 4-29DB.1 screen

Execution segment 5-18JCL segment 5-19Messages segment 5-19

DB.1 screen (continued)Resources segment 5-18

DBM batch commands, format 3-3DCM SAMPJCL member 2-20, 2-39Defining CA-Driver procedures 4-4DEND statement 4-7DFLUSH command 4-39DGOTO command 4-33DIF command 4-35Disk drives supported 5-12DLCTR command 4-39DM3Y function 4-28DM3YR function 4-29DMY function 4-28DMYR function 4-28DOW function 4-29DOW# function 4-29DSET command 4-37DSTEP command 4-33DTADD function 4-27DTDIF function 4-27DTSUB function 4-27Dynamic initialization routines 5-6

EEnd-of-Data Set (EODS) Statement 3-37Enhancements 1-1Error recovery 5-24Events, CAIENF 6-11Examples

Data Flow Within One CPU 5-4NCF VTAM PARM 5-17

Execution options 5-16External

See External CommunicatorsExternal Communicators 3-1

FFiles, permanent CA-7 NCF 5-13Flows 2-21Forecasting print volumes with CA-Dispatch 2-10Format

NCF communications data set 5-13UDQ 5-13

Functions for CA-Driver 4-26

IICOM

communications data set 5-14

X-2 CA-7 3.3 Interfaces Guide

ICOM (continued)requirements 5-12

Implementation considerationsCA-7 facilities 5-22data sets 5-21database 5-18DB.1 screen 5-18DD statements 5-20EXEC statements 5-20execution JCL 5-19general usage 5-22JES NJE capabilities 5-15JES2 statements 5-19JES3 statements 5-20JOB statement 5-19LOAD process 5-22NCFNODE parameter 5-22overview 5-15scheduling 5-18XPS CLIENT 6-21XPS SERVER 6-33

Including data 4-6Interfaces

CA-1 2-3CA-11 2-5CA-APCDDS 2-9CA-APCDOC 2-9CA-Dispatch 2-10CA-Earl 2-12CA-Easytrieve Plus 2-12CA-JCLCheck 2-13CA-Librarian 2-14CA-Netman 2-15CA-Opera 2-20CA-OPS/MVS II 2-20CA-Panvalet 2-23list 2-2OS/390 UNIX System services 2-24TSO/ISPF 2-29

ISPFinterface 2-29with CA-Driver 4-4

JJCL requirements for BCLP 3-27JDOM function 4-31JES2 statements 5-19JES3 statements 5-20JOB statement 5-19

LLDOM function 4-31Length attribute 4-24Librarian

See CA-Librarian interfaceLink editing node table 5-7List function in batch commands 3-4LJDOM function 4-31LOGOFF command 5-30LOGON command 5-29Loop control 4-39

MM3DY function 4-28M3DYR function 4-29MDY function 4-28MDYR function 4-28Memory requirements 5-12MNADD function 4-27MNSUB function 4-27MNT override statement 3-26MODIFY command 5-25MON function 4-29MON# function 4-29MONTH function 4-29Multi-access spool 5-8MVS dynamic initialization component 5-6

NN220 job 3-5NCF system

commands 5-25components 5-4Data Flow Within One CPU 5-4operations

CA-7 NCF functions 5-23create control blocks 5-23error recovery 5-24establish communications 5-23initialization 5-23loading node table 5-23overview 5-23scanning files 5-23standard operations 5-24status information 5-24termination 5-24

overviewCA-7 NCF components 5-4CAIRIM 5-6ICOM 5-7

Index X-3

NCF system (continued)overview (continued)

NCF Communications Data Set 5-8NCF undeliverable queue (UDQ) 5-8NCF VTAM Application Program 5-8node table 5-7OPERATOR commands 5-25purpose 5-2requirements 5-3SVC interface 5-6unknown node table 5-7

requirements 5-3NCF VTAM

application program 5-8application program functions 5-8PARM 5-17

NCFNODE parameter 5-22NEST statement 4-5Nested procedures 4-5, 4-14Network job entry (NJE) 5-2Node Table

loading 5-23requirements 5-7

Non-DBM batch commands, format 3-5Null value 4-22Number attribute 4-25

OOperating system environment 5-12Operator commands

format 5-26LOGOFF 5-30LOGON 5-29MODIFY 5-25overview 5-25PURGE 5-31response 5-26SHUTDOWN 5-26, 5-27STARTUP 5-28STATUS 5-27, 5-32STOP 5-25, 5-26TRACE 5-35

OPTION statement (BCLP) 3-30Options for CA-7 2-38OS/390 UNIX System services interface 2-24

PPassword requirements for cross-platform scheduling 6-28Permanent files, CA-7 NCF 5-13

PF key support 2-34Procedure for CA-Driver

creating 4-4expansion

aborting 4-39conditional 4-32controlling loops 4-39shifting during 4-15

nesting 4-5, 4-14parameter substitution 4-9retrieving 4-4storing 4-4

PURGE command 5-7, 5-31

RRegion size, calculating 5-12Reporting

CA-Earl reporting 2-12CA-Easytrieve Plus reporting 2-12

RequirementsCAIRIM 5-14DASD 5-13

Reserved-name variable parameters 4-16Resource initialization manager 5-4, 5-6Restarting jobs with CA-Driver 4-34Retrieving procedures for CA-Driver 4-4Return codes and SASSXXBT message table 3-6Router, XPS 6-25

SSASSBCLP (Batch Card Load Program)

using 3-26using with NCF 5-22

SASSBSTR programoverview 3-6PARM values 3-8

SASSDPCH module 2-10SASSLIBR module 2-14SASSNC01 module 5-35SASSNC03 module 5-35SASSNC04 module 5-35SASSNC12 program 5-13SASSNC15 program 5-13SASSPANV module 2-23SASSTRLR program 5-22SASSXXBT message table 3-6Scheduling

cross-platform 6-1day and time values 5-18


Shifting during expansion 4-15SHUTDOWN command, NCF

and STOP command 5-26description 5-27terminating NCF 5-24

SMF interface exits 5-3, 5-6Space allocations 5-13Startup command 5-28Status

CA-7 NCF VTAM 5-33command 5-24, 5-27, 5-32information 5-24

STOP command 5-24, 5-26Substring referencing 4-19Summary of enhancements 1-1SVC interface 5-3, 5-6System information

&C_DATE 4-16&C_DAY 4-16&C_JDATE 4-16&C_MONTH 4-16&C_TIME 4-16

TTermination 5-24Terminology 5-11TIQ interface 2-3TRACE command 5-35Trailer data 5-7, 5-8Trailer step facility

figure 3-10JCL 3-12overview 3-10

TSO/ISPF interface 2-29Type attribute 4-23Typical NCF environment 5-5

UU7SVC facility

at remote nodes 5-22overview 3-1using 3-13

UCC7NODE table 5-24UDQ

See Undeliverable queue (UDQ)Undeliverable queue (UDQ)

and PURGE command 5-24and unknown node table 5-7DASD requirements 5-13overview 5-8

Unicenter TNG 2-37, 6-1UNIX System Services

scheduling jobs 2-42Unknown node table 5-7

VVariable parameter

arrays 4-21, 4-25attribute testing 4-23coding 4-11in nested procedures 4-14length attribute 4-24number attribute 4-25reserved-name 4-16substitution 4-9, 4-13substring referencing 4-19types 4-23values

changing 4-37defining 4-11multiple 4-21null 4-22overriding 4-12testing 4-23

Verification of data inclusion 4-8Verifying JCL with CA-Driver 4-3Virtual terminals, installation requirements 2-37VTAM

PARM for NCF VTAM application program 5-17requirements for CA-7 under TSO/ISPF 2-29

WWOM function 4-29Workload

management and cross-platform scheduling 6-31management and NCF 5-2

WOY function 4-30

XXPS CLIENT

submission 6-5tracking 6-5

XPS Router 6-25XPS Submit Monitor

creating status information 6-22submission 6-22

Index X-5

YYM3D function 4-28YMD function 4-28YRM3D function 4-29YRMD function 4-28


Ca7 Interface Guide

Documents

Transcript of Ca7 Interface Guide