ftpdocs.broadcom.com · Contents Chapter 1. Using Unicenter CA-Driver Job Management for VSE.... 1-1 1.1 Using Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . .

Reference Guide r7.3

K01183-1E

Unicenter CA-Driver

Job Management for VSE

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

This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without the prior written consent of CA. This documentation is proprietary information of CA and protected by the copyright laws of the United States and international treaties.

Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for their own internal use, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the license for the software are permitted to have access to such copies.

This right to print copies is limited to the period during which the license for the product remains in full force and effect. Should the license terminate for any reason, it shall be the user’s responsibility to return to CA the reproduced copies or to certify to CA that same have been destroyed.

To the extent permitted by applicable law, CA provides this documentation “as is” without warranty of any kind, including without limitation, any implied warranties of merchantability, fitness for a particular purpose or noninfringement. In no event will CA be liable to the end user or any third party for any loss or damage, direct or indirect, from the use of this documentation, including without limitation, lost profits, business interruption, goodwill, or lost data, even if CA is expressly advised of such loss or damage.

The use of any product referenced in this documentation and this documentation is governed by the end user’s applicable license agreement.

The manufacturer of this documentation is Computer Associates International, Inc.

Provided with “Restricted Rights” as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections 52.227-19(c)(1) and (2) or DFARS Section 252.227-7013(c)(1)(ii) or applicable successor provisions.

2005 Computer Associates International, Inc.

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

Contents

Chapter 1. Using Unicenter CA-Driver Job Management for VSE . . . . 1-11.1 Using Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

1.1.1 Cataloging Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.1.2 Protecting Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.1.3 Calling Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31.1.4 Calling Partition-Dependent Procedures . . . . . . . . . . . . . . . 1-41.1.5 Nesting Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-51.1.6 Including Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-61.1.7 Verifying Data Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . 1-81.1.8 Passing CP Commands . . . . . . . . . . . . . . . . . . . . . . . . . 1-9

1.1.8.1 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-91.1.8.2 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9

1.2 Using Variable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 1-101.2.1 Partition-Dependent Variables . . . . . . . . . . . . . . . . . . . . 1-111.2.2 Reserved-Name Variable Parameters . . . . . . . . . . . . . . . . 1-12

1.2.2.1 Unicenter CA-Driver for VSE Reserved-Name VariableParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13

1.2.2.2 Unicenter CA-Scheduler/Unicenter CA-Driver for VSEReserved-Name Variable Parameters . . . . . . . . . . . . . . . . . 1-15

1.2.3 Substrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-171.2.4 Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-181.2.5 Variable Parameter Substrings . . . . . . . . . . . . . . . . . . . . 1-191.2.6 Variable Parameter Arrays . . . . . . . . . . . . . . . . . . . . . . 1-191.2.7 Null Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-201.2.8 Attribute Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21

1.2.8.1 Type Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-221.2.8.2 Length Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . 1-221.2.8.3 Number Attribute . . . . . . . . . . . . . . . . . . . . . . . . . 1-23

1.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-241.3.1 Unicenter CA-Driver for VSE Functions . . . . . . . . . . . . . . 1-34

1.3.1.1 Arithmetic Date Functions . . . . . . . . . . . . . . . . . . . . 1-341.3.1.2 Date Conversion Functions . . . . . . . . . . . . . . . . . . . 1-351.3.1.3 Day-of-Month Functions . . . . . . . . . . . . . . . . . . . . . 1-38

1.3.2 Unicenter CA-Scheduler/Unicenter CA-Driver for VSE Functions 1-401.3.2.1 Day-of-Month Functions . . . . . . . . . . . . . . . . . . . . . 1-401.3.2.2 Day-of-Period Functions . . . . . . . . . . . . . . . . . . . . . 1-481.3.2.3 Relative Date Functions . . . . . . . . . . . . . . . . . . . . . . 1-53

1.4 Using Conditional Procedure Expansion . . . . . . . . . . . . . . . . . 1-621.4.1 Defining Step Names (-STEP) . . . . . . . . . . . . . . . . . . . . . 1-62

Contents iii

1.4.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-631.4.2 Branching (-GOTO) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-63

1.4.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-631.4.3 Defining Conditions (-IF) . . . . . . . . . . . . . . . . . . . . . . . 1-64

1.4.3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-651.4.3.2 Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-651.4.3.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-65

1.4.4 Including Input from an IBM Source Library (-INPUT) . . . . . 1-671.4.4.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-67

1.4.5 Setting Variable Parameters (-SET) . . . . . . . . . . . . . . . . . . 1-681.4.5.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-69

1.4.6 Controlling Loops (-LCTR) . . . . . . . . . . . . . . . . . . . . . . 1-691.4.6.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-70

1.4.7 Flushing a Procedure (-FLUSH) . . . . . . . . . . . . . . . . . . . 1-701.4.7.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-70

1.4.8 Aborting Procedure Expansion (-ABORT) . . . . . . . . . . . . . 1-701.4.8.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-70

1.4.9 Writing Messages to the Operator (-WTO) . . . . . . . . . . . . . 1-711.4.10 Accepting Operator Replies (-REPLY) . . . . . . . . . . . . . . . 1-72

1.4.10.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-721.5 Using Conditional Execution . . . . . . . . . . . . . . . . . . . . . . . . 1-73

1.5.1.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-731.5.2 User Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-74

1.5.2.1 USER variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-741.5.2.2 USR variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-74

1.5.3 Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-741.5.4 System Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-751.5.5 Conditional Execution Statements . . . . . . . . . . . . . . . . . . 1-76

1.5.5.1 Overriding Generation Options (COPTION) . . . . . . . . . 1-771.5.5.2 Identifying Step Names (STEP, DSTEP) . . . . . . . . . . . . 1-781.5.5.3 Unconditional Branching (GOTO, DGOTO) . . . . . . . . . . 1-781.5.5.4 Bypassing Steps (FLUSH) . . . . . . . . . . . . . . . . . . . . 1-791.5.5.5 Setting Values (SET) . . . . . . . . . . . . . . . . . . . . . . . . 1-791.5.5.6 Conditional Branching (IF, DIF) . . . . . . . . . . . . . . . . . 1-81

1.5.6 Conditional Execution Program Interfaces . . . . . . . . . . . . . 1-831.5.6.1 Setting Variables from a Program (CARSET) . . . . . . . . . 1-831.5.6.2 Testing Variables Program (CARTEST) . . . . . . . . . . . . 1-86

1.6 Accessing the Procedure Library (CARACC) . . . . . . . . . . . . . . 1-911.6.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-921.6.2 Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-93

1.7 Automatic Job Submission . . . . . . . . . . . . . . . . . . . . . . . . . 1-941.7.1 From a Unicenter CA-Driver for VSE Procedure . . . . . . . . . 1-94

1.7.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-961.7.2 From a User Program . . . . . . . . . . . . . . . . . . . . . . . . . 1-96

1.7.2.1 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-981.7.2.2 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-99

1.7.3 From the Operator Console . . . . . . . . . . . . . . . . . . . . . . 1-991.7.3.1 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1011.7.3.2 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-101

1.8 Enabling and Disabling Unicenter CA-Driver for VSE . . . . . . . . . 1-1021.8.1 Enabling/Disabling with // CARCTL Commands . . . . . . . . 1-102

iv Unicenter CA-Driver for VSE Reference Guide

1.8.2 Enabling/Disabling with AR Commands . . . . . . . . . . . . . . 1-1031.9 Checking Status and Statistics . . . . . . . . . . . . . . . . . . . . . . . 1-1041.10 Procedure Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-105

1.10.1.1 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1051.10.1.2 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-106

1.11 Procedure Punching . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1071.12 Accessing the BrightStor CA-Dynam/T Catalog . . . . . . . . . . . 1-108

1.12.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-109

Chapter 2. Unicenter CA-Driver for VSE Commands . . . . . . . . . . . 2-12.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

2.1.1 Procedure Library Integrity . . . . . . . . . . . . . . . . . . . . . . . 2-32.1.2 Duplicate Update Protection . . . . . . . . . . . . . . . . . . . . . . 2-32.1.3 Executing CARUTIL . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

2.2 Coding Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52.2.1 Coding User-Supplied Values . . . . . . . . . . . . . . . . . . . . . . 2-62.2.2 Coding Variable Parameters . . . . . . . . . . . . . . . . . . . . . . 2-6

2.2.2.1 Assigning a Default Value . . . . . . . . . . . . . . . . . . . . . 2-72.2.2.2 Variable Parameter Arrays . . . . . . . . . . . . . . . . . . . . . 2-72.2.2.3 Supplying Values on the PROC Statement . . . . . . . . . . . 2-82.2.2.4 Multiple Variable Parameters . . . . . . . . . . . . . . . . . . . 2-82.2.2.5 Referencing Variable Parameters in the Procedure . . . . . . 2-92.2.2.6 Using Variable Parameters in Nested Procedures . . . . . . . 2-92.2.2.7 Shifting During Expansion . . . . . . . . . . . . . . . . . . . . 2-10

2.2.3 Disguising Job Control Statements . . . . . . . . . . . . . . . . . . 2-112.3 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-132.4 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

2.4.1 -CONTCHAR Command . . . . . . . . . . . . . . . . . . . . . . . 2-142.4.1.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-142.4.1.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

2.4.2 -CTLCHAR Command . . . . . . . . . . . . . . . . . . . . . . . . . 2-152.4.2.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152.4.2.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15

2.4.3 -DEBUG Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152.4.3.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-162.4.3.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-172.4.3.3 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-172.4.3.4 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18

2.4.4 -DISPLAY Command . . . . . . . . . . . . . . . . . . . . . . . . . . 2-192.4.4.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-192.4.4.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19

2.4.5 -LIB Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-202.4.5.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-202.4.5.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-202.4.5.3 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-202.4.5.4 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212.4.5.5 Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21

2.4.6 -LIB COR Command . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212.4.6.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212.4.6.2 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22

Contents v

2.4.6.3 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-222.4.7 -LIB PRINT,SCAN Parameters . . . . . . . . . . . . . . . . . . . . 2-22

2.4.7.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-222.4.7.2 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-232.4.7.3 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23

2.4.8 -LIB REPORT Command . . . . . . . . . . . . . . . . . . . . . . . 2-242.4.8.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-242.4.8.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25

2.4.9 -LIB STATUS Command . . . . . . . . . . . . . . . . . . . . . . . . 2-252.4.9.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-252.4.9.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25

2.4.10 -OVERRIDE Command . . . . . . . . . . . . . . . . . . . . . . . . 2-262.4.10.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-262.4.10.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26

2.4.11 -PROC Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-262.4.11.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-262.4.11.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-262.4.11.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27

2.4.12 -PROC COR Command . . . . . . . . . . . . . . . . . . . . . . . . 2-272.4.12.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-272.4.12.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-272.4.12.3 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-272.4.12.4 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-282.4.12.5 Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-292.4.12.6 Example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29

2.4.13 -PROC Create Option . . . . . . . . . . . . . . . . . . . . . . . . . 2-302.4.13.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-302.4.13.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-302.4.13.3 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-312.4.13.4 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-312.4.13.5 Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-312.4.13.6 Example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32

2.4.14 -PROC Delete Option . . . . . . . . . . . . . . . . . . . . . . . . . 2-322.4.14.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-322.4.14.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32

2.4.15 -PROC Delete Saved Option . . . . . . . . . . . . . . . . . . . . . 2-332.4.15.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-332.4.15.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-33

2.4.16 -PROC Punch Option . . . . . . . . . . . . . . . . . . . . . . . . . 2-332.4.16.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-332.4.16.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-332.4.16.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34

2.4.17 -PROC Print Option . . . . . . . . . . . . . . . . . . . . . . . . . . 2-342.4.17.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-342.4.17.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-342.4.17.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34

2.4.18 -PROC Release Option . . . . . . . . . . . . . . . . . . . . . . . . 2-342.4.18.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-352.4.18.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35

2.4.19 -PROC Replace Option . . . . . . . . . . . . . . . . . . . . . . . . 2-352.4.19.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35

vi Unicenter CA-Driver for VSE Reference Guide

2.4.19.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-352.4.19.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35

2.4.20 -PROC Select Option -ADD Command . . . . . . . . . . . . . . 2-362.4.20.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-362.4.20.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-362.4.20.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37

2.4.21 -PROC Select Option -COR Command . . . . . . . . . . . . . . 2-372.4.21.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-372.4.21.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-372.4.21.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37

2.4.22 -PROC Select Option -DEL Command . . . . . . . . . . . . . . . 2-382.4.22.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-382.4.22.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-382.4.22.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38

2.4.23 -PROC Select Option -REP Command . . . . . . . . . . . . . . . 2-392.4.23.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-392.4.23.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-392.4.23.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39

2.4.24 -PROC Select Option Change Parameter . . . . . . . . . . . . . 2-402.4.24.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-402.4.24.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-402.4.24.3 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-402.4.24.4 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-41

2.4.25 -PROC Select Option Delete Parameter . . . . . . . . . . . . . . 2-412.4.25.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-412.4.25.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-412.4.25.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-41

2.4.26 -PROC Punch Toggle . . . . . . . . . . . . . . . . . . . . . . . . . 2-422.4.26.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-422.4.26.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-422.4.26.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-42

2.4.27 -PROC Print Toggle . . . . . . . . . . . . . . . . . . . . . . . . . . 2-432.4.27.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-432.4.27.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-432.4.27.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-43

2.4.28 -PROC Rename Option . . . . . . . . . . . . . . . . . . . . . . . . 2-432.4.28.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-432.4.28.2 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-432.4.28.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44

2.4.29 -SEL Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-442.4.29.1 Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-442.4.29.2 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-452.4.29.3 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-452.4.29.4 Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45

2.5 Issuing CICS Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 2-462.5.1 Command Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-472.5.2 Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48

2.5.2.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48

Chapter 3. Online Driver Procedure Maintenance . . . . . . . . . . . . . 3-1

Contents vii

3.1 Driver Procedure Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33.1.1.1 Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

3.2 Displaying Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-53.3 Altering Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-63.4 Defining Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-73.5 Copying Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Chapter 4. Audit Events for Unicenter CA-Driver for VSE . . . . . . . . 4-14.1 Event Notification Selection . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

4.1.1.1 Prompt Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24.1.1.2 Command Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

4.2 AUDIT Data Set Directory - Unicenter CA-Driver for VSE(AUDT-1G00) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

4.2.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-44.2.2 Changing Selection Criteria . . . . . . . . . . . . . . . . . . . . . . . 4-54.2.3 Local Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-54.2.4 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

4.3 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G10) . . . . . . . . . 4-64.3.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-74.3.2 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

4.4 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G20) . . . . . . . . . 4-84.4.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-84.4.2 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9

4.5 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G30) . . . . . . . . 4-104.5.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-104.5.2 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

4.6 AUDIT Master Key Detail - CA-DRIVER (AUDT-1G40) . . . . . . . 4-124.6.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-124.6.2 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

4.7 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G50) . . . . . . . . 4-134.7.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-134.7.2 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14

4.8 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G60) . . . . . . . . 4-154.8.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-154.8.2 Local Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-164.8.3 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16

4.9 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G61) . . . . . . . . 4-174.9.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-174.9.2 Local Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-184.9.3 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18

4.10 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G70) . . . . . . . . 4-194.10.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-194.10.2 Local Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-204.10.3 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

4.11 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G80) . . . . . . . . 4-214.11.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-214.11.2 Local Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-224.11.3 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22

4.12 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G81) . . . . . . . . 4-234.12.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-234.12.2 Local Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24

viii Unicenter CA-Driver for VSE Reference Guide

4.12.3 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-244.13 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G90) . . . . . . . . 4-25

4.13.1 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-254.13.2 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26

Appendix A. Editor Commands . . . . . . . . . . . . . . . . . . . . . . . . A-1A.1 Protecting and Highlighting LInes . . . . . . . . . . . . . . . . . . . . A-2A.2 Defining, Copying, or Altering Unicenter CA-Driver for VSE

Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3A.3 Adding, Deleting, Copying, and Moving Lines . . . . . . . . . . . . A-5

A.3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5A.3.1.1 Changing the Current Line . . . . . . . . . . . . . . . . . . . A-5A.3.1.2 Adding Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6A.3.1.3 Deleting Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7A.3.1.4 Copying Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8A.3.1.5 Moving Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9A.3.1.6 Duplicating Lines . . . . . . . . . . . . . . . . . . . . . . . . . A-10

A.4 PF Key Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11

Appendix B. Event Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

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

Contents ix

Chapter 1. Using Unicenter CA-Driver JobManagement for VSE

Unicenter® CA-Driver® Job Management for VSE (Unicenter CA-Driver forVSE) is a powerful JCL and runtime management tool that can workhand-in-hand with Unicenter CA-Scheduler for VSE or as a stand-alone facility.Unicenter CA-Driver for VSE simplifies the normal operations of a data centerand provides a much needed approach to enhancing the restart/recoverycapabilities of jobs with minimal operator intervention.

If you are a Unicenter CA-Scheduler/Unicenter CA-Driver for VSE user, youcan define jobs to Unicenter CA-Scheduler for VSE that store their JCL withUnicenter CA-Driver for VSE-managed procedures. Unicenter CA-Driver forVSE controls the expansion of these procedures based upon values that yousupply.

When defining jobs to Unicenter CA-Scheduler for VSE that find their JCL inUnicenter CA-Driver for VSE procedures, Unicenter CA-Scheduler for VSE willalso ask you to define normal runtime parameters and rerun runtimeparameters. The normal runtime parameters will be passed from SCHEDULERto DRIVER when it is time to submit the job. The screen (DRIVER restartparms) parameters will be passed from SCHEDULER to DRIVER whenever thejob is being rerun via the Unicenter CA-Scheduler for VSE RERUN command.Thus, this facility gives you the flexibility to have your DRIVER proceduresexpanded differently depending on the circumstances at the time.

Unicenter CA-Driver for VSE also provides you with the ability to test VSEcompletion codes and the $RC and $MRC system variables on VSE/SP systemsbetween steps of a job. The results of these tests can be used to execute stepsof a job conditionally.

Chapter 1. Using Unicenter CA-Driver Job Management for VSE 1-1

1.1 Using Procedures


The following topics describe the various procedures in running UnicenterCA-Driver for VSE.

1.1.1 Cataloging ProceduresAfter the Unicenter CA-Driver for VSE procedure library is formatted (see theSystems Programmer Guide), you can begin cataloging procedures. To catalog anew procedure, execute CARUTIL with OPTION=CREATE on the -PROCcontrol statement and supply the name of the procedure. (The -PROCcommand and CARUTIL execution requirements are explained in detail underUnicenter CA-Driver for VSE Batch Library Maintenance.)

This job stream catalogs a procedure named PVTLABS, which will contain thelabel information necessary to compile a program:

// JOB CARUTIL EXAMPLE OF CREATING A PROC

// EXEC CARUTIL,SIZE=32K

-PROC PVTLABS,OPTION=CREATE

// DLBL IJSYS�1,'SYS��1 WORK FILE',79/��1,SD

// EXTENT SYS��1,T338�A,,,1,24


// EXTENT SYS��2,T338�A,,,24,24


// EXTENT SYS��3,T338�A,,,48,24

// DLBL IJSYSLN,'SYSLNK WORK FILE',79/��1,SD

// EXTENT SYSLNK,T338�A,,,72,36

-END

/�

/&

The statements between the -PROC and -END statements are now thePVTLABS procedure. To change any of the characteristics of these labels (likesize, location, file-id), only the PVTLABS procedure needs to be changed.

1.1.2 Protecting ProceduresYou may protect a procedure against unauthorized use and update by defininga READ password (RPW) and a WRITE password (WPW). Since the READpassword is visible in the JCL, the WRITE password must also be defined toensure that the procedure is not changed without valid update authority.However, if you want to protect against unauthorized update only and notagainst unauthorized use, you can define just a WRITE password.

Define the passwords on the -PROC statement when you catalog or update theprocedure:

-PROC PROCNAME,OPTION=CREATE,WPW=ABC,RPW=XYZ

1-2 Unicenter CA-Driver for VSE Reference Guide


From then on, the READ password must be supplied to retrieve the procedureor else an error message is issued:

// PROC PROCNAME(XYZ)

The WRITE password must be supplied to maintain the procedure:

-PROC PROCNAME,OPTION=SELECT,PRINT=YES,WPW=ABC

To change the READ password, specify the current password followed by thenew password. In this example, the READ password is being changed to RST.Note that the WRITE password must also be specified to access the procedure:

-PROC PROCNAME,WPW=ABC,RPW=XYZ=RST

To change the WRITE password, specify the current password followed by thenew password. This example changes the WRITE password to DEF.

-PROC PROCNAME,WPW=ABC=DEF

To remove password protection from a procedure, give the WRITE password,the current password and specify the new READ password as 'DELETE':

-PROC PROCNAME,WPW=ABC,RPW=XYZ='DELETE'

To remove WRITE protection, specify the new WRITE password as 'DELETE'.If there is a READ password, it will also be removed:

-PROC PROCNAME,WPW=ABC='DELETE'

1.1.3 Calling ProceduresOnce a procedure is cataloged in the Unicenter CA-Driver for VSE procedurelibrary, Unicenter CA-Driver for VSE replaces each PROC statement thatnames that procedure with the contents of the procedure. Therefore, eachoccurrence of the statement// PROC PVTLABS on an input job stream is replaced by the statements inthe PVTLABS procedure.



This is the input job stream that calls the PVTLABS procedure:

// JOB ASSEMBLE THE DRIVER GENERATION MACRO

// PROC PVTLABS

// EXEC ASSEMBLY

CAIRGEN

END

/�

/&

This is the expanded job stream that Unicenter CA-Driver for VSE submits toPOWER for execution:



// EXTENT SYS��1,T338�A,,,1,24


// EXTENT SYS��2,T338�A,,,24,24


// EXTENT SYS��3,T338�A,,,48,24



// EXEC ASSEMBLY

CAIRGEN

END

/�

/&

Note: The job streams that use the PVTLABS procedure to generate labels forthe assembly will automatically be expanded with the updated labelinformation.

If the PROC statement tries to reference a procedure that doesn't existin the library (for example, if PVTLABS were misspelled PUTLABS),the statement is passed to POWER and subsequently to VSE with thefirst slash changed to an asterisk (*) and the second slash changed to ablank. An error message will then appear on the console and the jobwill be cancelled.

1.1.4 Calling Partition-Dependent ProceduresIf procedures are partition-dependent, you can use the partition ID as the firsttwo characters of the procedure name when you catalog them. Now you donot have to manually submit different job streams to call the right procedure.Instead, you can set up a standard job stream and code the // PROCstatement with the symbolic partition identifier prefix &P as the first twocharacters in the procedure name. When you submit this job stream, UnicenterCA-Driver for VSE automatically replaces &P with the ID of the partition inwhich the job will run and retrieves the right procedure for that partition.

For example, set up the job stream to call the ASSGN procedure with thisPROC statement:



// PROC &PASSGN

If this job will be processed in the background partition, Unicenter CA-Driverfor VSE will retrieve and expand the procedure cataloged as BGASSGN. If thejob will be processed in foreground 2, Unicenter CA-Driver for VSE willretrieve and expand procedure F2ASSGN. This partition ID substitution takesplace even if the partition-dependent PROC statement is nested in anotherprocedure.

The partition ID is calculated in the following ways:

■ For jobs submitted using Unicenter CA-Scheduler, the partition ID is theone in which Unicenter CA-Scheduler for VSE is executing because this isthe partition in which the Unicenter CA-Driver for VSE preprocessor runs.

■ For other jobs, Unicenter CA-Driver for VSE determines the partition fromthpartition in which the preprocessor executes.

■ For Unicenter CA-Scheduler/Unicenter CA-Driver for VSE systems thathave the CAIRGEN option PARTEXP=Y, the id is determined from thepartition in which the preprocessor executes.

1.1.5 Nesting ProceduresOne cataloged procedure can contain a PROC statement which calls anothercataloged procedure. In turn, that procedure can contain a PROC statementwhich calls a third procedure. Each time a procedure calls another procedure,this is considered to be a level of nesting. The number of levels of nesting thatmay occur is determined by the NESTS= generation option.

You can use procedure nesting to catalog commonly used pieces of JCL anddata (especially data tables) as separate procedures. These procedures can thenbe retrieved, as needed, by nesting them in other procedures. If one of theseseparate procedures needs modification, you only need to make the changes tothat one procedure. When the procedure is called by another procedure, theupdated version is automatically retrieved; so the expanded job stream reflectsall changes.

To illustrate nesting, the assembly job used earlier can be cataloged asprocedure DRIVGEN. This procedure contains a PROC statement which callsthe PVTLABS procedure: (Note that the // PROC statement and job controlstatements must be disguised so they can be cataloged as part of a procedurewithout being acted upon.)



// JOB CARUTIL CATALOG A PROCEDURE


-PROC DRIVGEN,OPTION=CREATE

%/ JOB ASSEMBLE THE DRIVER GENERATION MACRO

%/ PROC PVTLABS

%/ EXEC ASSEMBLY

CAIRGEN

END

%�

%&

-END

/�

/&

It is now possible to run the entire job by submitting just one statement withPOWER JECL:

� $$ JOB JNM=DRIVGEN

// PROC DRIVGEN

� $$ EOJ

The expanded job stream submitted to POWER for execution would includethe contents of both procedures:




// EXTENT SYS��1,T338�A,,,1,24


// EXTENT SYS��2,T338�A,,,24,24


// EXTENT SYS��3,T338�A,,,48,24



// EXEC ASSEMBLY

CAIRGEN

END

/�

/&

� $$ EOJ

If the labels need to be moved or enlarged, only the procedure PVTLABS needbe modified to reflect the changes. When DRIVGEN calls PVTLABS, itautomatically retrieves PVTLABS in its updated form.

1.1.6 Including DataYou can design a procedure to stop expansion at predefined points, read oneor more records from the POWER queue, and continue expansion of theprocedure from the stopping point.

This is useful for job streams that process data which changes each time thejob is run and for those jobs which read data such as date statement data.



To use this facility, insert a // DATA statement in the procedure at the pointat which you want expansion to stop. Unicenter CA-Driver for VSE willreplace the // DATA statement with the statement(s) that follow the // PROCstatement in the input job stream. When Unicenter CA-Driver for VSE reachesa null // PROC statement (a // PROC statement with no procedure name), itwill return to the procedure and continue expansion.

For example, we could have designed procedure DRIVGEN so that thegeneration options are submitted from the card reader rather than from withinthe procedure itself. Instead of including CAIRGEN in the procedure, we usethe // DATA statement at the same point:

// JOB CARUTIL - CATALOG PROCEDURE DSERV




%/ PROC PVTLABS

%/ EXEC ASSEMBLY

// DATA

END

%�

%&

-END

/�

/&

Then we include the control statement CAIRGEN on the input job streamfollowed by a null // PROC statement. (A comma in the null // PROCstatement replaces the procedure name so that comments can follow.)


// PROC DRIVGEN ...To retrieve the procedure

CAIRGEN ...This is the data

// PROC , ...This is the end-of-data statement

� $$ EOJ

Unicenter CA-Driver for VSE will replace the // DATA statement withCAIRGEN.

You can use as many data statements as you want in a procedure. Each datastatement will direct Unicenter CA-Driver for VSE back to the POWER readerqueue until a null PROC is found.



1.1.7 Verifying Data InclusionTo ensure that the correct data is inserted into the expanded procedure at theappropriate places, you can use a verification name on each data statementand the same name on the null PROC statement which terminates that data. Ifthe name on the data statement and the name on the null PROC are not thesame, Unicenter CA-Driver for VSE will flag the condition as an error. Theverification name must be 1-8 alphanumeric characters, beginning with anAlpha character, and does not have to relate to the name of the procedure. Thesame name must be coded on the null PROC statement in the input job stream,preceded by a comma.

This example catalogs the same procedure with a data verification name:





%/ PROC PVTLABS

%/ EXEC ASSEMBLY

// DATA CAIRGEN1

END

%�

%&

-END

/�

/&

The same verification name is coded on the null PROC statement whichsignals the end of the data inclusion statements:

// PROC DRIVGEN ...To call procedure

DSPLY SD

// PROC ,CAIRGEN1 ...To end data and give verification name



1.1.8 Passing CP CommandsUnicenter CA-Driver for VSE provides a VM interface which allows aprocedure to pass CP commands to the VM machine. These commands can beexecuted by Unicenter CA-Driver for VSE procedures at any time required.Any CP command may be issued with the exception of LOGOFF andDISCONNECT. Any number of commands may be placed anywhere withinthe procedure. Consecutive commands are allowed. The CP commands areperformed at execution time. The format of the command is as follows :

// VM CP command

1.1.8.1 Example 1

-PROC CPMSG,OPTION=CREATE,PARM=(TEXT)

// VM CP MESSAGE OPERATOR &TEXT

� &TEXT MESSAGE SENT TO VM OPERATOR

-END

The message text is supplied on the // PROC statement:

// PROC CPMSG,TEXT='HELLO FROM CPMSG'

1.1.8.2 Example 2

-PROC CPPROC,OPTION=CREATE

// VM CP LINK DASD 37� 37� W

� JOB WILL LINK TO DASD 37� FOR THIS PROC ONLY

// PROC CPJOB

// VM CP DET 37�

// VM CP QUERY DASD

-END


1.2 Using Variable Parameters


Each procedure in the Unicenter CA-Driver for VSE library may contain asmany as 65 symbolic parameters, each starting with an alphabetic characterand from one to seven characters in length. No special characters are allowed.When the procedure is expanded into the POWER reader queue, thesesymbolic parameters are replaced by a default value or by variable informationthat is specified on the // PROC statement. This allows you to developgeneralized procedures and use variable parameters to make them specific to avariety of circumstances.

Variable parameters are identified to Unicenter CA-Driver for VSE by namingthem on the -PROC statement used to catalog the procedure as PARM values.The default value can also be defined at this time and can be overridden laterby a value on the PROC statement. If no default value is defined at this time, avalue must be specified on the PROC statement. (See 'Coding VariableParameters' in the next chapter.)

Variable parameters are referenced throughout the procedure by preceding thevariable parameter name with an ampersand (&). In this example, the variableparameter is SIZE which is given the default value of 64K. UnicenterCA-Driver for VSE will replace every occurrence of &SIZE in the procedurewith 64K unless another value for SIZE is supplied on the // PROC statement:



-PROC DRIVGEN,OPTION=CREATE,PARM=(SIZE=64K)


%/ PROC PVTLABS

%/ EXEC ASSEMBLY,SIZE=&SIZE

CAIRGEN

END

%�

%&

-END

/�

/&

The statement // PROC DRIVGEN would cause the procedure to be expandedas:






// EXTENT SYS��1,T338�A,,,1,24


// EXTENT SYS��2,T338�A,,,24,24


// EXTENT SYS��3,T338�A,,,48,24



// EXEC ASSEMBLY,SIZE=64K

CAIRGEN

END

/�

/&

� $$ EOJ

The statement // PROC DRIVGEN,SIZE=100K supplies an overriding value(100K) for the parameter size and would cause the procedure to be expandedas:




// EXTENT SYS��1,T338�A,,,1,24


// EXTENT SYS��2,T338�A,,,24,24


// EXTENT SYS��3,T338�A,,,48,24



// EXEC ASSEMBLY,SIZE=1��K

CAIRGEN

END

/�

/&

� $$ EOJ

1.2.1 Partition-Dependent VariablesThe default value PART-ID has a reserved meaning. When it is specified onthe PARM statement, its symbolic parameter will be replaced during expansionby the two-character ID of the partition in which the job is to be run.

The partition ID is calculated in either of two ways:

■ For jobs submitted using Unicenter CA-Scheduler, the partition ID is theone in which Unicenter CA-Scheduler for VSE is executing because this isthe partition in which the Unicenter CA-Driver for VSE preprocessor runs.

■ For other jobs, Unicenter CA-Driver for VSE determines the partition fromthe partition in which the preprocessor executes.



■ For Unicenter CA-Scheduler/Unicenter CA-Driver for VSE systems thathave the AIRGEN option PARTEXP=Y, the id is determined from thepartition in which the preprocessor executes.

This example demonstrates the use of a partition dependent variable parameterin addition to the variable parameter &SIZE shown previously:



-PROC PVTLABS,OPTION=CREATE,PARM=(SIZE=64K,XYZ=PART-ID)

// DLBL IJSYS�1,'&XYZ SYS��1 WORK FILE',79/��1,SD

// EXTENT SYS��1,T338�A,,,1,24


// EXTENT SYS��2,T338�A,,,24,24


// EXTENT SYS��3,T338�A,,,48,24

// DLBL IJSYSLN,'&XYZ SYSLNK WORK FILE',79/��1,SD


-END

/�

/&

The procedure is called by this PROC statement:

// PROC DRIVGEN,SIZE=8�K

If it is to be processed in the background partition, it would be expanded as:



// DLBL IJSYS�1,'BG SYS��1 WORK FILE',79/��1,SD

// EXTENT SYS��1,T338�A,,,1,24


// EXTENT SYS��2,T338�A,,,24,24


// EXTENT SYS��3,T338�A,,,48,24

// DLBL IJSYSLN,'BG SYSLNK WORK FILE',79/��1,SD


// EXEC ASSEMBLY,SIZE=1��K

CAIRGEN

END

/�

/&

� $$ EOJ

1.2.2 Reserved-Name Variable ParametersUnicenter CA-Driver for VSE provides a set of reserved-name variableparameters that you can reference anywhere that a variable parameter can bereferenced in a Unicenter CA-Driver for VSE procedure. Values areautomatically assigned by either Unicenter CA-Driver for VSE or UnicenterCA-Scheduler for VSE when the reserved-name variable parameter isreferenced during procedure expansion. These reserved-name variable



parameters cannot be defined in a DPROC statement, and assigned valuescannot be changed using the SET statement. All reserved-name variableparameters begins with &C_ to avoid conflicts with variable names defined onthe DPROC statement.

Reserved-name variable parameters fall into two categories: those supportedby Unicenter CA-Driver for VSE and those supported by UnicenterCA-Scheduler/Unicenter CA-Driver for VSE. The Unicenter CA-Driver forVSE reserved-name variable parameters can be used by any ComputerAssociates product (including Unicenter CA-Scheduler.) that is compatible withUnicenter CA-Driver for VSE. The Unicenter CA-Scheduler/UnicenterCA-Driver for VSE. reserved-name variable parameters are available only toUnicenter CA-Scheduler for VSE with Unicenter CA-Driver for VSE active.

1.2.2.1 Unicenter CA-Driver for VSE Reserved-Name Variable Parameters

The following table lists the reserved-name variable parameters that areoffered by Unicenter CA-Driver for VSE:

Some of the pre-7.2 releases of Unicenter CA-Driver for VSE did not follow thestandard naming conventions for reserved-name variable parameters andoffered variables that did not begin with &C_. Those old variable parameternames are supported when you set OLDVNAM=YES in the CAIRGENinstallation macro. (In this case, the new names for these reserved-namevariable parameters are also supported.) We strongly recommend that you donot use the old names unless you have procedures that already use thosenames. We also recommend that you convert to the new names as soon aspossible. The old names and their r7.2+ equivalents are displayed in the tablebelow:

Parameter Contents

&C_DATE Current system date in mm/dd/yy format (dd/mm/yyin Europe)

&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, etc.)

&C_MONTH Current month name (JANUARY, FEBRUARY, etc.)

&C_YEAR Current year (2003, 2004, etc.)

Pre-7.2 Variable Name r7.2+ Equivalent

&DATE &C_DATE

&JDATE &C_JDATE

&TIME &C_TIME



Pre-7.2 Variable Name r7.2+ Equivalent

&DAY &C_DAY

&MONTH &C_MONTH



Example

This example procedure uses four of the Unicenter CA-Driver for VSEreserved-name variable parameters:

-PROC TIMER

� IT IS &C_TIME ON &C_DAY IN &C_MONTH AND THE DATE IS &C_DATE

-END

The procedure would be retrieved with the following statement:

// PROC TIMER

and would be expanded like this:

� IT IS 1�.35.45 ON MONDAY IN OCTOBER AND THE DATE IS 1�/�1/94

1.2.2.2 Unicenter CA-Scheduler/Unicenter CA-Driver for VSE Reserved-NameVariable Parameters

The following reserved-name variable parameters are offered by UnicenterCA-Scheduler for VSE with Unicenter CA-Driver for VSE active:

Autoscan Information

Parameter Contents

&C_AUTDT Current autoscan Julian date

&C_AUTIM AUTOSCAN time



Job Information

Job Rerun Information

These reserved-name variable parameters are available only after the job hasbeen run at least once.

Parameter Contents

&C_JNAME Unicenter CA-Scheduler for VSE job name

&C_SNAME Unicenter CA-Scheduler for VSE schedule name

&C_JNO Unicenter CA-Scheduler for VSE job number

&C_SELRC Reason code for selecting the job

&C_DTAB Datetable used to select the job

&C_CAL Calendar used to select the job (if not datetable)

&C_JOBDT Date the job was selected to run (Julian)

&C_SYSID POWER SYSID controlling the job

&C_CMD Command causing job submission (RUN, SUBMIT,RERUN, etc.)

&C_RUNCD Julian date used on RUN command

Parameter Contents

&C_ABCC Completion code

&C_ABCT Abend count (number of times the job occurrenceabended)

&C_ABSTP Abending step name

&C_SPWR# POWER job number for Unicenter CA-Scheduler forVSE jobs



1.2.3 SubstringsYou can reference part of the value given to a variable parameter instead ofthe entire value. To do this, specify two numbers in parentheses following theparameter name:

&parmname(n,m)

where:

n = the location within the value of the start of the substring.m = the length of the substring (one or more bytes).

These examples show how the two numbers identify the substring that isbeing referenced:

Substrings can also be identified by variable parameters that representnumbers. This is illustrated below:

These sample control statements show how procedure expansion can be basedon the contents of a substring, rather than on the entire parameter value:

Parameter Value Substring Reference SubstringValue

&VAR1 HOWDY &VAR1(1,2) HO

&VAR1 93 &VAR1(2,1) 9

Parameter Value Substring Reference SubstringValue

&VAR2 4

&VAR3 2

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



This Control Statement References A Substring On OrderTo

-IF &C_DATE(1,2) NE 01 GOTOMONTHERR

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

-IF &C_DATE(3,1) NE '/' GOTOERROR

Check for a slash in the date (3rdposition)

-SET &VAR1=&C_DATE(7,2) Set VAR1 equal to year portion ofdate value (7th and 8th positions)

-IF &VAR1(&VAR2,&VAR3) EQ 9GOTO OK1

Test only part of VAR1 (VAR2 andVAR3 represent numbers)

1.2.4 Global VariablesUp to eight global variable values can be shared by all procedures in a job:

&C_GLBL1 &C_GLBL2 &C_GLBL3 &C_GLBL4

&C_GLBL5 &C_GLBL6 &C_GLBL7 &C_GLBL8

These variables are used in the same way as PARM variables, but they are notto be defined on the PARM field when the procedure is cataloged. Instead,they are set in -SET statements and referenced in -IF statements anywhere inthe procedure. They are only reset at end of job.

You can use these variables for inter-procedure communication. For example, aglobal variable may be set to a value in one procedure, and that same valuecan be retrieved in another procedure elsewhere in the job. Global variablesmay also be used to pass values between nested procedures.

Some of the pre-7.2 releases of Unicenter CA-Driver for VSE did not follow thestandard naming conventions for reserved-name variable parameters andoffered variables that did not begin with &C_. Those old variable parameternames are supported when you set OLDVNAM=YES in the CAIRGENinstallation macro. (In this case, the new names for these reserved-namevariable parameters are also supported.) We strongly recommend that you donot use the old names unless you have procedures that already use thosenames. We also recommend that you convert to the new names as soon aspossible.



1.2.5 Variable Parameter SubstringsYou can reference part of the value given to a variable parameter instead ofthe entire value. To do this, add two numbers to the variable that identify thesubstring by:

■ the location within the character string of the start of the substring

■ the length of the substring (one or more bytes)

In this example of conditional expansion, the DATE parameter is tested for theyear only. The year value is identified as the 7th and 8th positions in theDATE value:

-IF &C_DATE(1,2) NE �1 GOTO MONTHERR ... Verify month is valid

-SET &VAR1=&C_DATE(7,2) ... Set &VAR1 equal to year

-IF &VAR1(&VAR2,&VAR3) EQ 9 GOTO OK1

-IF &C_DATE(3,1) NE '/' GOTO ERROR ... Check date format

These examples illustrate that the substring can be identified by eithernumbers or by variable parameters that represent numbers:

VariableName

Variable Substring Reference Segment Value

&VAR1 HOWDY &VAR1(1,2) HO

&VAR1 99 &VAR1(2,1) 9

&VAR2 4

&VAR3 2

&VAR4 03/31/85 &VAR4(&VAR2,&VAR3) 31

1.2.6 Variable Parameter ArraysA variable parameter can be assigned multiple values or array elements. Toindicate that a variable parameter has an array of values, give the total numberof values in parentheses following the variable parameter name on the -PROCstatement. For example, PARM=(VAR(4)) indicates that a variable has fourvalues. When this procedure is expanded, each of these four values can beindividually referenced as:

&VAR(1)&VAR(2)&VAR(3)&VAR(4)



To define default values for any of these elements, specify the values inparentheses separated by commas in the order of the array elements. To omit adefault value, code two commas with no value in between:

-PROC NAME,PARM=(X(1�),Y(3)=(A,B,C), NAME(5)=(,,TESTJOB))

This example defines:

■ The variable parameter &X, which consists of ten elements in an array,none of which have default values.

■ The variable parameter &Y, which consists of three elements in an array,specifying default values for all three elements:

&Y(1) = A&Y(2) = B&Y(3) = C

■ The variable parameter &NAME, which consists of five elements in anarray, specifying a default value for the third element only.

Variable parameter arrays are updated, replaced, or deleted in the samemanner as simple variables. When a variable parameter array is deleted, allelements in the array are deleted; it is not possible to delete or replace a singleelement in an array.

When invoking a procedure, variable parameter array override values arespecified in the same manner as on the -PROC statement: by enclosing allvalues in parentheses and separating them with commas. Omitted values areindicated by the presence of contiguous commas:

// PROC NAME,VAR=(A,B,,D,,F)

This statement supplies overriding values for the first, second, fourth, andsixth elements of the variable parameter array VAR. The third and fifthelements would retain their default values.

1.2.7 Null ValuesA variable parameter or a variable parameter element must be associated witha value before it may be referenced or used during procedure expansion. Thismay be a null value. To define a null value on the procedure definition or //PROC statement, specify the default or override value as two special characterdelimiters with nothing in between:



// PROC NAME,Y=(1,2,'',4)

This example specifies override values for elements one through four of theparameter array &Y. The value for the third element is a null value. (If thedefault value were really supposed to be two apostrophes, you could useslashes as the delimiters: /''/). If &Y(3) is referenced in the procedure, it willbe replaced with nothing; the statement will be expanded as if the variableparameter reference is not there. Any concatenation character will also bedropped.

Note that a null value is different from having no value associated with avariable parameter. If a variable parameter has no default value assigned oroverride value supplied, an error message will be issued indicating that theprocedure cannot be expanded. If a variable parameter has a null default valueand no override is supplied, all references to the variable parameter areremoved and replaced with nothing.

The variable parameter &Y has a null value in the following examples. Duringexpansion, &Y is replaced with a null character string; therefore, it iseffectively removed from the expanded statement.

Procedure Statement Resulting Statement

// TLBL &Y.FILE,'DSN // TLBL FILE,'DSN'

// JOB TEST&Y // JOB TEST

1.2.8 Attribute TestingEvery variable parameter has associated with it two attributes: type andlength. Variable parameter arrays also have a third attribute: number. Eachattribute can be tested during conditional expansion using the followingformat:

Each attribute is described following.

Attribute Format

Type T'&VAR

Length L'&VAR

Number N'&VAR



1.2.8.1 Type Attribute

A variable parameter (or parameter array element) assumes one of four typeattributes as a result of its actual value, not as a result of either its definedvalue or how the value was stated (within delimiters or not):

To test the variable parameter for type, prefix it with T':

If The Value Is The Type Is

Character format C

Positive integer N

Negative integer M

Omitted (not the same as a nullvalue)

O

-IF T'&VAR1 EQ O GOTO CHARVALU

-IF T'&VAR2 EQ N GOTO ISNUMERC

Since variable parameters that are used in array indexing and segmentsubscripting must be positive integers (type N), it is a good idea to test thetype attribute of a variable parameter before using it for such a purpose.

1.2.8.2 Length Attribute

The length attribute of a variable parameter (or an element of an array) is thenumber of bytes of the associated value:

To test or otherwise use the length attribute in conditional expansionstatements, prefix the variable parameter with L':

If The Value Is The Length Is

CA-Driver for VSE 9

X 1

0049 4

(null) 0

27 2

-IF L'&VAR3 EQ � GOTO NOVALUE (zero length - null value)

-IF L'&VAR4 GT 4 GOTO TOOLARGE



1.2.8.3 Number Attribute

The number attribute gives the number of elements in a variable parameterarray.

To test a variable parameter for number, prefix it with N':

If The Variable Is Defined As The Number Is

A(6) 6

A(3) 3

A 1

-IF N'&VAR6 LT 1 GOTO NOVALUES

-IF N'&VAR7 EQ 5 GOTO DONEALL


1.3 Functions

1.3 Functions

Unicenter CA-Driver for VSE recognizes a set of predefined functions. AUnicenter CA-Driver for VSE function has a reserved name and accepts one ormore parameters. The general format of a function is:

function(parameter1,parameter2,..)

Function parameters may be absolute constants or may be coded as variableparameters containing valid values that the function expects. In either case,parameters values must be in valid format and must follow the order requiredby the function.

Unicenter CA-Driver for VSE functions are recognized on the right hand sideof the SET statement. To set a variable to the result of the predefined function,use the following format:

-SET variable=function(parameter1,parameter2,...)

For example,

-SET VAR1=DTADD(1,&C_JDATE)

The above statement adds one to the current system date and stores the resultin variable VAR1. (Note that all month end and leap-year adjustment isautomatically handled by the DTADD function.)

The primary value of these functions is that they can be used to automate yourJCL setup. By encoding the functions in your Unicenter CA-Driver for VSEprocedures, you eliminate the need for JCL staging and manual manipulation.Thus, data entry errors can be eliminated at the JCL staging station. Because allof the functions have parameters which accept or default to UnicenterCA-Driver for VSE variable parameters, the power of the functions and thevariable parameters can be combined.

To take a simple example, if your JCL setup requires entry of the job selectiondate each time it is run, you could instead call a simple Unicenter CA-Driverfor VSE procedure which uses the reserved-name variable parameter&C_JOBDT to obtain the date of job selection from Unicenter CA-Scheduler.By encoding &C_JOBDT as a parameter of any number of date conversionfunctions, you can alter its format to the one that is acceptable to your existingcode. Thus, you eliminate both the need to stage the JCL and the possibility ofdata entry errors. In addition, if jobs run days late, there is still no data entry


1.3 Functions

required because &C_JOBDT keeps track of the original job selection dateindefinitely. Keep in mind that this is a very simple example and that manymore sophisticated uses are available.

Some of the functions use datetables as parameters. This permits you to utilizeyour existing datetables to perform more complex date manipulation whichrequires the identification of working days, holidays, accounting days, or anyother cycle days you have defined. If the datetable parameter is left out, itdefaults to the datetable defined for the job. This is useful for codingprocedures which can handle a wide variety of jobs.

In addition, the functions perform more than simple arithmetic operationsbecause they take into account transitions between months, years, and periodsso that they return the expected values.

Functions fall into two categories: those supported by Unicenter CA-Driver forVSE and those supported by Unicenter CA-Scheduler/Unicenter CA-Driver forVSE. The Unicenter CA-Driver for VSE functions can be used by anyComputer Associates product (including Unicenter CA-Scheduler.) that iscompatible with Unicenter CA-Driver for VSE. The UnicenterCA-Scheduler/Unicenter CA-Driver for VSE functions are available only toUnicenter CA-Scheduler for VSE with Unicenter CA-Driver for VSE active.

Use the following Gregorian calendar to work out the provided examples.

January 2003

February 2003

SUN MON TUE WED THU FRI SAT

1 2 3 4

5 6 7 8 9 10 11

12 13 14 15 16 17 18

19 20 21 22 23 24 25

26 27 28 29 30 31


1

2 3 4 5 6 7 8

9 10 11 12 13 14 15

16 17 18 19 20 21 22

23 24 25 26 27 28


1.3 Functions

March 2003

April 2003

May 2003


1

2 3 4 5 6 7 8

9 10 11 12 13 14 15

16 17 18 19 20 21 22

23 24 25 26 27 28 28

29 30 31


1 2 3 4 5

6 7 8 90 10 11 12

13 14 15 16 17 18 19

20 21 22 23 24 25 26

27 28 29 30


1 2 3

4 5 6 7 8 9 10

11 12 13 14 15 16 17

18 19 20 21 22 23 24

25 26 27 28 29 30 31


1.3 Functions

June 2003

July 2003

August 2003


1 2 3 4 5 6 7

8 9 10 11 12 13 14

15 16 17 18 19 20 21

22 23 24 25 26 27 28

29 30


1 2 3 4 5

6 7 8 9 10 11 12

13 14 15 16 17 18 19

20 21 22 23 24 25 26

27 28 29 30 31


1 2

3 4 5 6 7 8 9

10 11 12 13 14 15 16

17 18 19 20 21 22 23

24 25 26 27 28 29 30

31


1.3 Functions

September 2003

October 2003

November 2003


1 2 3 4 5 6

7 8 9 10 11 12 13

14 15 16 17 18 19 20

21 22 23 24 25 26 27

28 29 30


1 2 3 4

5 6 7 8 9 10 11

12 13 14 15 16 17 18

19 20 21 22 23 24 25

26 27 28 29 30 31


1

2 3 4 5 6 7 8

9 10 11 12 13 14 15

16 17 18 19 20 21 22

23 24 25 26 27 28 29

30


1.3 Functions

December 2003

Use the following Julian calendar to work out the provided examples.

January 2003

February 2003


1 2 3 4 5 6

7 8 9 10 11 12 13

14 15 16 17 18 19 20

21 22 23 24 25 26 27

28 29 30 31


1 2 3 4

5 6 7 8 9 10 11

12 13 14 15 16 17 18

19 20 21 22 23 24 25

26 27 28 29 30 31


32

33 34 35 36 37 38 39

40 41 42 43 44 45 46

47 48 49 50 51 52 53

54 55 56 57 58 59


1.3 Functions

March 2003

April 2003

May 2003


60

61 62 63 64 65 66 67

68 69 70 71 72 73 74

75 76 77 78 79 80 81

82 83 84 85 86 87 88

89 90


91 92 93 94 95

96 97 98 99 100 101 102

103 104 105 106 107 108 109

110 111 112 113 114 115 116

117 118 119 120


121 122 123

124 125 126 127 128 129 130

131 132 133 134 135 136 137

138 139 140 141 142 143 144

145 146 147 148 149 150 151


1.3 Functions

June 2003

July 2003

August 2003


152 153 154 155 156 157 158

159 160 161 162 163 164 165

166 167 168 169 170 171 172

173 174 175 176 177 178 179

180 181


182 183 184 185 186

187 188 189 190 191 192 193

194 195 196 197 198 199 200

201 202 203 204 205 206 207

208 209 210 211 212


213 214

215 216 217 218 219 220 221

222 223 224 225 226 227 228

229 230 231 232 233 234 235

236 237 238 239 240 241 242

243


1.3 Functions

September 2003

October 2003

November 2003


244 245 246 247 248 249

250 251 252 253 254 255 256

257 258 259 260 261 262 263

264 265 266 267 268 269 270

271 272 273


274 275 276 277

278 279 280 281 282 283 284

285 286 287 288 289 290 291

292 293 294 295 296 297 298

299 300 301 302 303 304


305

306 307 308 309 310 311 312

313 314 315 316 317 318 319

320 321 322 323 324 325 326

327 328 329 330 331 332 333

334


1.3 Functions

December 2003


335 336 337 338 339 340

341 342 343 344 345 346 347

348 349 350 351 352 353 354

355 356 357 358 359 360 361

362 363 364 365


1.3 Functions

1.3.1 Unicenter CA-Driver for VSE FunctionsThe following topics describe each of the Unicenter CA-Driver for VSEfunctions.

1.3.1.1 Arithmetic Date Functions

The following arithmetic date functions are offered by Unicenter CA-Driver forVSE. All leap-year, month end, and year end adjustments are automaticallyhandled by Unicenter CA-Driver for VSE.

Function And Parameters Explanation

DTADD(n,&var) Adds "n" to variable "&var." The variable"&var" must contain a valid Julian date in theyyddd format. "n" represents a number ofdays to be added to "&var" and may be anumeric constant or a variable containing anumeric value.

Example: If &C_JOBDT=03366, DTADD(4,&C_JOBDT)=03003

DTSUB(n,&var) Subtracts "n" from variable "&var." Thevariable "&var" must contain a valid Juliandate in the yyddd format. "n" represents anumber of days to be subtracted from "&var"and may be a numeric constant or a variablecontaining a numeric value.

Example: If &C_JOBDT=03005, DTSUB(8,&C_JOBDT)=03363

DTDIF(&var1,&var2) Subtracts variable "&var2" from variable"var1." The variables "&var1" and "&var2"must contain valid Julian dates in the yydddformat.

Example: If &C_JOBDT=03045 and&C_JDATE=03040, DTDIF(&C_JOBDT,&C_JDATE)=5

MNADD(n,&var) Adds "n" to variable "&var." The variable"&var" must contain a valid Julian date in theyyddd format. "n" represents a number ofmonths to be added to "&var" and may be anumeric constant or a variable containing anumeric value.

Example: If &C_JOBDT=03023, MNADD(2,&C_JOBDT)=03081


1.3 Functions


MNSUB(n,&var) Subtracts "n" from variable "&var." Thevariable "&var" must contain a valid Juliandate in the yyddd format. "n" represents anumber of months to be subtracted from"&var" and may be a numeric constant or avariable containing a numeric value.

Example: If &C_JOBDT=03039, MNSUB(1,&C_JOBDT)=03008

1.3.1.2 Date Conversion Functions

The following date conversion functions are offered by Unicenter CA-Driverfor VSE. All leap-year, month end, and year end adjustments areautomatically handled by Unicenter CA-Driver for VSE.


MDYJ(&var) Converts a mm/dd/yy date to Julian.Slashes (/) are required as in the August 31,2004 reserved variable. &var must have validdate.

DMYJ(&var) Converts a dd/mm/yy date to Julian.Slashes (/) are required as in the August 31,2004 reserved variable. &var must have validdate.

YMDJ(&var) Converts a yy/mm/dd date to Julian.Slashes (/) are required as in the August 31,2004 reserved variable. &var must have validdate.

DMY(&var) Converts variable "&var" into ddmmyyformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032,DMY(&C_JOBDT)=010203

MDY(&var) Converts variable "&var" into mmddyyformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032,MDY(&C_JOBDT)=020103


1.3 Functions


YMD(&var) Converts variable "&var" into yymmddformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032,YMD(&C_JOBDT)=030201

DMYR(&var) Converts variable "&var" into ddmmccyyformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, DMYR(&C_JOBDT)=01022003

MDYR(&var) Converts variable "&var" into mmddccyyformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, MDYR(&C_JOBDT)=02012003

YRMD(&var) Converts variable "&var" into ccyymmddformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, YRMD(&C_JOBDT)=19030201

DM3Y(&var) Converts variable "&var" into ddmonyyformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, DM3Y(&C_JOBDT)=01FEB03

M3DY(&var) Converts variable "&var" into monddyyformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, M3DY(&C_JOBDT)=FEB0103

YM3D(&var) Converts variable "&var" into yymonddformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, YM3D(&C_JOBDT)=03FEB01


1.3 Functions


DM3YR(&var) Converts variable "&var" into ddmonccyyformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, DM3YR(&C_JOBDT)=01FEB2003

M3DYR(&var) Converts variable "&var" into monddccyyformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, M3DYR(&C_JOBDT)=FEB012003

YRM3D(&var) Converts variable "&var" into ccyymonddformat. The variable "&var" must contain avalid Julian date in the yyddd format.

Example: If &C_JOBDT=03032, YRM3D(&C_JOBDT)=2003FEB01

DAY(&var) Converts variable "&var" into the day of theweek (MONDAY, TUESDAY, etc.). Thevariable "&var" must contain a valid Juliandate in the yyddd format.

Example: If &C_JOBDT=03032, DAY(&C_JOBDT)=WEDNESDAY

MONTH(&var) Converts variable "&var" into the monthname (JANUARY, FEBRUARY, etc.). Thevariable "&var" must contain a valid Juliandate in the yyddd format.

Example: If &C_JOBDT=03032, MONTH(&C_JOBDT)=FEBRUARY

MON(&var) Converts variable "&var" into a threecharacter abbreviation of the month name(JAN, FEB, etc.). The variable "&var" mustcontain a valid Julian date in the yydddformat.

Example: If &C_JOBDT=03032,MON(&C_JOBDT)=FEB

MON#(&var) Converts variable "&var" into the monthnumber (01,02,03, etc.). The variable "&var"must contain a valid Julian date in the yydddformat.

Example: If &C_JOBDT=03032,MON#(&C_JOBDT)=02


1.3 Functions


DOW(&var) Converts variable "&var" into a threecharacter abbreviation of the day of the weekname (SUN, MON, etc.). The variable "&var"must contain a valid Julian date in the yydddformat.

Example: If &C_JOBDT=03032,DOW(&C_JOBDT)=WED

DOW#(&var) Converts variable "&var" into a two digit dayof the week (01, 02, 03, etc.). The variable"&var" must contain a valid Julian date in theyyddd format.

Example: If &C_JOBDT=03032,DOW#(&C_JOBDT)=04

WOM(&var) Converts variable "&var" into a two digitweek of the month (01, 02, 03, etc.). Thevariable "&var" must contain a valid Juliandate in the yyddd format.

Example: If &C_JOBDT=03032,WOM(&C_JOBDT)=01

WOY(&var) Converts variable "&var" into a two digitweek of the year (01, 02, 03, etc.). Thevariable "&var" must contain a valid Juliandate in the yyddd format.

Example: If &C_JOBDT=03032,WOY(&C_JOBDT)=05

1.3.1.3 Day-of-Month Functions

The following day-of-month functions are offered by Unicenter CA-Driver forVSE. These functions return dates or portions of dates by counting a specifiednumber of days forward from the beginning of months or backwards from theend of months. All leap-year, month end, and year end adjustments areautomatically handled by Unicenter CA-Driver for VSE. The functions areuseful for coding procedures that require a date which is always a certainnumber of days from the beginning or end of the month such as a billing datethat is constantly on the 10th day of the month.


1.3 Functions


LDOM(n,yyddd) Returns the day-of-month number bycounting "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 ofthe month.) If "yyddd" is not specified, thedefault is the current &C_JDATE value. "n"should be in the range of 1-31.

Example 1: LDOM(2,03025)=30Example 2: LDOM(2,03045)=27

JDOM(n,yyddd) Returns a Julian date by counting "n" daysfrom the beginning of the month of the theJulian date (yyddd) specified. Countingbegins at 1 on the first day of the month. (n=1returns a Julian date representing the first dayof a month.) If "yyddd" is not specified, thedefault is the current &C_JDATE value. "n"should be in the range of 1-31.

Example 1: JDOM(2,03025)=03002Example 2: JDOM(2,03045)=03033

LJDOM(n,yyddd) Returns a Julian date by counting "n" daysbackward from the end of the month of theJulian date (yyddd) specified. Countingbegins at 1 on the last day of the month. (n=1returns a Julian date representing the last dayof a month.) If "yyddd" is not specified, thedefault is the current &C_JDATE value. "n"should be in the range of 1-31.

Example 1: LJDOM(2,03025)=03030Example 2: LJDOM(2,03045)=03058


1.3 Functions

1.3.2 Unicenter CA-Scheduler/Unicenter CA-Driver for VSE FunctionsThe following topics describe the various functions available with CA-Driverfor VSE and CA-Scheduler.

1.3.2.1 Day-of-Month Functions

The following day-of-month functions are offered by Unicenter CA-Schedulerfor VSE with Unicenter CA-Driver for VSE active. These functions returndates or portions of dates by counting a specified number of days forwardfrom the beginning of months or backwards from the end of months. Inaddition, they have the ability to recognize predefined datetables so that thecounting can include only working, nonworking, accounting, or anypredefined type of cycle days. All leap-year, month end, and year endadjustments are automatically handled by Unicenter CA-Scheduler. Thefunctions are useful for coding procedures that require a date which is alwaysa certain number of a specific type of day (working, nonworking, accounting,etc.) from the beginning or end of the month such as a meeting date that isconstantly on the 5th working day of the month.


1.3 Functions

The examples following assume that the specified datetable (TABLE03)designates all Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays asworking days and all Saturdays and Sundays as nonworking days.


WDM(n,yyddd,dt) Returns A day-of-month number by counting"n" working days from the beginning of themonth of the Julian date (yyddd) specified.Nonworking days are not counted. Countingbegins at 1 on the first working day of themonth. (n=1 returns the first working day ofa month.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Workingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-31.

Example 1: WDM(7,03015,TABLE03)=10Example 2: WDM(31,03045,TABLE03)=15

JWDM(n,yyddd,dt) Returns A Julian date by counting "n" workingdays from the beginning of the month of theJulian date (yyddd) specified. Nonworkingdays are not counted. Counting begins at 1on the first working day of the month. (n=1returns a Julian date representing the firstworking day of a month.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Working days are determined according tothe datetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-31.

Example 1: JWDM(7,03015,TABLE03)=03010Example 2: JWDM(31,03045,TABLE03)=03074


1.3 Functions


HDM(n,yyddd,dt) Returns A day-of-month number by counting"n" nonworking days from the beginning of themonth of the Julian date (yyddd) specified.Working days are not counted. Countingbegins at 1 on the first nonworking day of themonth. (n=1 returns the first nonworking dayof a month.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Nonworkingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-31.

Example 1: HDM(7,03015,TABLE03)=22Example 2: HDM(31,03045,TABLE03)=20

JHDM(n,yyddd,dt) Returns A Julian date by counting "n"nonworking days from the beginning of themonth of the Julian date (yyddd) specified.Working days are not counted. Countingbegins at 1 on the first nonworking day of themonth. (n=1 returns a Julian date representingthe first nonworking day of a month.) If"yyddd" is not specified, the default is the&C_JOBDT value. Nonworking days aredetermined according to the datetablespecified (dt). If "dt" is not specified, thedefault is the &C_DTAB value. "n" should bein the range of 1-31.

Example 1: JHDM(7,03015,TABLE03)=03022Example 2: JHDM(31,03045,TABLE03)=03140


1.3 Functions

The examples following assume that the specified datetable (TABLE03)designates all Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays asaccounting days and all Saturdays and Sundays as nonaccounting days.

The examples following assume that "cycle" days are production days. (Cycledays may be any type of day that you defined on a datetable except working,nonworking, and accounting days.) The specified datetable (TABLE03) has aproduction version which uses R as the datetable prefix. That versiondesignates all days except Sundays as production days.


ADM(n,yyddd,dt) Returns A day-of-month number by counting"n" accounting days from the beginning of themonth of the Julian date (yyddd) specified.Nonaccounting days are not counted.Counting begins at 1 on the first accountingday of the month. (n=1 returns the firstaccounting day of a month.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Accounting days are determined according tothe datetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-31.

Example 1: ADM(7,03015,TABLE03)=10

Example 2: ADM(31,03045,TABLE03)=15

JADM(n,yyddd,dt) Returns A Julian date by counting "n"accounting days from the beginning of themonth of the Julian date (yyddd) specified.Nonaccounting days are not counted.Counting begins at 1 on the first accountingday of the month. (n=1 returns a Julian daterepresenting the first accounting day of amonth.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Accountingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-31.

Example 1: JADM(7,03015,TABLE03)=03010Example 2: JADM(31,03045,TABLE03)=03074


1.3 Functions



CDM(n,yyddd,dt,p) Returns A day-of-month number by counting"n" cycle days from the beginning of themonth of the Julian date (yyddd) specified.Noncycle days are not counted. Countingbegins at 1 on the first cycle day of the month.(n=1 returns the first cycle day of a month.)If "yyddd" is not specified, the default is the&C_JOBDT value. Cycle days are determinedaccording to the specified datetable (dt) anddatetable prefix (p). If "dt" is not specified,the default is the &C_DTAB value. "p" isrequired and must specify a datetable thatdefines cycle days other than working,nonworking, and accounting days. "n"should be in the range of 1-31.

Example 1: CDM(7,03015,TABLE03,R)=09Example 2: CDM(31,03045,TABLE03,R)=08

JCDM(n,yyddd,dt,p) Returns A Julian date by counting "n" cycledays from the beginning of the month of theJulian date (yyddd) specified. Noncycle daysare not counted. Counting begins at 1 on thefirst cycle day of the month. (n=1 returns aJulian date representing the first cycle day ofa month.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Cycle daysare determined according to the specifieddatetable (dt) and datetable prefix (p). If "dt"is not specified, the default is the &C_DTABvalue. "p" is required and must specify adatetable that defines cycle days other thanworking, nonworking, and accounting days."n" should be in the range of 1-31.

Example 1: JCDM(7,03015,TABLE03,R)=03009Example 2: JCDM(31,03045,TABLE03,R)=03067


1.3 Functions


LWDM(n,yyddd,dt) Returns A day-of-month number by counting"n" working days backward from the end ofthe month of the Julian date (yyddd)specified. Nonworking days are not counted.Counting begins at 1 on the last working dayof the month. (n=1 returns the last workingday of a month.) If "yyddd" is not specified,the default is the &C_JOBDT value. Workingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-31.

Example 1: LWDM(7,23015,TABLE03)=23Example 2: LWDM(31,03045,TABLE03)=17

LJWDM(n,yyddd,dt) Returns A Julian date by counting "n" workingdays backward from the end of the month ofthe Julian date (yyddd) specified.Nonworking days are not counted. Countingbegins at 1 on the last working day of themonth. (n=1 returns a Julian date representingthe last working day of a month.) If "yyddd"is not specified, the default is the &C_JOBDTvalue. Working days are determinedaccording to the datetable specified (dt). If"dt" is not specified, the default is the&C_DTAB value. "n" should be in the rangeof 1-31.

Example 1: LJWDM(7,03015,TABLE03)=03023Example 2: LJWDM(31,03045,TABLE03)=03017

LHDM(n,yyddd,dt) A day-of-month number by counting "n"nonworking days backward from the end ofthe month of the Julian date (yyddd)specified. Working days are not counted.Counting begins at 1 on the last nonworkingday of the month. (n=1 returns the lastnonworking day of a month.) If "yyddd" isnot specified, the default is the &C_JOBDTvalue. Nonworking days are determinedaccording to the datetable specified (dt). If"dt" is not specified, the default is the&C_DTAB value. "n" should be in the rangeof 1-31.

Example 1: LHDM(7,03015,TABLE03)=8Example 2: LHDM(15,03045,TABLE03)=8


1.3 Functions


LJHDM(n,yyddd,dt) Returns A Julian date by counting "n"nonworking days backward from the end ofthe month of the Julian date (yyddd)specified. Working days are not counted.Counting begins at 1 on the last nonworkingday of the month. (n=1 returns a Julian daterepresenting the last nonworking day of amonth.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Nonworkingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-31.

Example 1: LJHDM(7,03015,TABLE03)=03008Example 2: LJHDM(15,03045,TABLE03)=03008

The examples following assume that thespecified datetable (TABLE03) designates allMondays, Tuesdays, Wednesdays, Thursdays,and Fridays as accounting days and allSaturdays and Sundays as nonaccountingdays.

LADM(n,yyddd,dt) Returns A day-of-month number by counting"n" accounting days backward from the end ofthe month of the Julian date (yyddd)specified. Nonaccounting days are notcounted. Counting begins at 1 on the lastaccounting day of the month. (n=1 returns thelast accounting day of a month.) If "yyddd"is not specified, the default is the &C_JOBDTvalue. Accounting days are determinedaccording to the datetable specified (dt). If"dt" is not specified, the default is the&C_DTAB value. "n" should be in the rangeof 1-31.

Example 1: LADM(7,03015,TABLE03)=23Example 2: LADM(31,03045,TABLE03)=17


1.3 Functions



LJADM(n,yyddd,dt) Returns A Julian date by counting "n"accounting days backward from the end of themonth of the Julian date (yyddd) specified.Nonaccounting days are not counted.Counting begins at 1 on the last accountingday of the month. (n=1 returns a Julian daterepresenting the last accounting day of amonth.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Accountingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-31.

Example 1: LJADM(7,03015,TABLE03)=03023Example 2: LJADM(31,03045,TABLE03)=03017


LCDM(n,yyddd,dt,c) Returns A day-of-month number by counting"n" cycle days backward from the end of themonth of the Julian date (yyddd) specified.Noncycle days are not counted. Countingbegins at 1 on the last cycle day of the month.(n=1 returns the last cycle day of a month.) If"yyddd" is not specified, the default is the&C_JOBDT value. Cycle days are determinedaccording to the specified datetable (dt) anddatetable prefix (p). If "dt" is not specified,the default is the &C_DTAB value. "p" isrequired and must specify a datetable thatdefines cycle days other than working,nonworking, and accounting days. "n"should be in the range of 1-31.

Example 1: LCDM(7,03015,TABLE03,R)=24Example 2: LCDM(31,03045,TABLE03,R)=24


1.3 Functions


LJCDM(n,yyddd,dt,c) Returns A Julian date by counting "n" cycledays backward from the end of the month ofthe Julian date (yyddd) specified. Noncycledays are not counted. Counting begins at 1on the last cycle day of the month. (n=1returns a Julian date representing the lastcycle day of a month.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Cycle days are determined according to thespecified datetable (dt) and datetable prefix(p). If "dt" is not specified, the default is the&C_DTAB value. "p" is required and mustspecify a datetable that defines cycle daysother than working, nonworking, andaccounting days. "n" should be in the rangeof 1-31.

Example 1:LJCDM(7,03015,TABLE03,R)=03024Example 2:LJCDM(31,03045,TABLE03,R)=03024

1.3.2.2 Day-of-Period Functions

The following day-of-period functions are offered by Unicenter CA-Schedulerfor VSE with Unicenter CA-Driver for VSE active. These functions returndates or day-of-period numbers by counting a specified number of daysforward from the beginning of periods or backwards from the end of periods.In addition, they have the ability to recognize predefined datetables so that thecounting can include only accounting or any predefined type of cycle days.All leap-year, month end, and year end adjustments are automatically handledby Unicenter CA-Scheduler. The functions are useful for coding proceduresthat require a date which is always a certain number of accounting or cycledays from the beginning or end of the period such as a processing date that isconstantly on the third to last day of the period.


1.3 Functions

The examples following assume that the specified datetable (TABLE03)designates all Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays asaccounting days and all Saturdays and Sundays as nonaccounting days. It isalso assumed that the accounting period begins on the first day of the calendaryear and ends on the last day of the calendar year.


ADP(n,yyddd,dt) Returns A day-of-period number by counting"n" accounting days from the beginning of theperiod of the Julian date (yyddd) specified.Nonaccounting days are not counted.Counting begins at 1 on the first accountingday of the period. (n=1 returns the firstaccounting day of a period.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Accounting days are determined according tothe datetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-365.

Example 1: ADP(7,03015,TABLE03)=10Example 2: ADP(37,03333,TABLE03)=52

JADP(n,yyddd,dt) Returns A Julian date by counting "n"accounting days from the beginning of theperiod of the Julian date (yyddd) specified.Nonaccounting days are not counted.Counting begins at 1 on the first accountingday of the period. (n=1 returns a Julian daterepresenting the first accounting day of aperiod.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Accountingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-365.

Example 1: JADP(7,03015,TABLE03)=03010Example 2: JADP(37,03333,TABLE03)=03052


1.3 Functions

The examples following assume that "cycle" days are production days. (Cycledays may be any type of day that you defined on a datetable exceptaccounting days.) The specified datetable (TABLE03) has a production versionwhich uses R as the datetable prefix. That version designates all days exceptSundays as production days. It is also assumed that the production periodbegins on the first day of the calendar year and ends on the last day of thecalendar year.


CDP(n,yyddd,dt,p) Returns A day-of-period number by counting"n" cycle days from the beginning of theperiod of the Julian date (yyddd) specified.Noncycle days are not counted. Countingbegins at 1 on the first cycle day of the period.(n=1 returns the first cycle day of a period.)If "yyddd" is not specified, the default is the&C_JOBDT value. Cycle days are determinedaccording to the specified datetable (dt) anddatetable prefix (p). If "dt" is not specified,the default is the &C_DTAB value. "p" isrequired and must specify a datetable thatdefines cycle days other than accountingdays. "n" should be in the range of 1-365.

Example 1: CDP(7,03015,TABLE03,R)=9Example 2: CDP(37,03333,TABLE03,R)=44

JCDP(n,yyddd,dt,p) Returns A Julian date by counting "n" cycledays from the beginning of the period of theJulian date (yyddd) specified. Noncycle daysare not counted. Counting begins at 1 on thefirst cycle day of the period. (n=1 returns aJulian date representing the first cycle day ofa period.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Cycle daysare determined according to the specifieddatetable (dt) and datetable prefix (p). If "dt"is not specified, the default is the &C_DTABvalue. "p" is required and must specify adatetable that defines cycle days other thanaccounting days. "n" should be in the rangeof 1-365.

Example 1: JCDP(7,03015,TABLE03,R)=03009Example 2: JCDP(37,03333,TABLE03,R)=03044


1.3 Functions

The examples following assume that the specified datetable (TABLE03)designates all Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays asaccounting days and all Saturdays and Sundays as nonaccounting days. It isalso assumed that the accounting period begins on the first day of the calendaryear and ends on the last day of the calendar year.


LADP(n,yyddd,dt) Returns A day-of-period number by counting"n" accounting days backward from the end ofthe period of the Julian date (yyddd)specified. Nonaccounting days are notcounted. Counting begins at 1 on the lastaccounting day of the period. (n=1 returns thelast accounting day of a period.) If "yyddd"is not specified, the default is the &C_JOBDTvalue. Accounting days are determinedaccording to the datetable specified (dt). If"dt" is not specified, the default is the&C_DTAB value. "n" should be in the rangeof 1-365.

Example 1: LADP(7,03015,TABLE03)=355Example 2: LADP(37,03333,TABLE03)=313

LJADP(n,yyddd,dt) Returns a Julian date by counting "n"accounting days backward from the end of theperiod of the Julian date (yyddd) specified.Nonaccounting days are not counted.Counting begins at 1 on the last accountingday of the period. (n=1 returns a Julian daterepresenting the last accounting day of aperiod.) If "yyddd" is not specified, thedefault is the &C_JOBDT value. Accountingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-365.

Example 1: LJADP(7,03015,TABLE03)=03355Example 2: LJADP(37,03333,TABLE03)=03313


1.3 Functions

The examples following assume that "cycle" days are production days. (Cycledays may be any type of day that you defined on a datetable exceptaccounting days.) The specified datetable (TABLE03) has a production versionwhich uses R as the datetable prefix. That version designates all days exceptSundays as production days. It is also assumed that the production periodbegins on the first day of the calendar year and ends on the last day of thecalendar year.


LCDP(n,yyddd,dt,p) Returns A day-of-period number by counting"n" cycle days backward from the end of theperiod of the Julian date (yyddd) specified.Noncycle days are not counted. Countingbegins at 1 on the last cycle day of the period.(n=1 returns the last cycle day of a period.) If"yyddd" is not specified, the default is the&C_JOBDT value. Cycle days are determinedaccording to the specified datetable (dt) anddatetable prefix (p). If "dt" is not specified,the default is the &C_DTAB value. "p" isrequired and must specify a datetable thatdefines cycle days other than accountingdays. "n" should be in the range of 1-365.

Example 1: LCDP(7,03015,TABLE03,R)=357Example 2: LCDP(37,03333,TABLE03,R)=322

LJCDP(n,yyddd,dt,p) Returns A Julian date by counting "n" cycledays backward from the end of the period ofthe Julian date (yyddd) specified. Noncycledays are not counted. Counting begins at 1on the last cycle day of the period. (n=1returns a Julian date representing the lastcycle day of a period.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Cycle days are determined according to thespecified datetable (dt) and datetable prefix(p). If "dt" is not specified, the default is the&C_DTAB value. "p" is required and mustspecify a datetable that defines cycle daysother than accounting days. "n" should be inthe range of 1-365.

Example 1: LJCDP(7,03015,TABLE03,R)=03357Example 2:LJCDP(37,03333,TABLE03,R)=03322


1.3 Functions

1.3.2.3 Relative Date Functions

The following relative date functions are offered by Unicenter CA-Schedulerfor VSE with Unicenter CA-Driver for VSE active. These functions returndates or a number of days passed by counting a specified number of daysforward or backward from the specified date. In addition, they have theability to recognize predefined datetables so that the counting can include onlyworking, nonworking, accounting, or any predefined type of cycle days. (Notethat the "number of days passed" includes both the days that are counted andthe days that are skipped.) All leap-year, month end, and year endadjustments are automatically handled by Unicenter CA-Scheduler. Thefunctions are useful for coding procedures that require a date which is alwaysa certain number of a specific type of day (working, nonworking, accounting,etc.) from another given date (which can be a variable parameter) such as abackup processing date that is constantly 1 working day after the last day ofthe month.


1.3 Functions



RWD(n,yyddd,dt) Returns a number of days by counting "n"working days from the Julian date (yyddd)specified. Nonworking days are skipped inthe counting process but are included in thefunction's result. Counting begins at theJulian date (yyddd) specified. (n=1 returnsthe number of days from "yyddd" until thefirst working day.) If "yyddd" is not specified,the default is the &C_JOBDT value. Workingdays are determined according to thedatetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-366.

Example 1: RWD(7,03015,TABLE03)=9Example 2: RWD(31,03045,TABLE03)=43

JRWD(n,yyddd,dt) Returns A Julian date by counting "n" workingdays from the Julian date (yyddd) specified.Nonworking days are skipped in the countingprocess. Counting begins at the Julian date(yyddd) specified. (n=1 returns a Julian datebased on the number of days from "yyddd"until the first working day.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Working days are determined according tothe datetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-366.

Example 1: JRWD(7,03015,TABLE03)=03024Example 2: JRWD(31,03045,TABLE03)=03088


1.3 Functions


RHD(n,yyddd,dt) Returns a number of days by counting "n"nonworking days from the Julian date (yyddd)specified. Working days are skipped in thecounting process but are included in thefunction's result. Counting begins at theJulian date (yyddd) specified. (n=1 returnsthe number of days from "yyddd" until thefirst nonworking day.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Nonworking days are determined accordingto the datetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-366.

Example 1: RHD(7,03015,TABLE03)=27Example 2: RHD(31,03045,TABLE03)=109

JRHD(n,yyddd,dt) Returns A Julian date by counting "n"nonworking days from the Julian date (yyddd)specified. Working days are skipped in thecounting process. Counting begins at theJulian date (yyddd) specified. (n=1 returns aJulian date based on the number of days from"yyddd" until the first nonworking day.) If"yyddd" is not specified, the default is the&C_JOBDT value. Nonworking days aredetermined according to the datetablespecified (dt). If "dt" is not specified, thedefault is the &C_DTAB value. "n" should bein the range of 1-366.

Example 1: JRHD(7,03015,TABLE03)=03042Example 2: JRHD(31,03045,TABLE03)=03154


1.3 Functions



RAD(n,yyddd,dt) Returns a number of days by counting "n"accounting days from the Julian date (yyddd)specified. Nonaccounting days are skipped inthe counting process but are included in thefunction's result. Counting begins at theJulian date (yyddd) specified. (n=1 returnsthe number of days from "yyddd" until thefirst accounting day.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Accounting days are determined according tothe datetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-366.

Example 1: RAD(7,03015,TABLE03)=9Example 2: RAD(31,03045,TABLE03)=43

JRAD(n,yyddd,dt) Returns A Julian date by counting "n"accounting days from the Julian date (yyddd)specified. Nonaccounting days are skipped inthe counting process. Counting begins at theJulian date (yyddd) specified. (n=1 returns aJulian date based on the number of days from"yyddd" until the first accounting day.) If"yyddd" is not specified, the default is the&C_JOBDT value. Accounting days aredetermined according to the datetablespecified (dt). If "dt" is not specified, thedefault is the &C_DTAB value. "n" should bein the range of 1-366.

Example 1: JRAD(7,03015,TABLE03)=03024Example 2: JRAD(31,03045,TABLE03)=03088


1.3 Functions



RCD(n,yyddd,dt,p) Returns a number of days by counting "n"cycle days from the Julian date (yyddd)specified. Noncycle days are skipped in thecounting process but are included in thefunction's result. Counting begins at theJulian date (yyddd) specified. (n=1 returnsthe number of days from "yyddd" until thefirst cycle day.) If "yyddd" is not specified,the default is the &C_JOBDT value. Cycledays are determined according to thespecified datetable (dt) and datetable prefix(p). If "dt" is not specified, the default is the&C_DTAB value. "p" is required and mustspecify a datetable that defines cycle daysother than working, nonworking, andaccounting days. "n" should be in the rangeof 1-366.

Example 1: RCD(7,03015,TABLE03,R)=8Example 2: RCD(31,03045,TABLE03,R)=36

JRCD(n,yyddd,dt,p) Returns a Julian date by counting "n" cycledays from the Julian date (yyddd) specified.Noncycle days are skipped in the countingprocess. Counting begins at the Julian date(yyddd) specified. (n=1 returns a Julian datebased on the number of days from "yyddd"until the first cycle day.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Cycle days are determined according to thespecified datetable (dt) and datetable prefix(p). If "dt" is not specified, the default is the&C_DTAB value. "p" is required and mustspecify a datetable that defines cycle daysother than working, nonworking, andaccounting days. "n" should be in the rangeof 1-366.

Example 1: JRCD(7,03015,TABLE03,R)=03023Example 2: JRCD(31,03045,TABLE03,R)=03081


1.3 Functions



LRWD(n,yyddd,dt) Returns a number of days by counting "n"working days backwards from the Julian date(yyddd) specified. Nonworking days areskipped in the counting process but areincluded in the function's result. Countingbegins at the Julian date (yyddd) specified.(n=1 returns the number of days from"yyddd" until the last working day.) If"yyddd" is not specified, the default is the&C_JOBDT value. Working days aredetermined according to the datetablespecified (dt). If "dt" is not specified, thedefault is the &C_DTAB value. "n" should bein the range of 1-366.

Example 1: LRWD(7,03015,TABLE03)=10Example 2: LRWD(31,03045,TABLE03)=43

LJRWD(n,yyddd,dt) Returns A Julian date by counting "n" workingdays backward from the Julian date (yyddd)specified. Nonworking days are skipped inthe counting process. Counting begins at theJulian date (yyddd) specified. (n=1 returns aJulian date based on the number of days from"yyddd" until the last working day.) If"yyddd" is not specified, the default is the&C_JOBDT value. Working days aredetermined according to the datetablespecified (dt). If "dt" is not specified, thedefault is the &C_DTAB value. "n" should bein the range of 1-366.

Example 1: LJRWD(7,03015,TABLE03)=03005Example 2: LJRWD(31,03045,TABLE03)=03002


1.3 Functions


LRHD(n,yyddd,dt) Returns a number of days by counting "n"nonworking days backward from the Juliandate (yyddd) specified. Working days areskipped in the counting process but areincluded in the function's result. Countingbegins at the Julian date (yyddd) specified.(n=1 returns the number of days from"yyddd" until the last nonworking day.) If"yyddd" is not specified, the default is the&C_JOBDT value. Nonworking days aredetermined according to the datetablespecified (dt). If "dt" is not specified, thedefault is the &C_DTAB value. "n" should bein the range of 1-366.

Example 1: LRHD(7,03045,TABLE03)=23Example 2: LRHD(1,03055,TABLE03)=5

LJRHD(n,yyddd,dt) Returns A Julian date by counting "n"nonworking days backward from the Juliandate (yyddd) specified. Working days areskipped in the counting process. Countingbegins at the Julian date (yyddd) specified.(n=1 returns a Julian date based on thenumber of days from "yyddd" until the lastnonworking day.) If "yyddd" is not specified,the default is the &C_JOBDT value.Nonworking days are determined accordingto the datetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-366.

Example 1: LJRHD(7,03045,TABLE03)=03022Example 2: LJRHD(1,03055,TABLE03)=03050


1.3 Functions



LRAD(n,yyddd,dt) Returns a number of days by counting "n"accounting days backward from the Juliandate (yyddd) specified. Nonaccounting daysare skipped in the counting process but areincluded in the function's result. Countingbegins at the Julian date (yyddd) specified.(n=1 returns the number of days from"yyddd" until the last accounting day.) If"yyddd" is not specified, the default is the&C_JOBDT value. Accounting days aredetermined according to the datetablespecified (dt). If "dt" is not specified, thedefault is the &C_DTAB value. "n" should bein the range of 1-366.

Example 1: LRAD(1,03015,TABLE03)=2Example 2: LRAD(5,03045,TABLE03)=7

LJRAD(n,yyddd,dt) Returns A Julian date by counting "n"accounting days backward from the Juliandate (yyddd) specified. Nonaccounting daysare skipped in the counting process.Counting begins at the Julian date (yyddd)specified. (n=1 returns a Julian date based onthe number of days from "yyddd" until thelast accounting day.) If "yyddd" is notspecified, the default is the &C_JOBDT value.Accounting days are determined according tothe datetable specified (dt). If "dt" is notspecified, the default is the &C_DTAB value."n" should be in the range of 1-366.

Example 1: LJRAD(1,03015,TABLE03)=03013Example 2: LJRAD(5,03045,TABLE03)=03038


1.3 Functions



LRCD(n,yyddd,dt,p) Returns a number of days by counting "n"cycle days backward from the Julian date(yyddd) specified. Noncycle days areskipped in the counting process but areincluded in the function's result. Countingbegins at the Julian date (yyddd) specified.(n=1 returns the number of days from"yyddd" until the last cycle day.) If "yyddd" isnot specified, the default is the &C_JOBDTvalue. Cycle days are determined accordingto the specified datetable (dt) and datetableprefix (p). If "dt" is not specified, the defaultis the &C_DTAB value. "p" is required andmust specify a datetable that defines cycledays other than working, nonworking, andaccounting days. "n" should be in the rangeof 1-366.

Example 1: LRCD(7,03015,TABLE03,R)=8Example 2: LRCD(31,03045,TABLE03,R)=36

LJRCD(n,yyddd,dt,p) Returns A Julian date by counting "n" cycledays backward from the Julian date (yyddd)specified. Noncycle days are skipped in thecounting process. Counting begins at theJulian date (yyddd) specified. (n=1 returns aJulian date based on the number of days from"yyddd" until the last cycle day.) If "yyddd" isnot specified, the default is the &C_JOBDTvalue. Cycle days are determined accordingto the specified datetable (dt) and datetableprefix (p). If "dt" is not specified, the defaultis the &C_DTAB value. "p" is required andmust specify a datetable that defines cycledays other than working, nonworking, andaccounting days. "n" should be in the rangeof 1-366.

Example 1: LJRCD(7,03015,TABLE03,R)=03007Example 2:LJRCD(31,03045,TABLE03,R)=03009


1.4 Using Conditional Procedure Expansion


Procedures can be conditionally expanded to bypass or include steps that arerequired for a particular execution or to change the sequence in which stepsare executed. This allows you to design generalized procedures with differentsteps to be executed under different conditions and include statements in theprocedure that control which steps are expanded. These control statements testand reset the values supplied on the PROC statement, or used as default, forthe symbolic parameters in the procedure. Based on the results of the test, theprocedure can branch backward or forward to another step.

Use these control statements to program conditional expansion:

Each of the control statements is described on the following pages. Examplesof conditional expansion are given at the end of the section.

Use To

-STEP Define step names

-GOTO Branch to a step

-IF Define conditions for branching

-SET Set variable parameters

-LCTR Control looping

-FLUSH Bypass the rest of a procedure

-ABORT Flush all calling procedures

-WTO Send a message to the operator

-REPLY Accept an operator response

-INPUT Copy a book located in the source statement library

1.4.1 Defining Step Names (-STEP)-STEP stepname

Use -STEP statements to define step names that are referenced in the -IF and-GOTO statements. Step names may be one to eight alphanumeric characters(except for the reserved word FLUSH). A maximum of 256 step names may bedefined in each procedure.



1.4.1.1 Examples

-STEP ONE-STEP DAILYRUN-STEP STEP1

1.4.2 Branching (-GOTO)-GOTO stepname

The -GOTO statement stops procedure expansion and either

■ Branches forward or backward to another step or

■ Bypasses the remainder of the procedure.

To branch to another step, specify the name of the step on the -GOTOstatement. The step name must also be defined on a -STEP statement.Procedure expansion continues at this step.

To bypass the remainder of the procedure, specify FLUSH on the -GOTOstatement. If a nested procedure contains a -GOTO FLUSH statement, only thenested procedure will be bypassed, not the remainder of the calling procedure.

1.4.2.1 Examples

-GOTO ONE

-GOTO DAILYRUN

-GOTO STEP1

-GOTO FLUSH

The following example demonstrates how to use -STEP and -GOTO to restartan abended job stream at step three instead of step one. To do this, theprocedure is defined with a variable parameter called &RESTART which has adefault value of STEP01:



-PROC PAYROLL,OPTION=CREATE,PARM=(RESTART=STEP�1)

%/ JOB PAYROLL DAILY PAYROLL UPDATE JOB STREAM

� THIS JOB STREAM IS BEGINNING AT STEP &RESTART

-GOTO &RESTART

-STEP STEP�1

� STEP STEP�1

// TLBL TROUT,'PAY TRANS'

// ASSGN SYS��8,TAPE

// ASSGN SYS��6,READER

// EXEC PAY�1

%/ DATA

%�

-STEP STEP�2

� STEP STEP�2

// TLBL TROUT,'PAY TRANS'

// TLBL MSTRIN, 'PAYROLL MASTER'

// TLBL MSTROUT,'PAYROLL MASTER'


// ASSGN SYS�1�,TAPE

// EXEC PAY�2

%�

-STEP STEP�3

� STEP STEP�3

// TLBL REPORT,'PAYROLL MASTER'

// EXEC PAY�3

%�

%&

-END

When a restart is necessary, an overriding value may be supplied for the&RESTART parameter specifying the step name at which restart is to begin. Inthis case, this is step three:

// PROC PAYROLL,RESTART=STEP�3

This procedure could easily be expanded to include logic that would makestep selection stop at any specified step name as well as start at any specifiedstep name.

1.4.3 Defining Conditions (-IF)-IF &variable operator 'literal' GOTO stepname

Use the -IF statement for conditional branching:

&variable Specify a variable parameter which was defined by PARMwhen the procedure was cataloged or a global variable set ona -SET statement.

operator Specify the relationship between the variable and the literal asone of these operators: LT, GT, EQ, NE, GE, or LE. Symbols(=, <, >) may be used instead of EQ, LT and GT.



literal Specify a character string against which to test the variableparameter. It may be from one to 64 characters in length andmust be delimited by quotes or some other special character ifit contains other than all alphanumeric characters.

stepname Give the name of a step or specify FLUSH if the remainder ofthe procedure is to be bypassed. The stepname must bedefined on a -STEP statement in the procedure.

1.4.3.1 Examples

-IF &VAR1 EQ YES GOTO STEP1

-IF &VAR2 NE 'DAILY RUN' GOTO MONTHLY

-IF &VAR3 = ERROR GOTO FLUSH

-IF &VAR4 LE 99 GOTO TESTOK

-IF &SIZE GT 12� GOTO TOOLARGE

1.4.3.2 Note

Comparisons are made on a character-by-character basis. Therefore, whencoding the following statements, the -IF statement WILL NOT be true:

-SET VAR1=+99-IF &VAR1=99 GOTO ITS99

1.4.3.3 Example

The following example demonstrates how conditional procedure expansionselects different job steps from a large procedure depending on the day of theweek. The reserved variable &DAY is used to inform the procedure of the dayof the week. The procedure, as stored in the Unicenter CA-Driver for VSElibrary, would appear as follows:



-PROC PAYROLL,OPTION=CREATE

%/ JOB PAYROLL DAILY PAYROLL REPORTING RUN

-IF &C_DAY EQ SATURDAY GOTO BADAY

-IF &C-DAY EQ SUNDAY GOTO BADAY

-GOTO DAYOK

-STEP BADAY

� THIS JOB DOES NOT RUN ON &DAY

-GOTO EOJ

-STEP DAYOK

� THIS PAYROLL REPORTING RUN IS FOR &DAY

// TLBL SYS��9, 'PAYROLL MASTER',,,,,,1

// DLBL SORTWK1,'SORT WORK AREA',�,SD

// EXTENT SYS��1,WORK�1,1,�,19,19


// ASSGN SYS��1,333�,VOL=WORK�1,SHR

// EXEC PAY�7

%�

-IF &DAY NE FRIDAY GOTO NOTFRDY

� THIS STEP IS PROCESSED ONLY ON &DAY

// TLBL SYS��8,'WEEKLY PAY TRANS',,,,,,2


// EXEC PAY�8

%�

-STEP NOTFRDY

// MTC RUN,SYS��9

-STEP EOJ

%&

-END

When this procedure is called by the PROC statement // PROC PAYROLL onMonday, this expanded job stream is submitted:

// JOB PAYROLL DAILY PAYROLL REPORTING RUN

� THIS PAYROLL REPORTING RUN IS FOR MONDAY

// TLBL SYS��9,'PAYROLL MASTER ',,,,,,1


// EXTENT SYS��1,WORK�1,1,�,19,19



// EXEC PAY�7

/�

// MTC RUN,SYS��9

/&

When this procedure is called by the PROC statement // PROC PAYROLL onFriday, this expanded job stream is submitted:



// JOB PAYROLL DAILY PAYROLL REPORTING RUN

� THIS PAYROLL REPORTING RUN IS FOR FRIDAY

// TLBL SYS��9,'PAYROLL MASTER',,,,,,1


// EXTENT SYS��1,WORK�1,1,�,19,19



// EXEC PAY�7

/�

� THIS JOB STEP IS PROCESSED ONLY ON FRIDAY

// TLBL SYS��8,'WEEKLY PAY TRANS',,,,,,2


// EXEC PAY�8

/�

// MTC RUN, SYS��9

/&

1.4.4 Including Input from an IBM Source Library (-INPUT)-INPUT sublib.member-name

sublib Specify the sublibrary ID where the member is stored.

member-name Specify the name of the member to be included.

Use the -INPUT statement to access data from any IBM source library that isproperly libdef'ed in the partition.

Put the -INPUT statement in the procedure at the point where the data is to beexpanded. The designated member will be retrieved in accordance with theexisting library search order established for the executing partition.

Book names cannot be specified as variable names. Data in books retrieved byINPUT statements may not contain any Unicenter CA-Driver for VSEconditional expansion statements.

-INPUT statements may be nested up to 20 levels. An -INPUT statement maynot nest itself, and you must be careful to avoid nesting loops.

1.4.4.1 Example

The following example retrieves the book SORTCTL.A and places thestatements from it in the procedure.

-INPUT A.SORTCTL (Sort Control Cards from the Source Library)



1.4.5 Setting Variable Parameters (-SET)-SET &variable = &variable | constant [operator &variable | constant]

&variable Specify a variable parameter which was defined by PARM whenthe procedure was cataloged or a global variable set on a -SETstatement.

operator Specify the arithmetic operation to be performed: + (addition), -(subtraction), / (division), * (multiplication).

constant Specify a positive or negative numeric constant with or withouta sign.

Use the -SET statement to set the value of a variable parameter that will bereferenced during conditional expansion. The value may be one of these:

■ A literal

■ The value of another variable parameter

■ A combination of the above two used in a simple arithmetic expression

■ Substring value of a variable

Code the name of the variable parameter to be set and the value in this formatwith no spaces:

-SET &VAR1=n (where n is an integer)

-SET &VAR1=&VAR2

-SET &VAR1=&VAR2+n

-SET &VAR1=&VAR2-&VAR3

-SET &VAR1=&VAR2(1,3)

A variable parameter may be set to any integer value, positive or negative:

-SET &VAR1=4 (positive value is assumed)

-SET &VAR=-3 (negative value must be explicit)

-SET &VAR=+22 (positive value may be explicit)

A variable parameter may be set to the result of an arithmetic expression usinginteger values. Valid arithmetic operators are:

+ add

- subtract

* multiply

divide



1.4.5.1 Examples

-SET &VAR1=4-2

-SET &VAR1=8+7

-SET &VAR1=4�3

-SET &VAR1=8/4

A variable parameter may be set to the same value as another variableparameter, or to the result of an arithmetic expression using two variableparameters or one variable parameter and an integer:

-SET &VAR1=&VAR2

-SET &VAR1=&VAR2�&VAR3

-SET &VAR1=&VAR2/2

-SET &VAR1=&VAR1+1

-SET &VAR1=&VAR1+&VAR2

All variable parameters used in such an arithmetic expression must havenumeric values associated with them, rather than character values. The resultsof all arithmetic operations will be truncated in order to provide only integerresults.

A variable parameter may also be set to a character string:

-SET &VAR1=NO

-SET &VAR1='A CHARACTER STRING'

1.4.6 Controlling Loops (-LCTR)-LCTR nnn

As a result of backward step branching during procedure expansion,procedure expansion can enter a loop. Unicenter CA-Driver for VSEautomatically terminates procedure expansion when any step name (on a-STEP statement) is referenced more than the default number of times specifiedby the LCTR parameter of the CAIRGEN macro (see the Systems ProgrammerGuide). To override this default value of step references, use the -LCTRstatement and specify a number. This will be the maximum number of timesany one step may be branched to. The first time any step is referenced thisvalue plus one, an error message will be produced and the procedureexpansion process will be terminated.



1.4.6.1 Examples

-LCTR 4

-LCTR 9�

-LCTR 999

1.4.7 Flushing a Procedure (-FLUSH)-FLUSH

Use the -FLUSH statement to bypass the remainder of a procedure beingexpanded. If it is a nested procedure, the calling procedure will be returned to;the remainder of the calling procedure will not be bypassed.

This statement does the same thing as the -GOTO FLUSH statement.

1.4.7.1 Example

-FLUSH

1.4.8 Aborting Procedure Expansion (-ABORT)-ABORT

Use the -ABORT statement to completely terminate procedure expansion. The-ABORT statement flushes not only the remainder of the current procedure,but also the remainder of any and all calling procedures. In addition, itcancels the job.

1.4.8.1 Example

-ABORT



1.4.9 Writing Messages to the Operator (-WTO)-WTO message

Use the -WTO statement to issue messages to the operator's console duringprocedure expansion. The message text may be from 1 to 50 characters inlength and must be enclosed in quotes or some other special characterdelimiter if the text contains a quote:

-WTO 'HAVE A NICE DAY'

-WTO /THIS IS A MESSAGE TO BE SENT TO THE OPERATOR/

The message that is logged to the console is preceded by a UnicenterCA-Driver for VSE message number and the name of the procedure. Assumethe procedure named PAYROLL1 contains the statement:

-WTO 'ENTER YES IF IT IS FRIDAY'

The message written to the system console would be:

CACR398I PAYROLL1 - ENTER YES IF IT IS FRIDAY

Remember that the message is produced during procedure expansion, whichtakes place immediately before the job is processed. Messages to the operatormay be informational messages only:

CACR398I PAYROLL1 - STEPS PAYDEP7 AND PAYDEP8 NOT PROCESSED

Or the message may be a request for the operator to enter a parameter fromthe system console:

CACR398I PAYROLL1 - ENTER TODAY'S DATE MM/DD/YY

Replies are called for by the -REPLY statement discussed next.



1.4.10 Accepting Operator Replies (-REPLY)-REPLY &variable

&variable Specifies a variable parameter which was defined by PARM whenthe procedure was cataloged or a global variable set on a -SETstatement.

The -REPLY statement allows the operator to enter the value of a variableparameter from the console. The current value of the named variableparameter is immediately replaced by the value entered by the operator. Thisreplacement value may then be used to determine the outcome of theprocedure expansion by its use in other conditional expansion statements.

Each -REPLY statement should be preceded by a -WTO statement containinginstructions on what the operator is to enter. Each -REPLY statement willgenerate a CACR399 ENTER REPLY.

1.4.10.1 Example

-WTO 'ENTER DAY OF WEEK'

-REPLY &VAR1


1.5 Using Conditional Execution


Use conditional execution to dynamically modify the sequence in which stepsare executed, depending on the execution time value of certain variables.

Two types of variables can be tested with conditional execution job control:

■ User variables that are tested and set by conditional execution JCL andprovided subroutines

■ System variables that may be tested but not modified

Six conditional execution statements control job step execution:

Two subroutines, CARSET and CARTEST, allow you to test system and uservariables and set user variables from user programs.

Each of the variable types, conditional execution statements, and subroutinesare described in detail on the following pages.

Statement Function

// COPTION Overrides Unicenter CA-Driver for VSELOGSTEP and FLUSH generation options

// STEP or // DSTEP Identifies step names for console step loggingand branch reference

// GOTO or // DGOTO Branches forward unconditionally to a stepname

// FLUSH Bypasses the remainder of the job

// SET Sets user variables to user-specified values orto the system cancel code

// IF or // DIF Branches forward conditionally by testingeither a system variable or a user variable

1.5.1.1 Notes

The 'D' versions of the STEP, GOTO, and IF statements are used to distinguishthem from the VSE/SP control statements. Do not mix the 'D' versions and'non-D' versions within your procedure as unpredictable results may occur.

Unicenter CA-Driver for VSE can distinguish a VSE/SP IF statement from aUnicenter CA-Driver for VSE IF statement, but cannot distinguish a VSE/SPGOTO from a Unicenter CA-Driver for VSE GOTO unless the stepname beginswith a numeric (e.g. 1STEP). Therefore, when the Unicenter CA-Driver forVSE preprocessor encounters a// STEP statement, it generates both a Unicenter CA-Driver for VSE STEPstatement and a VSE/SP STEP label (if it begins with a non-numeric). The



Unicenter CA-Driver for VSE preprocessor will not change a // GOTOstatement into a Unicenter CA-Driver for VSE GOTO statement unless itbegins with a numeric.

1.5.2 User VariablesUser variables are used for step-to-step communication, rather than job streamto job stream communication. Between the start of a job and the end of thatjob, they are not modified by Unicenter CA-Driver for VSE except by explicitcommand of a SET statement or the CARSET subroutine. There are two typesof user variables: USER and USR.

1.5.2.1 USER variables

USER variables are one byte long and may have a value of one character, aone byte hexadecimal value (X'00'-X'FF'), or a numeric value in the range 0 -255. They are set to binary zeros at the start of each VSE job. In addition, theymay be tested against other USER or GLBL variables, literals, or the partitioncancel code. The following USER variables are available:

USER1 USER2 USER3 USER4 USER5 USER6 USER7 USER8

1.5.2.2 USR variables

USR variables are four bytes long and may have either a numeric (N'nnnn') orcharacter (C'cccc') value. The numeric value, however, only indicates that thefour digits must be numeric. For example, C'9999' is equal to N'9999'. Incontrast to USER variables, USR variables are set to blanks at the start of eachVSE job, and may be tested against other USR variables, the $RC or $MRCsystem variables. The following USR variables are available:

USR1 USR2 USR3 USR4 USR5 USR6 USR7 USR8

1.5.3 Global VariablesVariable names GLBL1 to GLBL8 can be set, and their value remainsunchanged until the variable is either reset by another SET statement or by asystem IPL. The variables have an initial value of X'00'. GLBL variables can beused to set system-wide values. Once set, a GLBL variable can be tested fromany job running in any partition on that CPU. The following are available:

GLBL1 GLBL2 GLBL3 GLBL4 GLBL5 GLBL6 GLBL7 GLBL8



1.5.4 System VariablesThese keywords are provided for testing system variables:

The partition ID (PARTN) is always tested against a two-character value, likeBG or F1, to the maximum number of partitions generated. The two-characterliteral does not need to be enclosed in quotes or other delimiters.

The date that is used for conditional execution testing is the date in thepartition communications region, not the system date. Thus, the presence of a// DATE statement in a job stream will affect the value of the date field usedfor this compare.

The time that is used for a conditional execution compare is that obtained bythe GETIME macro executed at the time the compare is made. The literalagainst which the time is compared must be in the form HHMMSS, with nopunctuation, leading zeros if necessary, and not enclosed in quotes or anotherdelimiter.

The Unicenter CA-Driver for VSE keyword SYS refers to the VSE cancel codeassigned to each user program upon termination, prior to loading and enteringthe job control program again. All user programs are assigned a cancel codeeven if a normal EOJ occurred, in which case the cancel code will be X'10'. Thecancel code (SYS) should always be tested against a one-byte hex literal in therange X'00' to X'FF'. A table of the VSE cancel codes can be found in the IBMmanual VSE/ADVANCED Functions Messages And Codes.

The keyword CPUID refers to the system CPU-ID value field. This fieldreflects the CPU-ID obtained by the supervisor at IPL time. To test the CPU-IDvalue a compare must be made using a six-digit literal in the form NNNNNN.

The keywords $RC and $MRC refer to the VSE/SP (or later version) keywordsof the same name.

Unicenter CA-Driver for VSEKeyword

VSE System Field Tested

PARTN partition ID (BG, F1, F2, F3, etc.)

DATE partition date (MM/DD/YY orDD/MM/YY), not the system date

TIME current system time (HHMMSS)

SYS partition cancel code

CPUID System CPU-ID (NNNNNN)

$RC VSE/SP return code

$MRC VSE/SP MAX return code



1.5.5 Conditional Execution StatementsConditional execution statements are designed for job step selection,JCL-to-program communications, and abend trapping. For branching withinthe confines of one job step to omit or include selected VSE job controlstatements, use conditional expansion.

Conditional execution statements are changed into VSE EXEC statements toinvoke the routines that perform the intended functions. Follow theseguidelines when coding conditional execution statements:

■ Do not place conditional execution statements between label informationstatements within a job step. All TLBL AND DLBL statements must eitherprecede or follow all conditional execution statements for each job step.For example, assume that the program PAY02 reads a tape on SYS008 andwrites a tape on SYS009 and therefore requires two TLBL statements. Usethis JCL to run this job step correctly:

// STEP PAY�2

// IF USER1 NE C'Y' GOTO BYPASSIT



// EXEC PAY�2

The above JCL would successfully process step PAY02, where user variableUSER1 is equal to 'Y'. The following example appears to do the samething; however, upon execution, the program PAY02 would cancel withthe VSE message 'NO LABEL INFORMATION SYS008', because the TLBLstatements are separated by conditional execution statements:

// STEP PAY�2


// IF USER1 NE C'Y' GOTO BYPASSIT


// EXEC PAY�2

■ Change the first slash (/) to a percent sign (%) when you catalogconditional execution statements into procedures. Upon retrieving andexpanding the procedure, Unicenter CA-Driver for VSE will change thepercent sign in position 1 back to a slash. (See Disguising Job ControlStatements.)



This Statement Must Be Cataloged As

// COPTION %/ COPTION

// STEP %/ STEP // DSTEP %/ DSTEP

// GOTO %/ GOTO // DGOTO %/ DGOTO

// FLUSH %/ FLUSH

// SET %/ SET

// IF %/ IF // DIF %/ DIF

1.5.5.1 Overriding Generation Options (COPTION)

// COPTION option,option,...

Use the COPTION statement to override the Unicenter CA-Driver for VSEgeneration options for the LOGSTEP and CANCEL parameters. One or two ofthese optional parameters may be entered in any order:

SLOG Log conditional execution step names on console.

NOSLOG Do not log step names on the system console.

FLUSH Flush the job if it cancels abnormally. This is the normal VSEprocedure for a canceled job.

NOFLUSH Do not flush upon job cancellation. This option will preventVSE from flushing a canceled job, and execution will continuewith the statement following the EXEC statement invoking theprogram that canceled. Therefore, if the NOFLUSH option is ineffect, whether by GEN option or by the COPTION statement,the VSE cancel code should be checked after the execution ofevery step, because the job will not be flushed uponcancellation for any reason. If a job stream contains data that aprogram which cancels does not read, that data will not bebypassed if the NOFLUSH option is in effect, resulting ininvalid statements on the system console.

The COPTION setting is in effect for the duration of the VSE job, unless it ischanged with another COPTION statement. This means that COPTION FLUSHfollowing COPTION NOFLUSH in the same VSE job (even the same step) willresult in the FLUSH option, as it is the last setting which remains in effect.



Examples

// COPTION SLOG,NOFLUSH

// COPTION NOSLOG

// COPTION FLUSH

1.5.5.2 Identifying Step Names (STEP, DSTEP)

// STEP stepname// DSTEP stepname

stepname Specify the name of the step (1-8 characters).

The STEP statement defines conditional execution step names that are

■ Targets of conditional or unconditional branches referenced on the IF andGOTO statements

■ Displayed on the system console if option SLOG is in effect

Step names may be from one to eight characters in length and must notcontain spaces. (The word FLUSH may not be defined as a step name.) Specialcharacters may be used. All references to a step name must precede the STEPstatement which defines that step name.

Examples

// STEP STEP1

// STEP CHECKVAL

// STEP 1

// STEP STEP#4

// STEP SEEIFBG

1.5.5.3 Unconditional Branching (GOTO, DGOTO)

// GOTO stepname// DGOTO stepname

stepname Specify the name of the step (1-8 characters).

The GOTO statement causes all JCL between the GOTO statement and thetarget step name to be bypassed. (The target step name must be defined on aSTEP statement within the same VSE job and after the GOTO backwardbranching is not allowed.) The operand of the GOTO statement can be either avalid step name or the keyword FLUSH which indicates that the remainder ofthe VSE job is to be bypassed:



// GOTO STEPNAME

// GOTO FLUSH

// DGOTO NEWSTEP

A GOTO action will be reported on the console if step logging is in effect(LOGSTEP=YES or COPTION SLOG).

1.5.5.4 Bypassing Steps (FLUSH)

// FLUSH

The FLUSH statement has no additional operands and causes the remainder ofthe VSE job to be bypassed. It is functionally equivalent to the GOTO FLUSHstatement.

1.5.5.5 Setting Values (SET)

// SET &variable=value

&variable Specify either a USER variable (USER1-USER8), a USR variable(USR1-USR8), or a Global variable (GLBL1-GLBL8).

value If the variable is a USER (USER1-USER8) or Global(GLBL1-GLBL8), specify either a one character literal, a one-bytehexadecimal value (X'00'-X'FF'), or a numeric value in the rangezero through 255 (N'0'-N'255'). To code a literal, first identify thevalue as character, hexadecimal or numeric by specifying C, X,or N. Then give the literal enclosed in quotes or some otherspecial character delimiter. Note that variables are stored asbinary values: the value N'33' is equal to the value X'21'; thevalue C'7' is not equal to the value N'7' but is equal to the valueX'F7' and the value N'247'.

If the variable is a USR variable (USR1-USR8), specify a four character literal inthe form N'nnnn' for a numeric value or C'cccc' for a character value.

Example For USER/Global Variables

C'A' The letter 'A'

C'4' The number four, specified as a character

C'/' The special character slash

C/'/ The special character apostrophe

X'��' Binary zero

X'27' The hexadecimal value 27, a decimal 39

X'FF' High values in hexadecimal

N'�' The number zero (same as X'��', but not C'�')

N'4' The number four, not equal to the character four (C'4')

N'255' The number 255, the maximum numeric value allowed

Example For USR Variables



C'AAAA' The character string AAAA

N'��' The numeric character string ��

C/'AB'/ The character string 'AB'

Use the SET statement to set or change the value of a USER, USR, or GLBLvariable variable. A USER or GLBL variable may be set to the value of anotherUSER variable, GLBL variable, reserved variable, or literal. A USR variablemay be set to another USR variable, a literal, the $RC, or $MRC systemvariables.

Examples

// SET USER1=GLBL3 Set USER1 equal to GLBL3

// SET USER4=SYS Set USER4 to the VSE cancel code

// SET GLBL8=X'45' GLBL8 will contain hexadecimal 45 (Dec 69)

// SET USER8=N'69' USER8 will contain the number 69

// SET USER6=N'255' The maximum numeric value allowed

// SET USER4=C'A' USER4 will contain the letter 'A'

// SET GLBL5=C'7' GLBL5 will contain the character '7'

// SET USR1=C'ABCD' USR1 will contain the characters 'ABCD'

// SET USR2=USR1 USR2 will contain the value of USR1

// SET USR1=$RC USR1 will contain the value of the system

variable $RC

// SET USR3=$MRC USR3 will contain the value of the system

variable $MRC

Setting a USER or GLBL variable to the VSE cancel code (// SET USER1=SYS)or setting a USR variable to $RC (// SET USR1=$RC) must be doneimmediately after the execution of the program from which the cancel code or$RC is to be saved. The SYS/$RC system variables of the last program toexecute are available only immediately after the completion of the program.Performing any function other than the SET statement will reset the SYS/$RCsystem variables including all other conditional execution statements, andexecutes of other user programs. The SYS or $RC system variable may betested with the IF statement rather than being saved with the SET statement;however, after the test it will be reset. As a result, it is generally easiest to set aUSER variable to the SYS code or a USR variable to the $RC and retain thevalue for later testing.



Example

// EXEC PAY�1

/�

// SET USER1=SYS Save the cancel code

// EXEC PAY�2

/�

// IF SYS NE X'1�' GOTO ABEND Check for normal EOJ in PAY�2

// IF USER1 EQ X'1�' GOTO OK Check for normal EOJ in PAY�1

// STEP ABEND Identify the step ABEND

// PAUSE � WARNING � CANCELLATION OCCURRED � EXEC PROC PAYRSR

// FLUSH

This example saves and tests the SYS code. Were USER1 tested before SYS, thedesired results would not have been obtained, as the testing of USER1 wouldhave reset the SYS code for the program PAY02.

1.5.5.6 Conditional Branching (IF, DIF)

// IF variable operator value GOTO stepname// DIF variable operator value GOTO stepname

Use the IF statement to test user variables and system variables against othervariables or literals and branch to the named step if the result of the test istrue. If the result is not true, execution continues with the next statement in thejob stream.

variable Any valid user or system variable:

SYS USER1 USER5 GLBL1 GLBL5 USR1 USR5

DATE USER2 USER6 GLBL2 GLBL6 USR2 USR6

TIME USER3 USER7 GLBL3 GLBL7 USR3 USR7

PARTN USER4 USER8 GLBL4 GLBL8 USR4 USR8

CPUID $RC $MRC

operator One of these relational operators:

LT less thanLE less than or equal to

EQ equal toGE greater than or equal to

GT greater thanNE not equal to

value A user variable, the SYS, CPUID, $RC, or $MRC systemvariable, or a literal in the format:

NNNNNN to compare against the CPUID

HHMMSS to compare against the time

MM/DD/YY to compare against the date

XX 2-character partition ID when testing PARTN



C'A' or any valid character literal

N'5' or any valid numeric literal (N'0'-N'255')

X'FF' or any valid hexadecimal literal (X'00'-X'FF')

N'nnnn' to compare against VSE/SP (or later version)$RC or $MRC values

C'cccc' to compare against USR1-USR8 user variables

GOTO This is optional and is used for documentation purposes.

stepname Any valid conditional execution stepname as defined on aSTEP statement that follows the referencing IF statement andprecedes VSE

end-of-job (/&). Stepname may also be the keyword FLUSH, indicating theremainder of the VSE job stream is to be bypassed.

Examples

These test a user or GLBL variable:

// IF GLBL1 EQ C'Y' GOTO STEP4

// IF USER6 LT N'147' GOTO FLUSH

// IF USER3 NE X'FF' GOTO NOTOFF

These test the SYS code system variable:

// IF SYS EQ X'1�' GOTO NORMEOJ

// IF SYS EQ X'24' GOTO OPERINT

These test the partition ID:

// IF PARTN NE BG GOTO CANTCATL

// IF PARTN EQ F1 GOTO CICSPART

These test the partition date:

// IF DATE LE 12/31/79 GOTO DO1979

// IF DATE EQ �2/29/8� GOTO LEAPDAY



These test the system time:

// IF TIME LE �6�� GOTO EARLYAM

// IF TIME GE 2�� GOTO AFTER8PM

These test the CPUID field:

// DIF CPUID EQ 123456 GOTO OKCPU

// IF CPUID NE 123456 GOTO FLUSH

These test the $RC field:

// DIF $RC NE N'��' GOTO ENDJOB

// IF $RC NE N'��' GOTO ENDJOB

1.5.6 Conditional Execution Program InterfacesUnicenter CA-Driver for VSE provides two callable subroutines to test userand system variables and to set user variables from user-written programs.These relocatable modules, CARTEST and CARSET, use standard IBM linkageconventions; the CALL macro is used to enter them from assembly programsand the CALL verb in ANSI COBOL.

1.5.6.1 Setting Variables from a Program (CARSET)

Use the CARSET subroutine to set USER variables (USER1-USER8), globalvariables (GLBL1-GLBL8 and &C_GLBL1-&C_GLBL8), or USR variables(USR1-USR8). Three fields are needed to call CARSET:

■ Receiving field - the user variable that will be set

■ Sending field - the value to which it will be set

■ Return-code field - an indication of the results

Receiving Field

The receiving field is the four, five or eight-byte name of the user variable thatwill be altered by calling CARSET: USER1-USER8, GLBL1-GLBL8, USR1-USR8



COBOL Example:

77 USER-VARIABLE PIC X(5) VALUE 'USER4'.

Assembly Language Example:

USERVARB DC CL5'USER4'

Sending Field

The sending field is variable in length, depending upon whether the variable isto be set equal to another variable, a literal, $RC, $MRC, or SYS (VSE cancelcode):

■ If a USER or GLBL variable is to be set equal to another variable, thesending field is five bytes: USER1-USER8, GLBL1-GLBL8,&C_GLBL1-&C_GLBL8.

■ If a USER or GLBL variable is to be set equal to a literal, the field lengthwill be from four to six bytes in length. The first byte indicates the type ofliteral: character (C), hexadecimal (X), or numeric (N). The next three tofive bytes are the value delimited by special characters. (In this case, usespecial characters other than quotes.)

■ If a USR variable (USR1-USR8) is to be set to another USR variable, thesending field is four bytes.

■ If a USR variable is to be set to a literal, the sending field must be sevenbytes long. The first byte indicates the type of literal: character (C) ornumeric (N). The next six bytes are the value delimited by a single quote(') for numeric (N), or a special character for character (C).

COBOL Examples:

77 SENDING-FIELD PIC X(4) VALUE 'C-Y-'.

77 SENDING-FIELD PIC X(5) VALUE 'X/�l/'.

77 SENDING-FIELD PIC X(6) VALUE 'N''255'''.

77 SENDING-FIELD PIC X(7) VALUE 'N''��'''.

Assembly Language Examples:

SDGFIELD DC C'C-Y-' The letter 'Y'

SDGFIELD DC C'X/�l/' The hexadecimal value '�1'

SDGFIELD DC C'N''255''' The number 255

SDGFIELD DC C'N''��''' The number ��



Return Code Field

The return code field is a one-byte character field that, after completion, willcontain one of the following:

0 no errors

1 receiving field name is invalid

2 sending field name or syntax is invalid

If the return code is other than zero, the operation was not performed.

Example 1

�1 CARSET-FIELDS.

�3 CF-VARIABLE PIC X(5) VALUE 'USER1'.

�3 CF-NEW-VALUE PIC X(4) VALUE 'C/Y/'.

�3 CF-RETURN-CODE PIC X.

88 CF-RETURN-CODE-IS-OK VALUE '�'.

CALL 'CARSET' USING CF-VARIABLE

CF-NEW-VALUE

CF-RETURN-CODE.

IF NOT CF-RETURN-CODE-IS-OK

GO TO USER-FIELD-NOT-SET.

This example calls CARSET from a COBOL program. After the execution ofthe program, the user variable USER1 would have been set to the letter 'Y'.This user variable could be subsequently tested by conditional executionstatements in a later step in order to determine, for instance, whether a laterstep should be processed. This facility, therefore, provides a means forprogrammatic decisions to determine which job steps are processed. Suchconditional JCL that would test USER1 might appear as follows:

// IF USER1 NE C'Y' GOTO EXITWKLY

// STEP WEEKLY

This conditional execution JCL would act upon the results of setting the uservariable to a 'Y' (indicating a weekly run) or to some other value, in whichcase step WEEKLY would be bypassed.



Example 2

CALL CARSET,(USERTO,USERFROM,USERCODE)

CLI USERCODE,C'�' Test for successful completion

BNE ERROR Branch if error occurred

USERTO DC C'USER1' Receiving field

USERFROM DC C'USER4' Sending field

USERCODE DC C' ' Return code

This example calls CARSET from an assembly language program. It showshow to set one user variable to be equal to another. In this case, USER1 willbe set to the same value as USER4.

1.5.6.2 Testing Variables Program (CARTEST)

Use the subroutine CARTEST to perform the same functions as the IFstatement. CARTEST can test the six system variables (SYS, PARTN, DATE,TIME, $RC, $MRC), the eight USER variables (USER1 - USER8), the eightglobal variables (GLBL1 - GLBL8), and the eight USR variables (USR1 - USR8).It provides a mechanism for program-to-program communications, as well asconditional execution JCL to program communications (see Example 3).

Three fields are necessary for this operation:

■ Field to be tested

■ Field (value) against which to test it

■ Resulting field

Field to Be Tested

The field to be tested is a three- to five-byte field containing the name of theuser or system variable to be tested:

SYS USER1 USER5 GLBL1 GLBL5 USR1 USR5

PARTN USER2 USER6 GLBL2 GLBL6 USR2 USR6

DATE USER3 USER7 GLBL3 GLBL7 USR3 USR7

TIME USER4 USER8 GLBL4 GLBL8 USR4 USR8

$RC $MRC



COBOL Examples:

77 TEST-FIELD PIC XXX VALUE 'SYS'.

77 TEST-FIELD PIC X(5) VALUE 'USER5'.

77 TEST-FIELD PIC X(4) VALUE 'DATE'.


TSTFIELD DC CL5'PARTN' ... To test the partition

TSTFIELD DC C'DATE' ... To test the date

TSTFIELD DC C'USER7' ... To test user variable USER7

Field to Test Against

The field against which the above will be tested may be:

USERn ...Any user variable (USER1 through USER8)

MM/DD/YY ...For testing the date

HHMMSS ...For testing the time

XX ...A valid partition ID for testing 'PARTN'

LITERAL ...For comparing a user variable to a literal

N'nnnn' ...For testing $RC and $MRC

C'cccc' ...For testing USR variables (USR1-USR8)

The format and syntax of these fields are the same as for CARSET and theconditional execution statements.

COBOL Examples:

77 TEST-VALUE-USER PIC X(5) VALUE 'USER4'.

77 TEST-VALUE-DATE PIC X(8) VALUE '�1/�1/96'.

77 TEST-VALUE-TIME PIC X(6) VALUE '183��'.

77 TEST-VALUE-PARTN PIC XX VALUE 'BG'.

77 TEST-VALUE-LITERAL PIC X(5) VALUE 'X/�1/'.

77 TEST-VALUE-LITERAL PIC X(4) VALUE 'USR1'.


TSTUSER DC C'USER4' To test against the value in USER4

TSTDATE DC CL8'�l/�l/96' To test the date

TSTTIME DC C'183��' To test the time

TSTPARTN DC C'BG' To test the partition

TSTLTRL1 DC C'X/�l/' To test against a literal

TSTLTRL2 DC C'N.22.' To test a numeric literal

TSTLTRL3 DC C'C-A-' To test a character literal

TSTLTRL4 DC C'N''��''' To test against $RC and $MRC



Resulting Field

The result of the test is passed back in the third field, which must be atwo-byte character field.

The result field in COBOL:

77 TEST-RESULT PIC XX VALUE SPACES.

The result field in assembler:

RESULT DS CL2

The contents of the result field will be as follows:

GT user or system variable was greater than second field

EQ the two fields were found to be equal

LT user or system variable was less than second field

01 user or system variable name was invalid (first field)

02 value against which to test was invalid (second field)



Example 1

�1 CARTEST-FIELDS.

�3 CF-VARIABLE1 PIC X(5) VALUE 'USER1'.

�3 CF-VARIABLE2 PIC X(5) VALUE 'USER2'.

�3 CF-RETURN-CODE PIC X(2).

88 CF-RETURN-CODE-NOT OK VALUE '�1' '�2'.

88 CF-VARIABLE1-EQUAL VALUE 'EQ'.

88 CF-VARIABLE1-LESS VALUE 'LT'.

88 CF-VARIABLE1-GREATER VALUE 'GT'.

CALL 'CARTEST' USING CF-VARIABLE1

CF-VARIABLE2

CF-RETURN-CODE.

IF NOT CF-RETURN-CODE-NOT-OK

GO TO CARTEST-ERROR.

IF NOT CF-VARIABLE1-EQUAL

GO TO CARTEST-NOT-EQUAL.

This sample COBOL routine determines if USER1 is equal to USER2.

Example 2

CALL CARTEST,(CARTST1,CARTST2,CARTST3)

CLI CARTST3,C'�' TEST FOR �1 OR �2

BE ERROR ERROR IF SO

CLC CARTST3,=C'EQ' WAS RESULT 'EQUAL'

BE USER5ISN YES USER5 IS AN 'N'

CARTST1 DC C'USER5' ...Name of the user variable

CARTST2 DC C'C/N/' ...The literal for character N

CARTST3 DS CL2 ...The result field

This assembly language example tests USER5 to determine if it is equal to theletter 'N'.

Example 3

Through the use of variable parameters, conditional execution statements, andthe CARTEST subroutine, parameters can actually be passed from the //PROC statement to user applications programs. Assume a procedure containsthe variable parameter &SWITCH. This procedure also contains the followingstatement:

%/ SET USER1=C'&SWITCH'

(with the first slash a percent sign)



As a result of this, the following PROC statement:

// PROC NAME,SWITCH=3

would result in the set statement being expanded as:

// SET USER1=C'3'

This would enable a user program to interrogate the user variable USER1 inorder to determine the value of SWITCH, which might be, for example, thenumber of input files to process.


1.6 Accessing the Procedure Library (CARACC)


The CARACC relocatable subroutine allows you to analyze UnicenterCA-Driver for VSE procedures via call linkage. You can access the informationin the procedure library and process it in any form you want. To useCARACC, follow these guidelines:

■ The call must be with the fields exactly defined as in the example, in thesame order.

■ The first field (one byte long) is the area in which the return code will bepassed back from the user access module.

■ The second byte is used by the calling program to indicate to CARAC thathe wants another PROC (one byte long - a one in that byte indicatesanother PROC is to be called).

■ The third field is an 80-byte field in which the proc statement is placed(exactly as in the example).

■ The fourth parameter is 80 bytes long and is the area in which CARACCreturns the proc statements one by one.



1.6.1 Example

CARSUB BALR RC,�

USING �,RC

LA RD,SAVE

DOLOOP CALL CARACC,(RETCODE,FCODE,PROCST,STMNTW)

MVI FCODE,C' '

CLI RETCODE,C'�'

BE WTCNS

TM SWITCH,X'8�'

BO ENPPRC

OI SWITCH,X'8�'

CLI RETCODE,C'4'

BE PROC2

B ENPPRC

PROC2 MVI FCODE,C'1'

MVC PROCST,PROCST1

B DOLOOP

SPACE 1

WTCNS LA R7,STMNTW

LA R6,L'STMNTW

STCM R7,7,RDRCCW+1

STC R6,RDRCCW+7

LA R1,BADRDR

EXCP (1)

WAIT (1)

MVC STMNTW,STMNTW-1

B DOLOOP

SPACE 1

ENPPRC EOJ

SPACE 1

BADRDR CCB SYSLOG,RDRCCW X'94��'

RDRCCW CCW X'�9',RDRMSG,�,8�

SWITCH DC X'�'

RDRMSG DC CL8�' '

RETCODE DC C' '

FCODE DC C' '

PROCST DC CL8�'// PROC WTOREP'

DC C' '

STMNTW DC CL8�' '

PROCST1 DC CL8�'// PROC CAJDDEM2'

SAVE DC 18F'�'

SPACE 1

R� EQU �

R1 EQU 1

R2 EQU 2

R3 EQU 3

R4 EQU 4

R5 EQU 5

R6 EQU 6

R7 EQU 7

R8 EQU 8

R9 EQU 9

RA EQU 1�

RB EQU 11

RC EQU 12

RD EQU 13

RE EQU 14

RF EQU 15

END CARSUB



1.6.2 Return Codes

ReturnCode

Meaning

1 Password security violation (no password on INPUT procstatement)

2 Password security violation (incorrect password)

3 $CAIRGEN not found

4 End of proc (move one to the function code and a new procstatement to field three in order to continue)

5 Invalid statement passed

6 Proc not found

7 Password given but not needed

8 Password syntax error

9 ADAPTER (Computer Associates system adapter not active)

A I/O error - dump your program; call Computer Associates


1.7 Automatic Job Submission


One or more job streams may be submitted during the processing of acurrently executing job. To submit job streams, you can use

■ a // SUBMIT statement in the job stream with conditional executionstatements which provide conditional job submission

■ a program call to the subroutine CARSUBMT which providesprogrammatic decisions about job submission

These submitted job streams are placed in the POWER reader queue forsubsequent scheduling and execution. All Unicenter CA-Driver for VSEfacilities are available for jobs submitted using either technique, including thesubmitting of // PROC statements (disguised as %/ PROC), and the use ofdata inclusion (with both the calling PROC and the terminating null PROCdisguised as %/ PROC).

1.7.1 From a Unicenter CA-Driver for VSE ProcedureAutomatic job submission may be invoked at any point in an executing jobstream by the SUBMIT statement:

// SUBMIT JOB=xxxxxxxx, CLASS=y,PRI=z,DISP=b,SYSID=s,LDEST=ldest,..... ....PDEST=pdest,USER=user

JOB=xxxxxxxx Give the POWER job name to be used for the submitted job.

CLASS=y Give the alphabetic class for the submitted job.

PRI=z Give the POWER priority number for the submitted job.

DISP=b Give the POWER disposition for the submitted job.

SYSID=s Give the POWER SYSID for the submitted job.

LDEST=ldest Give the POWER LDEST for the submitted job.

PDEST=pdest Give the POWER PDEST for the submitted job.

USER=user Give the POWER USER for submitted job.

These keywords are optional; if omitted, the values will default to the name,class, and priority of the job containing the submit statement.

You can also use a POWER JECL JOB statement to control the submitted job. Ifyou use a POWER JOB statement, the JOB keyword must be specified on the// SUBMIT statement. However, all job attributes will be taken from thePOWER JOB statement, whether or not they are included on the // SUBMITstatement.



Once automatic job submission has been invoked, it remains in effect (allencountered statements are submitted) until the following statement isencountered:

// SUBMIT END

Any and all statements between the // SUBMIT statement and the //SUBMIT END statement are considered to be part of the submitted job. Certainstatements, however, must be disguised when they are to be submitted usingthis facility:

■ All POWER JECL that is to be submitted must begin with $ ** rather than* $$. The submission process will modify such statements back to * $$ asthe job is submitted. If this change is not made, POWER will interceptthese statements and act upon them as the submitting job stream isprocessed, rather than as the submitted job stream is processed.

■ The VSE JCL statements // JOB, /*, and /& and the Unicenter CA-Driverfor VSE PROC statement // PROC must all begin with a percent sign (%)rather than with a slash (/).

■ If a SUBMIT statement is to be submitted, it also must be disguised byreplacing the first slash with a percent sign.

SUBMIT statements may be continued by:

■ placing a comma at the end of the statement

■ placing the DRIVER continuation character in position 1 of the nextstatement

■ continue with the rest of the parameter.

The // SUBMIT statement should be placed between job steps in a job stream.Label information for any job step may not be separated by SUBMIT controlstatements and the intervening job or jobs to be submitted.

A job stream may submit a job stream that will also submit a third job stream.The third job stream may not use job submission, with this exception: if the jobsubmission statements in the third job stream originate from a UnicenterCA-Driver for VSE procedure (rather than being actually submitted), the thirdjob stream may submit a fourth job stream, and so on (provided eachsucceeding job is submitted using a submit statement originating from theprocedure library).



1.7.1.1 Example

// JOB TEST1

// TLBL FILEIN,'ANY TAPE DSN'

// DLBL FILEOUT,'ANY DISK DSN',�,SD

// EXTENT SYS��6,VOLSER,1,�,SSSS,NNNN

// ASSGN SYS��6,DISK,VOL=VOLSER,SHR


// EXEC DUMPTAPE

/�

// SUBMIT JOB=TEST2,CLASS=T,PRI=7

$ �� LST CLASS=C,PRI=7

%/ JOB TEST2 Print 'ANY DISK DSN' file

// DLBL DISKIN,'ANY DISK DSN'

// EXTENT SYS��6,VOLSER


// EXEC PAYREPT

%�

%&

// SUBMIT END Terminate job submission

. . . Remainder OF TEST1 job stream

/&

In this example, the job stream TEST1 will submit the job stream TEST2 aftercompletion of the first step. The first step creates a disk file that may bereported on by the TEST2 job stream while the remainder of the TEST1 jobstream is executing (assuming another partition is available). Typically,automatic job submission will be used to submit // PROC statements whichwill cause retrieval of the desired job stream rather than submitting the entirejob stream itself.

1.7.2 From a User ProgramUse the callable subroutine CARSUBMT to submit job streams fromuser-written programs. This subroutine uses standard IBM linkage conventionsand standard call protocol for assembly language and ANSI COBOL.

Two fields are passed to CARSUBMT:

■ the first is the 80-byte field containing the statement to be submitted forthis call

■ the second is a one-byte field used as a return code which will contain

0 if no errors are found

1 if a CTL statement error is found

2 if a data statement has been found in input

3 if a program load error has occurred



As one call submits one statement, submitting a ten-statement job streamrequires ten calls to CARSUBMT. The first statement passed may be a // CTLstatement which generates a POWER '* $$ JOB' statement to provide thePOWER job name, class, and priority of the submitted job. (If POWER jobstatements are submitted, the job attributes from the POWER job statementswill be used instead of those from the // CTL statement.)

The format of the CTL statement is:

// CTL NAME=xxxxxxxx,CLASS=y,PRI=z,DISP=b,

SYSID=s,LDEST=ldest,PDEST=pdest,USER=user

NAME=xxxxxxxx Give the POWER job name to be used for the submitted job.

CLASS=y Give the alphabetic class for the submitted job.






USER=user Give the POWER USER for the submitted job.

If any of the parameters are omitted, the POWER defaults will be used. Thereis one exception: if NAME is omitted, the parameter will default to CARCOM.Multiple control statements are allowed but must follow one another withoutany intervening statements.

The last statement submitted to the CARSUBMT subroutine must be an //END statement. All statements between the // CTL statement and the // ENDstatement will be submitted to POWER for subsequent scheduling andexecution. No statements, POWER or VSE, need be disguised in any fashion(for example, // JOB should not be submitted as %/ JOB).



1.7.2.1 Example 1

SETLOOP LA 1,STMTABLE ... First stmt to submit

LA 2,8� ... Increment for BXLE

LA 3,LASTSTMT ... Last stmt to submit

DOLOOP MVC STMTWORK,�(1) ... Move the stmt to pass

CALL CARSUBMT,(STMTWORK,RETCODE)... Issue the call

CLI RETCODE,C'�' ... Check return code

BNE CTLERROR ... Branch if error

BXLE 1,2,DOLOOP ... Complete the loop

�

� ... Remainder of program

�

RETCODE DS C Return code from CARSUBMT

STMTWORK DS CL8�

STMTABLE DS �CL8�

DC CL8�'// CTL NAME=TESTJOB,CLASS=T,PRI=6'

DC CL8�'� $$ LST CLASS=A,PRI=8

DC CL8�'// JOB LIBR'

DC CL8�'// EXEC LIBR'

DC CL8�'AC S=IJSYSRS.SYSLIB'

DC CL8�'LD �.PROC'

DC CL8�'/� '

DC CL8�'/&& '

DC CL8�'// END'

LASTSTMT EQU �-8�

This example shows an assembly language program calling the CARSUBMTsubroutine to submit a job to obtain a directory listing of the system libraries.



1.7.2.2 Example 2

�1 W�1-INDEPENDENT-ITEMS.

�3 W�1-SUB PICTURE S9(4) COMP SYNC.

�3 W�1-RETURN-CODE PICTURE X.

88 W�1-RETURN-CODE-IS-OK VALUE '�'.

�

�1 W�2-JCL-TABLE.

�3 W�2-JT-CONSTANTS.

�5 FILLER PICTURE X(8�) VALUE

'// CTL NAME=TESTJOB,CLASS=F,PRI=6'.


'� $$ LST CLASS=B,PRI=8'.


'// JOB LIBR'


'// EXEC LIBR'


'AC S=IJSYSRS.SYSLIB'


'LD �.PROC'


'/�'.


'/&'.


'// END'.

�3 FILLER REDEFINES W�2-JT-CONSTANTS.

�5 W�2-JT-STMT PICTURE X(8�)

OCCURS 8 TIMES.

PROCEDURE DIVISION.

PERFORM 1��-CALL-CARSUBMT THRU 1��-CC-EXIT

VARYING W�1-SUB FROM +1 BY +1

UNTIL W�1-SUB GREATER +9.

� REMAINDER OF PROCEDURE DIVISION STATEMENTS

�

1��-CALL-CARSUBMT.

CALL 'CARSUBMT' USING W�2-JT-STMT (W�1-SUB)

W�1-RETURN-CODE.

IF NOT W�1-RETURN-CODE-IS-OK

PERFORM 2��-ERROR-RTN THRU 2��-ER-EXIT.

1��-CC-EXIT.

EXIT.

�

2��-ERROR-RTN.

ERROR HANDLING ROUTINE FOR CARSUBMT CALL ERROR

2��-ER-EXIT.

EXIT.

This example shows a COBOL program calling the CARSUBMT subroutine tosubmit a job to get a listing of the system libraries.

1.7.3 From the Operator ConsoleUse the utility program CARCOM to allow operators to submit jobs from thesystem console. Any type of JCL, DATA, PROC statements, or conditionalexecution statements may be submitted. To use the console job submissionprogram, execute CARCOM:



// JOB CARCOM

// EXEC CARCOM

/�

/&

All statements entered will be submitted to the POWER reader queue forexecution, except the two statements below:

// CTL

// END

The format of the CTL statement is:

// CTL NAME=xxxxxxxx,CLASS=y,PRI=z,DISP=b,

SYSID=s,LDEST=ldest,PDEST=pdest,USER=user

NAME=xxxxxxxx Give the POWER job name to be used for the submittedjob.

CLASS=y Give the class for the submitted job.






USER=user Give the POWER USER for the submitted job.

If any of the parameters are omitted, the POWER defaults will be used. Thereis one exception: if NAME is omitted, the parameter will default to CARCOM.Multiple control statements are allowed but must follow one another withoutany intervening statements.

The // END statement terminates the CARCOM execution. Simply hitting theEND or ENTER key on the console will result in entering a blank statement(blank statements are ignored by CARCOM); it will not terminate theCARCOM program.

Retaining a CARCOM job in the POWER reader queue with DISP=L specifiedallows the operator to release it at his convenience. JCL/DATA may be enteredthrough a normal job control read at the console.



1.7.3.1 Example 1

BG CACR71�R ENTER CARCOM STATEMENT ...A prompt from CARCOM for input

BG // CTL PRI=7,CLASS=A ...Specify the class and priority

BG // JOB DSERV

BG // EXEC DSERV

BG DSPLYS ALL

BG /�

BG /&

BG � $$ EOJ ...End this POWER job

BG // CTL CLASS=C ...Change the class, not priority

BG // PROC LVTOC,DISK=151 ...A sample PROC statement

BG // END ...Terminate the session

The first job, DSERV, would be submitted as class A and priority 7. Thesecond job would be submitted with a priority of 7, since that was notchanged, and a class of C, since that was explicitly changed by CTL statement.This example assumes that the PROC LVTOC exists and contains the necessaryPOWER and VSE job and end-of-job statements. Note that jobs may besubmitted to multiple partitions (classes) during one execution of CARCOM,and that data inclusion is fully supported.

1.7.3.2 Example 2

BG CACR71�R ENTER CARCOM STATEMENT ...A prompt from CARCOM for input

BG // CTL PRI=7,CLASS=A ...Specify the class and priority

BG � $$ JOB JNM=DSERV

BG // JOB DSERV

BG // EXEC DSERV

BG DSPLYS ALL

BG /�

BG /&

BG � $$ EOJ ...End this POWER job

BG // END ...Terminate the session

In this case, the job name will be DSERV, and all other attributes will comefrom the POWER defaults. The attributes specified on the // CTL statementwill be ignored for this POWER job.


1.8 Enabling and Disabling Unicenter CA-Driver for VSE


Unicenter CA-Driver for VSE's control over job input can be enabled ordisabled by either of the following two methods: from a // CARCTLstatement in a VSE job stream or from an AR command.

Whenever Unicenter CA-Driver for VSE is enabled or disabled, one of thesemessages is written to the system console:

CACR5�1I CA-DRIVER HAS BEEN ENABLED

CACR5�1I CA-DRIVER HAS BEEN ENABLED FOR pp PARTITION

CACR5�1I CA-DRIVER HAS BEEN DISABLED

CACR5�1I CA-DRIVER HAS BEEN DISABLED FOR pp PARTITION

where pp is the individual partition's ID

1.8.1 Enabling/Disabling with // CARCTL CommandsYou can enable/disable all partitions or an individual partition using aCARCTL statement. However, the command must be the first statement in thejob stream.

■ To disable all partitions or an individual partition, use one of the followingstatements:

// CARCTL DISABLE// CARCTL DISABLE,pp


Unicenter CA-Driver for VSE is disabled completely or in a partition untilone of the following statements is submitted to enable it.

■ To reenable the partition or entire CPU to resume normal systemfunctioning, use one of the following statements:

// CARCTL ENABLE// CARCTL ENABLE,pp


■ To temporarily disable Unicenter CA-Driver for VSE for a specific job (useful for jobs with no Unicenter CA-Driver for VSE statements), place thisstatement immediately after the POWER JECL job statement:

// CARCTL OFF

Unicenter CA-Driver for VSE temporarily disables itself for the specific jobuntil the job completes.



1.8.2 Enabling/Disabling with AR CommandsYou can enable/disable all partitions or an individual partition using an ARcommand.

■ To disable all partitions or an individual partition, enter one of the ARcommands on the system console:

DR DISABLEDR DISABLE,pp


■ To reenable all partitions or an individual partition, enter one of the ARcommands on the system console:

DR ENABLEDR ENABLE,pp



1.9 Checking Status and Statistics

1.9 Checking Status and Statistics

To display the status of all partitions and the Unicenter CA-Driver for VSEsystem, enter the following AR command on the system console:

DR STATUS

This command displays the following:

CACR512I CA-DRIVER PARTITION BG - STATUS ENABLEDCACR512I CA-DRIVER PARTITION F1 - STATUS ENABLEDCACR512I CA-DRIVER PARTITION F2 - STATUS ENABLEDCACR512I CA-DRIVER PARTITION F3 - STATUS DISABLED

To obtain Expanded JCL file statistics, enter the BUFSTATS command on thesystem console:

DR BUFSTATS

This command displays statistics such as the average number of buffers, thenumber of jobs, and the total number of buffers used by Unicenter CA-Driverfor VSE. For example,

dr bufstats

CACR515I CA-DRIVER AVERAGE BUFFERS=��2 JOBS=�� TOTAL

BUFFERS=�� MAX BUFFER=��


1.10 Procedure Modeling


Use procedure modeling to test procedure expansion without submitting theresults of the expansion to POWER for execution. This provides a list of theJCL used to process a specific job and allows you to test and debugcomplicated procedures.

To use procedure modeling, include this statement in the input job streamimmediately following the POWER job statement:

// CARCTL MODEL

The expanded job stream will be displayed on the device to which SYSLST isassigned in the partition in which the job would have been processed. Themodel listing indicates where a procedure is invoked, displays each statementafter processing conditional expansion statements and replacing variableparameters, indicates where procedure nesting begins and ends, and indicateswhere data inclusion is invoked and terminated.

Procedure modeling remains in effect for a job unit:

■ From the beginning of a POWER job to its end

■ From the beginning of a VSE job to its end if no POWER JECL surroundthe job (POWER JECL contained within a procedure will not terminateprocedure modeling.

The only statement in a submitted job stream that will not be printed on themodel listing is a POWER * $$ LST statement which immediately follows //CARCTL MODEL. This statement will be passed to POWER to control theclass, priority, and disposition of the model listing.

1.10.1.1 Example 1

� $$ JOB JNM=TESTRUN

// CARCTL MODEL

// PROC PAYROLL

� $$ EOJ

This example prints the entire procedure on SYSLST as it would have beensubmitted to POWER for execution were procedure modeling not in effect.Note that it doesn't matter whether or not the procedure PAYROLL containsJECL to identify the job boundaries. In fact, it may even contain multiplePOWER jobs or VSE jobs or any combination of both.



1.10.1.2 Example 2

� $$ JOB JNM=MODEL Begin job to be modeled

// CARCTL MODEL Enter modeling mode

� $$ LST CLASS=A,PRI=9 Control model listing

// PROC PROCNAME Proc to be modeled

� $$ EOJ Terminate model mode

This example includes a POWER LST statement to control the class andpriority of the model listing. Because this statement immediately follows themodel statement, it is passed to POWER.


1.11 Procedure Punching

1.11 Procedure Punching

Procedures may be punched rather than submitted to POWER for execution.This gives you an exact copy of the JCL that would be processed and can beused for off-site processing or programmer testing.

To use procedure punching, include this statement in the input job streamimmediately following the POWER job statement:

// CARCTL PUNCH

The expanded job stream is punched on the device assigned to SYSPCH in thepartition in which the job would have been processed.

Procedure punching works the same way as procedure modeling:

■ Punching is terminated by a POWER end-of-job statement if the job beginswith a POWER job statement or a VSE end-of-job if no POWER JECLsurrounds the VSE job.

■ A POWER * $$ PUN statement immediately following a CARCTL punchstatement will be used to control the class, priority, and disposition of thepunch output.

■ Any other JCL, POWER JECL, or a PUN statement not immediatelyfollowing the CARCTL punch statement will be punched with theexpanded procedure.


1.12 Accessing the BrightStor CA-Dynam/T Catalog


If BrightStor CA-Dynam/T is installed in your shop, you can use theBrightStor CA-Dynam/T interface to access the BrightStor CA-Dynam/Tcatalog through Unicenter CA-Driver for VSE. This allows operators to displaytape requirements before a job is processed.

When the BrightStor CA-Dynam/T interface is activated, Unicenter CA-Driverfor VSE accesses the BrightStor CA-Dynam/T catalog, locates the eligible tapedata sets and collects setup information. Any BrightStor CA-Dynam/Tparameters on the TLBL are resolved in order to locate the correct version ofthe data set. At completion of JOB preprocessing, Unicenter CA-Driver for VSElogs all collected setup information on the console. This may include:

■ The volume serial numbers of up to four input volumes per DSN

■ The data set name

■ A comment (either literal or from the catalog)

■ The number of scratch tapes needed

■ Any length, density and owner ID attributes

To activate the interface:

■ Specify DYNAMT=YES in the installation generation options.

■ Add CARMSG to the TLBL JCL statement to identify tape data sets thatare eligible for the BrightStor CA-Dynam/T interface. This is required toactivate the BrightStor CA-Dynam/T interface for that TLBL:

// TLBL TAPE, 'FILE-ID' CARMSG

CARMSG has these optional parameters:

CARMSG=Output(nn) | Input [,comment]

Output Specify O or OUTPUT if the TLBL is controlled by BrightStorCA-Dynam/T but is being created as an output volume. If this isnot specified, TLBL is assumed to be an input data set.

Input Specify I or INPUT if the TLBL is controlled by BrightStorCA-Dynam/T but is being used as an input volume.

(nn) Specify the number of scratch tapes needed if this is to be amultivolume file. Enclose the number in parentheses. If no numberis specified, one scratch tape is assumed.



comment Comments are printed on the console alongside the TLBL DSN towhich they apply. To supply a literal comment on the TLBLstatement, specify the text surrounded by quotes. To print thecomment field from the data set record of the BrightStorCA-Dynam/T catalog, specify $CARMSG.

1.12.1.1 Examples

CARMSG=OUTPUT(3)

CARMSG=O(2),'SEND BOTH TAPES OFF SITE'

CARMSG=I,'TAPE IS THE PAYROLL MASTER'


Chapter 2. Unicenter CA-Driver for VSE Commands

This chapter describes each of the Unicenter CA-Driver for VSE commandsand gives examples of usage.

Chapter 2. Unicenter CA-Driver for VSE Commands 2-1

2.1 Overview

2.1 Overview

Use these batch commands to maintain and report on the Unicenter CA-Driverfor VSE procedure library. To maintain the library online, see the chapter on"Online DRIVER Procedure Maintenance."

To Maintain The ProcedureLibrary

Use This Command

Change thecontrol charactercontinuation character

-CTLCHAR=character-CONTCHAR=character

Catalog procedures -PROC name,OPTION=CREATE

Replace procedures -PROC name,OPTION=REPLACE

Rename procedures -PROC name,RENAME=newname

Delete procedures -PROC name,OPTION=DELETE

Delete saved procedures -PROC name,OPTION=DELSAV

Release enqueue on a procedure. -PROC name,OPTION=RELEASE

To Report On The ProcedureLibrary

Use This Command

Update procedures by adding,changing, replacing and deletingstatements or variable parameters

-PROC name,OPTION=SELECT

Changing character strings in one procedure all procedures selected procedures

-PROC name,COR=dsdsd-LIB COR-LIB COR followed by -SEL

Override duplicate updateprotection

-OVERRIDE

Print a procedure -PROC name

Punch a procedure -PROC name,OPTION=PUNCH

Print and punch one procedure all procedures selected procedures

-PROC name,PUNCH=YES-LIB-LIB followed by -SEL

Print statements that containspecified character strings

-LIB PRINT,SCAN

List the library directory -DISPLAY


2.1 Overview

These commands are described in alphabetical order after the CARUTILcoding requirements and keywords.

To Report On The ProcedureLibrary

Use This Command

Produce cross-reference reports onprocedures in the library

-LIB REPORT-RPG report type

Report on the status of theprocedure library

-LIB STATUS

2.1.1 Procedure Library IntegrityTo ensure that the integrity of the procedure library is inviolate, partialupdates of library members will not occur if the update job is cancelled, thepower fails, or the operator IPLs the system during an update.

CARUTIL always indicates actions that have been taken, such as the creationof a procedure, the update of a procedure, and so forth. This action messageindicates exactly what CARUTIL did or did not do. When in doubt, rememberthat if CARUTIL did not state in an action message that a requested functionwas performed, it is safe to assume that the action was not performed.

2.1.2 Duplicate Update ProtectionCARUTIL accumulates a hash total for all update statements processed andretains the hash total for each library member. When a succeeding update isperformed, its hash total is compared to the hash total retained in theprocedure library from the last update. If the two totals are equal, UnicenterCA-Driver for VSE assumes that the same update statement was inadvertentlyprocessed twice and the update is not performed. If the situation arises thatthe two hash totals are coincidentally equal, you can temporarily deactivate theverification routine by running the update with the -OVERRIDE commanddescribed in this section.

2.1.3 Executing CARUTILCARUTIL can be executed in any partition and can execute concurrently intwo or more partitions of the same VSE system. Library update protectionapplies to concurrent updates of the same library from multiple real or virtualsystems.

// JOB CARUTIL


...CARUTIL input statements

/�

/&


2.1 Overview

The DTF used by CARUTIL for SYSIPT input is the device independent DTFDTFDI and SYSIPT may be assigned to tape or disk when executing CARUTIL.Regardless of the source (tape, disk, or cards), the record length must be 80 or81 bytes.


2.2 Coding Requirements


CARUTIL commands consist of a control character and a verb. Somecommands have positional parameters, keyword parameters or both.

The control character is a dash which must be coded in column one. (Tochange the control character, see -CTLCHAR.)

The verb must follow the dash with no intervening spaces.

The first parameter following the command must be preceded by one or morespaces. For example:

-LIB COR

Additional parameters must be preceded by a comma.

Variable parameter values must be enclosed in parentheses.

A space after a parameter signals the end of the statement.

Positional parameters must be coded exactly as shown, before keywordparameters.

Keyword parameters may be coded in any order following positionalparameters. Keyword parameters are optional and may be omitted.

Comment lines are indicated by -* in columns one and two, followed by thecomment anywhere in columns four through 80:

-� comment text

Comments may also follow the last parameter on a statement, if they areseparated by one or more spaces. Comments will appear only in proceduredisplays; they are not expanded into VSE JCL.

CARUTIL control statements may be continued to as many lines as necessaryas long as they are split between parameters. Code the comma after the lastparameter on the line and continue to the next line by coding a plus sign (+) incolumn one. Leave column two blank. Begin the next parameter in columnthree or greater. (To change the continuation character, see -CONTCHAR.)



The following documentation conventions are used in this section:

( ) indicate optional statement numbers or character strings;

... indicates the preceding value may be repeated more than once.

2.2.1 Coding User-Supplied ValuesPositional and keyword parameters are shown in all upper case. Values thatyou must supply are shown in lower case. Code these values as follows:

name the name of the procedure in 1-8 alphabetic or numeric characters,beginning with an alphabetic character. (To code PARM=name, seeCoding Variable Parameters.)

nn the CARUTIL sequence number to identify the place in a procedurewhere statements are to be added, deleted, replaced, or corrected.These sequence numbers are the numbers that CARUTIL assigns toeach statement in a procedure, beginning with statement one. Thesenumbers are printed to the right of the statement when the procedureis listed. Note that these numbers are external to the statement itself;columns 1-80 of the statement are not modified.

dsd The DELIMITER STRING DELIMITER, where STRING is a string ofcharacters to be scanned for. The character string may be 1-64 byteslong and may contain any characters including single spaces. (Twoconsecutive spaces terminate the character string.) DELIMITERs maybe quotes or other special characters, as long as they are not containedin the character string. Numbers, letters, equal signs, commas, orparentheses may not be used as delimiters. The same delimiter mustbe used before and after the character string.

dsdsd The DELIMITER STRING DELIMITER STRING DELIMITER, wherethe first STRING is a string of characters to be replaced by the secondSTRING of characters. All three DELIMITERs must be the samespecial special character and may not be contained in either STRING.

statement(s) one or more statements that are to be added to a procedure.

2.2.2 Coding Variable ParametersUp to 65 variable parameters may be defined for each procedure. Each variableparameter that will be used in a procedure must be named on the PARMkeyword when the procedure is cataloged. PARM keyword values must beenclosed in parentheses. PARM keyword values consist of the variableparameter name and an optional default value. Variable parameter names canbe from one to seven alphabetic or numeric characters (A-Z, 0-9) and mustbegin with an alphabetic character.



2.2.2.1 Assigning a Default Value

A default value for the parameter may be defined when the procedure iscataloged. The default value may be the partition ID or a character string of upto 64 characters:

■ If the default value is the partition ID, code the PARM statement like this:

PARM=(NAME=PART-ID)

The variable parameter will be replaced during expansion by thetwo-character partition ID of the partition in which the job is to beprocessed.

■ If the default value is a character string, follow these guidelines:

– If the character string contains any blanks or special characters, it mustbe enclosed in quotes or other special character delimiters (likeapostrophes or slashes).

– If the character string consists only of alphanumeric characters,delimiters are optional.

Examples

-PROC NAME,OPTION=CREATE,PARM=(VAR1=YES)

-PROC NAME,OPTION=CREATE,PARM=(VAR2='A B C')

-PROC NAME,OPTION=CREATE,PARM=(VAR3=/JOHN'S/)

-PROC NAME,OPTION=CREATE,PARM=(VAR4)

In the first example, the default value for VAR1 is YES. Since this consists onlyof alphanumeric characters, no quotes or other delimiters are needed. In thesecond example, VAR2 has a default value of A B C. Since this containsspaces, it must be enclosed in quotes or other delimiters. In the third example,the default value for VAR3 is JOHN'S. Since this character string contains aquote, a special character other than a quote must be used as a delimiter. Inthis example, a slash (/) is used. In the fourth example, no default value isspecified, so a value must be supplied on the PROC statement that calls thisprocedure.

2.2.2.2 Variable Parameter Arrays

If the variable parameter will be replaced with multiple values, specify thenumber of values in parentheses after the variable parameter name. Forexample, PARM=(LETTERS(26)) allows the variable parameter LETTERS tohave 26 values.

You can optionally specify defaults for any of the 26 values:



■ List the defaults in order, separated by commas and enclosed inparentheses.

■ To omit a value, just code the comma.

Example

PARM=(LETTERS(26)=(A,B,,D))

This example assigns defaults to three out of the 26 values for LETTERS: itassigns a default of A to &LETTERS(1), a default of B to &LETTERS(2), adefault of D to &LETTERS(4), and no defaults for the other 23 values.

2.2.2.3 Supplying Values on the PROC Statement

If no default value is specified on the cataloged procedure, the replacementcharacter string for the variable parameter must be given on the calling PROCstatement. If a default value is specified on the cataloged procedure, a valuegiven on the PROC statement will override it.

Variable parameter values that are supplied on the calling PROC statement arecoded the same way as default values:

■ If the value contains other than alphanumeric characters, delimiters arerequired.

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

Example

// PROC NAME,VAR1=NO

// PROC NAME,VAR2='D E F'

// PROC NAME,VAR3=/MARY'S/

// PROC NAME,VAR4='A CHARACTER STRING'

2.2.2.4 Multiple Variable Parameters

Multiple variable parameters may be listed one after the other, separated bycommas:

// PROC NAME,VAR1=NO,VAR2='D E F',VAR3=/MARY'S/

Each parameter and its value must be contained on one line. But additionalparameters may be continued to the next line by coding a comma after the lastparameter on the line and a plus sign in column 1 of the next line. The nextparameter may then begin in column three.



Example

// PROC NAME,VAR1=NO,VAR2='D E F',VAR3=/MARY'S/,

+ VAR4='A CHARACTER STRING'

2.2.2.5 Referencing Variable Parameters in the Procedure

An ampersand must precede the variable parameter wherever it is coded inthe body of the procedure. (The ampersand is never used on the -PROCdefinition statement or on the // PROC statement). It is the ampersand thatsignals Unicenter CA-Driver for VSE to replace the variable parameter with avalue. For example, assume the value FILE has been defined for the variableparameter VAR1:

If the variable parameter is followed immediately by an alphanumericcharacter, it must be terminated by a period in the procedure. If the variableparameter is to be followed by a period after replacement, it must appear inthe procedure followed by two periods. For example,

This Statement In The Procedure Will Be Expanded As

// TLBL &VAR1,'DATA SET' // TLBL FILE,'DATA SET'

// TLBL UIN,'MASTER &VAR1' // TLBL UIN,'MASTER FILE'

This Statement In The Procedure Will Be Expanded As

// TLBL &VAR1.A,'DATA SET' // TLBL FILEA,'DATA SET'

// TLBL UIN,'&VAR1..001' // TLBL UIN,'FILE.001'

2.2.2.6 Using Variable Parameters in Nested Procedures

Variable parameters may be passed from a calling procedure to a nestedprocedure. In order to do this, the variable parameter must be defined in eachprocedure using either the same variable name or different variable names. Forexample, a nested procedure being passed a variable parameter value from acalling procedure could be cataloged as:

%/ PROC NESTNAME,VAR2=&VAR1

Note that the nested procedure defines the variable parameter VAR2. Thecalling procedure must contain the definition for the variable parameter VAR1.If the possibility exists that what is being passed contains special characters,enclose the variable name in delimiters (for example %/ PROCABC,A='&VAR1').



2.2.2.7 Shifting During Expansion

During variable parameter substitution, the substitution character string maybe shorter or longer than the parameter name (including the ampersand andconcatenation character, if present). In either case, Unicenter CA-Driver forVSE will shift the character string during procedure expansion according tothese guidelines:

■ If the replacement character string is shorter in length than the variableparameter, the character string will be shifted left the number of bytes thatthe replacement character string is shorter than the variable parameter.This shift will continue until a string of two or more spaces is encountered,at which point the shift will terminate. As a result, these spaces will beincreased by the number of bytes that the variable parameter exceeds thereplacement character string.

■ If the replacement character string is longer than the variable parameter(including the ampersand and concatenation character, if present), allfollowing bytes will be shifted right by the number of bytes that thereplacement character string is longer than the variable parameter. Thisshift will continue until a string of spaces is encountered that is sufficientlylong enough to contain the number of characters shifted and still leave oneblank. If such a shift would result in data being shifted past column 80(the end of the statement), an error message will be issued and theprocedure expansion will terminate. Two or more character strings mayalso be shifted right if the number of spaces between them is sufficient tocontain the number of characters shifted and still leave one space.

In these examples, the variable parameter &F has a replacement value of FILEand &DATASET has a replacement value of DSN:

Original stmt: // TLBL &F,'PAYROLL MASTER' Input master file

Expanded stmt: // TLBL FILE,'PAYROLL MASTER' Input master file

Original stmt: // TLBL INPUT,'&DATASET XYZ' Input test file

Expanded stmt: // TLBL INPUT,'DSN XYZ' Input test file

Original stmt: // TLBL SYS��9,'MASTER &F OUT' Output master

Expanded stmt: // TLBL SYS��9,'MASTER FILE OUT' Output master

Original stmt: // JOB TEST UPDATE PAYROLL &F Monday only

Expanded stmt: // JOB TEST UPDATE PAYROLL FILE Monday only

Original stmt: // JOB UPDATE PAYROLL &DATASET Monday only

Expanded stmt: // JOB UPDATE PAYROLL DSN Monday only



2.2.3 Disguising Job Control StatementsWhen cataloging procedures, you must disguise certain job control statements,conditional execution statements, and // PROC statements so that they will beacted on when the procedure is retrieved instead of when the procedure iscataloged. To disguise them, code the first slash as a percent sign:

When the procedure is retrieved and expanded, Unicenter CA-Driver for VSEchanges a percent sign in position one to a slash.

If POWER JECL is cataloged as part of a procedure, you must also disguise itso POWER will not recognize these statements when the procedure iscataloged. To disguise POWER JECL statements, change the '* $$' POWERidentification characters to '$ **':

This Statement Should Be Cataloged As

// JOB %/ JOB

/* %*

/& %&

// STEP %/ STEP

// DSTEP %/ DSTEP

// GOTO %/ GOTO

// DGOTO %/ DGOTO

// IF %/ IF

// DIF %/ DIF

// FLUSH %/ FLUSH

// COPTION %/ COPTION

// SET %/ SET

// PROC %/ PROC

// SUBMIT %/ SUBMIT

This Statement Should Be Cataloged As

*$$JOB $**JOB

*$$LST $**LST

*$$PUN $**PUN

*$$CTL $**CTL

*$$RDR $**RDR



During procedure expansion, Unicenter CA-Driver for VSE will change thecharacters $ ** in positions one through four to * $$.


2.3 Keywords

2.3 Keywords

■ These optional keywords may be included on any -PROC command:

PRINT=NO Specify NO if you do not want a listing of the procedure.Otherwise a listing will be produced.

PUNCH=YES Specify YES if you want the procedure punched to cards.

RPW=readpass Define a READ password which must be supplied on the// PROC statement to access the procedure (1-8alphanumeric characters, beginning with an Alphacharacter).

WPW=writpass Define a WRITE password which must be supplied toupdate or delete the procedure (1-8 alphanumericcharacters, beginning with an alpha character).

■ This keyword may be used on the -PROC command withOPTION=CREATE or OPTION=REPLACE:

PARM=(name1=default,name2=default,...)Define up to 65 variable parameters for theprocedure and optional default values for each. (See'Coding Variable Parameters'.)

■ This keyword may be used on the -PROC command withOPTION=REPLACE or OPTION=SELECT:

RENAME=newname Rename the procedure.


2.4 Commands

2.4 Commands

This topic describes each of the Unicenter CA-Driver for VSE commands andgives usage examples of each.

2.4.1 -CONTCHAR Command

Command Description

-CONTCHAR=character Change the continuationcharacter for this execution ofCARUTIL.

2.4.1.1 Usage Notes

Only CARUTIL continuation statements may begin with a plus sign. If youneed to catalog a procedure that contains a statement that begins with a plus,you can use this command to temporarily change the Unicenter CA-Driver forVSE continuation character to another special character.

The new continuation character will remain in effect for the remainder of thisexecution of CARUTIL or can be changed again in the same execution withanother CONTCHAR command.

2.4.1.2 Example

// JOB CARUTIL


-CONTCHAR=�

-PROC JDRPTS,OPTION=CREATE,

� PARM=(&C_DAY=MONDAY)

%/ JOB JDRPTS

// EXEC USERPROG

++REPORTS

%�

%&

-END

/�

/&

This example catalogs a procedure that generates user reports. Since the++REPORTS command must appear in the procedure, -CONTCHAR changesthe continuation character to an asterisk. This allows ++REPORTS to becataloged as part of the procedure without being mistaken for a continuationstatement.


2.4 Commands

2.4.2 -CTLCHAR Command

Command Description

-CTLCHAR=character Change the control characterfor this execution ofCARUTIL.

2.4.2.1 Usage Notes

Only CARUTIL control statements may begin with a dash. If you need tocatalog a procedure that contains a statement that begins with a dash, you canuse this command to temporarily change the Unicenter CA-Driver for VSEcontrol character.

The new control character will remain in effect for the remainder of thisexecution of CARUTIL or can be changed again in the same execution withanother CTLCHAR command.

2.4.2.2 Example

// JOB CARUTIL


-CTLCHAR=�

�PROC BACKUP,OPTION=CREATE

%/ JOB CARUTIL

// TLBL CARSAVE,'PROCLIB BACKUP'



-SAVE ALL

%�

%&

�END

/�

/&

This example catalogs the procedure that backs up the library to tape. Sincethe -SAVE command must appear in the procedure, -CTLCHAR changes thecontrol character to an asterisk. This allows -SAVE to be cataloged as part ofthe procedure without being mistaken for a control statement.

2.4.3 -DEBUG Command

Command Description

-DEBUG ENABLE|DISABLE Display return codeinformation after each linethat has an error whichcauses a return code.


2.4 Commands

2.4.3.1 Keywords

ENABLE Turns on the DEBUG facility

DISABLE Turns off the DEBUG facility


2.4 Commands

2.4.3.2 Usage Notes

When a procedure is cataloged in the library correctly, the -DEBUG commandis discarded. This works the same way in the online environment with thefollowing exception: if there is an error that results in the procedure not beingcreated nor replaced, the -DEBUG command, along with all other data, isstored in a SAVED member until the error is corrected. Once this error hasoccurred, the -DEBUG commands are removed before the procedure iscataloged.

2.4.3.3 Example 1

Executed Job

// JOB TEST�1

// EXEC CARUTIL

-DEBUG ENABLE

-PROC TEST�1,PRINT=YES,OPTION=CREATE

$ �� JOB JNM=TEST�1,USER=TEST

$ �� LST DISP=H,CLASS=Q

%/ JOB TEST�1 EXECUTE IDCAMS

// ID USER=PROD,PWD=FREEZE

// LIBDEF CL,SEARCH=(USRCL4,USRCL2)

// EXEC IDCAMS,SIZE=AUTO

%�

%&

$ �� EOJ

-END

Job Listing Output

// JOB TEST�1

// EXEC CARUTIL

CACR219I CA-DRIVER DEBUG HAS BEEN ENABLED

-PROC TEST�1,PRINT=YES,OPTION=CREATE

CACR�76E CREATE FUNCTION FAILED SINCE MEMBER TEST�1 ALREADY EXISTS.

CACR216I CURRENT RETURN CODE= ��12

CACR141I STATEMENT IGNORED







%�

%&

$ �� EOJ

CACR216I HIGHEST RETURN CODE= ��12


2.4 Commands

2.4.3.4 Example 2

Executed Job

// JOB TEST�2

// EXEC CARUTIL

-PROC TEST�2,PRINT=YES,OPTION=CREATE,

+ PARM=(VAR1=TEST)





-DEBUG ENABLE

-IF &VAR1 NE TEST GOTO NOTEXT


-STEP NOTEST


-DEBUG DISABLE

%�

%&

$ �� EOJ

-END

Job Listing Output

// JOB TEST�2

// EXEC CARUTIL

-PROC TEST�2,PRINT=YES,OPTION=CREATE,

+ PARM=(VAR1=TEST)

PARM-DEFINITION VAR1 =TEST





CACR219I CA-DRIVER DEBUG HAS BEEN ENABLED

-IF &VAR1 NE TEST GOTO NOTEXT


-STEP NOTEST


CACR219I CA-DRIVER DEBUG HAS BEEN DISABLED

%�

%&

$ �� EOJ

CACR�86E CONDITIONAL EXPANSION STEP NOTEXT IS UNDEFINED

CACR�83W CONDITIONAL EXPANSION STEP NOTEST IS UNREFERENCED

CACR�84E ERROR(S) FOUND WHILE PROCESSING MEMBER TEST�2

CACR216I HIGHEST RETURN CODE= ��12


2.4 Commands

2.4.4 -DISPLAY Command

Command Description

-DISPLAY List a directory of theprocedure library.

2.4.4.1 Usage Notes

-DISPLAY must be processed in a separate execution of CARUTIL.

This information is provided about the procedure library:

■ creation date

■ date of last backup

■ date of last restore

Each library member is listed in alphabetical order with the followinginformation:

■ procedure name

■ creation date and time

■ last access date and time

■ number of statements

■ number of times the procedure has been updated

2.4.4.2 Example

// JOB CARUTIL � PRODUCE DIRECTORY LISTING


-DISPLAY

/�

/&

This example lists a directory of the procedure library.


2.4 Commands

2.4.5 -LIB Command

Command Description

-LIB Print and/or punch allprocedures in the library.

2.4.5.1 Keywords

PRINT Specify this to print all procedures.

PUNCH Specify this to punch all procedures along with the CARUTILcontrol statements necessary to recatalog the procedures.

PRINT,PUNCH Specify this to print and punch all procedures.

NOHDR Specify this with PUNCH to suppress the CARUTIL controlstatements.

2.4.5.2 Usage Notes

The procedures are printed or punched in alphabetical order.

SYSPCH may be cards, tape, or disk.

CARUTIL control statements necessary to recatalog the procedures are writtento SYSPCH with OPTION=CREATE, not with OPTION=REPLACE.

Use NOHDR to punch procedures that are to be cataloged to the systemprocedure library or that are to be run without Unicenter CA-Driver for VSE.

To print/punch only selected procedures, specify INCLUDE or EXCLUDE onthe -LIB statement and any number of -SEL statements. (See -SEL.)

-LIB should be processed in a separate execution of CARUTIL.

2.4.5.3 Example 1

// JOB CARUTIL SHOW SAMPLE USAGE OF '-LIB' COMMAND


-LIB PRINT

/�

/&

This example prints the entire library.


2.4 Commands

2.4.5.4 Example 2



-LIB PUNCH

/�

/&

This example punches the entire library with CARUTIL control statements.

2.4.5.5 Example 3



-LIB PRINT,PUNCH,NOHDR

/�

/&

This example prints and punches the entire library without CARUTIL controlstatements.

2.4.6 -LIB COR Command

Command Description

-LIB COR-COR dsdsd

Scan the library and changeone character string toanother character string.

2.4.6.1 Usage Notes

The delimiter between the old character string and the replacement charactercan be any special character.

To update only selected procedures, specify INCLUDE or EXCLUDE on the-LIB statement and any number of -SEL statements. (See -SEL.)

Any members that are in SAVED status are not updated. -LIB COR bypassesthem even though -LIB SCAN does not. Only five -COR statements areallowed per -LIB COR.


2.4 Commands

2.4.6.2 Example 1

// JOB CARUTIL


-LIB COR

-COR /2��3/2��4/

/�

/&

This example scans the procedure library and changes all occurrences of 2003to 2004.

2.4.6.3 Example 2

// JOB CARUTIL


-LIB COR,INCLUDE ... include selected procs

-SEL CICS.,IMS.,MYPROC

-COR /OLDDATA/NEWDATA/

/�

/&

This example scans all procedures beginning with CICS or IMS and theprocedure named MYPROC and changes all occurrences of OLDDATA toNEWDATA.

2.4.7 -LIB PRINT,SCAN Parameters

Command Description

-LIB PRINT,SCAN-SCAN dsd[,dsd...,dsd]

Print only statements thatcontain specified characterstrings.

2.4.7.1 Usage Notes

Specify up to 64 character strings on one or more -SCAN statements followingthe -LIB command. (CARUTIL scans the entire library in one pass regardless ofthe number of -SCAN statements.)

Enclose each character string in special character delimiters. Separate multiplecharacter strings with commas.

To scan only selected procedures, specify INCLUDE or EXCLUDE on the -LIBstatement and any number of -SEL statements. (See -SEL.)

The output on SYSLST lists:


2.4 Commands

■ each procedure that contains one of the scan strings

■ the contents and number of each statement in each procedure that containsone of the scan strings

■ a hit count for each scan string at the end of the listing

■ an audit listing at the end of the report, if -SEL was used, showing whichprocedures were involved in the scan and the number of proceduresscanned for each generically named group

2.4.7.2 Example 1

// JOB CARUTIL


-LIB PRINT,SCAN

-SCAN 'CHARACTER STRING 1','CHARACTER STRING 2'

-SCAN /CHARACTER STRING 3/,'// JOB'

/�

/&

This example scans the procedure library and prints all statements that containCHARACTER STRING 1, CHARACTER STRING 2, CHARACTER STRING 3,or // JOB.

2.4.7.3 Example 2

// JOB CARUTIL


-LIB PRINT,SCAN,INCLUDE

-SEL CICS.,PAY.

-SCAN 'TLBL','DLBL'

/�

/&

This example scans only procedures beginning with CICS or PAY for alloccurrences of the character strings DLBL and TLBL.


2.4 Commands

2.4.8 -LIB REPORT Command

Command Description

-LIB REPORT-RPG report type

Produce cross-referencereports.

2.4.8.1 Usage Notes

Submit the -LIB REPORT command in a separate execution of CARUTIL withone or more -RPG statements. Specify one of these report types on each -RPGstatement:

Provide DLBL and EXTENT information for the file WORK1 using theprogrammer logical unit SYS001, since these reports invoke CA-SRAM.

When a field on a cross-reference report terminates in a period, this indicatesthat the field on the procedure statement exceeded VSE standards in lengthand was truncated on the report. This is because the length of a key field (suchas a DLBL filename for the report DFN,PROC) is longer than the VSE JCL fieldlength. Therefore, the field is truncated to the correct length, and a period isappended to the field on the report. This typically will only occur whenvariable parameters are used on the key fields:

To Report On Specify

Procedures that nest other procedures PROC,NEST

Procedures that are called by other procedures NEST,PROC

Programs executed EXEC,PROC

DLBL filenames contained in procedures DFN,PROC

DLBL file-ids contained in procedures DID,PROC

TLBL filenames contained in procedures TFN,PROC

TLBL file-ids contained in procedures TID,PROC

If The Procedure StatementSpecifies

The Field Is Reported AsWith Maximum Length of

Specifies TheVariable As

// DLBL FILE&VAR1 FILE&VA. 7

// EXEC PAY&PROGNAM PAY&PROG. 8

'ACCOUNT &NUMBERMASTER'

ACCOUNT &NUMBER M. 17


2.4 Commands

2.4.8.2 Example

// JOB CARUTIL CROSS-REFERENCE REPORTS

// DLBL WORK1,,�

// EXTENT SYS��1,VOLSER,1,�,SSSS,NNNN



-LIB REPORT ...Invoke reporting function

-RPG PROC,NEST ...XREF of PROCs with nests

-RPG NEST,PROC ...XREF of nested PROC

-RPG DFN,PROC ...XREF of DLBL filenames

-RPG DID,PROC ...XREF of DLBL file-id's

-RPG TFN,PROC ...XREF of TLBL filenames

-RPG TID,PROC ...XREF of TLBL file-id's

-RPG EXEC,PROC

/�

/&

This example produces all seven reports.

2.4.9 -LIB STATUS Command

Command Description

-LIB STATUS Display driver procedurelibrary status information.

2.4.9.1 Usage Notes

The master library password, if defined, must be present in order to displaythe library information.

Submit the -LIB STATUS command in a separate execution of CARUTIL.

2.4.9.2 Example

// JOB CARUTIL

// EXEC CARUTIL,SIZE=2��K

-LIB STATUS

/�

/&

This example will display the library status information for the driverprocedure library (CAIJDRV).


2.4 Commands

2.4.10 -OVERRIDE Command

Command Description

-OVERRIDE Override duplicate updateprotection for this executiononly.

2.4.10.1 Usage Notes

If Unicenter CA-Driver for VSE's duplicate update protection does not allowyou to make updates that you are sure are correct, place the -OVERRIDEcommand before the update commands and submit them again.

Do not use this too often or you will lose the benefit of duplicate updateprotection.

2.4.10.2 Example

// JOB CARUTIL


-OVERRIDE

-PROC PROCNAME,OPTION=SELECT

... Update statements

-END

/�

/&

2.4.11 -PROC Command

Command Description

-PROC name Print a procedure.

2.4.11.1 Keywords

RPW=readpassWPW=writpass


PRINT=YES is the default and need not be specified. Procedures will beprinted unless PRINT=NO is specified.

Procedures are printed in the sequence in which the -PROC commands areencountered, with each procedure beginning on a new page. All variableparameter definitions and their associated values are also printed.


2.4 Commands

2.4.11.3 Example

// JOB CARUTIL


-PROC SAMPLE15

-PROC SAMPLE16

/�

/&

This example prints the entire contents of procedures SAMPLE15 andSAMPLE16 on SYSLST.

2.4.12 -PROC COR Command

Command Description

-PROC name,COR=dsdsd Replace an old characterstring with a new characterstring throughout aprocedure.

2.4.12.1 Keywords

PRINT=NOPUNCH=YESRPW=readpassWPW=writpass


The delimiter between the old character string and the replacement string canbe any special character.

CARUTIL issues a warning message whenever a statement that was changedcontains what appears to be a character string of any type. This indicates thatCARUTIL found two special characters used as delimiters in the statement.This does not affect the update but warns you to double-check the globalchange for that statement to ensure that it did not detrimentally affect acharacter string.

2.4.12.3 Example 1

-PROC SAMPLE9,COR=/FIRST/SECOND/


2.4 Commands

This example replaces all occurrences of the character string FIRST with thecharacter string SECOND.

2.4.12.4 Example 2

-PROC SAMPLE1�,COR=/ST,/STFLE,/

This example changes the statement:

// DLBL CUST,'CUSTOMER.MASTER.FILE',99/365,SD COMMENT


2.4 Commands

to:

// DLBL CUSTFLE,'CUSTOMER.MASTER.FILE',99/365,SD COMMENT

Notice that the number of blanks between the COMMENT and the end of theDLBL information was reduced by the number of characters that thereplacement string was longer than the scan string.

2.4.12.5 Example 3

-PROC SAMPLE11,COR='STFLE,'ST,'


// DLBL CUSTFLE,'CUSTOMER.MASTER.FILE',99/365,SD COMMENT

to:

// DLBL CUST,'CUSTOMER.MASTER.FILE',99/365,SD COMMENT

Notice this time that the number of spaces between the COMMENT and theend of the DLBL information increased by the number of characters that thereplacement string was shorter than the scan string.

2.4.12.6 Example 4

-PROC SAMPLE12,COR=/CUSTFLE,/CUST,/


// DLBL CUSTFLE,'CUSTOMER MASTER FILE',99/366,SD COMMENT

to:

// DLBL CUST,'CUSTOMER MASTER FILE',99/366,SD COMMENT


2.4 Commands

Notice that the three space difference between CUSTFLE and CUST was addedafter the word CUSTOMER, which was the first space encountered after thechange.

2.4.13 -PROC Create Option

Command Description

-PROC name,OPTION=CREATE Catalog a procedure.

2.4.13.1 Keywords

PARM=(name1=default,name2=default,...)PRINT=NOPUNCH=YESRPW=readpassWPW=writpass


All statements between the -PROC command and an -END command arecataloged under the procedure name. The cataloged procedure is retrievedwith a // PROC statement and expanded into the job stream in place of the// PROC statement.

To catalog multiple procedures, follow the -END statement of one procedurewith the -PROC statement of the next procedure.

% in column 1 is expanded as /. * $ $ in columns 1-4 are expanded as $ $ *.(See Disguising Job Control Statements.)

If a variable parameter has no default value, you must supply a value on the// PROC statement.

If a READ password is defined, a WRITE password must also be definedbecause the READ password is visible in the JCL and must be protectedagainst unauthorized update.

To protect procedures against unauthorized update only, define just a WRITEpassword. This will allow the procedure to be used without a password.

The master password may be used in place of the WRITE password to updateany procedure.


2.4 Commands

2.4.13.3 Example 1

-PROC DSERV,OPTION=CREATE,PARM=(SIZE=64K)

%/ JOB DSERV � DISPLAY SYSTEM LIBRARIES

// EXEC DSERV,SIZE=&SIZE

DSPLYS ALL

%�

%&

-END

This example catalogs the five statements between -PROC and -END as theDSERV procedure. When retrieved with the statement // PROC DSERV theprocedure is expanded as:

// JOB DSERV

// EXEC DSERV,SIZE=64K

DSPLYS ALL

/�

/&

The variable parameter &SIZE was replaced with its default value, as nooverriding value was supplied on the calling PROC statement. Statementscataloged with a percent sign are expanded with a slash.

2.4.13.4 Example 2

-PROC SAMPLE1,OPTION=CREATE,PARM=(XYZ,ABC=��1,DEF='')

This example defines a procedure named SAMPLE1 which will be listed whencataloged (PRINT=YES is the default). Three variable parameters are definedand may be used throughout the procedure. The variable parameter &XYZ isdefined with no default value. The variable parameter &ABC is defined with adefault value of 001. The variable parameter &DEF is defined as having a nullvalue for its default value. This means that the parameter will be replaced withnothing during procedure expansion (see 'Null Values' in the "Using UnicenterCA-Driver for VSE" chapter).

2.4.13.5 Example 3

-PROC SAMPLE2,OPTION=CREATE,PARM=(XYZ=��2,ABC(4)=(V,4�,,'TAPE FILE' ))


2.4 Commands

This example defines the procedure SAMPLE2 and names two variableparameters. The variable parameter &XYZ has a default value of 002. Thevariable parameter &ABC consists of four elements:

■ The first has a default value of V

■ The second has a default value of 40

■ The third has no default value (indicated by the comma without a valu)

■ The fourth has a default value of TAPE FILE

2.4.13.6 Example 4

// JOB CARUTIL


-PROC SAMPLE4,OPTION=CREATE,WPW=SAMPLEPW

... Statements for procedure SAMPLE4

-END

-PROC SAMPLE5,OPTION=CREATE,PARM=(ABC=NO)

... Statements for procedure SAMPLE5

-END

/�

/&

This example catalogs two procedures by following the -END statement of oneprocedure with the -PROC statement for the next procedure.

2.4.14 -PROC Delete Option

Command Description

-PROC name,OPTION=DELETE Delete a procedure.

2.4.14.1 Keywords


2.4.14.2 Example

// JOB CARUTIL


-PROC SAMPLE5,OPTION=DELETE

-PROC DSERV,OPTION=DELETE,WPW=PIZZA

/�

/&


2.4 Commands

This example deletes procedure SAMPLE5 and procedure DSERV which waspassword protected.

2.4.15 -PROC Delete Saved Option

Command Description

-PROC name,OPTION=DELSAV Deletes a saved procedure.

2.4.15.1 Keywords


2.4.15.2 Example

// JOB CARUTIL


-PROC SAMPLE6,OPTION=DELSAV

-PROC SAMPLE7,OPTION=DELSAV,WPW=PIZZA

/�

/&

This example deletes saved procedures SAMPLE6 and SAMPLE7 (procedureSAMPLE7 was password protected. This will only delete the saved proceduresthat were created by the Unicenter CA-Driver for VSE online facility.

2.4.16 -PROC Punch Option

Command Description

-PROC name,OPTION=PUNCH Punch a procedure.

2.4.16.1 Keywords



Use this to punch a procedure without printing it.

All control statements necessary to recatalog the procedure are also punched.


2.4 Commands

2.4.16.3 Example

// JOB CARUTIL


-PROC SAMPLE18,OPTION=PUNCH


/�

/&

This example writes to SYSPCH the contents of SAMPLE18 and SAMPLE19.

2.4.17 -PROC Print Option

Command Description

-PROC name,OPTION=PRINT Print a procedure.

2.4.17.1 Keywords



Use this to print a procedure.

All control statements necessary to recatalog the procedure are also printed.

2.4.17.3 Example

// JOB CARUTIL


-PROC SAMPLE18,OPTION=PRINT

-PROC SAMPLE19,OPTION=PRINT

/�

/&

This example prints to SYSLST the contents of SAMPLE18 and SAMPLE19.

2.4.18 -PROC Release Option

Command Description

-PROC name,OPTION=RELEASE Release a procedure.


2.4 Commands


This command must be used with caution. It frees procedures that areenqueued due to a system failure, but it can also free a procedure that is in useonline by another user.

2.4.18.2 Example

// JOB CARUTIL


-PROC SAMPLE,OPTION=RELEASE

/�

/&

This example releases a procedure named SAMPLE.

2.4.19 -PROC Replace Option

Command Description

-PROC name,OPTION=REPLACE Replace an old procedurewith a new one if theprocedure name does notexist.

2.4.19.1 Keywords

PARM=(name1=default,name2=default,...)PRINT=NOPUNCH=YESRENAME=newnameRPW=readpassWPW=writpass


Only existing procedures can be replaced. If a procedure does not exist, it willbe created. If the old procedure has a password, it will also apply to the newprocedure. To change the password, specify WPW=OLDPW=NEWPW.

2.4.19.3 Example


2.4 Commands

// JOB CARUTIL


-PROC DSERV,OPTION=REPLACE,WPW=PIZZA

%/ JOB DSERV � DISPLAY ALL SYSTEM LIBRARIES AND LABELS

// EXEC DSERV

DSPLYS ALL

%�

// EXEC LSERV

%&

-END

/�

This example replaces the previously defined DSERV procedure with a new setof statements. Since the old DSERV was not password protected, the passworddefined on the REPLACE statement will protect the new DSERV.

2.4.20 -PROC Select Option -ADD Command

Command Description

-PROC name,OPTION=SELECT-ADD nn

Add statements to aprocedure after statementnumber nn.

2.4.20.1 Keywords

PRINT=NOPUNCH=YESRENAME=newnameRPW=readpassWPW=writpass


All statements on this command will be added to the procedure until anothercontrol statement signals the end of statements that are to be added (-ADD,-DEL, -REP, or -END). Unicenter CA-Driver for VSE conditional expansionstatements (-IF, -STEP, -GOTO) do not signal the end of statements that are tobe added.

Specify nn as the number that CARUTIL assigned to the statements in theprocedure, not as any sequence number that might appear within theprocedure.

-ADD, -DEL, and -REP may be mixed during an update run as long as twodifferent update statements do not refer to the same statement numbers andstatement number ranges do not overlap. For example, -DEL 15,18 and -ADD17 are invalid in the same update run.


2.4 Commands

2.4.20.3 Example

-PROC SAMPLE7,OPTION=SELECT ...Select the procedure

-ADD 12 ...Add after statement 12

// TLBL FILEA,'FILEA DSN' ...These two TLBL statements will be added

// TLBL FILEB, 'FILEB DSN'

-END ...Terminate the update statements

This example adds two TLBL statements to procedure SAMPLE7 afterstatement 12.

2.4.21 -PROC Select Option -COR Command

Command Description

-PROC name,OPTION=SELECT-COR nn[,nn],dsdsd

Replace an old characterstring with a new characterString on one statement or arange of stat ements.

2.4.21.1 Keywords



Identify the first and last statements in the range as nn, where nn is thenumber that CARUTIL assigned to each statement in the procedure. Toupdate only one statement, omit the second nn.

The delimiter between the old character string and the replacement string canbe any special character.

2.4.21.3 Example

-PROC SAMPLE13,OPTION=SELECT

-COR 4,/SCAN1/REPLACE1/ ...Scan statement 4 only

-COR 7,l�,'SCAN2'REPLACE2' ...Scan statements 7 through 1�

-END ...End of update statements


2.4 Commands

This example replaces a character string in statement 4 and another characterstring in statements 7 through 10.

2.4.22 -PROC Select Option -DEL Command

Command Description

-PROC name,OPTION=SELECT-DEL nn[,nn]

Delete statements from aprocedure.

2.4.22.1 Keywords



Specify nn as the number that CARUTIL assigned to the statements in theprocedure, not as any sequence number that might appear within theprocedure.

To delete a range of statements, use the first nn for the beginning of the rangeand the second nn for the end of the range.

-ADD, -DEL, and -REP may be mixed during an update run as long as twodifferent update statements do not refer to the same statement numbers andstatement number ranges do not overlap. For example, -DEL 15,18 and -ADD17 are invalid in the same update run.

2.4.22.3 Example


-DEL 12

-DEL 14

-DEL 17,21

-END

This example deletes statement numbers 12, 14, and 17 through 21 fromprocedure SAMPLE8.


2.4 Commands

2.4.23 -PROC Select Option -REP Command

Command Description

-PROC name,OPTION=SELECT-REP nn[,nn]statement(s)

Replace old procedurestatements with newstatements.

2.4.23.1 Keywords



All statements on this command will be added to the procedure until anothercontrol statement signals the end of the replacement statements (-ADD, -DEL,-REP, or -END). Unicenter CA-Driver for VSE conditional expansionstatements (-IF, -STEP, -GOTO) do not signal the end of the replacementstatements.

Specify nn as the number that CARUTIL assigned to the statements in theprocedure, not as any sequence numbers within the procedure.

To replace a range of statements, use the first nn for the beginning of the rangeand the second nn for the end of the range.

-ADD, -DEL, and -REP may be mixed during a CARUTIL update as long astwo different update statements do not refer to the same statement numbersand statement number ranges do not overlap. For example, -DEL 15,18 and-REP 17 are invalid in the same update run.

2.4.23.3 Example


-REP 4

// TLBL FILEIN,'NEW DSN'

-REP 11,14

// DLBL FILEOUT,'NEW DSN'

-REP 18

%/ COPTION NOFLUSH

// EXEC USERPROG

%�

%/ IF SYS NE X'1�' GOTO ABEND

%/ COPTION FLUSH

-END


2.4 Commands

This example replaces statement number 4 with a TLBL statement, statements11 through 14 with one DLBL statement and statement 18 with several otherstatements.

2.4.24 -PROC Select Option Change Parameter

Command Description

-PROC name,OPTION=SELECT+PARM=(name2=default,name3=default,...)

Change a variable parameterdefault value or add avariable parameter to anexisting procedure.

2.4.24.1 Keywords



Variable parameter updates may be done separately or along with updates tothe contents of the procedure.

To change a default value, specify the variable parameter and the new value.Other variable parameters defined for that procedure remain the same.

To add a variable parameter, name the new variable parameter and anoptional default value. Existing variable parameters for that procedure remainthe same.

2.4.24.3 Example 1

// JOB CARUTIL


-PROC SAMPLE14,OPTION=SELECT,PARM=(VAR3=ABC)

-END

/�

/&

This example changes the default value of the variable parameter &VAR3 toABC for the procedure SAMPLE14.


2.4 Commands

2.4.24.4 Example 2

// JOB CARUTIL


-PROC SAMPLE14,OPTION=SELECT,PARM=(VAR4,VAR5=Y)

. . . Any needed update statements

-END

/�

/&

This example adds the variable parameter &VAR4 to the procedureSAMPLE14, with no default value specified, and the variable parameter&VAR5 with a default value of Y.

2.4.25 -PROC Select Option Delete Parameter

Command Description

-PROC name,OPTION=SELECT+ PARM=(name2='DELETE')

Remove a variable parameterfrom a procedure.

2.4.25.1 Keywords



Change the value of the variable parameter to 'DELETE'.

Remove all references to this variable parameter from the procedure.

'DELETE' is only valid if you are maintaining the procedure through the batchutility.

2.4.25.3 Example


2.4 Commands

// JOB CARUTIL


-PROC SAMPLE14,OPTION=SELECT,

+ PARM=(VAR2='DELETE')

... Any update statements necessary to remove references to VAR2

-END

/�

/&

This example removes the variable parameter &VAR2 from SAMPLE14.

2.4.26 -PROC Punch Toggle

Command Description

-PROC name,PUNCH=YES Print and punch a procedure.

2.4.26.1 Keywords



Unless you specify PRINT=NO, the procedure will also be printed. If you wantto punch a procedure without printing it, use OPTION=PUNCH instead ofPUNCH=YES.

All control statements necessary to recatalog the procedure are also punched.

2.4.26.3 Example

// JOB CARUTIL




-PROC SAMPLE2�,PUNCH=YES

/�

/&

This example writes to SYSPCH the contents of SAMPLE18 and SAMPLE19and both prints and punches the contents of SAMPLE20.


2.4 Commands

2.4.27 -PROC Print Toggle

Command Description

-PROC name,PRINT=YES Print and punch a procedure.

2.4.27.1 Keywords



The PRINT keyword prints all control statements that are necessary torecatalog the procedure.

2.4.27.3 Example

// JOB CARUTIL

// EXEC CARUTIL

-PROC SAMPLE2�,PRINT=YES

/�

/&

This example prints the contents of procedure SAMPLE20.

2.4.28 -PROC Rename Option

Command Description

-PROC name,PRINT=YES Rename a procedure.

2.4.28.1 Keywords

PRINT=NOPUNCH=YESRPW=readpassWPW=writpass


The name must be new to the procedure library.


2.4 Commands

2.4.28.3 Example

-PROC DSERV,RENAME=NEWNAME,PRINT=NO,WPW=PIZZA

This example renames procedure DSERV to become procedure NEWNAME. Itwill not be printed.

2.4.29 -SEL Command

Command Description

-SEL name,name,... Select procedures forprint/punch or update.


Place the -SEL command after the -LIB command. Add INCLUDE orEXCLUDE to the -LIB command to specify whether the selected procedures areto be included or excluded.

Select up to 256 procedure names or generic procedure names on one or more-SEL commands. You can list them in any order; they will always be written toSYSLST or SYSPCH in alphabetical order.

To select procedure names generically, give the first 1-7 characters followed bya period.


2.4 Commands

2.4.29.2 Example 1

// JOB CARUTIL PRINT ALL PROCEDURES BEGINNING WITH 'CS'


-LIB PRINT,INCLUDE

-SEL CS.

/�

/&

This example prints all procedures in the library beginning with CS.

2.4.29.3 Example 2

// JOB CARUTIL PRINT ALL PROCEDURES THAT DO NOT BEGIN WITH 'CICS'


-LIB PRINT,EXCLUDE

-SEL CICS.

/�

/&

This example prints all procedures in the library except those beginning withCICS.

2.4.29.4 Example 3

// JOB CARUTIL PUNCH SEVERAL NAMED PROCEDURES


-LIB PUNCH,INCLUDE

-SEL SAMPLE21,SAMPLE22,SAMPLE23

-SEL SAMPLE24

-SEL PAY.,CICS.,L47��

/�

/&

This example punches procedures SAMPLE 21, SAMPLE22, SAMPLE23,SAMPLE24, L4700, and all procedures beginning with PAY and CICS.


2.5 Issuing CICS Commands


The Unicenter CA-Driver for VSE CICS command processor accepts CEMT andUSER commands passed from the CARUCMDA program and, in turn, passesthe command to the CICS command interface. This function allows CICScommands and transactions to be issued from a VSE job. The commandprocessor is supported on CICS r1.5 or above.

The command may also contain a partition-id and/or job name of the targetedCICS partition. If neither partition-id nor CICS job name are specified andmultiple CICS systems are active, the command will be passed to the firstCICS system encountered. Using the following partition scanning sequence:

BG, FN, FN-1, FN-2, ..., F2, F1

The CEMT command issued from the batch program facilitates batchprocessing against data sets which are accessed by CICS transactions. Thebatch partition may issue a CEMT command to close data sets prior to batchprocessing and, in turn, an OPEN command after batch processing is complete.This eliminates the need for the batch partition to pause and wait for theoperator to manually issue the CLOSE and OPEN requests. The probability ofprocessing data sets which are OPEN for updating is eliminated. This facilityallows batch and CICS processing to live together without the potentialproblems which have existed in the past.

The CEMT command is not limited to OPEN and CLOSE; it is supportedcompletely by the CICS command processor. Some CEMT functions, however,have little or no usefulness when issued from a batch partition. There are otherrestrictions which apply to the interface to CICS; i.e., CEMT PERFORMSHUTDOWN is not allowed. For a complete description, see the MasterTransaction (CEMT) section of the IBM manual CICS/VS Operator's Guide.

The CEMT command is primarily a CICS control and information command.When issued from a batch partition, its utility value is greatly enhanced.

The CICS START command may be used to automatically cause a CICStransaction to be started. The transaction may run either attached orunattached. In addition, data may be passed to the started transaction. It is theresponsibility of the started task to retrieve the passed data. Once atransaction has been started, it will run asynchronously. Unicenter CA-Driverfor VSE will not necessarily be involved with its continued execution ortermination.



2.5.1 Command Format

[ (Partid=partition-id, ]

CI [ Jobname=jobname, ] transaction-id [ transaction data ]

[ Termid=terminal-id, ]

[ User=cics-user-id) ]

where:

CI Is the required command prefix.

transaction-id Is the required CICS transaction id.

transaction data Is any data associated with this transaction. When the'transaction-id' is a user-written CICS transaction, thedata is passed to the user transaction by the intervalcontrol facility of CICS. This means that the usertransaction must retrieve this data through the intervalcontrol facility. This data cannot be passed to a usertransaction as a CICS 'TIOA' buffer. In the case of theCEMT transaction, the 'transaction data' is passed to theCICS CEMT program interface.

The parentheses ( ) are required if any of the following options are used:

Partid= Specifies the two-character partition-id of the CICS towhich this transaction is to be directed. For defaultvalues, see the next page.

Jobname= Specifies the jobname of the CICS to which thistransaction is to be directed. Up to eight characters maybe specified. For default values, see the next page.

Termid= Specifies the CICS terminal id (TCT entry) to whichCICS user-written transactions can be attached. Thisoptional parameter cannot be specified for CEMTtransactions. Up to four characters may be specified.Default: This is a batch (nonterminal) transaction.

User= This is the CICS signon (DFHSNT, CSSN) of the userthat wishes to invoke a CICS transaction. This field willbe passed to a user-written security exit. Up to 20characters may be specified. Default: blanks (X'40').



2.5.2 CasesThe Partid= and Jobname= optional parameters are used to direct the CICStransaction to a specific CICS, when multiple CICS partitions are runningwithin the same VSE machine. Either, both, or neither of the parameters maybe specified. These four possibilities are described below:

Case 1: Both P= and J= are specified.

The batch command processor will "look" for the specific jobname running inthe specified partition and direct the CICS transaction there. If the batchcommand processor cannot locate the P= and J= combination, an error messagewill be printed and the command will be bypassed.

Case 2: Only P= is specified.

The batch command processor will locate the partition specified and direct theCICS transaction to that CICS. If CICS is not running in the partitionspecified, an error message will be printed and the command will be bypassed.

Case 3: Only J= is specified.

The batch command processor will locate the partition running the jobnamespecified and direct the CICS transaction to that CICS. If CICS is not runningwith the jobname specified, an error message will be printed and the commandwill be bypassed.

Case 4: Neither P= nor J= is specified.

The batch command processor will locate the first CICS partition running (i.e.FN, FN-1,..., F2, F1) and direct the CICS transaction to that CICS. If CICS isnot running in any partition, an error message will be printed and thecommand will be bypassed.

Input must be one record and complete prior to COL 72 as no continuation isallowed.

2.5.2.1 Example

// EXEC CARUCMDA

CI (P=F2) CEMT SET TERM(L�3�) OUT Set terminal L�3� out of service

CI (P=F2,TERMID=L�3�) DRIV Set DRIV transaction on term L�3�

CI (J=CICS) CEMT SET DAT(FILEB) OPE

/�


Chapter 3. Online Driver Procedure Maintenance

When you enter the DRIV transaction or start the CMS EXEC DRIV you willbe presented with the Unicenter CA-Driver for VSE Procedure MaintenanceMenu shown below. Unicenter CA-Scheduler/Unicenter CA-Driver for VSEusers will see this panel after entering the SCHD transaction or starting theCMS EXEC SCHD and then selecting DRIVER PROCEDURE MAINTENANCEfrom the Main Menu.

� � SCHD-VM �DRIVER PROCEDURE MAINTENANCE� CA-DRIVER

===>

FUNCTION ENTER

-------- ------

DISPLAY FULL DIRECTORY............(PRESS ENTER)

SELECTIVELY DISPLAY DIRECTORY.... 1,SELECT CRITERIA

DISPLAY SPECIFIC PROCEDURE....... 2,PROCEDURE

ALTER PROCEDURE.................. 3,PROCEDURE

DEFINE PROCEDURE................. 4,PROCEDURE

DELETE PROCEDURE................. 5,PROCEDURE

COPY PROCEDURE................... 6,PROCEDURE

PF1=HELP

� �

To exit the DRIV transaction or return to the SCHD Main Menu, press CLEAR.

Within the Driver Procedure Maintenance menu, press ENTER to display thefull Procedure Directory. Otherwise, select from the following activities byentering the appropriate information on the command line:

Chapter 3. Online Driver Procedure Maintenance 3-1

A procedure name may be 1-8 alphanumeric characters in length. The firstcharacter must be alphabetic.

Enter To

1,selection criteria Display the directory based upon the enteredselection criteria. The selection criteria may beeither a single procedure or a group ofprocedures.

Examples:

1,PAYROLL Selects the procedure namePAYROLL.

1,PAY* Selects all procedures which beginwith the string "PAY."

2,procedure Display the specified procedure.

3,procedure Display the specified procedure for alteration.

4,procedure Create a new procedure of the specifiedname.

5,procedure Delete the specified procedure.

6,procedure Copy the specified procedure.


3.1 Driver Procedure Directory


If you press ENTER or choose option 1 in the Driver Procedure MaintenanceMenu, the following panel appears:

� � SCHD-VD � DRIVER PROC DIRECTORY � CA-DRIVER

===>

PROCEDURE CREATED LAST UPDATED RECS UPDTS

ATEST �6/31/95 12.46.17 �6/31/95 12.46.17 17 1

ATEST � SAVED DATE/TIME==> �7/�8/95 12.46.17

BTEST �6/31/95 12.46.59 �6/31/95 12.46.59 2� 1

DTEST �6/31/95 13.�3.52 �6/31/95 13.�3.52 2� 1

PTEST �6/31/95 13.�1.11 �6/31/95 13.�1.11 19 1

�� END OF DIRECTORY LIST ��

PF1=HELP

� �

This panel lists the procedures in the Unicenter CA-Driver for VSE procedurelibrary. From here you can also display, alter, copy, delete, or releaseindividual procedures.

Press CLEAR to return to Driver Procedure Maintenance panel.

If you receive message CACO207E when you try to update a record on thispanel, it usually indicates that another user is updating the record. Wait for theother user to finish updating the member and try again. If this is not the case,enter an R next to the procedure, thereby releasing it.

Use this command carefully because the ENQUEUE is the highest level ofupdate protection.

To Enter This Next To TheProcedure

Display a procedure D

Alter a procedure A

Define a new procedure using this one as amodel

C

Delete a procedure L

Release a procedure R



3.1.1.1 Headings

The following headings describe data fields that contain information you havealready specified on other Unicenter CA-Driver for VSE panels.

PROCEDURE Names of procedures.

CREATED The date this procedure was created.

LAST UPDATED The date this procedure was last updated.

RECS The number of records in this procedure.

UPDTS The number of times this file was opened, includingits creation and any updates.

* SAVED DATE/TIME==> indicates that while you were editing the namedprocedure you issued a SAVE command, or when you attempted to file theprocedure, Unicenter CA-Driver for VSE detected an error that would haveprevented successful expansion and execution of the procedure. If you wish toreedit the procedure, then no matter which procedure you select (original orsaved), you will be presented with the saved version. You may then make anycorrections and either save the procedure again or file it. If you do not wantthe saved procedure, you can delete it as you would any Unicenter CA-Driverfor VSE procedure.


3.2 Displaying Procedures

3.2 Displaying Procedures

If you select option 2 from the Driver Procedure Maintenance panel or enter Dnext to a procedure in the Procedure Directory, the following panel appears:

� � SCHD-DRVE DSP P=BTEST CA-DRIVER

===>

RANGE=�1-72

1...+....1....+....2....+....3....+....4....+....5....+....6....+....7..

+ PARM=(A) ��1

%/ JOB CAJDDEM1 ��2

// OPTION NODUMP ��3

-IF &A EQ NORMAL GOTO NORMAL ��4

// EXEC CAIBR14,SIZE=24K ��5

-GOTO END ��6

-STEP NORMAL ��7

// EXEC CAIABEND,SIZE=24K ��8

-STEP END ��9

%� ��1�

%& ��11

��12

��13

��14

��15

��16

��17

��18

��19

1...+....1....+....2....+....3....+....4....+....5....+....6....+....7..

� �

This panel displays Unicenter CA-Driver for VSE procedures. To return to theprevious panel without saving the new procedure, enter QUIT on thecommand line.


3.3 Altering Procedures

3.3 Altering Procedures

If you select option 3 from the Driver Procedure Maintenance panel or enter Anext to a procedure in the Procedure Directory, the following panel appears:

� � SCHD-DRVE ALT P=BTEST CA-DRIVER

===>

RANGE=�1-72

1...+....1....+....2....+....3....+....4....+....5....+....6....+....7..

+ PARM=(A) ��1





-GOTO END ��6



-STEP END ��9

%� ��1�

%& ��11

��12

��13

��14

��15

��16

��17

��18

��19

1...+....1....+....2....+....3....+....4....+....5....+....6....+....7..

� �

Use this panel to alter Unicenter CA-Driver for VSE procedures.

To Return To The Previous Panel Enter

And file the new procedure in the database FILE

Without saving the new procedure QUIT

And save the procedure for future updating SAVE


3.4 Defining Procedures


If you select option 4 from the Driver Procedure Maintenance panel, thefollowing panel appears:

� � SCHD-DRVE DEF P= CA-DRIVER

===>

RANGE=�1-72

1...+....1....+....2....+....3....+....4....+....5....+....6....+....7..

��1

��2

��3

��4

��5

��6

��7

��8

��9

��1�

��11

��12

��13

��14

��15

��16

��17

��18

��19

1...+....1....+....2....+....3....+....4....+....5....+....6....+....7..

� �

Use this panel to define Unicenter CA-Driver for VSE procedures.

To define a procedure, enter the procedure name in the following formatwhere xxxxxxxx is the procedure name:

P=xxxxxxxx

If you want to define variable parameters or passwords for the procedure, typethem in this format, separated by commas, starting in column 1, line 1:

+ PARM=(name1=default,name2=default,...)+ RPW=readpass+ WPW=writpass

Then type the contents of the procedure. See the Appendix for a list of editorcommands which you can use to enter or change the procedure and highlightor protect lines.



To Return To The Previous Screen Enter


Without saving the new procedure QUIT



3.5 Copying Procedures

3.5 Copying Procedures

If you select option 6 from the Driver Procedure Maintenance panel or enter Cnext to a procedure in the Procedure Directory, the following panel appears:

� � SCHD-DRVE CPY P=BTEST CA-DRIVER

===>

RANGE=�1-72

1...+....1....+....2....+....3....+....4....+....5....+....6....+....7..

+ PARM=(A) ��1





-GOTO END ��6



-STEP END ��9

%� ��1�

%& ��11

��12

��13

��14

��15

��16

��17

��18

��19

1...+....1....+....2....+....3....+....4....+....5....+....6....+....7..

� �

Use this panel to copy Unicenter CA-Driver for VSE procedures. You mustchange the procedure name before you SAVE/FILE by specifying P=xxxxxxxxon the command line.

To Return To The Previous Panel Enter


Without saving the new procedure Quit



Chapter 4. Audit Events for Unicenter CA-Driver forVSE

By way of the comprehensive system event logging and reporting facility(CAIAUDIT), Unicenter CA-Driver for VSE allows you to

■ Log events made on behalf of Unicenter CA-Driver for VSE and

■ View them online.

The Audit Facility is an optional feature that can be selected through thesystem options, not through the CMS transaction.

This chapter explains how to access and use CAIAUDIT's online eventnotification system to track Unicenter CA-Driver for VSE events.

For information on

■ Selecting the Audit Facility feature, see the Unicenter CA-Driver for VSESystems Programmer Guide.

■ Unicenter CA-Driver for VSE event codes and their descriptions, see"Appendix B."

Chapter 4. Audit Events for Unicenter CA-Driver for VSE 4-1

4.1 Event Notification Selection

4.1 Event Notification Selection

You can browse information logged to the CAUDPCn data set by CAICUI onbehalf of Unicenter CA-Driver for VSE. The event information panels may beaccessed from prompt mode, command mode, or a combination of both.

4.1.1.1 Prompt Mode

To access the panels in prompt mode, follow these steps:

1. From the CUI Primary Selection Panel (CUI-MENU), select the option forEvent Notification Selection and press Enter.

2. Once the AUDIT Data Set Browse Selection (AUDT-1000) panel isdisplayed, specify the Unicenter CA-Driver for VSE product code, CARD,and press Enter.

This displays the AUDIT Data Set Directory - CA-DRIVER (AUDT-1G00)panel, listing all events logged for Unicenter CA-Driver for VSE.

4.1.1.2 Command Mode

To transfer directly from any panel, issue the following long command on thecommand line and press Enter.

AUDIT DISPLAY AUDIT PRODUCT=CARD

This command displays the AUDIT Data Set Directory - Unicenter CA-Driverfor VSE (AUDT-1G00) panel, which lists events logged for UnicenterCA-Driver for VSE.


4.2 AUDIT Data Set Directory - Unicenter CA-Driver for VSE (AUDT-1G00)

4.2 AUDIT Data Set Directory - Unicenter CA-Driver for VSE(AUDT-1G00)

This panel displays one line of information for each Unicenter CA-Driver forVSE record logged to the CAUDPCn data set currently being browsed.

It can be accessed either by

■ Specifying the Unicenter CA-Driver for VSE product code, CARD, on theAUDIT Data Set Browse Selection Panel (AUDT-1000), as discussed in theCA90s Services Reference Guide, or

■ Typing the long command DISPLAY AUDIT PRODUCT=CARD andpressing Enter.

� � AUDT-1G�� AUDIT Data Set Directory - CA-DRIVER CA AUDIT

====>

Cmd Evnt Date Time Procedure Description

___ LRST �4/19/94 14:�4:11 LIBRARY RESTORE

___ PRST �4/19/94 14:�5:42 PROCEDURE RESTORE

___ PRST �4/19/94 14:�7:1� PROCEDURE RESTORE

___ CRE8 �4/19/94 14:4�:�1 TSTPROC PROCEDURE CREATE

___ LBPR �4/19/94 14:4�:18 LIBRARY PRINT

___ LBPU �4/19/94 14:4�:3� LIBRARY PUNCH

___ LBPU �4/19/94 14:42:57 LIBRARY PUNCH

___ LBPP �4/19/94 14:43:14 LIBRARY PRINT/PUNCH

___ SCAN �4/2�/94 1�:23:�3 LIBRARY SCAN

___ SCAN �4/2�/94 1�:23:�3 LIBRARY SCAN

___ CRE8 �4/2�/94 12:3�:35 TESTPROC PROCEDURE CREATE

___ CRE8 �4/2�/94 12:3�:35 TESTPRO1 PROCEDURE CREATE

___ LCOR �4/2�/94 12:3�:47 LIBRARY CORRECT

___ DELT �4/2�/94 12:3�:55 TESTPROC PROCEDURE DELETE

__ __ __ __

==> ____ ______ ______ ________

1=Help 2= 3=Quit 4= 5= 6=

7=Backward 8=Forward 9= 1�= 11= 12=Exit

� �

With this panel you can:

■ Change selection criteria

■ Select a record for detail display

■ Use local commands



4.2.1 Field DescriptionsPrompts are shown at both input and display fields. All input fields areoptional. Tab to the desired fields and supply all pertinent information beforepressing Enter.

Cmd Enter short commands in this area. For this panel, thefollowing commands are valid and may be stacked:

DSP Displays available detail information abouta specific event. Type DSP in the shortcommand area on the line of the desiredrecord or, if no other short commands havebeen entered, position the cursor anywhereon the desired line and press Enter.

Evnt Displays the event code identifying the specific event thatoccurred. (See "Appendix B" for a list of all the UnicenterCA-Driver for VSE event codes and their explanations.)

Date Displays the date the event occurred.

Time Displays the time the event occurred.

Procedure Displays the name of the procedure involved in the event.

Description Displays a brief description of the event.

==> Use this area to change selection criteria. Supply a newrelation(s) to the right of the arrow ( ===> ), and/or anynew selection information on the line below it. (Also see"Changing Selection Criteria" below.) The followingrelations are valid for this panel:

Abbreviation Symbol Relationship

EQ = equal to the selection criteria.

NE ¬= not equal to the selection criteria.

LT < less than the selection criteria.

GT > greater than the selection criteria.

LE <= less than or equal to the selection criteria.

GE >= greater than or equal to the selectioncriteria.



4.2.2 Changing Selection CriteriaThe selection criteria can be changed at any time by tabbing to the bottom ofthe panel and entering the new information. Press Enter to redisplay thedirectory with newly selected data.

4.2.3 Local CommandsType any of the following commands on the command line and press Enter:

Command Function

BAckward nnn Scrolls backward a specified number of panels.BOTtom Scrolls to the last entry in a display.Down nnn Scrolls forward a specified number of lines.FOrward nnn Scrolls forward a specified number of panels.TOP Scrolls to the first entry in a display.UP nnn Scrolls backward a specified number of lines.

4.2.4 PF Key SettingsUse any of the following PF key default settings:

PF Key Function

PF1/PF13 HELPPF3/PF15 QUITPF7/PF19 BACKWARDPF8/PF20 FORWARDPF12/PF24 EXIT


4.3 AUDIT Procedure Detail - CA-DRIVER (AUDT-1G10)


This panel displays details about any of the following event codes, selectedfrom the AUDIT Data Set Directory - CA-DRIVER (AUDT-1G00) panel:

CRE8 EDCP PRNT RDEQ SDEL DDIR EDRO PRPU RELP STAT DELT EDRW PUNH REPL UPDT

� � AUDT-1G1� AUDIT Procedure Detail - CA-DRIVER CA AUDIT

====>

Event Code: CRE8 Description: Creating a Procedure

Facility Id: BG User Id: CARUTIL Date: �4/19/94 Time: 14:4�:�1

Procedure Name: TSTPROC

Procedure Printed: Yes

Procedure Punched: No

1=Help 2= 3=Quit 4= 5= 6=

7= 8= 9= 1�= 11= 12=Exit

� �



4.3.1 Field DescriptionsAll prompts on this panel are display fields and cannot be altered.

Event Code: Displays the selected event code.

Description: Displays a brief description of the event.

Facility Id: Displays the ID of the VSE partition from which theaudit event was logged.

User Id: Displays the VSE job name that originated the auditevent.

Date: Displays the date on which the audit event was logged.

Time: Displays the time at which the audit event was logged.

Procedure Name: Name of the procedure involved in the event.

Procedure Printed: Indicates whether the procedure was printed.

Procedure Punched: Indicates whether the procedure was punched.


PF Key Function

PF1/PF13 HELPPF3/PF15 QUITPF12/PF24 EXIT




This panel displays details about the event code PCOR, selected from theAUDIT Data Set Directory - CA-DRIVER (AUDT-1G00) panel:


====>

Event Code: PCOR Description: Correction of a Procedure

Facility Id: BG User Id: CARUTIL Date: �4/22/94 Time: 1�:26:23

Procedure Name: TSTPROC

Old String: /1994/

New String: /1995/

String Found: Yes

1=Help 2= 3=Quit 4= 5= 6=

7= 8= 9= 1�= 11= 12=Exit

� �




Facility Id: Displays the ID of the VSE partition from which the auditevent was logged.

User Id: Displays the VSE job name that originated the audit event.



Procedure Name: Name of the procedure involved in the event.

Old String: Displays the string that was being searched for.

New String: Displays the string to replace it.

String Found: Indicates whether the string was found.




PF Key Function





This panel displays details about the event code RNAM, selected from theAUDIT Data Set Directory - CA-DRIVER (AUDT-1G00) panel:


====>

Event Code: RNAM Description: Rename of a Procedure

Facility Id: BG User Id: CARUTIL Date: �4/22/94 Time: 1�:28:31

Old Procedure Name: TSTPROC

New Procedure Name: NEWPROC

1=Help 2= 3=Quit 4= 5= 6=

7= 8= 9= 1�= 11= 12=Exit

� �


Event Code: Displays the selected event code with a briefdescription.

Description: Displays the user-defined text associated with thispanel.



Date: Displays the date on which the audit event waslogged.

Time: Displays the time at which the audit event waslogged.

Old Procedure Name: Displays the old name of the Procedure.

New Procedure Name: Displays the new name of the Procedure.




PF Key Function



4.6 AUDIT Master Key Detail - CA-DRIVER (AUDT-1G40)

4.6 AUDIT Master Key Detail - CA-DRIVER (AUDT-1G40)

This panel displays details about the event code MAST, selected from theAUDIT Data Set Directory - CA-DRIVER (AUDT-1G00) panel:

� � AUDT-1G4� AUDIT Master Key Detail - CA-DRIVER CA AUDIT

====>

Event Code: MAST Description: Master Key was Defined

Facility Id: BG User Id: MASTKEY Date: �4/22/94 Time: 1�:31:13

1=Help 2= 3=Quit 4= 5= 6=

7= 8= 9= 1�= 11= 12=Exit

� �


Event Code: Displays the selected event code with a brief description.

Description: Displays the user-defined text associated with this panel.






PF Key Function





This panel displays details about the event code REPT, selected from theAUDIT Data Set Directory - CA-DRIVER (AUDT-1G00) panel:


====>

Event Code: REPT Description: Procedure Cross-Reference Reports

Facility Id: BG User Id: REPORT Date: �4/22/94 Time: 1�:35:3�

Reports Requested:

PROC,NEST

NEST,PROC

EXEC,PROC

DFN,PROC

DID,PROC

TFN,PROC

TID,PROC

1=Help 2= 3=Quit 4= 5= 6=

7= 8= 9= 1�= 11= 12=Exit

� �


Event Code: Displays the selected event code with a brief description.

Description: Displays the user-defined text associated with this panel.





Reports Requested: Displays a list of requested reports.




PF Key Function






LBPR LBPU LBPP


====>

Event Code: LBPR Description: Print of Procedure Library

Facility Id: BG User Id: LIBPRINT Date: �4/19/94 Time: 14:4�:18

Print: Yes

Punch: No Punch Noheader: No

----------------------- Include Procedure Names -----------------------

1=Help 2= 3=Quit 4= 5= 6=


� �








Print: Indicates whether the procedure(s) were printed.

Punch: Indicates whether the procedure(s) were punched.

Punch Noheader: Indicates whether the procedure(s) were punched withoutthe information required to recatalog them.



Include Procedure Names:Displays a list of procedures involved in the event.


Command Function



PF Key Function





This panel displays details about the event code SCAN, selected from theAUDIT Data Set Directory - CA-DRIVER (AUDT-1G00) panel:

� � AUDT-1G61 AUDIT Procedure Detail - CA-DRIVER CA AUDIT

====>

Event Code: SCAN Description: Scan of Procedure Library

Facility Id: BG User Id: LIBSCAN Date: �4/2�/94 Time: 1�:23:�3

String: /EXEC/

----------------------- Include Procedure Names -----------------------

A�� A��1 A��2 A��3 A��4 A��5 A��6 A��7

A��8 A��9 A�1� A�11 A�12 A�13 A�14 A�15

A�16 A�17 A�18 A�19 A�2� A�21 A�22 A�23

A�24 A�25 A�26 A�27 A�28 A�29 A�3� A�31

A�32 A�33 A�34 A�35 A�36 A�37 A�38 A�39

A�4� A�41 A�42 A�43 A�44 A�45 A�46 A�47

A�48 A�49 A�5� A�51 A�52 A�53 A�54 A�55

A�56 A�57 A�58 A�59 A�6� A�61 A�62 A�63

A�64 A�65 A�66 A�67 A�68 A�69 A�7� A�71

A�72 A�73 A�74 A�75 A�76 A�77 A�78 A�79

A�8� A�81 A�82 A�83 A�84 A�85 A�86 A�87

A�88 A�89 A�9� A�91 A�92 A�93 A�94 A�95

1=Help 2= 3=Quit 4= 5= 6=


� �








String: Displays the string that was being scanned for.





Command Function



PF Key Function





This panel displays details about the event code LCOR, selected from theAUDIT Data Set Directory - CA-DRIVER (AUDT-1G00) panel:


====>

Event Code: LCOR Description: Correction of Selected Procedure

Facility Id: BG User Id: CORRECT Date: �4/2�/94 Time: 12:3�:47

Old String: /ABCDE/

New String: /XYZ/

----------------------- Include Procedure Names ----------------------

A�� A��1 A��2 A��3 A��4 A��5 A��6 A��7

A��8 A��9 A�1� A�11 A�12 A�13 A�14 A�15

A�16 A�17 A�18 A�19 A�2� A�21 A�22 A�23

A�24 A�25 A�26 A�27 A�28 A�29 A�3� A�31

A�32 A�33 A�34 A�35 A�36 A�37 A�38 A�39

A�4� A�41 A�42 A�43 A�44 A�45 A�46 A�47

A�48 A�49 A�5� A�51 A�52 A�53 A�54 A�55

A�56 A�57 A�58 A�59 A�6� A�61 A�62 A�63

A�64 A�65 A�66 A�67 A�68 A�69 A�7� A�71

A�72 A�73 A�74 A�75 A�76 A�77 A�78 A�79

A�8� A�81 A�82 A�83 A�84 A�85 A�86 A�87

1=Help 2= 3=Quit 4= 5= 6=


� �








Old String: Displays the string that was being searched for.

New String: Displays the string that replaced it.





Command Function



PF Key Function






LBAK PBAK


====>

Event Code: LBAK Description: Backing up Procedure Library

Facility Id: BG User Id: DRIVSAVE Date: �4/22/94 Time: 11:�4:42

Replace: No Initial Record:

Saved as JCL: Yes Continuation Record:

-------------------------- Procedure Names ---------------------------

1=Help 2= 3=Quit 4= 5= 6=


� �








Replace: not used

Saved as JCL: Indicates that a -SAVEJCL command was used to dothe backup.

Initial Record: Indicates this is first record of the audit event.



Continuation Record: Indicates this is record 2-n of the audit event.

Procedure Names: Displays the names of the procedures involved in theevent.


Command Function



PF Key Function






LRST PRST

� � AUDT-1G81 AUDIT Procedure Detail - CA-DRIVER CA AUDIT

====>

Event Code: PRST Description: Restoring selected Procedures

Facility Id: BG User Id: DRIVREST Date: �4/19/94 Time: 14:�5:42

Replace: No

Old Name New Name Old Name New Name Old Name New Name Old Name New Name

-------- -------- -------- -------- -------- -------- -------- --------

DATEFUN INPUT PARTDEP PWRJOB

RESERVD SRESRVD VMPROC

1=Help 2= 3=Quit 4= 5= 6=


� �








Replace: Specifies whether replacement of existing procedure wasallowed.

Old Name: Name of a procedure that was restored.

New Name: New name of the restored procedure.




Command Function



PF Key Function





This panel displays details about the event code FRMT, selected from theAUDIT Data Set Directory - CA-DRIVER (AUDT-1G00) panel:


====>

Event Code: FRMT Description: Procedure Library Format

Facility Id: BG User Id: DRIVER Date: �4/22/94 Time: 11:11:�9

Share: Yes

Owner Id: CA-DRIV.PROCLIB

Number of Procedures: 2�

Control Interval Size: 2�48

1=Help 2= 3=Quit 4= 5= 6=

7= 8= 9= 1�= 11= 12=Exit

� �







Time: Displays the time at which the audit event waslogged.

Share: Displays the share option for the Procedure Library.

Owner Id: Displays the name of the owner of the ProcedureLibrary.

Number of Procedures: Displays the number of procedures expected to befound in the library.



Control Interval Size: Displays the CISIZE of the Procedure Library.


PF Key Function



Appendix A. Editor Commands

This appendix describes each of the Unicenter CA-Driver for VSE editorcommands and shows examples of each.

Appendix A. Editor Commands A-1

A.1 Protecting and Highlighting LInes

A.1 Protecting and Highlighting LInes

Use these letters to protect and highlight lines in Unicenter CA-Driver for VSEprocedures. In order to specify one of these letters in column 73, use theRANGE command (on page &range) to include column 73 in the range. Thelines that require one of these control characters can also be designated at theiroriginal source.

To Type This In Column 73

Protect a line P

Highlight a line H

Both protect and highlight a line F

Protect a line and keep it from displaying D

A-2 Unicenter CA-Driver for VSE Reference Guide

A.2 Defining, Copying, or Altering Unicenter CA-Driver for VSE Procedures

A.2 Defining, Copying, or Altering Unicenter CA-Driver forVSE Procedures

Use the following editor commands to define, copy, or alter UnicenterCA-Driver for VSE procedures.

Command abbreviations are shown in upper case. Optional operands areshown in parentheses. If you do not specify a number where a command callsfor a number, 1 is assumed.

To Type This After ====>

Leave the panel you are editingand enter new values in the database or

staging filewithout saving any values

FILE

Quit

Save new values without leaving the panel(not applicable to criteria modification)

Save

Repeat the last command you entered =

Execute a command and keep the cursor after====>

&command

Set a key to perform a command, wherekey can be PFn, PAn, CLEAR,

or ENTER(Note: See PF key editor defaults.)

SET key command

Goto first line of fileto last line of filebackward n panels (toward first line of file)forward n panels (toward last line of file)

TopBOttomBackward (n)Forward (n)

Move the panel displayup n lines (toward first line of file)down n lines (toward last line of file)

to right or left so that column n is the firstcolumn displayed on the panel

Up (n)Down (n) Next (n)

COLumn n

Limit the LOCATE or CHANGE commandsto specific columns: from column c to columnd

Range c d

Find the first occurrence of character string sanywhere in the fileat the beginning of a line(embedded blanks are not allowed)

Locate sFInd s


A.2 Defining, Copying, or Altering Unicenter CA-Driver for VSE Procedures

To Type This After ====>

Replace character string s with characterstring t

anywhere in the filestarting at line lonly from lines l to m(embedded blanks are not allowed)

CHange s tCHange s t lCHange s t l m

Add n blank lines after line l Add l (n)

Delete n lines starting with line l DElete 1 (n)

Copyline l and insert it after line mn number of lines, starting with line l, and

insert them after line m

Copy 1 mCopy 1 m n

Moveline l after line mn number of lines, starting with line l, and

insert them after line m

Move 1 mMove 1 m n

Displaynumbers in the line-command area====== in the line-command area

NUmNOnum


A.3 Adding, Deleting, Copying, and Moving Lines


You can also add, delete, copy, and move lines by moving the cursor to theline command area. This area is located at the far right of the panel, beginningat the editor-generated line number. To use the following commands, overtypethis line number.

Examples of these line commands appear on the following pages.

To Type

Make this the current line /

Add lines A(n) or (n)A

Deleteone or more linesa block of lines

D(n) or (n)DDD

Copyone or more linesa block of lines

C(n) or (n)CCC

Moveone or more linesa block of lines

M(n) or (n)MMM

Place the moved or copied linesafter this linebefore this line

FP

Duplicate a line n times "(n) or (n)"

A.3.1 ExamplesFor the line command examples that follow, the panel width has been reducedsomewhat in order to include the arrows for illustration.

A.3.1.1 Changing the Current Line

To make line 6 the current line:



1...+....1....+....2....+....3... ...5....+....6....+....7...

THIS IS LINE 1. ��1





THIS IS LINE 6. /��6 <---THIS IS LINE 7. ��7



THIS IS LINE 1�. ��1�






The result will be:

1...+....1....+....2....+....3... ...5....+....6....+....7...











A.3.1.2 Adding Lines

To add 3 lines after line 4:

1...+....1....+....2....+....3... ...5....+....6....+....7...




THIS IS LINE 4. a3��4 <---THIS IS LINE 5. ��5











The result will be:



1...+....1....+....2....+....3... ...5....+....6....+....7...





��5

��6

��7



THIS IS LINE 7. ��1�



THIS IS LINE 1�. ��13






A.3.1.3 Deleting Lines

To delete 5 lines, starting at line 5:

1...+....1....+....2....+....3... ...5....+....6....+....7...





THIS IS LINE 5. 5d��5 <---THIS IS LINE 6. ��6










The result will be:

1...+....1....+....2....+....3... ...5....+....6....+....7...













A.3.1.4 Copying Lines

To copy lines 4-6 to an area following line 10:

1...+....1....+....2....+....3... ...5....+....6....+....7...




THIS IS LINE 4. cc��4 <---THIS IS LINE 5. ��5

THIS IS LINE 6. cc��6 <---THIS IS LINE 7. ��7



THIS IS LINE 1�. f��1� <---THIS IS LINE 11. ��11





The result will be:

1...+....1....+....2....+....3... ...5....+....6....+....7...





















A.3.1.5 Moving Lines

To move the 6 lines starting at line 10 to the area preceding line 1:

1...+....1....+....2....+....3... ...5....+....6....+....7...

THIS IS LINE 1. p��1 <---THIS IS LINE 2. ��2








THIS IS LINE 1�. 6m�1� <---THIS IS LINE 11. ��11





The result will be:

1...+....1....+....2....+....3... ...5....+....6....+....7...


















A.3.1.6 Duplicating Lines

To duplicate line 2 twice, and line 10 once:

1...+....1....+....2....+....3... ...5....+....6....+....7...


THIS IS LINE 2. 2"��2 <---THIS IS LINE 3. ��3







THIS IS LINE 1�. "1�1� <---THIS IS LINE 11. ��11





The result will be:

1...+....1....+....2....+....3... ...5....+....6....+....7...




















A.4 PF Key Settings

A.4 PF Key Settings

The default PF key settings for the Unicenter CA-Scheduler for VSE onlineeditor are as follows:

If your PF keys are not set to these defaults, see your Systems Programmer.

PF Keys CommandFunction

PF1/PF13 HELP Invoke the online Help facility.

PF2/PF14 Unassigned

PF3/PF15 Quit Leave the edit panel without savingchanges.

PF4/PF16 Down Move the panel down one line.

PF5/PF17 Up Move the panel up one line.

PF6/PF18 Unassigned

PF7/PF19 Backward Scroll back one panel.

PF8/PF20 Forward Scroll forward one panel.

PF9/PF21 Unassigned

PF10/PF22 Top Go to the top of the file.

PF11/PF23 BOttom Go to the end of the file.

PF12/PF24 Unassigned


Appendix B. Event Codes

The event codes for Unicenter CA-Driver for VSE functions are listed below:

Code Event Description

CRE8 Creating a procedure

DDIR Displaying Procedure Library Directory

DELT Deletion of a procedure

EDCP Editing a procedure for copying

EDRO Editing a procedure read only

EDRW Editing a procedure read/write

FRMT Procedure Library format

LBAK Backing up Procedure Library

LBPP Print/punch of Procedure library

LBPR Print of Procedure Library

LBPU Punch of Procedure Library

LCOR Correction of selected procedure

LRST Restoring Procedure Library

MAST Master key was definedMaster Key was purgedMaster Key was changedMaster Key was accessedMaster Key was deleted

PBAK Backing up selected procedures

PCOR Correction of a procedure

PRNT Displaying a procedure

PRPU Displaying and punching a procedure

PRST Restoring selected procedures

PUNH Punching a procedure

RDEQ Dequeue of the Procedure Library

Appendix B. Event Codes B-1

Code Event Description

RELP Release a hold on a procedure

REPL Replacing a procedure

REPT Procedure cross-reference reports

RNAM Rename of a procedure

SCAN Scan of Procedure Library

SDEL Deletion of a saved procedure

STAT Displaying Procedure Library statistics

UPDT Updating of a procedure

B-2 Unicenter CA-Driver for VSE Reference Guide

Index

Special Characters-ABORT 1-70-ADD 2-36-CONTCHAR 2-14-COR 2-21, 2-37-CTLCHAR 2-15-DEBUG 2-15-DEL 2-38-DISPLAY 2-19-FLUSH 1-70-GOTO 1-63-IF 1-64-INPUT 1-67-LCTR 1-69-LIB 2-20-MASTKEY 2-2-OVERRIDE 2-3, 2-26-PROC 1-2, 2-26-REP 2-39-REPLY 1-72-RPG 2-24-SCAN 2-22-SEL 2-44-SET 1-68-STEP 1-62-WTO 1-71// CARCTL 1-102// COPTION 1-77// DATA 1-6// DGOTO 1-78// DIF 1-81// DSTEP 1-78// FLUSH 1-79// GOTO 1-78// IF 1-81// PROC 1-3, 2-8// SET 1-79

// STEP 1-78// VM CP 1-9&C_ABCC 1-16&C_ABCT 1-16&C_ABSTP 1-16&C_AUTDT 1-15&C_AUTIM 1-15&C_CAL 1-16&C_CMD 1-16&C_DATE 1-13&C_DAY 1-13&C_DTAB 1-16&C_GLBL variables 1-18&C_JDATE 1-13&C_JNAME 1-16&C_JNO 1-16&C_JOBDT 1-16, 1-24&C_MONTH 1-13&C_RUNCD 1-16&C_SELRC 1-16&C_SNAME 1-16&C_SPWR# 1-16&C_SYSID 1-16&C_TIME 1-13

AADM function 1-41ADP function 1-49Altering procedures 3-6AR commands

BUFSTATS 1-103DISABLE 1-103ENABLE 1-103STATUS 1-103

Arrays 1-19, 2-7Attribute testing 1-21AUDIT DISPLAY AUDIT

PRODUCT=CARD command 4-2

Index X-1

Auditing eventsbrowse panels 4-2codes B-1overview 3-9

AUDT-1G00 AUDIT Data Set Directory -CA-DRIVER

fields 4-4local commands 4-5PF keys 4-5relations 4-4short commands 4-4

AUDT-1G00 AUDIT Data Set Directory - UnicenterCA-Driver for VSE

panel 4-3AUDT-1G10 AUDIT Procedure Detail - CA-DRIVER

fields 4-7panel 4-6PF keys 4-7

AUDT-1G20 AUDIT Procedure Detail - CA-DRIVERfields 4-8panel 4-8PF keys 4-9


AUDT-1G40 AUDIT Master Key Detail -CA-DRIVER

fields 4-12panel 4-12PF keys 4-12


AUDT-1G60 AUDIT Procedure Detail - CA-DRIVERfields 4-15local commands 4-16panel 4-15PF keys 4-16






Automatic job submissionfrom a Unicenter CA-Driver for VSE

procedure 1-94from a user program 1-96from the operator console 1-99overview 1-94

BBatch commands 2-2Branching

conditional 1-64, 1-81unconditional 1-63, 1-78

Browsing events 4-4BUFSTATS 1-103

CCA-DYNAM 1-107CAIAUDIT

browse panelsaccess to 3-9for Unicenter CA-Driver for VSE events 4-3

event codes B-1CARACC 1-91CARCOM 1-99CARCTL 1-102CARMSG 1-108CARSET 1-83CARSUBMT 1-96CARTEST 1-86CARUTIL commands

-ADD 2-36-CONTCHAR 2-14-COR 2-21, 2-37-CTLCHAR 2-15-DEBUG 2-15

X-2 Unicenter CA-Driver for VSE Reference Guide

CARUTIL commands (continued)-DEL 2-38-DISPLAY 2-19-LIB 2-20-OVERRIDE 2-26-PROC 2-26-REP 2-39-RPG 2-24-SCAN 2-22-SEL 2-44executing 2-3keywords 2-13overview 2-2syntax 2-5

Cataloging procedures 1-2CDM function 1-41CDP function 1-50CICS commands 2-46Conditional

execution 1-73, 1-76, 1-83procedure expansion 1-61

Continuation character 2-14Control character 2-5, 2-15COPTION 1-77Copying procedures 3-9CP commands 1-9CPU ID 1-75CREATE 2-30

DData inclusion 1-6, 1-8DATE system variable 1-75DAY function 1-35Defining procedures 3-7DGOTO 1-78DIF 1-81DISABLE 1-102Disabling Unicenter CA-Driver for VSE 1-102Disguising job control statements 2-11Displaying procedures 3-5DM3Y function 1-35DM3YR function 1-35DMY function 1-35DMYJ function 1-35DMYR function 1-35DOW function 1-35DOW# function 1-35DRIV transaction 3-1Driver

Procedure Directory 3-3

Driver (continued)Procedure Maintenance 3-1

DSTEP 1-78DTADD function 1-34DTDIF function 1-34DTSUB function 1-34

EEditor

commands A-1ENABLE 1-102Enabling Unicenter CA-Driver for VSE 1-102EQ 1-64Event codes

list B-1panels 4-4

FFLUSH 1-77, 1-79Functions for Unicenter CA-Driver for VSE 1-24

GGLBL 1-74GLOBAL 1-18Global variables 1-18, 1-74GOTO 1-78GT 1-64

HHDM function 1-41

IIBM source library 1-67IF 1-81Including data 1-6, 1-8Installation options 1-77Interfaces

conditional programs 1-83VM 1-9

JJADM function 1-41JADP function 1-49JCDM function 1-41JCDP function 1-50

Index X-3

JDOM function 1-39JHDM function 1-41Job

automatic submissionfrom a Unicenter CA-Driver for VSE

procedure 1-94from a user program 1-96from the operator console 1-99overview 1-94

flushing 1-79JRAD function 1-56JRCD function 1-57JRHD function 1-54JRWD function 1-54JWDM function 1-41

LLADM function 1-45LADP function 1-51LCDM function 1-47LCDP function 1-52LDOM function 1-39Length attribute 1-22LHDM function 1-45Listing procedures 3-3LJADP function 1-51LJCDM function 1-47LJCDP function 1-52LJDOM function 1-39LJHDM function 1-45LJRAD function 1-60LJRCD function 1-61LJRHD function 1-58LJRWD function 1-58LJWDM function 1-45Local commands for

AUDT-1G00 4-5AUDT-1G60 4-16AUDT-1G61 4-18AUDT-1G70 4-20AUDT-1G80 4-22AUDT-1G81 4-24

Logging event codes 4-2Long command, AUDIT DISPLAY AUDIT

PRODUCT=CARD 4-2Loop control 1-69LRAD function 1-60LRCD function 1-61LRHD function 1-58

LRWD function 1-58LT 1-64LWDM function 1-45

MM3DY function 1-35M3DYR function 1-35Main menu

for CAIAUDIT browse panels 4-2MDY function 1-35MDYJ function 1-35MDYR function 1-35Messaging the operator 1-71MNADD function 1-34MNSUB function 1-34Modeling 1-104MON function 1-35MON# function 1-35MONTH function 1-35

NNested procedures 1-5, 2-9NOFLUSH 1-77NOSLOG 1-77Null

PROC 1-7value 1-20

Number attribute 1-23

OOLDVNAM installation option 1-13, 1-18Online

CAIAUDIT transaction panels 4-3procedure maintenance 3-1

PPanels

AUDT-1G00 AUDIT Data Set Directory -Unicenter CA-Driver for VSE 4-3

AUDT-1G10 AUDIT Procedure Detail -CA-DRIVER 4-6



AUDT-1G40 AUDIT Master Key Detail -CA-DRIVER 4-12



Panels (continued)AUDT-1G60 AUDIT Procedure Detail -

CA-DRIVER 4-15AUDT-1G61 AUDIT Procedure Detail -





CA-DRIVER 4-25PART-ID 1-12Partition-dependent

procedures 1-4variables 1-11

PARTN system variable 1-75Passwords 1-2POWER 1-102PRINT 2-43PROC 1-3, 2-8Procedure

aborting expansion 1-70altering 3-6calling 1-3cataloging 1-2, 2-11, 2-30conditional execution 1-73controlling loops 1-69copying 3-9defining 3-7deleting 2-32directory 2-19, 3-3displaying 3-5expansion 1-3, 1-61, 2-10flushing 1-70library

accessing 1-91integrity 2-3listing 2-19printing 2-20punching 2-20reporting 2-24scanning 2-21, 2-22

listing 3-3maintenance 3-1modeling 1-104naming 2-6nesting 1-5, 2-9overview 1-2partition dependent 1-4

Procedure (continued)passwords 1-2, 2-30printing 2-22, 2-26, 2-34, 2-42, 2-43punching 1-106, 2-33, 2-42querying library status 2-25referencing variables 2-9releasing 2-34renaming 2-43replacing 2-35selecting 2-44statement numbers 2-6updating 2-21, 2-27, 2-36

Procedure Maintenance Menu 3-1PUNCH 1-106, 2-42

RRAD function 1-56RCD function 1-57Relations for AUDT-1G00 4-4RENAME 2-43Reports 2-24Reserved-name variable parameters for Unicenter

CA-Driver for VSE 1-12Restarting jobs 1-63Return codes 2-15RHD function 1-54RWD function 1-54

SSecurity 1-2SET 1-79Short commands for AUDT-1G00 4-4SLOG 1-77STATUS 1-103STEP 1-78SUBMIT 1-94Substrings

referencing 1-17variable parameters 1-19

SYS system variable 1-75

TTIME system variable 1-75Type attribute 1-22

UUnicenter CA-Driver for VSE

commands 2-1

Index X-5

Unicenter CA-Driver for VSE (continued)disabling 1-102enabling 1-102events, browse panels 4-3functions 1-24reserved-name variable parameters 1-12status 1-103

Update protection 2-3USER variables 1-74USR variables 1-74

VVariable parameter

arrays 1-19, 2-7attribute testing 1-21coding requirements 2-6default values 2-7defining 2-13deleting 2-41global 1-18in nested procedures 2-9multiple 2-8overview 1-10partition dependent 1-12reserved-name 1-12setting 1-68, 1-79, 1-83substitution 1-10, 2-9, 2-10substring referencing 1-17, 1-19system 1-75testing 1-81, 1-86updating 2-40user 1-74values

multiple 1-19, 2-7override 2-8

Verifying data inclusion 1-8VM interface 1-9

WWDM function 1-41WOM function 1-35WOY function 1-35

YYM3D function 1-35YMD function 1-35YMDJ function 1-35

YRM3D function 1-35YRMD function 1-35


Documents

ftpdocs.broadcom.com · Contents Chapter 1. Using Unicenter CA-Driver Job Management for VSE.... 1-1 1.1 Using Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . .