ROSCOE - B001723e - System Reference Guide

Advantage CA-Roscoe
 
Interactive Environment
System Reference Guide

r6
This documentation and any related computer software help programs (hereinafter referred to as the
“Documentation”) is for the end user’s informational purposes only and is subject to change or withdrawal by CA at
any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in
part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA
and 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 the documentation for
their own internal use, and may make one copy of the related software as reasonably required for back-up and
disaster recovery purposes, 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 provisions of the license for
the product are permitted to have access to such copies.
The right to print copies of the documentation and to make a copy of the related software is limited to the period
during which the applicable 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 certify in writing to CA that all copies and partial copies of the
Documentation have been returned to CA or destroyed.
EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, 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 the Documentation is governed by the end user’s applicable license
agreement.
The manufacturer of this Documentation is CA.
Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the
restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-
7014(b)(3), as applicable, or their successors.
All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
Copyright  2005 CA. All rights reserved.

Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Chapter 1. Advantage CA-Roscoe Overview . . . . . . . . . . . . . . . . . 1-1

1.1 Active Work Space (AWS) . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.2 User Libraries and UPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
1.3 OS Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.4 Data Management Facilities . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
1.5 ROSCOE Printing Services . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
1.6 Monitor Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
1.7 ETSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
1.8 Operator Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
1.9 Accounting and Statistical Facilities . . . . . . . . . . . . . . . . . . . . 1-10
1.9.1 Accounting Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
1.10 Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
1.11 HELP and Interactive Training Aids . . . . . . . . . . . . . . . . . . 1-14
Chapter 2. File Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

2.1 File Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
2.1.1 Sample Volume Layouts . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
2.2 Accounting Files (ROSACTnn) . . . . . . . . . . . . . . . . . . . . . . . . 2-3
2.2.1 File and Space Requirements . . . . . . . . . . . . . . . . . . . . . . 2-5
2.2.2 Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
2.3 AWS Files (SYSAWSnn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
2.3.1 Structure of the AWS . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
2.3.2 AWS Cache Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
2.3.3 Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
2.3.4 Determining the Appropriate Number of AWSs . . . . . . . . . 2-11
2.3.5 Recovery Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
2.3.6 Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
2.4 Library Files (ROSLIBnn) . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
2.4.1 Library Cache Facility . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
2.4.2 Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
2.4.2.1 Index File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
2.4.2.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
2.4.2.3 Online Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
2.4.2.4 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
2.4.3 Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
2.4.4 Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
2.4.4.1 Backing Up the User Libraries . . . . . . . . . . . . . . . . . 2-16
Contents iii
2.4.4.2 Restoring the User Libraries . . . . . . . . . . . . . . . . . . . 2-17
2.4.4.3 Selective Backups and Restores . . . . . . . . . . . . . . . . . 2-18
Chapter 3. Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.1 Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
3.2 Maintenance Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
3.2.1 Daily . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
3.2.2 Weekly (or as Required) . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
3.3 Operator/Privileged Controls . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.3.1 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.4 Site Sign-on Messages and Program . . . . . . . . . . . . . . . . . . . . 3-6
3.4.1 Maintaining the Newsletter . . . . . . . . . . . . . . . . . . . . . . . 3-6
3.4.2 Global Sign-on Program . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3.4.3 Execution Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
| 3.5 Site Signoff Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Chapter 4. User Profile System (UPS) . . . . . . . . . . . . . . . . . . . . . 4-1

4.1 UPS Member Components . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
4.2 Creating and Maintaining User Profiles . . . . . . . . . . . . . . . . . . 4-5
4.2.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
4.3 Executing UPSMNTnn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
4.3.1 1. Add a New Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
4.3.2 2. Update an Existing Profile . . . . . . . . . . . . . . . . . . . . . . 4-7
4.3.3 3. Delete an Existing Profile . . . . . . . . . . . . . . . . . . . . . . . 4-7
4.3.3.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8
4.4 Executing UPSBLKnn . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
4.5 Creating Restricted Profiles . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
4.5.1 Controlling Restricted Users . . . . . . . . . . . . . . . . . . . . . 4-15
4.5.2 Temporary Restricted Users . . . . . . . . . . . . . . . . . . . . . . 4-16
4.5.3 Permanent Restricted Users . . . . . . . . . . . . . . . . . . . . . . 4-16
4.5.4 Execution Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
4.6 Using the UPS Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
4.7 Special Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
4.7.1 Distributed User Profiles . . . . . . . . . . . . . . . . . . . . . . . . 4-19
4.7.1.1 Reserved Profile Names . . . . . . . . . . . . . . . . . . . . . 4-19
4.7.2 Privileged Profiles (RO and AI) . . . . . . . . . . . . . . . . . . . 4-21
4.7.3 Reserved User Profiles . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
4.8 Security Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
4.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
4.8.1.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
4.8.2 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
4.8.2.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
4.8.3 Sample Security Groups Definition . . . . . . . . . . . . . . . . . 4-27
Chapter 5. General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

5.1 Attention Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
5.1.1 Synchronous/Asynchronous Attention Support . . . . . . . . . . . 5-2
5.2 Data Streams Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.3 Devices Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.4 Protocols Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
iv System Reference Guide

Chapter 6. Operations Considerations . . . . . . . . . . . . . . . . . . . . . 6-1
6.1 Operation System Generation . . . . . . . . . . . . . . . . . . . . . . . . 6-2
6.2 Resident Access Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
6.3 Required Device I/O Modules . . . . . . . . . . . . . . . . . . . . . . . . 6-4
6.4 Error Recovery for Local/Remote Devices . . . . . . . . . . . . . . . . . 6-5
6.5 TTY and TTY Compatible Terminal Considerations . . . . . . . . . . . 6-7
6.5.1 IGG019MP Modification to Suppress Time Out . . . . . . . . . . . 6-7
6.5.2 IGG019MP Modification for Autospeed . . . . . . . . . . . . . . . . 6-7
6.5.3 Multispeed TTY Compatible Terminal Considerations . . . . . . . 6-8
6.5.4 Advantage CA-Roscoe Speed Table for TTY Compatible Terminals 6-8
6.5.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
6.5.5 Advantage CA-Roscoe TTY ID Verification (ROSTTYID) . . . . 6-10
6.5.6 TTY Transmission Control . . . . . . . . . . . . . . . . . . . . . . . 6-11
6.5.6.1 Inbound Control Characters . . . . . . . . . . . . . . . . . . . 6-11
6.5.6.2 Outbound Control Characters . . . . . . . . . . . . . . . . . . 6-12
6.5.6.3 Translation Table Customization . . . . . . . . . . . . . . . . 6-12
6.5.7 Modifications to ERP to Use TTY BREAK . . . . . . . . . . . . . 6-13
Chapter 7. ROSCOE Communication Services (RCS) . . . . . . . . . . . 7-1

7.1 Determining if the Default RCS Definition May Be Used . . . . . . . . 7-2
7.2 Establishing an RCS Network Definition . . . . . . . . . . . . . . . . . . 7-3
7.2.1 RCSGEN: Access Method Definition . . . . . . . . . . . . . . . . . 7-3
7.2.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
7.2.1.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
7.2.2 RCSBTAMR: Initiate Remote Table . . . . . . . . . . . . . . . . . . 7-6
7.2.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
7.2.2.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
7.2.3 RCSLINE: Define a Line Group . . . . . . . . . . . . . . . . . . . . 7-8
7.2.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
7.2.3.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
7.2.4 RCSCLSTR: Define Cluster on a Line . . . . . . . . . . . . . . . . . 7-9
7.2.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
7.2.4.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
7.2.5 RCSDVICE: Define a Device on the Cluster . . . . . . . . . . . . 7-10
7.2.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
7.2.5.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
7.2.6 RCSGEND: End Communication Network Definition . . . . . . 7-13
7.2.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13
7.2.6.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13
7.3 JCL to Assemble and Link Edit . . . . . . . . . . . . . . . . . . . . . . 7-14
7.4 Sample RCSDEF Definition . . . . . . . . . . . . . . . . . . . . . . . . . 7-15
7.4.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16
Chapter 8. ROSCOE Printing Services (RPS) . . . . . . . . . . . . . . . . . 8-1

8.1 RPS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
8.1.1 Operational Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
8.1.2 Advantage CA-Roscoe JCL Considerations . . . . . . . . . . . . . . 8-3
8.1.3 Definition of Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
8.2 328x Type Printer Considerations . . . . . . . . . . . . . . . . . . . . . . 8-5
8.2.1 VTAM Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Contents v
8.2.2 BTAM Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
8.3 Establishing a Printing Network Environment . . . . . . . . . . . . . . 8-7
8.3.1 RPSGEN: Start the Network Definition . . . . . . . . . . . . . . . . 8-8
8.3.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
8.3.1.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
8.3.2 RPSPRNTR: Define 328x Type Printer Features . . . . . . . . . . 8-10
8.3.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
8.3.2.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
8.3.3 JESPRNTR: Define System Printer Features . . . . . . . . . . . . 8-14
8.3.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14
8.3.3.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
8.3.4 RPSDEST: Define Destinations . . . . . . . . . . . . . . . . . . . . 8-16
8.3.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16
8.3.4.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
8.3.5 RPSDLIST: Destination List Generation . . . . . . . . . . . . . . . 8-20
8.3.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
8.3.5.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
8.3.6 RPSTERM: Terminal Authorization . . . . . . . . . . . . . . . . . 8-21
8.3.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
8.3.6.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22
8.3.7 RPSGEND: End the Network Definition . . . . . . . . . . . . . . 8-23
8.3.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
8.3.7.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
8.4.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25
8.5 Sample Printing Network Environment Definitions . . . . . . . . . . 8-26
Chapter 9. VTAM Considerations . . . . . . . . . . . . . . . . . . . . . . . 9-1

9.1 Defining Advantage CA-Roscoe to VTAM . . . . . . . . . . . . . . . . . 9-2
9.1.1 APPL Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
9.1.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
9.1.2 LOCAL Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
9.2 Defining VTAM Session Parameters . . . . . . . . . . . . . . . . . . . . 9-3
9.2.1 VTAM Session Parameters . . . . . . . . . . . . . . . . . . . . . . . 9-3
9.2.2 VTAM PSERVIC Matrix Requirements . . . . . . . . . . . . . . . . 9-4
9.2.2.1 Presentation Size . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
9.2.2.2 Outbound (to device) RUSIZE . . . . . . . . . . . . . . . . . . . 9-5
9.2.2.3 Inbound (to Advantage CA-Roscoe) RUSIZE . . . . . . . . . . 9-5
9.2.2.4 MODEENT Example . . . . . . . . . . . . . . . . . . . . . . . . 9-6
9.3 Defining USS Definition Table . . . . . . . . . . . . . . . . . . . . . . . . 9-7
9.4 Defining an Interpret Table . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
9.4.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
9.5 SNA Logons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
9.6 Defining Control Characters to NCP for NTO Support . . . . . . . . 9-10
9.7 Advantage CA-Roscoe/VTAM Stop/Start Processing . . . . . . . . . 9-11
| 9.8 Balancing the Workload . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13
Chapter 10. XTPM Support . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Chapter 11. ATTACH JOB, CONSOLE and DISPLAY Requirements . 11-1

11.1 Defining ROSGBL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
vi System Reference Guide

11.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
11.1.2 Assemble and Link Edit ROSGBL . . . . . . . . . . . . . . . . . 11-7
11.1.2.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
11.2 ATTACH JOB Requirements . . . . . . . . . . . . . . . . . . . . . . . 11-8
11.2.1 Causing a Job to be Held . . . . . . . . . . . . . . . . . . . . . . . 11-9
11.2.1.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9
11.2.2 Space Requirements and Usage . . . . . . . . . . . . . . . . . . . 11-9
11.3 CONSOLE Routine Requirements . . . . . . . . . . . . . . . . . . . . 11-12
11.3.1 To Use This Routine . . . . . . . . . . . . . . . . . . . . . . . . . 11-12
11.3.2 To Customize/Modify This Routine . . . . . . . . . . . . . . . . 11-12
11.4 DISPLAY Routine Requirements . . . . . . . . . . . . . . . . . . . . . 11-13
11.5 JES2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15
11.5.1 Advantage CA-Roscoe JES2 EXIT5 Overview . . . . . . . . . . 11-15
11.5.2 JES2 Initialization Implications . . . . . . . . . . . . . . . . . . . 11-16
11.5.2.1 Processing Overview . . . . . . . . . . . . . . . . . . . . . . . 11-17
11.5.2.2 RO$EXIT5 Processing . . . . . . . . . . . . . . . . . . . . . . 11-18
11.5.2.3 Return Processing . . . . . . . . . . . . . . . . . . . . . . . . 11-19
11.5.2.4 Recovery Processing . . . . . . . . . . . . . . . . . . . . . . . 11-20
11.6 JES3 Local Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 11-21
11.6.1 Assembling the IATUX30 Exit . . . . . . . . . . . . . . . . . . . . 11-21
11.6.2 Creating the BDAM Data Set . . . . . . . . . . . . . . . . . . . . 11-22
Chapter 12. Data Set Facility Considerations . . . . . . . . . . . . . . . . 12-1

12.1 Advantage CA-Roscoe JCL Changes . . . . . . . . . . . . . . . . . . . 12-2
12.1.1 Initialization Parameters . . . . . . . . . . . . . . . . . . . . . . . 12-2
12.1.2 DD Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
12.2 Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
12.2.1 Sites Using AllFusion CA-Librarian: . . . . . . . . . . . . . . . . 12-3
12.3 Space Requirements and Usage . . . . . . . . . . . . . . . . . . . . . 12-4
12.3.1 Catalog Space Needs . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
12.3.2 Line Queue Elements . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
12.4 Enqueue Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
12.4.1 ENQTYPE=OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
12.4.2 ENQTYPE=ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
12.4.3 Considerations for Sites with ENQ/RESERVE Control Software 12-7
Chapter 13. DB2 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Chapter 14. ETSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

14.1 Evaluating Applications . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
14.1.1 Application Considerations . . . . . . . . . . . . . . . . . . . . . 14-2
14.1.2 Site Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5
14.2 Controlling Resources and Use . . . . . . . . . . . . . . . . . . . . . . 14-7
14.3 Defining Applications to ETSO . . . . . . . . . . . . . . . . . . . . . . 14-9
14.3.1 Loading Programs on ETSOLIB . . . . . . . . . . . . . . . . . . . 14-9
14.3.2 Defining Programs in the EPL . . . . . . . . . . . . . . . . . . . . 14-10
14.4 Writing and Executing Applications . . . . . . . . . . . . . . . . . . . 14-13
Contents vii
| Chapter 15. BTSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1
15.1 Application Considerations . . . . . . . . . . . . . . . . . . . . . . . . 15-2
15.2 CSA Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3
15.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
15.3.1 Define BTSO to CAIRIM . . . . . . . . . . . . . . . . . . . . . . . 15-4
15.3.2 Define BTSO to ETSO . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
15.3.3 Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
15.3.4 Copy Supplied RPFs . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
15.3.5 USERMOD MR06026 - Modify IRXISPRM for Advantage
CA-Roscoe CLIST/REXX Usage . . . . . . . . . . . . . . . . . . . . . . 15-5
15.3.6 RPF Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
15.3.7 Calling RTBETSO . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
15.3.8 RTB Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-6
| 15.3.9 RTBEXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-7
Chapter 16. HELP Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1

16.1 Accessing Help Members . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
16.2 Scrolling Help Members . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
16.3 Installing and Maintaining Help Members . . . . . . . . . . . . . . . 16-4
16.4 Creating Site-Specific Help Members . . . . . . . . . . . . . . . . . . 16-5
16.4.1 Identifying Title, Function and Syntax/Screen Break . . . . . . 16-5
16.4.1.1 Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-5
16.4.1.2 Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-5
16.4.1.3 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-6
16.4.1.4 Creating Screen Breaks (3270 only) . . . . . . . . . . . . . . 16-7
16.4.2 Creating Levels Within Help Members . . . . . . . . . . . . . . 16-8
16.4.2.1 Level/Subcommand List . . . . . . . . . . . . . . . . . . . . 16-8
16.4.2.2 Level/Subcommand Labels . . . . . . . . . . . . . . . . . . . 16-8
16.4.3 Specifying Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-10
16.4.4 Commenting Help Members . . . . . . . . . . . . . . . . . . . . . 16-11
16.4.5 Highlighting Lines (3270 Only) . . . . . . . . . . . . . . . . . . . 16-12
16.5 Customizing the Distributed Help Members . . . . . . . . . . . . . . 16-13
Chapter 17. Job Submission and Notification . . . . . . . . . . . . . . . 17-1

17.1 Internal Readers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
17.2 Job Completion Notification . . . . . . . . . . . . . . . . . . . . . . . 17-3
Chapter 18. Monitor Routines . . . . . . . . . . . . . . . . . . . . . . . . . 18-1

18.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
18.1.1 Common Distribution Information . . . . . . . . . . . . . . . . . 18-3
18.1.2 Common Advantage CA-Roscoe JCL Changes . . . . . . . . . . 18-4
18.1.3 Common Accounting Information . . . . . . . . . . . . . . . . . 18-4
18.2 AMS Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
18.2.3 AMSAUTH: Restricting Access . . . . . . . . . . . . . . . . . . . 18-5
18.2.4 AMSDFLT: Changing Defaults . . . . . . . . . . . . . . . . . . . 18-6
18.2.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-7
18.3 AWS Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-9
18.4 CONSOLE Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-10
viii System Reference Guide

18.5 DISPLAY Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-11
18.6 DMS Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-12
18.7 EXPORT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-13
18.7.3 RSSCEXPU: Changing Defaults . . . . . . . . . . . . . . . . . . . 18-13
18.7.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-14
18.7.3.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-15
18.7.4 ENAMES: Restricting Data Set Access . . . . . . . . . . . . . . . 18-16
18.7.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-16
18.7.5 To Install an ENAMES Table . . . . . . . . . . . . . . . . . . . . 18-17
18.8 IMPORT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-18
18.8.1.1 To Customize/Modify This Routine . . . . . . . . . . . . . 18-18
18.8.2 INAMES: Restricting Data Set Access . . . . . . . . . . . . . . . 18-18
18.8.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-19
18.8.3 To Install an INAMES Table . . . . . . . . . . . . . . . . . . . . . 18-19
18.9 JCK Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-21
18.9.2 To Install a Modified JCLOPTS Table . . . . . . . . . . . . . . . 18-22
18.10 MONITOR Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-23
18.11 PURGE Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-24
18.11.2 To Install RSSCPUR0 . . . . . . . . . . . . . . . . . . . . . . . . 18-24
18.11.3 To Customize/Modify This Routine . . . . . . . . . . . . . . . 18-24
18.12 ROS Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-25
18.13 RTF Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-26
18.14 SORT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-27
18.14.2 To Install RSSCSOR0 . . . . . . . . . . . . . . . . . . . . . . . . 18-27
18.15 ZAP Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-28
18.15.3 ZAPDEFLT: Processing Option and Default Table . . . . . . . 18-28
18.15.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-29
18.15.4 To Install a Modified ZAPDEFLT Table . . . . . . . . . . . . . 18-31
18.16 CA Product Monitor Routines . . . . . . . . . . . . . . . . . . . . . . 18-32
18.16.1 DDO Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-32
18.16.1.1 To Use This Routine: . . . . . . . . . . . . . . . . . . . . . 18-32
18.16.2 ETC Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-32
18.16.3 MAIL Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-32
Contents ix
Chapter 19. PF/PA Key Assignment Definitions . . . . . . . . . . . . . . 19-1

19.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
19.2 ROSPFUSE Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
19.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
19.2.2 PF/PA Key Assignment Considerations . . . . . . . . . . . . . . 19-4
19.2.2.1 Assigning a Single Fixed Value . . . . . . . . . . . . . . . . 19-5
19.2.2.2 Assigning Multiple Values . . . . . . . . . . . . . . . . . . . 19-5
19.2.2.3 Assigning Commands With String Operands . . . . . . . . 19-6
19.2.2.4 Assigning RPF Programs . . . . . . . . . . . . . . . . . . . . 19-6
19.2.2.5 Assigning Variable Values . . . . . . . . . . . . . . . . . . . 19-7
19.2.3 Assigning Predefined Functions . . . . . . . . . . . . . . . . . . 19-9
19.2.3.1 Predefined Functions - Position Display . . . . . . . . . . . 19-9
19.2.3.2 Predefined Functions - Split Screen . . . . . . . . . . . . . . 19-10
19.2.3.3 Predefined Functions - Miscellaneous Functions . . . . . . 19-10
19.2.4 Sample ROSPFUSE . . . . . . . . . . . . . . . . . . . . . . . . . . 19-13
19.3 ROSPCODE Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-14
19.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-14
19.4 To Modify the PF/PA Key Assignment Table . . . . . . . . . . . . . 19-16
Chapter 20. ROSDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1

20.1 Changing ROSDATA Default Values . . . . . . . . . . . . . . . . . . 20-2
20.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
20.2.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4
Chapter 21. Security/Accounting Exit Facilities . . . . . . . . . . . . . . 21-1

21.1 Security Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
21.2 Exits Taken at Critical Moments During Advantage CA-Roscoe
Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-3
21.3 Monitor Routine Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-4
Chapter 22. TRAINING (RPF) . . . . . . . . . . . . . . . . . . . . . . . . . 22-1

22.1 Installing and Maintaining the TRAINING RPF . . . . . . . . . . . . 22-2
22.1.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2
22.2 System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
22.2.1 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
22.2.1.1 Help Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
22.2.1.2 Summary Panels . . . . . . . . . . . . . . . . . . . . . . . . . 22-4
22.2.1.3 Additional Members in TRAINING . . . . . . . . . . . . . . 22-4
22.2.2 Assigned Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
22.2.3 Members Added to User's Library . . . . . . . . . . . . . . . . . 22-5
22.3 Processing Technique . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-7
22.4 Customizing the TRAINING . . . . . . . . . . . . . . . . . . . . . . . 22-8
22.4.1 Verifying DMF Prefix . . . . . . . . . . . . . . . . . . . . . . . . . 22-8
22.4.2 Reviewing Distributed JCL . . . . . . . . . . . . . . . . . . . . . . 22-8
22.5 Executing TRAINING . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9
22.5.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9
Chapter 23. TUTORIAL (Advantage CA-Roscoe) . . . . . . . . . . . . . 23-1
x System Reference Guide

23.1 Installing and Maintaining the TUTORIAL . . . . . . . . . . . . . . . 23-2
23.1.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
23.2 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-3
23.3 Processing Technique . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-4
23.4 Customizing the TUTORIAL . . . . . . . . . . . . . . . . . . . . . . . 23-5
23.5 Executing the TUTORIAL . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
23.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
23.5.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
Chapter 24. BulletinBoard System (BBS) Support . . . . . . . . . . . . . 24-1

24.1.1 BulletinBoard System Prefixes . . . . . . . . . . . . . . . . . . . . 24-2
24.1.2 BulletinBoard System Initialization Parameter Requirement . . 24-2
24.1.3 BulletinBoard System ETSO EPL Requirement . . . . . . . . . . 24-3
Chapter 25. User-Contributed Routines . . . . . . . . . . . . . . . . . . . 25-1
| Chapter 26. Functionally Stabilized Routines . . . . . . . . . . . . . . . 26-1

26.1 ACCTREPT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-2
26.2 CAT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3
26.2.1 To Use This Routine: . . . . . . . . . . . . . . . . . . . . . . . . . 26-3
26.2.2 To Install RSSCCAT0 . . . . . . . . . . . . . . . . . . . . . . . . . 26-3
26.3 COB Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-5
26.4 LOOK Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-6
26.4.1 To Use This Routine: . . . . . . . . . . . . . . . . . . . . . . . . . 26-6
26.5 PLI Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-7
26.6 UTILITY Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-8
26.6.3 DEFAULT: Changing Defaults . . . . . . . . . . . . . . . . . . . 26-9
26.6.4 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-9
26.6.5 To Install a Modified DEFAULT Table . . . . . . . . . . . . . . 26-10
26.6.6 ROSTABLE: Modifying Subcommand Table . . . . . . . . . . . 26-11
26.6.7 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-11
26.6.7.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-11
26.6.8 To Install a Modified Subcommand Table . . . . . . . . . . . . . 26-12
26.6.9 ROSPASS: Modifying Password Table . . . . . . . . . . . . . . . 26-12
26.6.10 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-12
26.6.10.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-13
26.6.11 To Install a Modified Password Table . . . . . . . . . . . . . . 26-13
26.6.12 ROSUTNDX: Protecting Data Sets . . . . . . . . . . . . . . . . . 26-14
26.6.13 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-14
26.6.14 To Modify ROSUTNDX to Protect Data Sets . . . . . . . . . . 26-15
26.6.15 PUNITL: Unit Definition and Dynamic Allocation . . . . . . . 26-15
26.6.15.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-16
26.6.16 To Modify the Unit Definition Table . . . . . . . . . . . . . . . 26-17
26.7 VCAT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-18
Contents xi
26.7.2 To Install RSSCVCA0 . . . . . . . . . . . . . . . . . . . . . . . . . 26-18
Appendix A. Advantage CA-Roscoe System Extensions . . . . . . . . . A-1

A.1 Use of OS/390 Cross-Memory Services . . . . . . . . . . . . . . . . . A-2
A.2 Support Address Space (ROSAS) . . . . . . . . . . . . . . . . . . . . . A-4
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1
xii System Reference Guide

About This Guide
The System Reference Guide is intended for the individual responsible for
maintaining Advantage CA-Roscoe. It contains introductory and specific
information about all components of Advantage CA-Roscoe.
About This Guide xiii

Organization
CHAPTER DESCRIPTION
1 Provides an overview of all the major components
composing Advantage CA-Roscoe.
2 Describes Advantage CA-Roscoe file requirements.
3 Discusses maintenance procedures and scheduling, operator,
RO and A1 controls, sign-on messages and programs.
4 Describes the User Profile System (UPS), how to create
profiles, special profiles, and security groups.
5 Describes attention, data streams, device, and protocol
support.
6 Describes BTAM considerations.
7 Describes the ROSCOE Communications Services (RCS)
where the RCS network definition is required and how to
establish a definition.
8 Describes ROSCOE Printing Services (RPS) and how to
establish a printing network environment definition.
9 Describes VTAM considerations.
10 XTPM introductions.
11 Describes ATTACH JOB, CONSOLE, and DISPLAY
requirements.
12 Describes Data Set Facility considerations.
13 Describes DB2 support provided with Advantage
CA-Roscoe and Advantage CA-Roscoe/DB2.
14 Describes ETSO and how to evaluate and define
applications to run under ETSO.
15 Describes BTSO and how to evaluate and define
applications to run under BTSO.
16 Describes the HELP Facility and how to add or customize
HELP members.
17 Describes job submission and notification considerations.
18 Describes Monitor routines in general plus specific
information about enabling and customizing the distributed
Monitor routines.
19 Describes how to change PF/PA key assignments.
20 Describes how to change ROSDATA default values.
21 Introduces the security and accounting exits provided with
Advantage CA-Roscoe.
xiv System Reference Guide

CHAPTER DESCRIPTION
22 Describes how to maintain and customize the RPF online
training called TRAINING.
23 Describes how to maintain and customize the Advantage
CA-Roscoe online training called TUTORIAL.
24 Describes how to set up and define the Advantage
CA-Roscoe Bulletin Board System.
25 Describes user-contributed routines and how they are
distributed.
| 26 Describes the FUNCTIONALLY STABILIZED monitor
| routines.
Appendix A Describes Advantage CA-Roscoe system extensions
involving the use of OS/390 Cross-Memory Services and the
Advantage CA-Roscoe Support Address Space.
About This Guide xv

Revisions and Enhancements
The following information has been provided as a quick reference regarding
revisions and enhancements that have been made in the the core release and
the Service Packs that followed.
Summary of Revisions for Service Pack 7

■ LIBDEF and FILE DEF statements for load libraries are not supported in
ETSO.
■ The ROSLIB00 file must not reside on the same volume as the JES3 BDAM
communication file.

■ To allow multiple archiving products, two new Advantage CA-Roscoe
start-up parameters (RECALVL2 and RECALVL3) have been added.
■ When installing and using the JCK monitor to check JCL in Advantage
CA-Roscoe's AWS, a blank screen is often encountered without any error
messages or indication of any kind that there is a problem. Messages and
options have been added to specify and list out the options passed to
JCLCHECK. New options for JCL include: -D, -X, and -A. JCK-D display
parms passed to JCLCHECK. JCK-X turns off Advantage CA-Roscoe's
SVC screening of issues and JCK-A places output to an Advantage
CA-Roscoe AWS.
■ New messages have been added to describe problems that can occur
during execution of JCK that would have normally returned with no
indication of a problem.

■ The BTSO facility has been enhanced to allow batch jobs to be started by a
started task or JCL.
■ Module RTBETSO is the BTSO component that runs within the Advantage
CA-Roscoe by processing parameters passed by the user and starts the
new address space. The module then waits for feedback from the new
address space.
■ Module RTBBATCH is the BTSO component that runs in the new address
space created by RTBETSO and sets up SVC screening so that any TPUTs
or TGETs can be passed back to the RTBETSO program. RTBBATCH then
invokes the third-party or user application that was requested by the user.
■ An RTB monitor is supplied as a load module to let you view the status of
BTSO.
■ RTBEXIT is the new user exit provided for BTSO.
xvi System Reference Guide

Summary of Revisions in this Edition
Added the global signoff RPF program option. For more information, see 3.5,
“Site Signoff Program” on page 3-8.
Changed the definition for destname in 8.3.4, “RPSDEST: Define Destinations”

on page 8-16. It must begin with an alphabetic or national character.
About This Guide xvii

Summary of Revisions
■ UPSMNTnn and UPSBLKnn: When adding or updating profiles, two new
user privileges can be assigned. Users can be permitted to issue privileged
commands for the following Advantage CA-Roscoe subject areas:
– LIB: Allows use of the privileged commands UPDATE, SAVE,
DELETE, RENAME, and AFTER for daily library maintenance,
regardless of the way security groups are established.
– UPS: Allows use of the privileged command UPSMNTnn.
■ The following monitors can be functionally stabilized for Velease 6.0.
CAT
KEY
VCAT
■ The following monitor is obsolete for Velease 6.0.
UTILITY
■ Editorial and minor technical changes have been made throughout this
manual.
xviii System Reference Guide

Advantage CA-Roscoe Publications
The following publications are supplied with Advantage CA-Roscoe Interactive
Environment. They are divided into a User Series and a System Series.
User Series Contents

Name
Command Reference Describes all Advantage CA-Roscoe primary and
Guide line commands and Monitor commands.
Extended Development Describes how: 1) the Application Programming
Tools Guide Interface (API) can be used by applications
executing under ETSO to take advantage of
Advantage CA-Roscoe facilities, and 2) the
interactive facilities provided by SKETCH can be
used to generate and maintain panels used in
programs running under CICS or IMS.
Getting Started Introduces Advantage CA-Roscoe to
non-programmers.
Release Guide Provides a summary of the enhancements included
in this release.
RPF Language Guide Describes all components of the RPF language and
how to write RPF programs. It also describes the
Dialog Management Facility (DMF) which can be
used to develop, maintain and execute panel-driven
RPF applications.
User Guide Provides task-oriented descriptions of how to use
About This Guide xix

System Series Contents
Name
Extended Facilities for Describes how sites can make extensions to their
System Programmers Advantage CA-Roscoe system. This includes
Guide creating site-written Monitor routines and
customizing security and other online exits.
Installation Guide Describes the steps to follow when installing or
upgrading Advantage CA-Roscoe.
Messages and Codes Explains all messages that might be received by
Guide individuals using Advantage CA-Roscoe or by the
individual responsible for maintaining Advantage
CA-Roscoe.
Programs and Utilities Describes Advantage CA-Roscoe execution
Guide requirements. Also describes maintenance and
reporting programs for the accounting facility,
Active Work Space (AWS), library system, and user
profile system.
Security Administration Describes implementation of internal and external
Guide security to protect your Advantage CA-Roscoe
system.
System Commands Guide Describes commands used to control and monitor
Advantage CA-Roscoe and to obtain performance
information about that execution.
System Reference Guide Intended for the individual responsible for
maintaining Advantage CA-Roscoe. It describes
Advantage CA-Roscoe and its components.
xx System Reference Guide

Related Publications
The CA Common Services r11 for z/OS SP6 (formerly known as Unicenter
TNG Framework for OS/390 and CA Common Services for z/OS and OS/390
Services) documentation can be found on http://supportconnect.ca.com.
The following manuals relate to Advantage CA-Roscoe and are on

http://supportconnect.ca.com.
Title Contents
Advantage CA-Earl Reference Guide Contains detailed information about
Advantage CA-Earl statements,
parameters, and coding rules. Also
explains the Advantage CA-Earl
Reporting Service.
Advantage CA-Earl User Guide Designed for users interested in
learning about Advantage CA-Earl. It
presents an introduction to
Advantage CA-Earl features and
capabilities.
Advantage CA-Earl Systems Lists the installation options for
Programmer Guide Advantage CA-Earl and instructions
for modifying them. Also describes
size requirements and program
execution.
Advantage CA-Earl Examples Guide Contains sample programs that show
a variety of common applications.
About This Guide xxi

CA Common Services for z/OS and OS/390
CA Common Services for z/OS and OS/390 are a common set of services that
may be used by any MVS Computer Associates product. These services are
maintained separately from the product and are documented and installed
separately as well. Advantage CA-Roscoe uses CAIRIM for installation services
and security.
Licensing Management Program (LMP)
Advantage CA-Roscoe now interfaces with CAIRIM services to determine

product licensing authorization.
xxii System Reference Guide

Reading Syntax Diagrams
The formats of all statements and some basic language elements are illustrated
using syntax diagrams. Read syntax diagrams from left to right and top to
bottom.
The following terminology, symbols, and concepts are used in syntax

diagrams.
Keywords: Appear in uppercase letters, for example, COMMAND or PARM.

These words must be entered exactly as shown.
Variables: Appear in italicized lowercase letters, for example, variable.
Required Keywords and Variables: Appear on a main line.
Optional Keywords and Variables: Appear below a main line.
Default Keywords and Variables: Appear above a main line.
Double Arrowheads Pointing to the Right: Indicate the beginning of a

statement.
Double Arrowheads Pointing to Each Other: Indicate the end of a

statement.
Single Arrowheads Pointing to the Right: Indicate a portion of a statement,

or that the statement continues in another diagram.
Punctuation Marks or Arithmetic Symbols: If punctuation marks or

arithmetic symbols are shown with a keyword or variable, they must be
entered as part of the statement or command. Punctuation marks and
arithmetic symbols can include:
, comma > greater than symbol

. period < less than symbol
( open parenthesis = equal sign
) close parenthesis ¬ not sign
+ addition − subtraction
* multiplication / division
About This Guide xxiii

The following is an example of a statement without parameters.
Statement Without Parameters

──COMMAND─────────────────────────────────────────────────────
You must write:
COMMAND
Required parameters appear on the same horizontal line (the main path of the
diagram) as the command or statement. The parameters must be separated by
one or more blanks.
Statement with Required Parameters

──COMMAND──PARM1──PARM2───────────────────────────────────────
You must write:
COMMAND PARM1 PARM2
Delimiters such as parentheses around parameters or clauses must be included.
Delimiters Around Parameters

──COMMAND──(PARM1)──PARM2='variable'──────────────────────────
If the word variable is a valid entry, you must write:
COMMAND (PARM1) PARM2='variable'
Where you see a vertical list of parameters as shown in the following example,
you must choose one of the parameters. This indicates that one entry is
required and only one of the displayed parameters is allowed in the statement.
Choice of Required Parameters

──COMMAND──┬─PARM1─┬──────────────────────────────────────────
├─PARM2─┤
└─PARM3─┘
You can choose one of the parameters from the vertical list, such as in the
following examples:
COMMAND PARM1
COMMAND PARM2
COMMAND PARM3
xxiv System Reference Guide

When a required parameter in a syntax diagram has a default value, it
indicates the value for the parameter if the command is not specified. If you
specify the command, you must code the parameter and specify one of the
displayed values.
Default Value for a Required Parameter

┌─YES─┐
──COMMAND──PARM1=─┴─NO──┴───PARM2─────────────────────────────
If you specify the command, you must write one of the following:
COMMAND PARM1=NO PARM2

COMMAND PARM1=YES PARM2
A single optional parameter appears below the horizontal line that marks the
main path.
Optional Parameter
──COMMAND──┬───────────┬──────────────────────────────────────
└─PARAMETER─┘
You can choose (or not) to use the optional parameter, as shown in the
following examples:
COMMAND
COMMAND PARAMETER
If you have a choice of more than one optional parameter, the parameters
appear in a vertical list below the main path.
Choice of Optional Parameters

──COMMAND──┬───────┬──────────────────────────────────────────
├─PARM1─┤
└─PARM2─┘
You can choose any of the parameters from the vertical list, or you can write
the statement without an optional parameter, such as in the following
examples:
COMMAND
COMMAND PARM1
COMMAND PARM2
About This Guide xxv

For some statements, you can specify a single parameter more than once. A
repeat symbol indicates that you can specify multiple parameters. The
following examples include the repeat symbol.
Repeatable Variable Parameter

┌──
──────────┐
─variable─┴───────────────────────────────────────
──COMMAND───
In the preceding example, the word variable is in lowercase italics, indicating

that it is a value you supply, but it is also on the main path, which means that
you are required to specify at least one entry. The repeat symbol indicates that
you can specify a parameter more than once. Assume that you have three
values named VALUEX, VALUEY, and VALUEZ for the variable. Some of
your choices are:
COMMAND VALUEX
COMMAND VALUEX VALUEY
COMMAND VALUEX VALUEX VALUEZ
If the repeat symbol contains punctuation such as a comma, you must separate
multiple parameters with the punctuation. The following example includes the
repeat symbol, a comma, and parentheses.
Separator with Repeatable Variable and Delimiter

┌─,────────┐
─variable─┴──)─────────────────────────────────
──COMMAND──(───
In the preceding example, the word variable is in lowercase italics, indicating

that it is a value you supply. It is also on the main path, which means that
you must specify at least one entry. The repeat symbol indicates that you can
specify more than one variable and that you must separate the entries with
commas. The parentheses indicate that the group of entries must be enclosed
within parentheses. Assume that you have three values named VALUEA,
VALUEB, and VALUEC for the variable. Some of your choices are:
COMMAND (VALUEC)
COMMAND (VALUEB,VALUEC)
COMMAND (VALUEB,VALUEA)
COMMAND (VALUEA,VALUEB,VALUEC)
The following example shows a list of parameters with the repeat symbol.
Optional Repeatable Parameters

┌──
─────────┐ ┌──
─────────┐ ┌──
─────────┐
┬───────┬┴───
──COMMAND─── ┬───────┬┴───
┬───────┬┴──────────────
└─PARM1─┘ └─PARM2─┘ └─PARM3─┘
xxvi System Reference Guide

Some choices you can make include:
COMMAND PARM1
COMMAND PARM1 PARM2 PARM3
COMMAND PARM1 PARM1 PARM3
For example, YES in the following diagram, its special treatment indicates it is
the default value for the parameter. If you do not include the parameter when
you write the statement, the result is the same as if you had actually specified
the parameter with the default value.
Default Value for a Parameter

──COMMAND──┬─────────────────┬──PARM2─────────────────────────
│ ┌─YES─┐ │
└─PARM1=─┴─NO──┴──┘
Because YES is the default in the example preceding, if you write:
COMMAND PARM2
you have written the equivalent of:
COMMAND PARM1=YES PARM2
In some syntax diagrams, a set of several parameters is represented by a single

reference, as in this example:
Variables Representing Several Parameters

──COMMAND──┬─────────────────────┬────────────────────────────
├─PARM1───────────────┤
└─┤ parameter-block ├─┘
parameter-block:
├──┬──────────────────┬──────────────────────────────────────────┤
├─PARM2────────────┤
└─PARM3─┬───────┬──┘
├─PARM4─┤
└─PARM5─┘
The parameter-block can be displayed in a separate syntax diagram.
Choices you can make from this syntax diagram therefore include (but are not
limited to) the following:
COMMAND PARM1
COMMAND PARM3
COMMAND PARM3 PARM4
Note: Before you can specify PARM4 or PARM5 in this command, you must
specify PARM3.
About This Guide xxvii

A note in a syntax diagram is similar to a footnote except that the note appears
at the bottom of the diagram box.
──COMMAND──┬─────────┬────────────────────────────────────────
(1)
└─PARM1─── ┘
Note:
1 This is a note about the item.
xxviii System Reference Guide

Chapter 1. Advantage CA-Roscoe Overview
Advantage CA-Roscoe is an online program development system that runs as

a continuing telecommunications task. This section introduces the major
components of Advantage CA-Roscoe and refers the reader to the appropriate
chapter or section of this manual for additional information.
As a telecommunications task, Advantage CA-Roscoe coordinates data transfer

activities among user terminals, temporary work areas (for example, the
Advantage CA-Roscoe Active Work Space, or AWS) and permanent data
storage facilities (for example, the Advantage CA-Roscoe user libraries) and OS
data sets. Subtasks of Advantage CA-Roscoe permit users to perform such
functions as submitting job streams for background execution, executing
programs online and browsing job output plus performing a variety of data
management tasks and executing operator commands.
Information concerning the maintenance of specific Advantage CA-Roscoe

components is included with the detailed descriptions of these components. In
addition, Chapter 3 contains information about the required and optional
procedures that should be performed on a regular basis to ensure the
successful operation of Advantage CA-Roscoe.
Chapter 1. Advantage CA-Roscoe Overview 1-1

1.1 Active Work Space (AWS)
1.1 Active Work Space (AWS)

The AWS is a temporary work area. (Each Advantage CA-Roscoe user has a
minimum of two AWSs.) Every time a user presses the Enter key or a PF key,
data typed at the terminal is placed in the active AWS. The data can then be
manipulated by primary or line commands and the terminal hardware editing
facilities.
Data in the AWS resides both in memory and on disk. The memory portion
consists of a series of buffers which contain the data currently being
manipulated and pointers to the data that is on disk. (The memory portion is
equal in size to the block size of the file on which the data resides plus 1.5K.)
The disk portion of the AWS consists of at least two files. One is the pointer
file (SYSAWSP) which contains the indexes to the data file(s). At least one
data file (SYSAWS1) is required; there can be a maximum of 16 data files. The
characteristics of the AWS are site-defined. These characteristics include the
block size of the files, the number of data files, the number of temporary work
areas and the size of each work area. The AWS is described in 2-7.
After data entry and editing, the data can be submitted directly to the
operating system's job queues, printed at a local printer, saved in the
Advantage CA-Roscoe user libraries or directed to an OS data set or
production source library.
1-2 System Reference Guide

1.2 User Libraries and UPS
1.2 User Libraries and UPS

The Advantage CA-Roscoe user libraries provide a permanent data storage
area. There is no restriction on the type of data that can be saved in the
libraries. It can be source code, JCL, test data, copies of job output files, and so
forth. The data is saved as a member created by the user. To modify the
contents of a member, a copy of the member is brought into the AWS. The
contents of the member remain unchanged until explicitly modified by the
user.
The user libraries are a set of three or more files that are treated as a single
system. As with the AWS, there is an index file (ROSLIB00) which contains
pointers to the location of user library members. A minimum of two data files
(ROSLIB01 and ROSLIB02) are required. (There can be a maximum of 99 data
files.) These files contain the data saved by the terminal users. The user
libraries are described in Section 2.3.
Each individual eligible to use Advantage CA-Roscoe is identified within the

User Profile System. Whenever a user signs on, the user's profile is read to
determine if the sign-on key password, if included) is valid. The profile
contains such additional information as the user's prefix and security group,
the name of the user's sign-on procedure that is to be automatically invoked
whenever the user signs on, the maximum number of data lines the user can
save in the library, and the current number of lines saved in the library. The
User Profile System is described in Chapter 4.
There are three categories of Advantage CA-Roscoe users. The categories and
the privileges extended to each are:
1. General Advantage CA-Roscoe users, who are permitted to execute all but
the privileged commands. The majority of Advantage CA-Roscoe users at a
site are established under this category.
2. Restricted users, who are limited in their use of Advantage CA-Roscoe. A
restricted user's terminal session is controlled by site-written RPF
programs.
3. Privileged users, who are assigned privileged user IDs. These individuals
are usually responsible for maintaining the Advantage CA-Roscoe system.
As such, they are permitted to use commands and facilities unavailable to
all other users. (These users must initially specify the SET PRIVILEGE ON
command to execute privileged commands.)
Chapter 4 provides detailed information about how each category of user is

defined to Advantage CA-Roscoe.
Excluding individuals who are assigned restricted sign-on keys, the terminal
users are free to use all Advantage CA-Roscoe commands and site-designated
Monitor commands.

1.3 OS Jobs
1.3 OS Jobs
When a job is submitted to the operating system's job queues, Advantage
CA-Roscoe commands can be used to display the execution status of the job.
(Information can also be obtained about job initiators, job queues and devices.)
Advantage CA-Roscoe also provides facilities that lets users browse jobs that
are awaiting execution, executing or awaiting print. While browsing the job,
users can copy it into the AWS, print a copy at a local printer, alter its remote
output status or delete the job. The procedures to establish this facility are
described in Chapter 11.

1.4 Data Management Facilities
1.4 Data Management Facilities

The Data Set Facility includes primary commands and selection lists that let
users browse sequential data sets; partitioned data users can also browse such
production source libraries as Allfusion CA-Librarian Users can also use
commands or function panels to perform such actions as allocate, delete,
rename, catalog, copy and print data sets and members. See Chapter 12 for
additional information.

1.5 ROSCOE Printing Services
1.5 ROSCOE Printing Services

The ROSCOE Printing Services (RPS) permit terminal users to print the
contents of the AWS, one or more library members, job output or a data set
object at 328x-type printers or at system (JES) printers. Chapter 8 describes
how to define and install an RPS printing network.

1.6 Monitor Commands
1.6 Monitor Commands

A Monitor command is a command that invokes a Monitor routine. Monitor
routines extend the services provided by Advantage CA-Roscoe commands.
Some of the distributed Monitor routines are:
1. PL/I and COBOL Syntax Checkers - Verifies the syntax of a source
program before its execution.
2. CONSOLE - Permits the: 1) display of messages written to a console, 2)
display the OS/390 Master Trace Table, and 3) execution of operator
commands
3. DISPLAY - Permits terminal users to get information from the operating
system about jobs, initiators, job queues and devices.
4. IMPORT and EXPORT - Copies from and writes to an OS data set,
AllFusion CA-Librarian master file, or AllFusion CA-Panvalet member.
5. DDO, ETC, JCK, LOOK and MAIL - to permit the use of Advantage
CA-Datacom/DB Datadictionary, CA-ETC, Unicenter
CA-JCLCheck, Unicenter CA-SYSVIEW, and CA-eMAIL+,
respectively.
Many of the Monitor routines can be customized to meet site security

requirements or to conform to site standards. For a complete list of the
distributed routines and how they may be customized, see Chapter 18.
For information about how a site can write their own Monitor routines, see
Advantage CA-Roscoe Interactive Environment Extended Facilities for System
Programmers Guide. For information about contributing site-written Monitor
routines, see Chapter 24.

1.7 ETSO
1.7 ETSO
Advantage CA-Roscoe can be further extended with ETSO. ETSO is an
application execution system that allows purchased applications and user
developed programs to execute without modification under Advantage
CA-Roscoe. This permits these applications to become an integral part of the
Advantage CA-Roscoe single mode environment. See Chapter 14 for a
description of ETSO.

1.8 Operator Controls
1.8 Operator Controls

The operator console is also the Advantage CA-Roscoe control console. The
operator may manually intervene and, in general, operate Advantage
CA-Roscoe as he would operate OS. The scope of his duties have been limited,
however, so as not to affect his response to operating system directives.
In addition to these operator controls, Advantage CA-Roscoe provides facilities

so that the individuals assigned privileged user IDs can communicate with
Advantage CA-Roscoe. See page 3-5 for additional information about operator
and privileged controls.

1.9 Accounting and Statistical Facilities

Sites have the option of designating whether accounting information is to be
provided by Advantage CA-Roscoe. If the information is desired, it can be
written to the Advantage CA-Roscoe accounting files, SMF files or both. (This
facility is controlled by Advantage CA-Roscoe initialization parameters
described in the Advantage CA-Roscoe Interactive Environment Programs and
Utilities Guide.)
■ If only SMF records are to be produced, no special Advantage CA-Roscoe
files are needed.
■ If Advantage CA-Roscoe accounting records are to be produced, one or
more accounting files must be included in the Advantage CA-Roscoe JCL.
These files are described in detail on page 2-3.
The information gathered by Advantage CA-Roscoe includes:

■ Statistics about the online activities of every Advantage CA-Roscoe user.
■ System shutdown record with initialization and termination times.
■ Data Set Facility audit record plus additional information that may be
obtained at site option.
■ Response-Time Monitor (RTM) statistics record.
■ RPS statistics record providing information about the use of the PRINT
command.

1.9.1 Accounting Reports

Reports containing information about Advantage CA-Roscoe and its use cover
such areas as:
■ Advantage CA-Roscoe Configuration: The ROSTAT program produces a
report which shows the initialization parameters used for the most current
execution of Advantage CA-Roscoe.
■ Advantage CA-Roscoe Usage: Advantage CA-Earl, using information
gathered by Advantage CA-Roscoe, can be used to produce reports that
contain information about:
1. The online activity of every Advantage CA-Roscoe user. This includes:
– Sign-on and sign-off dates and times.
– Number of jobs submitted.
– Name of the Monitor commands and ETSO applications executed
and the number of times each was executed.
– Connect times, plus the amount of CPU time used, number of
terminal accesses and number of disk I/Os.
– Optionally, user library statistic information.
2. Monitor commands and ETSO usage. The report includes information
about: 1) each Monitor command and the number of times it was
executed by an individual, and 2) the applications that were executed
under ETSO.
3. Response and resource statistics. This shows usage statistics by
transaction for all or selected users.
4. RPS usage. This report contains information about the use of the
PRINT command at the site.
■ AWS Information: Advantage CA-Earl also produces an AWS statistics
report. The report provides information about the AWS configuration and
status at the time Advantage CA-Roscoe was shutdown. It also provides
performance statistics.
The FAWSDS program produces a report that shows the parameters used
to format the AWS and the current status of the AWS files.
The ROSTAT program produces a report that shows the current AWS
configuration.
■ The Advantage CA-Roscoe User Libraries: Information can be obtained
about the library usage, library member maintenance and user profiles.
– Library Usage: The ROSTAT program produces a report which
includes the date of the last format run, number of data files, library
block size, total number of user library members, total number of all
user records, average, maximum and minimum index capacities, total
number of data blocks, free data blocks and dead data blocks.

– Library Member Maintenance:

The LIBBKUP program produces a report that lists the contents of the
backup file it created.
The LIBSERVE program produces a report which shows the result of
its execution. The execution could be to rename or delete library
members, list all or part of one or more members, or scan members for
particular character strings.
The LIBUTIL program, which is used to backup and restore the
Advantage CA-Roscoe libraries, optionally provides reports identifying
the specific library members involved in a backup or restore operation.
The ROSMAILS program produces:
1. A two-part report showing:
a. Names of library members that have been deleted because they
are unknown, and
b. Detailed information about each library member.
2. A Line Count Violation report that identifies, by sign-on key, those
users who have saved more lines in the library than are permitted
by site management.
■ User Profile Information:
The UPSLIST program produces a report that describes each user defined
to Advantage CA-Roscoe.
Note that all of the programs mentioned in this section are described in
the Advantage CA-Roscoe Interactive Environment Programs and Utilities Guide.

1.10 Exits
1.10 Exits
To obtain additional accounting information or for security purposes, sites may
want to take advantage of the exits that are provided with Advantage
CA-Roscoe. These exits are taken:
1. At Advantage CA-Roscoe initialization.

2. At sign-on.
3. Whenever a command is entered.
4. Whenever a Monitor command is entered. (In addition, many of the
Monitor commands have exit facilities to allow sites to provide extra
controls.)
5. Whenever a record is written to the accounting file.
6. Whenever a job is submitted.
7. Whenever there has been no I/O activity at a terminal for a site-specified
period of time.
8. At Advantage CA-Roscoe termination.
The exits are introduced in Chapter 21. For a detailed description of how to
write an exit routine, see the Advantage CA-Roscoe Interactive Environment
Extended Facilities for Systems Programmers Guide.

1.11 HELP and Interactive Training Aids
1.11 HELP and Interactive Training Aids

The Advantage CA-Roscoe includes several facilities that assist individuals in
using Advantage CA-Roscoe. These facilities, which can be used as distributed
or customized to meet site requirements, are:
1. The HELP facility, which contains descriptions of all commands available
with Advantage CA-Roscoe. This information can be displayed by the
terminal user through the HELP command. Sites can add to or modify the
descriptions to suit their needs. For information on maintaining and
customizing the HELP facility, see Chapter 16.
2. The TUTORIAL, which is a series of RPF programs that guide a user
through a simulated Advantage CA-Roscoe session at a 3270 1 type
terminal. It introduces most of the Advantage CA-Roscoe primary and line
commands and provides the user with the ability to execute these
commands in a controlled environment. The TUTORIAL is described in
Chapter 23.
3. The RPF TRAINING, which is a series of RPF programs that introduce the
user to the ROSCOE Programming Facility (RPF). This interactive
application describes an RPF command or facility and then tells the user to
use that command/facility. During the course of executing the application,
the user creates a working RPF program. The RPF TRAINING is described
in Chapter 22.

Chapter 2. File Requirements
This chapter describes the various files comprising Advantage CA-Roscoe,

their architecture, space requirements and specific maintenance requirements.
Advantage CA-Roscoe must be an authorized program. Information on how to

assign APF status to Advantage CA-Roscoe is contained in the member
| ROSAPF on ROSCOE.SAMPJCL.
Also, ensure that Advantage CA-Roscoe is defined with a protect key of 8 in

the Program Property Table (PPT). This can be done either explicitly or
implicitly. (If Advantage CA-Roscoe is not defined in the PPT, it is assigned
the default protect key of 8.) See the appropriate Job Management IBM
manual for additional information about the PPT.
Chapter 2. File Requirements 2-1

2.1 File Placement
2.1 File Placement

This section highlights the Advantage CA-Roscoe file requirements and
discusses the placement of the these files.
■ All Advantage CA-Roscoe data sets are cataloged during installation.
■ All Advantage CA-Roscoe data sets use a unique first level index.
ROSCOE is used in all discussions and examples in the Advantage
CA-Roscoe documentation, but this index is up to your discretion.
■ ROSCOE.ROSACTnn (the accounting files) should reside on system
residence volumes or on volumes chosen to be online when Advantage
CA-Roscoe is executing.
■ ROSCOE.RO60LIB (the Advantage CA-Roscoe target library) should reside
on a system residence volume.
■ The following data sets are high contention and high use. They should
reside on separate, permanently mounted volumes, if possible.
ROSCOE.SYSAWSP
ROSCOE.SYSAWS1
ROSCOE.SYSAWS2
...
ROSCOE.SYSAWSnn
ROSCOE.ROSLIB00
ROSCOE.ROSLIB01
ROSCOE.ROSLIB02
...
ROSCOE.ROSLIBnn
The AWS pointer file (ROSCOE.SYSAWSP) should not reside on the same
volumes as the AWS data files; the library index file (ROSCOE.ROSLIB00)
also should not reside on the same volumes as the library data files. It is
further recommended that the AWS pointer file and the library index file
| not reside on the same volume. The ROSLIB00 file must also not reside on
| the same volume as the JES3 BDAM communication file.
2.1.1 Sample Volume Layouts
Volume1 Volume2 Volume3 Volume4

Four Volume RO60LIB ROSLIB00 ROSACT01 SYSAWSP
Layout ROSACT00 SYSAWS1 ROSLIB01 ROSLIB02
Three RO60LIB ROSACT01 ROSAWSP
Volume ROSLIB00 ROSLIB01 ROSLIB02
Layout SYSAWS1
ROSACT00

2.2 Accounting Files (ROSACTnn)

Required DD Names: ROSACT00 through ROSACT09
Suggested Data Set Names: ROSCOE.ROSACT00 through
ROSCOE.ROSACT09
When the accounting facility is activated, records are written to internal

buffers. (This is done to minimize disk I/O. Two buffers are provided by
default. The number and size of the buffers can be set by an initialization
parameter.) When the current buffer is filled, Advantage CA-Roscoe
automatically: 1) directs subsequent records to the next buffer and 2) writes the
contents of the current buffer to the appropriate accounting file.
The Advantage CA-Roscoe accounting files are designated ROSACT00 through

ROSACT09. When multiple accounting files are used, they must be numbered
sequentially, starting with ROSACT00 and incremented by 1. The DD
statements can be specified in any order when included in the Advantage
CA-Roscoe JCL.
There is no relationship between the number of active users and the number of
accounting files needed. The number of accounting records written to the files
varies based on the activity of the individual users; the size of each file is left
to the discretion of the site.
When multiple files are used, Advantage CA-Roscoe treats them as an

integrated collection of independent files. During initialization, the files are
examined and each file is classified as being: Empty, Partially Full or Full.
■ If all of the files are empty:
Advantage CA-Roscoe begins writing accounting records to ROSACT00.
■ If the files are a combination of empty and partially full or empty, partially
full and full:
Advantage CA-Roscoe searches for the partially full file with the most
current date and begins writing records to that file.
■ If the files are a combination of empty and full:
Advantage CA-Roscoe searches for the empty file with the lowest number
in its DD name.
■ If all of the files are full:
A message is written to the console and user sign-ons are suspended. To
correct this situation, the owner of the RO prefix (who is still entitled to
sign-on) should execute the ACCTDUMP program to offload the
accounting files. Since user sign-ons are suspended, the owner of the RO
prefix must then either: 1) enable user sign-ons but with the accounting
facility disabled, or 2) use the ACCT ROSCOE ON command to enable the
accounting facility.

After initialization is completed, Advantage CA-Roscoe begins writing

accounting records to the internal buffers. When a buffer becomes full, its
contents are written to the active file. Note that Advantage CA-Roscoe causes
an end-of-file marker to be positioned to the end of the first block that is
written out. Thereafter, the end of file marker is repositioned either every five
minutes or after every five blocks are written, whichever occurs first. This is
done to prevent the loss of accounting records in the event of an abnormal
termination.
When that file becomes full, Advantage CA-Roscoe automatically switches to

the next sequentially numbered empty file. (If there is no empty file, a message
is issued and the accounting facility is terminated.) At the time Advantage
CA-Roscoe switches files, it does a look-ahead to the next sequentially
numbered file and issues a warning message if that file is not empty. This
process continues until Advantage CA-Roscoe is shutdown or all of the files
are filled.
If the last sequential file is filled during the current execution, Advantage
CA-Roscoe checks to see if the first file (ROSACT00) is still full. If it is, a
message is written to the console and accounting records are no longer written
to the Advantage CA-Roscoe files. (If SMF accounting is in effect, Advantage
CA-Roscoe accounting records will continue to be written to the SMF files.)
For example, assume a site defines three files, where:

1. ROSCOE.ROSACT00 is empty,
2. ROSCOE.ROSACT01 is full, and
3. ROSCOE.ROSACT02 is partially full.
Advantage CA-Roscoe will begin writing accounting records to the partially

full file (for example, ROSCOE.ROSACT02). The status of the next file
(ROSCOE.ROSACT00 in this case) is also checked to see if it is empty. When
ROSCOE.ROSACT02 becomes filled, Advantage CA-Roscoe automatically
transfers to ROSCOE.ROSACT00 since it is empty. Again, a look ahead is done
to determine the status of the next file. In this case, ROSCOE.ROSACT01 is
full so a message stating this fact is directed to the console. If
ROSCOE.ROSACT00 becomes full and ROSCOE.ROSACT01 remains full,
Advantage CA-Roscoe sends a message to the console and stops writing
accounting records.
The program ACCTDUMP can be executed at any time to copy the contents of
one or more accounting files to a holding file. (If one or more of the files are
empty or currently in use, they are ignored.) The information in the holding
file can then be passed to Advantage CA-Earl to produce the Advantage
CA-Roscoe accounting reports. Both programs and the reports they produce
are described in detail in the Advantage CA-Roscoe Interactive Environment
Programs and Utilities Guide.

2.2.1 File and Space Requirements

The following characteristics must be included in the ROSACTnn DD
statements:
DSORG PS is required.
LRECL The minimum length is 1020. The specified length must be
equal to the block size minus 4. For example if the block size
is 1024, then the logical record length must be specified as
1020.
RECFM VB (variable blocked) is required.
BLKSIZE The minimum block size is 1024.
The file block size must be compatible with the site-specified internal buffer
size since accounting records are written to these buffers. When a buffer is full,
it is then written to the accounting files. Therefore, the block size of the file
should be equal to or greater than the internal buffer size.
Note: The size of the internal buffer is controlled by the ACCTBUF=
initialization parameter, which is described in the Advantage CA-Roscoe
Interactive Environment Programs and Utilities Guide.
■ If the file block size is smaller than the internal buffer size, Advantage
CA-Roscoe opens the files with a block size that is equal to the buffer size.
■ If the file block size is greater than the internal buffer size and the files are
empty, Advantage CA-Roscoe opens the file with a block size that is equal
to the buffer size.
■ If the file block size is greater than the internal buffer size and the first file
is partially full, the file is opened with the larger block size. (Advantage
CA-Roscoe then adjusts the internal buffer size to be equal to the block
size.)
The Advantage CA-Roscoe installation procedure, by default, creates two

accounting files that use the default LRECL, RECFM and BLKSIZE mentioned
above. Ten cylinders are allocated for each data set. It is suggested that sites
use the installation values initially.
Actual experience is the best gauge for determining the amount of space
required per file. Before changing the allocation, sites should first determine
how often the ACCTDUMP program is to be executed. Obviously, the more
often this program is executed, the less space is required for each accounting
data set.

If it is determined that the allocation is to be increased or decreased, the site

should:
1. Use the following formula to estimate the number of accounting records

that are generated during an execution of Advantage CA-Roscoe:
(A * B) * (2 + C + D) + 2 = Number of Records
where:
A Average number of user sessions per hour.
B Number of hours per Advantage CA-Roscoe execution.
2 One user sign-on record and one sign-off record.
C Average number of Monitor commands executed per user session.
D Average number of site defined records per user session.
2 One AWS record and one system shutdown record.
To illustrate, assume 100 user sign-ons per hour, an execution time of 12
hours, 3 Monitor commands executed per user session and no user-defined
records:
(100 * 12) * (2 + 3 + 0) + 2 = 6002 records
2. Use the record block size to determine the number of records that can be
written to one track or cylinder.
3. Finally, calculate the total number of tracks or cylinders needed to hold the
estimated number of records.
The result can then be allocated to a single data set or spread over a maximum
of ten. Remember that the amount of space must be large enough to
accommodate all of the records that could be written to the accounting files
between executions of the ACCTDUMP program.
2.2.2 Maintenance
When any or all of the accounting files become full, they can be offloaded to a
holding file using the ACCTDUMP program. The dumping and clearing of the
accounting files can occur while Advantage CA-Roscoe is executing. Note that
if a file identified in the JCL is empty or is currently in use, the ACCTDUMP
program ignores the file. Thus, it is not necessary for a site to modify the JCL
(by adding or deleting DD statements) every time this program is executed.
(The ACCTDUMP program is described in the Advantage CA-Roscoe Interactive
Environment Programs and Utilities Guide.)

2.3 AWS Files (SYSAWSnn)

Required DD Names SYSAWSP and SYSAWS1 through SYSAWS16
Suggested Data Set Names ROSCOE.SYSAWSP and ROSCOE.SYSAWS1
through ROSCOE.SYSAWS16
The Active Work Space (AWS) is a system of at least two files which provides
each terminal user with a temporary work area. The AWS is used to hold a
number of records and perform additions, insertions, deletions and
modifications rapidly and efficiently. The AWS system consists of:
■ A pointer file (SYSAWSP) containing the indexes to the data file(s),
organizational criteria and SAVEAWS records.
■ At least one data file (SYSAWS1 through SYSAWS16) containing, at any
time during the ROSCOE execution, all of the editing work space assigned
for all terminals allocated to the system.
These files must be allocated on separate volumes (or channels, where

possible) and located centrally on the disk packs that exhibit low system
contention properties during ROSCOE operations. Online work packs or
operating system library packs are the most suitable. System residence and/or
spooling volumes are the least suitable.
| Since the pointer file (SYSAWSP) is usually less than one cylinder, it can be
| placed under a fixed head disk volume. This placement should improve
ROSCOE performance.
2.3.1 Structure of the AWS

The logical structure of the AWS exists as a three level tree: the master index,
the data index and the data itself. Between levels there can be a one-to-many
relationship of nodes. One buffer is held in memory for each level. The buffer
size is equal to the data block size plus 1.5 KB. Both the master and data index
blocks reside on the pointer file. The data blocks are kept on the data files.
2.3.2 AWS Cache Facility

MVS/ESA and MVS/XA sites (and non XA sites where main storage
constraints are not critical) can use the AWS Cache Facility to increase AWS
performance.
When the AWS Cache Facility is activated, an intermediate set of main storage
buffers is added between the internal buffer allocated to each user and the disk
storage where all data blocks for the user's AWS reside. This cache of buffers is
used to satisfy read requests for the data and thus bypass the physical disk
I/O normally required to perform such reads. The Cache's effectiveness varies
depending upon the amount of storage allocated for caching, the amount of

data comprising the user's AWS and the activity pattern of that AWS.
Frequently, a high percentage of reads can be satisfied with a fairly modest
amount of storage dedicated to caching.
Once activated, data is always written to both the cache and disk. (This
facilitates AWS recovery in the event an abnormal termination occurs.) When
data is to be retrieved, the cache is searched first. If the data is not found and
the Cache buffers are not full, the data blocks on disk are searched and data is
added to the Cache. If the Cache buffers are full, the data in the Cache that is
the oldest (for example, least recently referenced) is purged and its space is
reused for new (for example, currently active) data.
The AWS Cache Facility is activated through the AWSCACHE=initialization

parameter. This parameter is used to specify the amount of storage to be
acquired for this facility. (At ESA and XA sites, the storage is allocated above
the 16 MB line, as are the AWS primary buffers.) The amount that should be
allocated varies based upon the specifics for a given Advantage CA-Roscoe
configuration and use.
The following table lists some suggested starting points:
Number oOf Users AWSCACHE Specification

10-29 192 KB
30-49 384 KB
50-69 512 KB
70-99 1 MB
100-129 153 KB
over 130 2 MB
The AWS Monitor command can be used to tune the AWS Cache Facility.
Specifying AWS-M causes cache utilization statistics to be displayed. The
information shows the amount of storage allocated, the amount in use, the
amount allocated but currently unused, the number of reads, writes and read
hits and the read hit ratio. (The AWS Monitor command is described in the
Advantage CA-Roscoe Interactive Environment System Commands Guide .)
Sites can use these statistics to determine if the storage specified by the
AWSCACHE=initialization parameter needs to be changed. As a general rule,
sites should try to obtain a READ HIT ratio (the ratio of reads that were
satisfied from the cache to the total number of reads) of 95 percent or greater.
MVS/ESA and MVS/XA sites (especially those with extended storage) may be
less concerned with main storage constraints and try for a higher percentage.
Non XA site with more storage constraints may feel that a lower percentage,
70 percent for example, provides sufficient benefits to the overall performance
of the AWS without using an excessive amount of main storage.

2.3.3 Space Requirements

| The RPF program AWSSPACE (distributed on the ROSCOE.CONTROL
| account) can be used to determine the AWS space requirements. To execute
this program, enter:
EXEC AWSSPACE
The following screen sample illustrates the panel that is displayed. Note that
AWS space requirements are always calculated in blocks.

AWS Space Estimator
Enter the following information:
Data Block Size 256 Average Record Length 6

Number of AWS Files 1 Average Records/AWS 3
Number of AWS's 32 Maximum Records/AWS 1
Index Block Size (fixed) 512
The above configuration requires:
Data blocks/File 372

Index Blocks 322
Create sample FAWSDS JCL? N (Enter "Y" when configuration OK)
Press Enter to continue - any PF key to terminate

The variable information that can be tested through AWSSPACE is:
Data Block Size

Physical block size of the AWS data files. (The default block
size is 2560; the minimum is 1024, the maximum is the full
track capacity of the device.)
The ideal block size is 2560. If larger blocks are desired, they
should be in multiples of 4 KB greater than 2560, where 4 KB
is the size of a page. (The table below can be used to
determine the appropriate block size for a particular disk
drive to get the most efficient use of memory plus the
maximum number of blocks per track.)

| Ideal Block Size If Drive:

| SIZE 3330 3350 3380 3390 9345
| 2560 2498 2560 2484 2555 2555
| 6656 6447 6233 6356 6531 6531
| 10752 N/A N/A 9076 9797 9797
| 14848 N/A N/A 14848 14696 14696
| 18944 N/A 18944 18944 18944 18944
| Number of AWS Files

| Number of physical AWS data files. (The default number of
| files is 1; the maximum is 16.)
There should be one AWS data file for every 25 to 50 users. If
the data files are on high contention packs, allow more users
per file. If the files are on low-contention packs, allow fewer
users per file. Spreading AWS I/O over multiple packs
reduces arm contention between Advantage CA-Roscoe users.
The greater the number of users, the more advantageous it
becomes to have multiple data files, and vice versa.
The data files should not be on the same pack as the index
file. It is also counterproductive to have multiple data files on
the same pack.
Number of AWSs
Number of AWSs that could be needed when Advantage
CA-Roscoe is executing. (The default number of AWSs is 32;
the minimum is 2; the maximum is 2048.)
Average Record Length
Average length of the record in the data files. It is usually 50
to 60 bytes.
Average Records/AWS
Average number of records allowed for each user's AWS. (The
default size is 32000; the minimum is 100; the maximum is
32000.)
The results of the calculations performed by the AWSSPACE program are:

Data blocks/File The number of blocks required for each data file. (With
multiple data files, the number of blocks is divided by the
number of files.)
A maximum of 32,767 data blocks can be allocated per file.
If the calculation shows this value is exceeded, a message is
displayed advising: 1) increasing the number of data files,

or 2) increasing the data block size if 16 files are currently in

use.
Index Blocks The number of blocks required for the index file.
After determining the number and size of the data files, use the FAWSDS
program (described in the Advantage CA-Roscoe Interactive Environment Programs
and Utilities Guide) to format the AWS file. The space for these files can be
allocated before or during the execution of FAWSDS.
2.3.4 Determining the Appropriate Number of AWSs

Sites can control:
■ The number of AWSs an individual may use.
The AWSLIM= initialization parameter (described in the Advantage
CA-Roscoe Interactive Environment Programs and Utilities Guide establishes
the maximum number of AWSs an individual may use during an
Advantage CA-Roscoe session. For example, if AWSLIM=5 is specified,
each Advantage CA-Roscoe user can have a maximum of five AWSs
concurrently active.
■ The total number of AWSs available.
Since users and some Advantage CA-Roscoe facilities can use multiple
AWSs, there is no formula available to calculate the total number of AWSs
a site will need.
Suggestion: As an initial value, set the number of AWSs (specified with the
AWSSPACE RPF program and the FAWSDS program) to three times the
value specified with the TERMSO= initialization parameter. (TERMSO=,
described in the Advantage CA-Roscoe Interactive Environment Programs and
Utilities Guide, establishes the maximum number of concurrent subsessions
that can be active.) Then use the AWS command (described in the
Advantage CA-Roscoe Interactive Environment System Commands Guide) to
monitor the number of AWSs that are actually used. After determining the
activity at the site, adjust the number of AWSs as needed.
2.3.5 Recovery Procedures

AWS recovery processing occurs:
■ Under the control of Advantage CA-Roscoe if the user signs off or if a
session failure occurs and one or more AWSs contain data.
■ By the SAVEAWS program when an Advantage CA-Roscoe or system
failure occurs.
Note: See the Advantage CA-Roscoe Interactive Environment Programs and
Utilities Guide for a description of the SAVEAWS program.

Data found in an AWS that has a recoverable attribute is saved in the

Advantage CA-Roscoe library as the member SAVAWSnn (where nn is a
unique identifier). One SAVAWSnn member is created for each user whose
recoverable AWSs contained data. In addition to a time and date stamp, each
member is identified by the ROSID assigned to the Advantage CA-Roscoe that
the user was signed on to. If there are any prior SAVAWSnn members that
match the Advantage CA-Roscoe ROSID, those members are usually deleted
when the new members are created. (This is done so that SAVAWSnn
members are treated individually at sites that are running multiple Advantage
CA-Roscoes and sharing a single Advantage CA-Roscoe library.)
2.3.6 Maintenance
The programs to maintain the AWS are:
FAWSDS Formats/reformats the AWS index and data files.
SAVEAWS Permits recovery of user AWSs when Advantage CA-Roscoe is
shut down. SAVEAWS can be run either during Advantage
CA-Roscoe initialization or stand-alone.

2.4 Library Files (ROSLIBnn)

Required DD Names: ROSLIB00 through ROSLIB99
Suggested Data Set Names: ROSCOE.ROSLIB00 through
ROSCOE.ROSLIB99
The user libraries are a set of at least three files consisting of:
■ An index file (ROSLIB00) containing control information on the location of
user library members within the system and data on available space for
writing new members. Also, the first block of ROSLIB00 contains the
Advantage CA-Roscoe universal password. (This is done for security
purposes so that the parameter establishing the password need not be
included in the Advantage CA-Roscoe initialization member for every
execution.)
■ Online files (ROSLIB01 through ROSLIB99). ROSLIB01 and ROSLIB02 are
required. They must be sequentially numbered, starting with ROSLIB01
and incrementing by 1. (It is not necessary, however, that the DD
statements be in sequential order when specified within the Advantage
CA-Roscoe JCL.)
There is no relation between the number of active users (terminals) and the
number of libraries allocated. The libraries are shared concurrently by all active
users of the system.
The user libraries are a single system rather than a collection of independent
files. They are treated by all Advantage CA-Roscoe components as a single file
and must always be handled in backup/restore operations as a single file.
The library organization provides optimum throughput for online usage, and
is characterized by: compression of records (any sequence of three or more
blanks is compressed); rapid location and retrieval of user library members (to
locate any user's members requires no more than two disk accesses); and
immediately available reuse of space freed by an update or deletion.
The user libraries have identical characteristics and differ only in space
allocations.
| All library files must be defined as direct-access (DSORG=DA) and must have
| the same block size. The minimum block size is 536 bytes, the maximum is the
| track size of the device in use. The track size must always be a multiple of 8
| bytes. A file can have a maximum of 32 KB blocks. Specifying an invalid
block size results in an abend during initialization (for example, the formatting
run).

2.4.1 Library Cache Facility

Sites have the option of activating a Library Cache Facility. When this facility
is activated, an intermediate set of main storage buffers are used to bypass
physical I/O for certain types of read operations and thus improve
performance. This facility is intended to:
■ Improve RPF performance by eliminating the I/O bottlenecks that can
occur due to the single buffering of RPF data blocks.
■ Maintain the master index library blocks in storage and thus decrease the
amount of time required to access library members.
The Library Cache Facility is activated through the LIBCACHE initialization

parameter. This parameter is used to specify the amount of storage to be
acquired for this facility. (At ESA and XA sites, the storage is allocated above
the 16MB line.) The amount that should be allocated varies based upon the
specifics for a given Advantage CA-Roscoe configuration and use. A suggested
starting value is LIBCACHE=1024K. (The LIBCACHE parameter is described in
the Advantage CA-Roscoe Interactive Environment Programs and Utilities Guide.)
Sites should then use the information provided by the LIBCACHE command
to determine if the storage amount specified with the LIBCACHE initialization
parameter needs to be changed. (The LIBCACHE command may be used to: 1)
display cache statistics, 2) enable and disable the cache, and 3) purge the cache
of all data. For additional information about this command, see the Advantage
CA-Roscoe Interactive Environment System Commands Guide.)
As a general rule, sites should try to obtain a READ HIT ratio (the ratio of
reads that were satisfied from the cache to the total number of reads) of 75
percent or greater. MVS/ESA and MVS/XA sites (especially those with
extended storage) may be less concerned with main storage constraints and try
for a higher percentage. Non-XA site with more storage constraints may feel
that a lower percentage, 60 percent for example, provides sufficient benefits to
the overall performance of the library without using an excessive amount of
main storage.
2.4.2 Space Requirements

Space requirements fall into two separate categories:
■ Requirements for the index file (ROSLIB00).
■ Requirements for the online files (ROSLIB01 through ROSLIB99).
Prior to computing any space requirements, it is necessary to determine the

necessary library block size. A value of 2560 bytes is recommended. Sites may
wish to increase this block size to speed up backup/restore operations and to
reduce the Advantage CA-Roscoe I/O to the library system. But, increasing the
library block size results in increased memory usage, since each potential,
simultaneous user requires a buffer equal in size to the library block size. A

large block size may also result in more unused space within data blocks
because small library members still require at least one block.
Note that the same block size must be used for computing space requirements
for both the index and online files.
2.4.2.1 Index File
The space requirements for the index file are a function of the number of user
library members to be kept in the system. Use the following formula to
determine the approximate number of blocks required:
Number of blocks = 20 + N / (R + 1)
where:
N Number of members to be kept in the libraries.
R Number of records that can fit in a block and is determined by using
the following formula:
Number of records = (blksize - 20) / 140 (Ignore any remainder.)
2.4.2.2 Notes
1. When the libraries are restored, the index blocks on ROSLIB00 are half
filled. This allows for the addition of new index entries (for example, new
library members) without incurring excess overhead. When the addition of
a new index entry causes an index block overflow, a block split occurs.
2. In the event that insufficient space is allocated for the index file, the
libraries can be restored from a backup file with more space specified for
the index file.
2.4.2.3 Online Files
The number of blocks required for the online files can be calculated by using
the formula:
Number of blocks per file = (A / R) / N (Ignore remainder from directory)
where:
A Estimated number of records in the online files.
R Number of records that fit in a block. R is determined by using the
following formula:
Number of records = (blksize - 8) / 40
The value of 40 assumes that a typical record, after compression, takes
about 40 bytes (including a record overhead of 6 bytes). See Note 1,
below.

N Number of online files. At least two online files must always be

provided. Additional online files may optionally be provided. See
Note 2, below.
2.4.2.4 Notes
1. Experience has shown the value of 40 to be realistic for most sites as an

initial estimate. If actual experience should prove that value to be
inaccurate, the libraries can be restored from a backup file with more space
specified for the online files.
2. If two data channels are available, it may be advantageous to use three
online libraries to get maximum benefit of I/O overlap. However, pack
and channel separation between the online library and the AWS files are of
greater importance to achieve satisfactory throughput (terminal response
time). Using many libraries on different disk packs could possibly
improve efficiency by reducing head movement, but the I/O requirements
of other tasks in the CPU could negate any such advantage.
2.4.3 Shared Libraries

Multiple Advantage CA-Roscoe systems can access a single, common user
library system.
Since the user sign-on keys are defined in the UPS account of the Advantage
CA-Roscoe libraries, the same user sign-on key can be active on multiple
Advantage CA-Roscoes simultaneously and can access and update all members
belonging to that user.
2.4.4 Maintenance
2.4.4.1 Backing Up the User Libraries
To ensure the integrity of the backup operation, Advantage CA-Roscoe must

either be shut down or quiesced during a backup execution.
ATTENTION
THE CA-ROSCOE LIBRARIES SHOULD BE BACKED UP DAILY.
THE LIBRARIES MUST ALWAYS BE HANDLED IN BACKUP AND

RESTORE OPERATIONS AS A SINGLE FILE.
The programs LIBUTIL and LIBBKUP produce a backup file that is logically
independent of the separate physical files and that represents the state of the
library system at the time of backup.

Depending on a site's needs, one of the following backup procedures should

be adopted:
1. Use the LIBUTIL program to take a full backup nightly or on a very
frequent basis.
2. Use the LIBBKUP program to take a full backup on a weekly basis and
then partial backups daily. (The partial backup only writes library
members that have been saved or updated since the last successful
backup.)
Both the LIBUTIL and LIBBKUP programs are described in the Advantage
CA-Roscoe Interactive Environment Programs and Utilities Guide.
2.4.4.2 Restoring the User Libraries
The LIBUTIL program must be used to restore the libraries from a backup file
created by either LIBUTIL or LIBBKUP. The types of restores that can be done
include:
■ Full Restore from Full Backup Files
Use the RESTORE option of the LIBUTIL program. The backup file(s) may
have been created by either the LIBUTIL or LIBBKUP program.
■ Full Restore from Full and Partial Backup Files
Use the most current full backup file and do a full restore using the
RESTORE option of LIBUTIL.
Follow the full restore with a series of partial restores using all of the
partial backup files created since the last full backup. (The partial restores
must be run in chronological order using LIBUTIL with the RESTORE and
NOCLEAR options.) For example, assume that a full backup is taken at
midnight every Sunday and that a partial backup is taken nightly.
Further, assume that the Advantage CA-Roscoe libraries become
contaminated on Wednesday, and it is necessary to restore them to their
condition as of Tuesday night. The steps to restore the libraries are:
1. Using the last full backup file, execute LIBUTIL with the option
RESTORE or RESTORE,NOFORMAT. This restores the entire libraries
to their condition as of Sunday night.
2. Using the oldest partial backup file, execute LIBUTIL with the
RESTORE,NOCLEAR option. This restores the library members saved
or updated on Monday.
3. Using the next oldest partial backup file, execute LIBUTIL with the
RESTORE,NOCLEAR option. This restores the library members saved
or updated on Tuesday.
The libraries are now restored to their condition as of Tuesday night. Note:
Library members deleted on Wednesday will reappear in the libraries;
members added on Wednesday will not appear; changes made to members
on Wednesday also will not appear.

2.4.4.3 Selective Backups and Restores
There may be occasions when specific library members need to be backed up

or restored.
■ Backing Up Specific Members
Either the LIBBKUP or LIBUTIL program can be used to backup one or
more specific library members.
■ Backing Up User Keys
The LIBUTIL program can be used to backup the library members
belonging to one or more specific Advantage CA-Roscoe sign-on keys.
■ Restoring Library Members
Options of the LIBUTIL program permit sites to restore: 1) one or more
specific library members; 2) all members belonging to one or more sign-on
keys, or 3) all members belonging to one or more user prefixes.
A dump/restore (D/R) program such as IEHDASDR can only satisfy the

backup/restore requirements under the following conditions:
■ The D/R dump of the ROSLIBnn files were all made at the same time and
no user library members were added to or deleted from the libraries at
that time.
■ The D/R dump of the ROSLIBnn files are all restored at the same time
(that is, ROSLIB01 cannot be restored independently of ROSLIB00 and
ROSLIB02, and so on.).
■ The libraries are known to have been internally valid at the time the D/R
dump was taken.
■ The D/R restore is being performed because of physical damage to the
original disk packs from which the libraries were dumped, or a new pack
is being formatted to replace the old disk pack.
If any of the above conditions cannot be satisfied, use of a D/R program will
result in an invalid library system, with unpredictable results in the operation
of the online system and the integrity of the user data stored on the libraries.
| LIBBKUP and LIBUTIL are the preferred utilities for maintaining the
| Advantage CA-Roscoe libraries.

Since the data in the libraries is stored in compressed format to save space, the
IBM utilities cannot be used to copy from or to OS data sets. The following
batch programs can be used for the movement of data between the Advantage
CA-Roscoe libraries and external data sets:
ROSCOPY Writes one or more library members to an OS data set.
ROSDATA Creates one or more library members from batch input.
Additional programs include:

LIBSERVE Performs maintenance on the Advantage CA-Roscoe libraries
in batch. It can be used to rename and delete library members,
obtain library listings and scan members for a specific
character string.
ROSMAILS Produces a listing of each user's library members (sorted by
sign-on key), and optionally deletes members belonging to
specific sign-on accounts.
ROSTAT Produces statistics on library usage.
All of these programs are described in the Advantage CA-Roscoe Interactive

Environment Programs and Utilities Guide.
For the convenience of sites wishing to add additional library maintenance

routines, a variety of user interfaces to the library I/O modules are described
in the Advantage CA-Roscoe Interactive Environment Extended Facilities for System
Programmers Guide.

Chapter 3. Maintenance
Each site should select an individual to be the Advantage CA-Roscoe

Operations Manager. This individual should be responsible for scheduling
offline operations, and determining and publicizing the times when Advantage
CA-Roscoe is running. The person should also act as an interface with the
operators and system programmers as to current and future requirements.
Additionally, that individual should be the only person to contact CA
Technical Support.
Chapter 3. Maintenance 3-1

3.1 Scheduling
3.1 Scheduling
It is anticipated that Advantage CA-Roscoe will be most heavily used during
the day when the programmers are on site. A typical schedule is 8 a.m. to
midnight, seven days per week, with the down time in the middle of the night
for library backup and maintenance. Any temporary suspension of Advantage
CA-Roscoe services or erratic scheduling of running times may seriously
inconvenience users.
The startup time for Advantage CA-Roscoe is approximately 2 to 5 minutes.

The job is initiated by reading in the Advantage CA-Roscoe JCL deck through
a card reader or starting an Advantage CA-Roscoe procedure from the
operator console. (The Advantage CA-Roscoe job requirements are described in
the Advantage CA-Roscoe Interactive Environment Programs and Utilities Guide.)
Shutdown takes less than 1 minute. For scheduled shutdowns, the operator
should broadcast a message to all users 10 to 15 minutes before the shutdown
occurs.
Startup and shutdown can take place while other jobs are in execution.

3.2 Maintenance Procedures

This section summarizes the maintenance procedures that should be followed
to ensure the successful operation of Advantage CA-Roscoe. (All of the
programs mentioned here are described in detail in the Advantage CA-Roscoe
Interactive Environment Programs and Utilities Guide.)
3.2.1 Daily
Sites should perform the following tasks on a daily basis:
■ Backup the User Libraries
Sites can use either the LIBUTIL or LIBBKUP program to do a full, partial
or selective backup of the user libraries.
Advantage CA-Roscoe should either be shut down or quiesced when the
libraries are backed up.
See the section 'Library Files' for specific information about backing up and
restoring the libraries. If the backup schedule presented in that section is
followed, then each backup tape should be retained for a minimum of one
week before recycling.
■ Monitor Online Resource Usage
The ROSTAT program produces a report showing:
1. Statistics on the amount of space being used in the Advantage
CA-Roscoe libraries,
2. Current values of the Advantage CA-Roscoe initialization parameters,
3. Current AWS configuration.
This report is particularly useful in monitoring library usage. It contains
statistics on total space used, number of blocks used, number of dead
blocks and number of library members. This information can be used as a
planning aid to determine the need for modification to the configuration of
the library system.
■ Verify User's AWS Data is Saved
If a user's session did not terminate normally, as when an unscheduled
Advantage CA-Roscoe shutdown occurs, the user's AWS data may not be
automatically saved. The SAVEAWS program ensures that the data is
saved in the appropriate member(s) of the user libraries. The SAVEAWS
program should be executed either prior to or as part of Advantage
CA-Roscoe initialization.
■ Dump Accounting Information to a Holding File
When accounting information is desired, the records are written to the
ROSACTnn files. The ACCTDUMP program copies the accounting

information to a holding file and then clears the files (ready them for
additional information).
The ACCTDUMP program can be run when Advantage CA-Roscoe is
executing.
3.2.2 Weekly (or as Required)

The following procedures should be performed on an as needed basis:
■ Perform Offline Library Member Maintenance
The LIBSERVE program can be used to rename and delete specific library
members, produce a library index or listing of members, and do a global
scan for particular character strings.
■ Reformat the AWS/User Libraries
The FAWSDS program can be used to reallocate the AWS data sets as
needed.
The LIBUTIL program can be used to reformat the user libraries. Another
option of LIBUTIL permits a new data file to be formatted (and the index
file modified) while Advantage CA-Roscoe is executing. Thus, the new file
can be used as soon as the new ROSLIBnn DD statement is added to the
Advantage CA-Roscoe JCL.
■ Produce Accounting, Statistical and Usage Reports
Advantage CA-Earl can be used to produce accounting reports that
provide detailed information about Advantage CA-Roscoe usage, Monitor
command and ETSO usage, AWS statistics, Response Time Monitor
statistics and RPS PRINT command usage.
The ROSMAILS program provides the: 1) ROSMAILS report which is an
index of all library members by sign-on key, and 2) Line Count Violation
Report, which identifies those individuals who have exceeded the
maximum number of lines they can save in the library. ROSMAILS can
also be used to delete library members that are unowned or belong to
specified sign-on keys.
The UPSLIST program produces a listing of the user profiles sorted by
informal key, formal key or prefix.

3.3 Operator/Privileged Controls
3.3 Operator/Privileged Controls

Advantage CA-Roscoe provides facilities that allow the console operator and
individuals assigned privileged user IDs to:
■ Send messages to one or more Advantage CA-Roscoe users.
■ Request status information about lines, terminals and Advantage
CA-Roscoe spool volumes.
■ Control a user's ability to sign-on to Advantage CA-Roscoe, submit jobs
and send messages to the operator.
■ Shut Advantage CA-Roscoe down.
The operator communicates with Advantage CA-Roscoe by the operating

system MODIFY and STOP commands. Privileged users communicate with
Advantage CA-Roscoe through the OPERATOR commnd. These commands
are described in the Advantage CA-Roscoe Interactive Environment System
Commands Guide.
3.3.1 Messages
The operator console is the primary Advantage CA-Roscoe control console.
Messages written to the console include:
■ Information about users signing on and off, terminals being connected and
disconnected, and jobs submitted for background execution.
Sites that do not want these messages written to the operator console can
specify the initialization parameter ROSLOG=OFF. (These messages are
also written to the SYSLOG and JOBLOG. The ROSLOG= initialization
parameter has no affect on SYSLOG and JOBLOG.)
Note: 1. See the Advantage CA-Roscoe Interactive Environment Programs and
Utilities Guide for a description of all Advantage CA-Roscoe
initialization parameters.
2. Advantage CA-Roscoe handles WTO messages subject to
ROSLOG=OFF by setting the MCS flags parameter to 'hard copy
only.' Sites using WTO exits should be careful that their exits do
not override the MCS flags parameter setting for these messages,
thus ensuring that they will be directed to only hard copy devices.
■ Messages from individual Advantage CA-Roscoe users. (An Operator
command, described in the Advantage CA-Roscoe Interactive Environment
System Commands Guide, allows the operator to deactivate this facility.)
■ Advantage CA-Roscoe error conditions and warning messages. (These
messages are described in the Advantage CA-Roscoe Interactive Environment
Messages and Codes Guide. Their descriptions can also be displayed through
the online Help Facility.)

3.4 Site Sign-on Messages and Program

Site management can send messages to Advantage CA-Roscoe users at any
time. Messages can be directed to:
■ The Advantage CA-Roscoe Sign-on Screen
Sites can use the initialization parameter SONMSG to display a 1-59
character message on the Advantage CA-Roscoe sign-on screen. (See the
Advantage CA-Roscoe Interactive Environment Programs and Utilities Guide for
a detailed description of all Advantage CA-Roscoe initialization
parameters.)
■ The Advantage CA-Roscoe Screen Immediately Following Sign-on
If the message is fairly short, sites can use the SEND initialization
parameter to display a 1-64 character message at the terminal as soon as a
user successfully signs on.
For longer messages, sites can use the automatic newsletter facility. With
this facility, the contents of a special library member is automatically
displayed immediately after a user signs on.
3.4.1 Maintaining the Newsletter

By default, the newsletter is kept in the member RO.HELLO. (Sites can use
the HELLO= initialization parameter to designate both a different prefix and
library member name.)
The newsletter may be used to provide information directly and to instruct the
user to invoke an RPF program for daily or additional news. For example, the
contents of the member containing the newsletter may look like:
For CA-Roscoe information ---- EXEC RO.NEWS (June 26)
In this example, the program RO.NEWS will provide whatever information the
site wants. It is suggested that information be provided in a cumulative form
so that the user need not receive all of the previously viewed news. The
following example illustrates one way to do this.
<<NEWS>>
WRITE 'The new WIDGET command is now available. For a'
WRITE 'description of this command, type HELP WIDGET'
WRITE 'Enter GO or STOP.'
PAUSE : allow user to stop or continue
WRITE 'The following news was posted June 9, GO OR STOP'
PAUSE
LIST RO.NEWS2
WRITE 'The following new was posted May 2, GO OR STOP'
PAUSE
LIST RO.NEWS1
WRITE ' '
WRITE 'End of Report...'

3.4.2 Global Sign-on Program

Sites also have the option of establishing a global sign-on RPF program that is
executed every time a user signs on to Advantage CA-Roscoe. To enable a site
sign-on program, the name of the member containing the program must be
specified with the ONRPF initialization parameter. If a site sign-on procedure
is defined to Advantage CA-Roscoe, it is executed after the site sign-on
message is displayed and before the user's own sign-on procedure.
For information about writing an RPF program, see the Advantage CA-Roscoe
Interactive Environment RPF Language Guide.
3.4.3 Execution Hierarchy

The sign-on message/program execution hierarchy is:
1. Site newsletter.
2. Site sign-on program.
■ If this program contains an untrapped error, a message is displayed
and the user's sign-on program is invoked.
■ If this program contains the OFF command, the current setting of the
OFF initialization parameter designates whether or not the command
will be recognized.
Note: Sites with restricted users should see the 'Restricted Profiles'
chapter.
3. User sign-on program.

3.5 Site Signoff Program
3.5 Site Signoff Program

|
| Sites have the option of establishing a global signoff RPF program that is
| executed when a signoff is initiated using:
| ■ OFF command
| ■ OFFON command
| ■ OFF option entered on TLOCK screen
| ■ AUTOFF
| To enable a site signoff program, the name of the member containing the
| program must be specified with the OFFRPF initialization parameter.
| The parameters passed to the global signoff program depend on how the
| signoff was initiated:
| ■ OFF command. Two parameters passed. First parameter is OFF, second
| paramter is the options user specified on the OFF command.
| ■ ONOFF command. Two parameters passed. First parameter is OFFON,
| second parameter is the options user specified on the OFFON command.
| ■ OFF option entered on TLOCK. One parameter passed, TLOCK.
| ■ User auto offed. One parameter, AUTOFF.
| For information about writing an RPF program, see the Advantage CA-Roscoe
| Interactive Environment RPF Language Guide.
| Notes: The global signoff program must contain an OFF or OFFON command
| to complete the signoff process.

Chapter 4. User Profile System (UPS)
The User Profile System (UPS) contains information about each individual that
a site permits to use Advantage CA-Roscoe.
This chapter describes:

■ The members comprising UPS.
■ How to create and maintain user profiles.
■ Profiles that are created during Advantage CA-Roscoe installation, have
special privileges or are reserved.
■ How to create a restricted Advantage CA-Roscoe user.
■ How to create and use security groups.
Chapter 4. User Profile System (UPS) 4-1

4.1 UPS Member Components

UPS is created during the installation of Advantage CA-Roscoe as part of the
Advantage CA-Roscoe user libraries. At the time it is created, a number of
members are added to UPS. These members include:
■ pfx (individual profiles)
Note: UPS itself is one of the profiles. See the section 'Distributed User
Profiles' for a description of all the profiles added to UPS during
installation.
Each profile is identified by the prefix and sign-on key assigned to the
profile. The prefix is used as the name of the library member containing
the profile information. The sign-on key is used as the member description.
(The sign-on key and, if specified, the password are scrambled and may
contain non printable characters.) The profile information includes:
– User and formal sign-on keys.
The user sign-on key is required. The user must enter it when signing
on to Advantage CA-Roscoe. The formal key is optional. If one is
specified, it is used to identify the user in the accounting reports
produced by Advantage CA-Roscoe.
– User prefix.
A 2- or 3-character prefix is required. Advantage CA-Roscoe
automatically associates the user's prefix with his library members,
thus ensuring unique library member names.
– Sign-on password.
A sign-on password is optional. If a user has a password, the user
must enter it to gain access to Advantage CA-Roscoe.
– Sign-on procedure name.
A sign-on procedure is optional. If a user has a sign-on procedure, it is
executed as soon as the user gains access to Advantage CA-Roscoe.
– Library line limit.
A line limit is optional. It establishes the maximum number of lines the
user can save in the library.
When an individual's profile is displayed (using UPSMNTnn), the
panel includes the current number of lines the user has saved in the
library. This value is not accurate when:
1. Library members are deleted by the LIBSERVE program or added
by the ROSDATA program.
2. A system crash occurs while the user is signed on.

Use the ROSMAILS program to produce a line count violation report

listing those users whose current count exceeds the maximum.
(LIBSERVE, ROSDATA and ROSMAILS are described in the Advantage
CA-Roscoe Interactive Environment Programs and Utilities Guide.)
– Access restriction. Sites have the option of controlling a user's access
to Advantage CA-Roscoe commands and facilities.
– Security group name. Security groups are optional. If a site establishes
such groups, each group designates the library member access
authority allowed to individuals within the group and to individuals
assigned to other groups.
Each user profile also includes a field for the Protect Code. Protect
Codes have no meaning to sites running Advantage CA-Roscoe
Velease 5.3 or later. It is provided for compatibility with earlier
releases of Advantage CA-Roscoe. All new profiles are assigned a
protect code of 1.
■ GROUPS
This member contains the site defined list of security groups which are
used to control read/write library member access. (See the section
'Security Groups' for additional information.) Do not change the name of
this member.
■ KEYTABLE
Do not change the name of this member.
During Advantage CA-Roscoe initialization, UPS is searched for the
member KEYTABLE.
If KEYTABLE is found and is current, it is used to create a memory
resident table.
If KEYTABLE is not found or is not current, both the member and the
memory resident table are created.
KEYTABLE and the memory resident table contain an alphabetical list, by
prefix, of each user's sign-on key and security group. The memory resident
table is used by Advantage CA-Roscoe to quickly determine library
member ownership and accessibility.
When user profile maintenance is performed (through UPSMNTnn or
UPSBLKnn), the changes are applied to the appropriate UPS profile and
the memory resident table; the member KEYTABLE is marked as changed.
At any time during an execution of Advantage CA-Roscoe, the REFRESH
UPS command can be used to rebuild the memory-resident table and the
KEYTABLE member with the most current UPS information.
Note: REFRESH UPS is described in the Advantage CA-Roscoe Interactive
Environment System Commands Guide.
At sites running multiple Advantage CA-Roscoes and sharing the user
libraries, each Advantage CA-Roscoe has its own memory-resident table

while sharing the KEYTABLE member. Since the REFRESH UPS command
rebuilds the memory-resident table and the member KEYTABLE, the
Advantage CA-Roscoe from which the command is issued is now aware of
UPS changes made through other Advantage CA-Roscoes.
■ UPSMNTnn and UPSBLKnn (where 'nn' is a two-digit version identifier)
These members contain RPF programs that are used to create and maintain
user profiles. (See the section 'Creating and Maintaining User Profiles' for
additional information.) The names of these two members may be
changed.

4.2 Creating and Maintaining User Profiles
4.2 Creating and Maintaining User Profiles

Any individual who is to be permitted to use Advantage CA-Roscoe must be
identified by a profile in the User Profile System. Two RPF programs are
provided to create and maintain these profiles. They are:
UPSMNTnn To create/maintain one profile at a time.
UPSBLKnn To create/maintain one or more profiles at a time.
where 'nn' is a two-digit version identifier. (This naming convention allows

multiple versions of these programs to be used at sites executing different
levels of Advantage CA-Roscoe.)
To execute these programs, the individual responsible for creating and

maintaining the site's user profiles must sign-on to UPS using the UPS sign-on
key and then enter the appropriate RPF program name.
4.2.1 Notes
■ If a user is signed on when his or her profile is updated, the changes are
not applied.
■ Since UPS is part of the Advantage CA-Roscoe user libraries:
– The profiles are backed up every time the libraries are backed up.
– The LIBUTIL program can be used to restore any user profile that is
inadvertently deleted.

4.3 Executing UPSMNTnn

To execute the RPF program that lets you create or maintain a profile, sign-on
to Advantage CA-Roscoe using the UPS sign-on key and enter:
(UPS.) UPSMNTnn
where (UPS.) is the UPS prefix (required when doing maintenance from an
account other then the UPS account), and 'nn' is a two digit version identifier.
This RPF program consists of two panels. The initial panel, shown below,
prompts the user to perform one of three UPS actions.
Executing UPSMNTnn

R O S C O E U S E R P R O F I L I N G S Y S T E M
ENTER SELECTION: _
1. ADD A NEW PROFILE

2. UPDATE AN EXISTING PROFILE
3. DELETE AN EXISTING PROFILE
FOR ADD: ENTER PROTOTYPE KEY OR PFX (IF DESIRED)

FOR UPDATE: ENTER KEY OR PFX TO BE UPDATED
FOR DELETE: ENTER KEY OR PFX TO BE DELETED
KEY: ______________________
PFX: ___
FKEY: ______________________
PF3/PF15 TO END

The UPS actions are:
1. ADD A NEW PROFILE
2. UPDATE AN EXISTING PROFILE
3. DELETE AN EXISTING PROFILE
These actions are described in detail on the following pages.
Specify either the user's prefix or key. The first entry specified is used by UPS.
The formal key is provided for verification purposes; this field is not
modifiable.

4.3.1 1. Add a New Profile

Type the number 1 in the field ENTER SELECTION and press the Enter key.
The panel shown below will appear. To add a new profile, type the
appropriate information in each field and press Enter. The profile is added to
UPS.
Note that if the information about the new profile is similar to that of an
existing profile, type the sign-on key of the existing user in the KEY field of
the first panel. The resulting display will contain the profile information for the
designated user. Change the appropriate information and press the Enter key.
Add/Update User Profile Panel
C A - R O S C O E U S E R P R O F I L I N G S Y S T E M

PROTOTYPE KEY: __________1___________ MODE: ___2__
USER KEY: ______________________ 3

PREFIX: ___ 4
FORMAL KEY: ______________________ 5
7 8
PASSWORD: ____6_____ PASSWORD REQUIRED (Y/N): _ ABLE TO CHANGE
MAXIMUM LINES USER CAN SAVE: ___9____ CURRENT LINES SAVEDl
11SIGNON PROCEDURE: ___________ ABLE TO CHANGE (Y/N): _ 1

13RESTRICTED USER (Y/N): _
14USER ABLE TO USE PRIVILEGED COMMANDS (Y/N):

| OPER: _ RPS: _ ACCT: _ ETSO: _ LIB: _
15LIBRARY SECURITY GROUP : ________
16MORE PROFILES TO ADD/UPDATE (Y/N): _
PF1/13 BYPASS UPDATE PF3/15 TERMINATE UPSMAINT

4.3.2 2. Update an Existing Profile

Type the number 2 in the ENTER SELECTION field and the user's sign-on key
in the KEY field, or the prefix in the PFX field. After pressing Enter, a panel
containing the user's profile information (as shown above) will appear. To
update the profile, change the appropriate fields and press the Enter key.
4.3.3 3. Delete an Existing Profile

Type the number 3 in the ENTER SELECTION field. Then type the sign-on key
of the profile in the field KEY, or the prefix in the PFX field. After you press
Enter, a message appears to confirm deletion. No other panel is necessary for
the delete operation.

4.3.3.1 Notes
When updating or deleting a profile, UPSMNTnn uses the ROS Monitor

routine to determine if the user associated with the designated profile is
currently signed on to the Advantage CA-Roscoe under which UPSMNTnn is
executing.
■ If the ROS Monitor is available and the user is signed on, the person
executing UPSMNTnn receives a warning message that includes the option
of continuing or cancelling the operation. (No message is issued if the
user is not signed on.)
■ If the ROS Monitor is not available, the person executing UPSMNTnn
receives a warning message noting that the user may be signed on and is
again provided with the option of continuing or cancelling.
If the user is signed on and the UPS operation is:

Update The modifications may not be applied to the profile.
Delete The profile is deleted. The cancellation option lets the person
executing UPSMNTnn to reconsider this action. For example, if
the profile is supposed to be inactive, the person executing
UPSMNTnn may want to find out who is signed on under that
profile before deleting it.
The remainder of this section describes the fields on page 4-7 that are
displayed when adding or updating profiles.
1 PROTOTYPE KEY: Non-modifiable. Contains the key of an existing
user is to use as a model for a new profile.
2 MODE: Non-modifiable. It will contain the word UPDATE or ADD,
according to the action performed.
3 USER KEY: Specify a unique sign-on key not exceeding 22 characters
| in length. After the profile has been added to UPS, it may contain the
| characters 'A-Z, 0-9, @, #, $, .'; spaces are not permitted. The sign-on
| key is scrambled.
User sign-on keys are usually short keys that a site provides for the
convenience of their users. Such keys might be:
ACCOUNTING
JONES
JA
If both user and formal sign-on keys are established for an individual,
that person is able to sign-on to Advantage CA-Roscoe through his
user key, and all accounting reports will identify the user by their
formal sign-on key.
If IBM RACF is used, a user sign-on key should not exceed seven
characters in length and should match the RACF user ID. See the
Advantage CA-Roscoe Interactive Environment Extended Facilities for

System Programmers Guide for additional information concerning

RACF.
4 PREFIX: Specify two or three unique characters that are to be
prefixed to all library members saved by the user during an
Advantage CA-Roscoe session. (We recommend using three character
prefixes.)
The characters can be uppercase alphabetics (A through Z,) numerics
(0 through 9) or $, # or @. Numerics should not be used as the first
character of the prefix.
ATTENTION
All three-character prefixes beginning with R (for example, RAA -
R99) are reserved.
| 5 FORMAL KEY: Optional. If a formal key is specified, it must be

| unique and not exceed 22 characters in length. It can only contain
| characters 'A-Z 0-9 @ # $ .'; spaces are not permitted. This field is
| scrambled.
6 PASSWORD: Optional. If a password is specified, it cannot exceed
10 characters in length, cannot contain a slash (/), and is scrambled.
7 PASSWORD REQUIRED (Y/N): Optional. Enter Y if the user must
always have a password. Enter N if the user is not required to have a
password. The default is N.
8 ABLE TO CHANGE: Optional. Enter Y if the user may change the
password at any time. Enter N if the password can only be changed
by site management. The default is Y.
9 MAXIMUM LINES USER CAN SAVE: Specify the maximum
number of lines the user can save in the library or the keyword
NONE. If a value is specified, it cannot be greater than eight
characters in length (for example, 99999999). If NONE is specified, no
limit is placed on the number of lines the user can save. The default is
NONE.
1 CURRENT LINES SAVED: This field is maintained by Advantage
CA-Roscoe. It is non-modifiable, and contains a value only when the
profile already exists. The value represents the current number of
lines the user has saved in the library. It is updated when ATTACH
LIB is executed or at sign-off.
11 SIGNON PROCEDURE: Optional. The name of an RPF program
that is to be executed whenever the user signs on to Advantage
CA-Roscoe. The RPF program can be saved as a member in the user's
library or in another user's library.

12 ABLE TO CHANGE (Y/N): Optional. Enter Y if the user can change
the name of the sign-on procedure. The user can also remove the
procedure at any time. Enter N if the user cannot change or remove
the sign-on procedure. The default is Y.
13 RESTRICTED USER (Y/N): Optional. Enter Y if the user's access to
Advantage CA-Roscoe is to be controlled by an RPF program that is
named as the sign-on procedure. Enter N if the user's access to
Advantage CA-Roscoe is not controlled. The default is N. (See the
section 'Creating Restricted User's for additional information.)
14 USER ABLE TO USE PRIVILEGED CMDS (Y/N): Optional. Enter Y
if the user is allowed to issue privileged commands for the specified
Advantage CA-Roscoe subject areas. The default is N. The subject
areas are the following:
OPER: Allows use of the DEBUG, LIBCACHE, OPERATOR (OPR),
RCSTRACE, ROZAP commands, privileged use of
MESSAGE command, and the PEEK function.
RPS: Allows use of the privileged operands of the PRINT
command.
ACCT: Allows use of the ACCT and RTM commands.
ETSO: Allows use of the privileged operands of the CANCEL,
FREE, and QUERY commands.
| LIB: Allows use of the privileged commands UPDATE, SAVE,
| DELETE, RENAME, and ALTER for daily library
| maintenance, regardless of the way security groups are
| established.
| UPS: Allows use of the privileged command UPSMNTnn.
| Note: A user that is enabled to use the UPS privileged
| commands must also be enabled to use the LIB
| privileged commands. A user that is enabled UPS
| privileges cannot enable privileged commands for
| other users through a UPS ADD or UPS UPDATE
| command. The privileged command field on the
| UPSMNTnn panel is protected and has a value of
| 'N.' Only the owner of the UPS prefix can enable
| privileged commands to a user.
15 LIBRARY SECURITY GROUP: Optional. 1-8 character name of the
security group to which the user is associated. (See the section
'Security Groups' for additional information.)
16 MORE PROFILES TO ADD/UPDATE (Y/N): Enter Y to redisplay a
blank prompt panel. Enter N to terminate the maintenance session.

4.4 Executing UPSBLKnn

UPSBLKnn is an RPF program that can be used to add, change or delete one
or more user profiles. To execute this program, sign on to Advantage
CA-Roscoe using the UPS sign-on key and enter:
(UPS.) UPSBLKnn
where (UPS.) is the prefix for the UPS account (required when doing
maintenance from an account other than the UPS account), and 'nn' is a
two-digit version identifier.
This program expects the AWS to contain information about the profiles to be
added, changed or deleted. The information must be defined in the AWS
according to the following format, and BEGIN and END must begin in column
1:
Executing UPSBLKnn
BEGIN operation KEY=key
PREFIX=pfx
qualifiers
END
BEGIN Required.
operation Required. Specify one of the following:
DEFAULT Establish profile to be used as a default or
prototype. Qualifiers omitted from subsequent
profiles are set to the values associated with this
prototype profile. The defaults remain in effect
until the next DEFAULT profile is encountered
or the end of the input is reached.
DELETE Delete existing profile. No qualifiers need be
specified. (A message appears when a profile is
deleted.)
ADD Add profile.
If a DEFAULT profile is not previously defined,
omitted qualifiers are set to their default values.
If a DEFAULT profile is previously defined,
omitted qualifiers are set to: 1) values specified
with the DEFAULT profile, or 2) their default
values if the qualifiers are not defined in the
DEFAULT profile.

CHANGE Change existing profile. When this operation is

chosen, specify only those qualifiers that are to
be changed.
KEY= Required. Specify the sign-on key for the profile that is to be
added, changed, deleted or used as a default.
PREFIX= The 2-3 character prefix to be associated with this profile.
Required when adding a profile or changing a prefix.
Note: All three-character prefixes beginning with R (for
example, RAA through R99) are reserved.
qualifiers Optional. The following qualifiers may be specified in any
order:
FKEY= Specifies a 1-22 character formal user
key. If omitted, the user's sign-on key is
used in accounting reports.
PASSWORD= Specifies a 1-10 character password that
does not contain a slash (/). If omitted,
the profile does not have a password.
NOPASSWORD= Specifies Y (yes) or N (no) to designate
whether the user may change the
password. If omitted, the default is Y.
PASSREQ= Specifies Y (yes) or N (no) to designate
whether a password is required. If
omitted, the default is N.
SOPROC= Specifies the name of the library
member containing the RPF program
that is to be executed whenever this
user signs on.
NOPROC= Specifies Y (yes) or N (no) to designate
whether the user may change the name
of the sign-on procedure. If omitted, the
default is Y.
MAX= Specifies the maximum number of lines
the user may save in the library or the
keyword NONE (for no limit). If
omitted, no limit is placed on the
number of lines that may be saved.
GROUP= Specifies the name of the security group
to which the user is assigned.

RESTRICT= Specifies Y (yes) or N (no) to designate

whether the user's access to Advantage
CA-Roscoe is to be restricted. If omitted,
the default is N.
NKEY= Specifies the new sign-on key to be
assigned to this user.
OPERCMD= Specifies Y (yes) or N (no) to designate
whether the user has operator
privileges. This lets you use of the
DEBUG, LIBCACHE, OPERATOR
(OPR), RCSTRACE, and ROZAP
commands, privileged use of MESSAGE
command, as well as the PEEK function.
RPSADM= Specifies Y (yes) or N (no) to designate
whether the user has RPS privileges.
This lets you use of the privileged
operands of the PRINT command.
ACCTADM= Specifies Y (yes) or N (no) to designate
whether the user has accounting
privileges. This lets you use of the
ACCT and RTM commands.
ETSOADM= Specifies Y (yes) or N (no) to designate
whether the user has ETSO privileges.
This lets you use of the privileged
operands of the CANCEL, FREE, and
QUERY commands.
| LIBADM= Specifies Y (yes) or N (no) to designate
| whether the user has daily library
| maintenance privileges. This lets you
| use of the privileged commands SAVE,
| UPDATE, DELETE, RENAME, and
| ALTER, regardless of the way security
| groups are established.
| UPSADM= Specifies Y (yes) or N (no) to designate
| whether the user has UPS privileges.
| This lets you use of the UPSMNTnn
| RPF for adding, updating, or deleting
| user sign-on keys.
| If UPSADM=Y is specified, LIBADM=Y
| must also be specified.
| Note: The UPSBULK RPF can only be
| executed by the owner of the
| UPS prefix.
END Required.

The example below illustrates the type of input UPSBLKnn expects to find in
the AWS.
Sample Input to UPSBLKnn
BEGIN ADD KEY=JONES

PREFIX=JON PASSWORD=HELLO
FKEY=71.JONES
GROUP=GRP1
END
BEGIN DEFAULT KEY=BROWN
END
BEGIN ADD KEY=SMITH
PREFIX=SMI
FKEY=71.SMITH
END
BEGIN CHANGE KEY=JONES
PASSWORD=NEWPASS
END
BEGIN DELETE KEY=GREEN
END
In this example:
1. A profile with the sign-on key JONES is added to UPS. (The default value
of omitted qualifiers is used in establishing this profile.)
2. A profile with the sign-on key BROWN is designated as the default profile.
The definition of this profile is used when adding subsequent profiles.
3. A profile with the sign-on key SMITH is added. Only a sign-on key, prefix
and formal sign-on key are specified; the default profile is used to provide
the rest of the profile definition.
4. The profile with the sign-on key JONES is changed. Since only the
PASSWORD qualifier is specified, this is the only part of the definition that
is changed.
5. The profile with the sign-on key GREEN is deleted. No qualifiers need be
specified.

4.5 Creating Restricted Profiles

A site can permanently place a user in a restricted state when the user's UPS
profile is defined. When a restricted user signs on, the individual's use of
Advantage CA-Roscoe is controlled through RPF programs. Often, restricted
users are non-data processing personnel.
To create a restricted user, the following characteristics must be established in

the user's profile:
RESTRICT= Specify Y (for YES) to designate that the user is to
be restricted.
SIGNON PROCEDURE= Specifies the name of the RPF program to control
the user's terminal session.
CHANGE SIGNON= Specify N (for NO) to prevent the user from
changing or removing the sign-on program.
When a restricted user signs on to Advantage CA-Roscoe, the sign-on program

named in the user's profile is executed. The sign-on program thus becomes the
controlling program that directs the user's terminal session.
It should be noted that sites can also control a user's actions under Advantage
CA-Roscoe:
■ By Command or Facility
Advantage CA-Roscoe includes a variety of command and facility exits
that sites can use to monitor and control the actions of their users. The
Programmers Guide contains detailed information about developing site
written exit routines.
■ Temporarily
A site sign-on program (or any RPF program) can temporarily place a user
in a restricted state through the SET PAUSE command. If, while in this
state, the program is paused, the user can only scroll or issue the GO
command. This state can be explicitly terminated by the SET PAUSE. It
will be implicitly terminated when program execution ends and terminal
control is returned to the user.
4.5.1 Controlling Restricted Users

A user's ability to use Advantage CA-Roscoe commands and facilities can be
permanently or temporarily restricted by site management.
The following notes are provided to assist sites in developing RPF programs
that control a restricted user's session.

4.5.2 Temporary Restricted Users

When a user is temporarily placed in a restricted state and the program is
paused, the program will only recognize the GO command and those PF keys
assigned scrolling functions.
4.5.3 Permanent Restricted Users

■ If the sign-on program named in the user's profile is not found, the user is
signed off.
■ If the program prompts for input (through a WRITE/READ or panel) and
a restricted user enters a question mark (?), control returns to the sign-on
program. (The question mark is a valid RPF termination command.) A
restricted user cannot end a terminal session until permitted to do so by
the program.
■ If the program is explicitly paused by a PAUSE RES command or
implicitly paused (as when an ATTACH command is executed), only the
scrolling keys and the GO command are recognized.
When issuing the GO command, restricted users cannot include a line
number with the command. (Nonrestricted users can include a line number
with the GO command to cause execution to resume at that line in the
program.)
■ The sign-on program controls program termination and reexecution. If the
program contains:
– OFF: When encountered, the restricted user is always signed off,
regardless of the value specified with the OFF initialization parameter.
– RETURN: When encountered in the sign-on program, control always
returns to the start of that program.
When encountered in a subprogram, control returns to the invoking
program and resumes with the first executable statement following the
EXEC.
– STOP: When encountered at any RPF program execution level, control
always returns to the start of the sign-on program. Note that if the
sign-on program is not found (for example, the program has been
renamed or deleted), an error message appears and the restricted user
is placed in an unrestricted state.
■ The RPF trap facility should be used. If it is not used and an error occurs
in the program, program control transfers to the beginning of the sign-on
procedure. Depending on the type of error, the program could go into a
loop.
For additional information about writing RPF programs, see the Advantage
CA-Roscoe Interactive Environment RPF Language Guide.

4.5.4 Execution Hierarchy

The sign-on message/program execution hierarchy is:
1. Site newsletter.
2. Site sign-on program.
If this program contains an untrapped error, a message appears and the
site written program is invoked.
3. Site written program.

4.6 Using the UPS Exit
4.6 Using the UPS Exit

Sites have the option of using a UPS 'exit' that is available with both
UPSMNTnn and UPSBLKnn.
To use this facility, a library member named UPSMEXIT must reside on the
UPS key. This member must contain the site written RPF program that is to
process the information passed from UPSMNTnn and UPSBLKnn.
Please refer to the Advantage CA-Roscoe Interactive Environment Extended

Facilities for System Programmers Guide for more information.

4.7 Special Profiles

This sections describes user profiles that are:
■ Automatically added to UPS during installation.
■ Reserved for use by Advantage CA-Roscoe.
■ To be assigned to the individuals responsible for controlling and
maintaining Advantage CA-Roscoe.
4.7.1 Distributed User Profiles

When Advantage CA-Roscoe is installed, the user profiles identified in the
table below are automatically added to UPS from ROSCOE.KEYS.
When two prefixes are shown for one profile, two versions of the associated
members are available. One version contains uppercase and lowercase text; the
other version contains only uppercase text. By default, the members associated
with the first prefix (for example, the uppercase/lowercase version) is added
to UPS.
4.7.1.1 Reserved Profile Names
Member Name Sign-on Key Contents

RO ROSCOE.CONTROL Contains members for use in
maintaining Advantage
CA-Roscoe. (See the section
'Privileged Profiles' for
AI ROSCOE.CONTROL2 Contains members for use in
maintaining Advantage
CA-Roscoe. (See the section
'Privileged Profiles' for
RBS ROSCOE.RBS Contains the messages created
by the users of the Bulletin
Board system (BBS).
RBX ROSCOE.RBX Contains the RPF programs
constituting the online Bulletin
Board system (BBS).
RDF or RD5 ROSCOE.DMF Contains the programs
constituting the Dialog
Management Facility. (RD5
contains uppercase version.)

Member Name Sign-on Key Contents

RHE or RD3 ROSCOE.HELP Contains members describing all
Advantage CA-Roscoe, RPF and
Monitor commands. (RD3
| RIF ROSCOE.MAINT Contains members that provide
| information about applications
| that can execute under ETSO.
RPS ROSCOE.RPS Use as the default RPS spool
queue. See the chapter on
'ROSCOE Printing Services' for
RSK or RD4 ROSCOE.SKETCH Contains the programs
constituting SKETCH. (RD4
RTR or RD2 ROSCOE.RPFTRAIN Contains the program
constituting the online RPF
training. (RD2 contains
uppercase version.)
RTU or RD1 ROSCOE.TUTORIAL Contains the programs
constituting the online
Advantage CA-Roscoe tutorial.
(RD1 contains uppercase
version.)
R2D ROSCOE.DB2 Contains the RPF programs
used by Advantage
CA-Roscoe/DB2. (This profile is
added to UPS during the
installation of Advantage
CA-Roscoe/DB2.)
UPS ROSCOE.PROFILE Contains user profiles and
members used for the
maintenance of those profiles.

4.7.2 Privileged Profiles (RO and AI)

The prefixes RO and AI should be assigned to the individuals who are to be
| responsible for the daily maintenance of Advantage CA-Roscoe. Additional
| users can be assigned as privileged profiles through the UPSMNTnn RPF.
The privileges extended to the owners of these prefixes include:

■ Extended library member facilities. Regardless of the way security groups
are established, the owner of the RO or AI prefix can always:
– Update any user's library member.
– Save library members using any user's prefix.
– Delete library members belonging to any user.
– Rename any user's library members. (This is, in effect, a DELETE and
SAVE.)
■ Sending messages to the operator, even if the Operator command
NOMESSAGE has been issued.
■ The ability to use special commands that can be used to control and
monitor:
– An execution of Advantage CA-Roscoe.
– Applications executing through ETSO.
– ROSCOE Printing Services (RPS).
For descriptions of these commands, see the Advantage CA-Roscoe Interactive
During installation, a variety of library members are written to the library of

the individual assigned the RO prefix. These members include:
■ Sample JCL to execute the programs that are distributed with Advantage
CA-Roscoe.
| ■ Advantage CA-Roscoe RPFs for the AJOB, EDSN, SDSN, and QDSN
| facilities.
A sample Advantage CA-Roscoe sign-on newsletter (HELLO) is also placed in

the library of the individual assigned the RO prefix. All maintenance of the
HELLO member must be performed under the sign-on key assigned to the
owner of the RO prefix.

4.7.3 Reserved User Profiles

In addition to the prefixes shown on page 4-19, Advantage CA-Roscoe reserves
all three-character prefixes beginning with R (for example, RAA through R99).
The profile or library members associated with any individual assigned such
a prefix is subject to unpredictable results.
While it is not reserved, care should be exercised if SYS is used as a prefix. The
user assigned this prefix could encounter problems when executing
applications under ETSO.

4.8 Security Groups
4.8 Security Groups

ATTENTION
| The information presented in this section does not apply to the owners of
| the RO or AI prefix (if internal security is used for LIBADM functions).
| These individuals always have access to any member saved in the
Advantage CA-Roscoe library.
When an individual saves data in the library as a member, the member can be
assigned the access attribute of SHARED, EXECONLY or RESTRICTED.
Sites have the option of controlling the type of access allowed to members
with a SHARED access attribute. To use this option, sites must establish
security groups. A security group designates the read and write access
permitted to:
■ Individuals associated with the group (for example, intra group access).
■ Individuals associated with other groups (for example, inter group access).
The definitions of the security groups must be placed in the member GROUPS
under the UPS prefix.
| The absence of a GROUPS member provides all users with READ access.
(This allows any user to fetch SHARED library members but only the owner to
change or update them.)
The member GROUPS may contain:

1. A global default access definition.
If no security groups are defined, this definition controls the access any
individual has to other people's library members.
If an individual is not associated with a group, this definition controls the
access other users have to that individual's library members.
2. Individual group definitions.
Sites can establish a maximum of 255 different security groups. Once the
groups are defined, each user's profile should be updated to show the
group to which he is assigned. Note that a user can be assigned to only
one group.

4.8 Security Groups
To establish default access:
4.8.1 Syntax
──GBLACC=──access─────────────────────────────────────────────
GBLACC= Access authority permitted to all users unless overridden by a

group definition. The valid access codes and their meanings
are:
NONE Only the owner has access to his library members.
EXEC Anyone can execute a library member containing
an RPF program.
READ Anyone can execute or fetch a library member.
ALTER Anyone can execute, fetch or change the attributes
of a library member.
UPDATE Anyone can execute, fetch, alter and change a
library member. (UPDATE also permits anyone to
save a member in anyone's library.)
DELETE Anyone can execute, fetch, alter, change or delete
anyone's library member.
4.8.1.1 Notes
■ GLBACC must be the first, or only, statement in the member GROUPS.

■ If an individual is not associated with a group, this definition controls
other users access to that individual's library members.
To establish a group definition:
4.8.2 Syntax

4.8 Security Groups
──GROUP──name──┬───────────────────┬──ENDGROUP────────────────
├─GRPACC=access─────┤
├─INTACC=access─────┤
│ ┌─,───┐ │
group┴────┤
├─XNONE=──
│ ┌─,───┐ │
├─XEXEC=──
│ ┌─,───┐ │
├─XREAD=──
│ ┌─,───┐ │
├─XALTER=── group┴───┤
│ ┌─,───┐ │
├─XUPDATE=── group┴──┤
│ ┌─,───┐ │
└─XDELETE=── group┴──┘
name One-eight character unique name that conforms to Advantage

CA-Roscoe library member naming conventions.
GRPACC= Overrides the global access to the library members owned by
the users associated with this group. One of the following
access codes must be specified:
EXEC Anyone can execute a library member, containing
an RPF program, that is associated with this group.
READ Anyone can execute or fetch a library member that
is associated with this group.
ALTER Anyone can execute, fetch or change the attributes
of a library member that is associated with this
group.
UPDATE Anyone can execute, fetch, alter and change a
library member that is associated with this group.
(UPDATE also permits anyone to save a member in
anyone's library.)
DELETE Anyone can execute, fetch, alter, change or delete a
library member that is associated with this group.
INTACC= Overrides the global access and, if specified, group access for
individuals associated with the group. One of the following
access codes must be specified:
EXEC Anyone within this group can execute a library
member, containing an RPF program, that is
associated with this group.
READ Anyone within this group can fetch a library
member that is associated with this group.

4.8 Security Groups
ALTER Anyone within this group can execute, fetch or

change the attributes of a library member that is
UPDATE Anyone within this group can execute, fetch, alter
and change a library member that is associated
with this group. (UPDATE also permits anyone to
save a member in anyone's library.)
DELETE Anyone within this group can execute, fetch, alter,
change or delete a library member that is
XNONE= Name of one or more groups that are not allowed any form of
access to library members associated with this group.
XEXEC= Name of one or more groups that are only allowed to execute
library member containing RPF programs that are associated
with this group.
XREAD= Name of one or more groups that are allowed to execute and
fetch library members associated with this group.
XALTER= Name of one or more groups that are allowed to execute, fetch
and alter the attributes of library members associated with this
group.
XUPDATE= Name of one or more groups that are allowed to execute,
fetch, alter and update library members associated with this
group.
XDELETE= Name of one or more groups that are allowed to execute,
fetch, alter, update and delete library members associated with
this group.
ENDGROUP Optional. This keyword is used to mark the end of a group
definition. If omitted, the next GROUP keyword or the end of
the member terminates the current GROUP definition.
4.8.2.1 Notes
■ If GRPACC is specified, it overrides the global access for the designated

group. It must be the first or only statement in the group definition.
■ If INTACC is specified, it overrides the global (and group, if specified)
access for individuals associated with the designated group. It must follow
GRPACC if a GRPACC statement is also specified.
■ XNONE, XEXEC, XREAD, XALTER, XUPDATE and XDELETE can be used
to extend or exclude access. They override the global and group access,
allowing specific groups to have independent access to the members
associated with the designated group.
If more than one group is to be extended or excluded the same access, the
group names must be separated by commas. Also, the group names must

4.8 Security Groups
be complete on a single line. To specify additional groups, repeat the

access type and include the necessary group names, as in:
XALTER=APPLIC,SYSTEM,ACCTING
XALTER=WORDPROC
■ If an individual is not associated with a security group, access to his
library member is controlled by the global default access (for example, the
value of GBLACC=).
■ Group definitions can be changed at any time. The new definitions will be
available the next time Advantage CA-Roscoe is brought up. If there is an
error in the definitions, all users will be restricted to READ access. Use the
privileged command UPSVER to syntax check the GROUPS member. The
command syntax is:
UPSVER mem
where mem is the name of the library member containing the group
definitions. (The production definition must be in the member GROUPS;
alternate definitions can be saved under any name.)
■ Comments may be included anywhere within a group definition. The
colon (:) identifies the text following it as a comment. A comment extends
from the colon to the end of the line.
4.8.3 Sample Security Groups Definition

The Sample Security Group Definitions listed below illustrates the type of
security group definitions that could be found in a GROUPS library member.
Sample Security Group Definitions
GBLACC=EXEC : Default Access
GROUP SYSTEM : Access to members associated with SYSTEM.

GRPACC=NONE : General: No one can access with members.
INTACC=DELETE : Within Group: Anyone can delete.
ENDGROUP :
GROUP APPLIC : Access to members associated with APPLIC.

GRPACC=READ : General: Anyone can fetch members.
INTACC=UPDATE : Within Group: Anyone can update.
XDELETE=SYSTEM : Exception: SYSTEM has full access.
ENDGROUP :
GROUP ACCTING : Access to members associated with ACCT.

INTACC=UPDATE : General: Default Access.
ENDGROUP : Within Group: Anyone can update.
GROUP WORDPROC : Access to members associated with WORDP.

ENDGROUP : General & Within Group: Default access.
Using the definitions listed above and the matrix shown on the next page, you
can see that:

4.8 Security Groups
■ Individuals assigned to SYSTEM have total (DELETE) access to each others

library members. While individuals outside of the group have no (NONE)
access.
■ Individuals assigned to APPLIC can UPDATE each others members.
Excluding individuals assigned to SYSTEM who have total (XDELETE)
access, individuals outside of APPLIC has READ access.
■ Individuals assigned to ACCTING can UPDATE each others members.
Since no explicit access to the group's members is specified, the global
access (EXEC) is permitted individuals outside of the group.
■ Individuals assigned to WORDPROC and individuals attempting to access
members associated with group are permitted to execute (EXEC) only. (The
global access is used since it is not overridden by the group definition.)
If an individual is not assigned to a security group, access to his library

members is controlled by the global default access (shown as the 'global' group
in the table below. His ability to access members belonging to individuals
assigned to security groups depends on the value assigned to that groups'
GRPACC.
Calling Target Group

Group Global System Applic Accting Wordproc
GLOBAL EXEC NONE READ EXEC EXEC
SYSTEM EXEC DELETE DELETE EXEC EXEC
APPLIC EXEC NONE UPDATE EXEC EXEC
ACCTING EXEC NONE READ UPDATE EXEC
WORDPROC EXEC NONE READ EXEC EXEC

Chapter 5. General
This chapter provides information about:

■ Attention support
■ Supported data streams
■ Supported devices
■ Supported protocols
Chapter 5. General 5-1

5.1 Attention Support
5.1 Attention Support

■ Hardware ATTN Key Support
Advantage CA-Roscoe provides synchronous and asynchronous SNA
VTAM ATTN key support.
■ Software ATTN Key Support
Sites using non SNA VTAM or BTAM terminals have the option of using
the NSNAATTN= initialization parameter to define the key PA1, PA2 or
PA3 as their site attention key (for example, NSNAATTN=PA1). (If the
designated key is also defined in the site's ROSPFUSE table, its ROSPFUSE
definition is overridden.)
This facility is not available at terminals defined to IBM CICS.
Note: Initialization parameters are defined in the Advantage CA-Roscoe
If a site defines a software ATTN key and a user presses the defined PA key at
a:
■ SNA VTAM Terminal: The key is ignored as an attention key and its
ROSPFUSE definition is used.
■ Non SNA VTAM Or Remote BTAM Terminal: Both synchronous and
asynchronous attention support is provided. The attention is treated
described below.
■ Local BTAM Terminal: Synchronous support attention support is provided.
The attention is treated as described following.
5.1.1 Synchronous/Asynchronous Attention Support

■ Synchronous (Advantage CA-Roscoe is waiting for terminal input):
If an application with an attention exit is executing under ETSO, the
application's attention exit gets control. If the application does not have an
exit, Advantage CA-Roscoe issues a prompt which allows the user to
specify whether the application should continue or be terminated.
■ Asynchronous (Advantage CA-Roscoe is not waiting for terminal input):
– An application with an attention exit is executing under ETSO, the exit
gets control. If the application does not have an exit, Advantage
CA-Roscoe issues a prompt allowing the user to continue or terminate
the application.
– If the user is: 1) using the Library Facility or the Data Set Facility or 2)
viewing job output, the operation is terminated.
– If the user is executing an RPF program and the program has an ON
ATTN exit, the designated routine gets control; otherwise, the
operation is terminated.

5.2 Data Streams Supported
5.2 Data Streams Supported

Both Data Stream Compatibility (DSC) mode and SNA Character Stream (SCS)
mode are supported.
Extended Data Stream Support is provided for those terminals with color,
extended highlighting, or a graphic escape capability. It is also provided for
terminals that support partitioning. For individuals to take advantage of these
features, sites must note this support when defining the appropriate terminals.
1. VTAM sites must code the extended data stream capability in the PSERVIC
field in the MODEENT macro.
2. BTAM sites with local terminals must specify the feature code as Q in the
devices' DD name.
3. BTAM sites with remote terminals must code FEATUR1=QS in the
RCSDVICE macro which defined their communications environment.
Notes on using the SCREEN command:

■ The SCREEN command allows the terminal user to alter the number of
rows and columns comprising the display. (See the Advantage CA-Roscoe
Interactive Environment Command Reference Guide for additional details about
this command.)
■ Terminals which support partitions require 3274 controllers to have at least
microcode Configuration Support Level D, Release 64.
■ Sites using 3180 type terminals must ensure that the model ID key on the
keyboard is set to a model 6-9 while in setup mode. If this is not done, the
operands 2-5, ROW and COLUMN of the SCREEN command will be
rejected if it does not match either the primary or alternate screen size.
■ Sites using non IBM terminals that have an external hardware switch to
alter the screen size to a model 2-5 (for example, Lee Data terminals) must
ensure that the SCREEN command exit SCREXIT is available. If it is not,
the operands 2-5, ROW and COLUMN of the SCREEN command may be
rejected. SCREXIT is described in the Advantage CA-Roscoe Interactive
Environment Extended Facilities for System Programmers Guide..

5.3 Devices Supported
5.3 Devices Supported

The following device types are supported by Advantage CA-Roscoe:
3270 subsystem (SNA, BSC3 and Local)
Teletype (NTO, BTAM-S/S)
3767 (SNA in single line mode, auto switch in 'AUTO')
The following device types are not supported by Advantage CA-Roscoe:

3270 Model 1 Displays (BTAM and VTAM)
3270 Model 1 Printers (BTAM)
Dial-up 3275 under BTAM
Unbuffered printers attached to a 3275
2741 (NTO, BTAM S/S)
Device Specific Information:

■ To achieve a satisfactory response time, terminals should have a minimum
transmission rate of 4800 bps. The preferred keyboard for 3270s is a 78-key
typewriter keyboard. Audible alarm is supported. Selector pen is disabled
by software control. Operator identification card reader is not permitted.
■ Due to BTAM restrictions, TTY 33/35 devices are only supported over
switched lines.
■ Sites using 3290 terminals should review the appropriate IBM Control Unit
Customization guide. Option 173 (Distributed Function Terminal Options)
must have 'Update Panel Before Allowing Buffer Change' set in (for
example, set to 1).
Advantage CA-Roscoe Device Support Disclaimer
Advantage CA-Roscoe can work with non-IBM hardware provided the

hardware and its firmware are plug and protocol compatible with the
device types previously listed. Advantage CA-Roscoe is not responsible for
supporting any hardware that is not IBM compatible.

5.4 Protocols Supported
5.4 Protocols Supported

The following protocols are supported under BTAM:
Local
Remote
Switched Start/Stop Devices
The following protocols are supported under VTAM:

Local non SNA
Remote BSC
Local SNA
Remote SNA (switched or dedicated)
NTO (Network Terminal Option)

Chapter 6. Operations Considerations
This chapter provides information about the following BTAM considerations:

■ Operation system generation
■ Resident access methods
■ Required device I/O modules
■ Error recovery for local/remote devices
■ TTY and TTY-compatible terminal considerations
Chapter 6. Operations Considerations 6-1

6.1 Operation System Generation
6.1 Operation System Generation

A new system generation may be necessary if terminal support is not already
included in the present system. Other options normally present in the site's
system are listed following.
1. To support Teletype or IBM 3270 terminals:
──DATAMGT──ACSMETH=(BDAM,BTAM....)────────────────────────
2. To allocate each Teletype to Advantage CA-Roscoe:
──IODEVICE──UNIT=TWX,ADDRESS=---,──FEATURE=(AUTOANSR),─────
──ADAPTER=TELE2,──SETADDR=---,─────────────────────────────
These options are necessary to allocate each teletype to Advantage

CA-Roscoe.
3. To allocate each local 3270 display station:
──IODEVICE──Unit=3277,MODEL=2,ADDRESS=cuu,─────────────────
┌─DEKY3277─┐
──FEATURE=(DOCHAR,─┴─EBKY3277─┴─,KB78KEY...)───────────────
A 1920 byte device buffer is assumed (Model 2). DEKY3277 is acceptable in

place of EBKY3277. SELPEN (selector pen) may be chosen if present, but
Advantage CA-Roscoe does not permit its use. AUDALRM (audible
alarm) may be chosen if present Advantage CA-Roscoe will use it to alert
the operator in case of transmission errors.
4. To allocate remote 3270 lines:
──IODEVICE──UNIT=BSC3,──ADDRESS=cuu,──ADAPTER=BSCA,────────
──FEATURE=(AUTOPOLL─┬───────────┬──┬───────────┬─)─────────
└─,DUALCODE─┘ └─,DUALCOMM─┘
One IODEVICE is required for every remote 3270 line group. The
organization of the line group is described to Advantage CA-Roscoe in the
RCS Communication Network Definition.

6.2 Resident Access Methods
6.2 Resident Access Methods

The requirements for resident access methods are not clearly defined in IBM
documentation. If certain portions of an access method are marked for
residency, care must be taken that all contingent access method modules are
also included in the list.
For BTAM, the rule is that if IGG019MA (BTAM read/write) is resident, all
device I/O modules that are shared between TP tasks must also be resident.
(See the appropriate BTAM PLM for additional information.) Consult the table
in the next section to determine which device I/O modules are required by

6.3 Required Device I/O Modules
6.3 Required Device I/O Modules

Sites should ensure that their system includes the I/O modules listed
following.
Common To All Devices: IGG019MA

IGG019MB
IFF019LP
For TTYs: IGG019MP
For Local 3270s: IGG019PA
IGG019PG
IGG019PH
For Remote 3270s: IGG019PC

6.4 Error Recovery for Local/Remote Devices

IECTLOPEN must be in either the Advantage CA-Roscoe Load library or in
the system LINKLIST.
To make IECTLOPN available, sites must either:

1. Copy IECTLOPN to the Advantage CA-Roscoe load library, or
2. Place SYS1.TELCMLIB in the STEPLIB concatenation or in the system link
list and give it the same authorization as the Advantage CA-Roscoe load
library.
The following table shows how RCS and RPS process certain 'exception'
responses. This information is useful to those sites using certain programmable
control units (for example, COMTEN with MAFS) which allow multiple BTAM
applications to be accessed from a single device.
I/O Operations Exception Response Action Code

WRITE WACK A1 (printer)
(address select) (DECFLAGS=X'CO') A2 (display)
WRITE RVI B
(address select) (DECFLAGS=X'42')
WRITE WACK C1 (printer)
(text) (DECFLAGS=X'CO') A2 (display)
WRITE ECB=X'7F' C1 (printer)
(text) No exception C2 (display)
READ Device end and D
(specific poll status intervention required
message) X='C250'
READ Intervention D
(status message) Required X'4050'
READ Device end X'C240' E
(general poll)

The Action Codes identify the action taken, which can be:
A1 Pause 10 seconds then retry buffer transmit.
A2 Retry 1 additional time, disable if retry fails.
B Issue read to pick up status message.
C1 Assume print started, general poll should respond with device end
to indicate buffer has been printed.
C2 Write complete, proceed.
D Wait for device end which signals that the device is available.
E If from D, retransmit current buffer. If from C1, transmit next
buffer.

6.5 TTY and TTY Compatible Terminal Considerations
6.5.1 IGG019MP Modification to Suppress Time Out

To support TTYs as true conversational devices, the BTAM CCW table for
TTYs (IGG019MP) has been modified to suppress all time outs on READ
operations which is done by changing the READ CCW (operation code 02) to
an INHIBIT (operation code 0a). The modified version of IGG019MP is
distributed on the Advantage CA-Roscoe load library, as well as on the
Advantage CA-Roscoe source library (for the convenience of system
programmers wishing to verify the modifications).
For Advantage CA-Roscoe to coexist with other TP processors using TTYs

where BTAM is resident, the BTAM operation codes used by Advantage
CA-Roscoe when issuing read operations for the TTY have been redefined;
thus, Advantage CA-Roscoe can coexist in an environment where other TP
processors (such as IMS) expect the time out on READ operations. This is done
by employing new BTAM operation codes for READ TI and READ TV.
Therefore, when BTAM is resident or where access method component loading

is guaranteed from LPALIB, the Advantage CA-Roscoe version of IGG019MP
must be moved from the Advantage CA-Roscoe load library into
SYS1.MLPALIB. This is normally done during Advantage CA-Roscoe
installation. If this move is omitted, Advantage CA-Roscoe is not able to
execute with TTYs under BTAM.
6.5.2 IGG019MP Modification for Autospeed

Autospeed is an option on Memorex controllers for handling different TTY
transmission speeds with the same controller port.
The Autospeed option determines its clocking rate from the first character
transmitted by the terminal after it has been connected to the TCU. The correct
character for a given speed is defined in the manufacturer's technical literature.
If used, this information is to be made known to any users of the system. The
standard BTAM channel program for the TTY READ INITIAL (TI) must be
modified since it has a WRITE (PADS) immediately following ENABLE CCW,
which prevents any subsequent change of internal transmission clocking.
To use the Autospeed option, a ZAP must be applied to IGG019MP. The ZAP
| is described in member RO19MPZP on ROSCOE.SAMPJCL.

6.5.3 Multispeed TTY Compatible Terminal Considerations

Standard Western Union Model 33/35 TWX devices require no special
modifications to IBM hardware or Advantage CA-Roscoe software. Likewise,
any TTY compatible terminal with a speed of 10 cps requires no modification
in Advantage CA-Roscoe code.
Terminals with higher speeds may require modifications both to hardware and
software. Unless the port in the TCU is wired to accept the different
transmission speed, a faster terminal cannot be used because of hardware
incompatibility. A fast terminal requires either that the port be permanently
wired at its transmission speed, or that a feature such as the Memorex
Autospeed option be available. In either case, a special TTY speed table may
have to be generated in Advantage CA-Roscoe (see the following section). If
the Autospeed option is used, the clocking rate for any terminal is determined
in the TCU hardware by the initial transmission from the terminal. (To use the
Autospeed option, a single ZAP must be applied to IGG019MP. The ZAP is
| described in member RO19MPZP on ROSCOE.SAMPJCL.
The successful operation of any TTY compatible device cannot be guaranteed,

since it is bound to the TTY handling provided by IBM BTAM. In practice,
almost any TTY compatible terminal have been found to operate correctly.
6.5.4 Advantage CA-Roscoe Speed Table for TTY Compatible

Terminals
To handle non standard TTYs operating at different speeds and with different
requirements as to the number of pad (idle) characters that must be inserted in
the transmission, Advantage CA-Roscoe uses a special table of speed
characteristics with the CSECT name ROSTTY. The entries in this table are
referenced by the Advantage CA-Roscoe command TTY, as explained in the
Advantage CA-Roscoe Interactive Environment Command Reference Guide. The
operand of the TTY command is a numeric value which is actually the offset to
the desired entry in the ROSTTY table as set up at the site. The standard table
provided when the system is installed contains a single entry for the standard
TTY 33/35. To handle different terminals, the table must be reassembled and
linked into the Advantage CA-Roscoe system, replacing the prior table.
The table and CSECT statement are generated by the macro ROSTTY. The
ROSTTY macro is coded as follows:

6.5.4.1 Syntax
ROSTTY Macro
┌─,─────────┐
┬─────────┬┴─────────────────────
──┬─────┬──ROSTTY──pad-def───
└─tag─┘ └─pad-def─┘
tag Any valid Assembler tag. It is ignored.

pad def Pad definition for a specific TTY compatible device. Each
definition consists of one or two numeric values. The first of
the two values defines variable pad requirements. The second
defines the fixed pad requirement. If both a variable and a
fixed requirement are necessary, enclose the two values in
parentheses and separate them with a comma; for example,
(34,5). If only a variable requirement is necessary for The
terminal, omit the second value and do not code the
parentheses; for example, 34.
A value of 0 or 255 indicates that no extra pads are required.
Requirements for fixed and variable pad insertions are determined from the
manufacturer of the equipment:
■ Fixed requirements are coded as the number of pad characters that must
always follow a carriage return to bring the carrier to the left margin
without dropping data characters. Very few TTY compatible devices
require a fixed number of pads. No fixed requirement greater than 10 can
be encoded.
The number of pads defined by the fixed requirement is always inserted
into the data transmission.
■ Variable requirements are coded as to the number of positions the carrier
moves to the right, for which one pad is inserted when the carrier returns
to the left margin. That is, if a certain TTY device requires that for every 20
characters printed, one pad is needed to return the carrier, the variable
value for that device is 20. No variable requirement less than 8 may be
encoded.
The number defined by the variable requirements is divided into the
number of data characters to derive the number of pads to be inserted into
the transmission.
■ The actual number of pads inserted is the sum of the fixed requirement
and the variable requirement.
ROSTTY is assembled and linked to the RO60LIB by the SMP/E RECEIVE and
APPLY of product USERMOD MRO602A, which is found in the installation
sample JCL library. The generation source for ROSTTY is placed in the
RO60OPT data set as member TTYTAB by the SMP/E APPLY of the base
Advantage CA-Roscoe function SYSMOD CRO6000.

The assembled table will contain a site default with a value of X'FF' (standard
TTY 33/35) and four special entries which can be referenced by the commands
TTY 1, TTY 2, TTY 3, TTY 4, respectively.
The ROSTTY table should always be changed by means of an assembly and

link edit, as previsouly described. If, however, the table is to be modified by
means of SUPERZAP, note the following ROSTTY table description.
Offset Length Contents

0 1 X'AA' (ROSTTY identification field; do not
change.)
1 1 1 byte unsigned binary count of entries,
excluding the site default entry.
2 2 Site default (for format, see the following).
4 2 First and successive special entries (for
format, see the following).
Note: Each entry consists of two 1 byte values. The first is the variable and
the second is the fixed requirement. The actual value of the fixed
requirement field is always 1 less than the value encoded in the macro.
6.5.5 Advantage CA-Roscoe TTY ID Verification (ROSTTYID)

As a site option, Advantage CA-Roscoe can perform TTY ID verification at
sign-on time. This option can be used only if all TTYs (including all TTY
compatible devices) that call Advantage CA-Roscoe can transmit a TTY ID in
response to a WRU control. If the TTYs have no answer back drum, or if only
some of the TTYs have an answer-back drum, do not use the ID verification
option. This option is used for data center security to prevent dial ups from
unauthorized TTYs. Only those devices whose ID sequence is coded in the
TTY ID table (ROSTTYID) are permitted to complete sign-on proceedings; any
TTY not represented in the TTY ID table that attempts to connect to Advantage
CA-Roscoe TTY ID table is immediately disconnected.
The TTY ID table is generated by the macro ROSTTYID in the Advantage

CA-Roscoe macro library. It generates a CSECT, also named ROSTTYID, which
must be linkedited onto the Advantage CA-Roscoe load library with the
attribute RENT, as shown in the following sample JCL.
Code the TTY IDs that are to be accepted by Advantage CA-Roscoe as a list
enclosed in parentheses. The identifier is the EBCDIC representation of the
answer back sequence transmitted by the TTY. The identifier cannot exceed 20
characters in length.
If the TTY ID table is not present on the Advantage CA-Roscoe load library, no
TTY ID verification is performed.

ROSTTYID is assembled and linked to the RO60LIB by the SMP/E RECEIVE

and APPLY of product USERMOD MRO602B, which is found in the
installation sample JCL library. The generation source for ROSTTY is placed in
the RO60OPT data set as member TTYID by the SMP/E APPLY of the base
Advantage CA-Roscoe function SYSMOD CRO6000.
ROSTTYID is not used in a VTAM system, since VTAM facilities are used for
all ID verification.
6.5.6 TTY Transmission Control

Advantage CA-Roscoe uses two translate tables, one for inbound ASCII line
code to EBCDIC translation and the other for outbound EBCDIC to ASCII line
code translation. These tables are distributed on RO60LIB as the members
RCSTTTYI (inbound) and RCSTTTYO (outbound).
6.5.6.1 Inbound Control Characters
See IBM BTAM SRL (GC30-2004) for the standard TTY transmission codes.
Advantage CA-Roscoe sends even parity transmission code, but recognizes
either even or odd parity if accepted by the TCU. Terminals capable of
transmitting both uppercase and lowercase alphabetics may also be used.
The following table shows the TTY control characters Advantage CA-Roscoe
receives from the TTY.
Control/ TTY Code Explanation

Graphic Received
XOFF C9 Turns transmitter off.
EOT 21 End of transmission. Causes disconnect.
Should be disabled in terminal itself.
XON 88, 89 Turns transmitter on.
WRU A1, A0 Treated as Break or Attention.
LF 50, 51 Line feed.
CR B1 Carriage return. May be used as RETURN.
See Note below.
10, 11 Backslash. Shift L. Cancels character(s) as
3A, 3B input.
Note: For terminal user convenience, where possible, the RETURN key may
be wired in the terminal so that it causes CR, LF, XOFF.

6.5.6.2 Outbound Control Characters
The following table shows the TTY control characters transmitted by

Control/ TTY Code Explanation

Graphic Received
XOFF C9 Turns transmitter off.
XON 88 Turns transmitter on.
LF 50, 51 Line feed.
CR B1 Carriage return.
RU or F 60 Transmitted after a prompt, XON sequence.
idle (pad) 00 Idles to prevent overtyping after CR.
SI FO Idles after CR for password mask.
6.5.6.3 Translation Table Customization
Sites that would like to:

■ Permanently change the inbound or outbound tables can do so by
| modifying the members RCSTTTYI and/or RCSTTTYO on RO60OPT. If
these tables are modified, they must then be reassembled and relinked. (It
is recommended that the distributed translation tables be renamed and
thus available for backup.)
■ Change the outbound table on a per-output basis can do so through the
RCSEXIT. This exit is described in the Advantage CA-Roscoe Interactive
Environment Extended Facilities for System Programmers Guide.
Also, sites executing applications under ETSO can have their users issue the
command TTY OPT 1 to provide the following facilities:
■ If the application issues a TGET after an ASIS TPUT, ETSO causes an XON
(ASCII X'88') to be transmitted.
■ The tables used to translate the data to and from ASCII are RCSTTYO1
and RCSTTI1, respectively. (If an RCSEXIT exit routine is called, which
returns an address for output translation table on a per I/O call, that table
takes precedence over RCSTTYO1.)
■ The application may issue a TPUG FULLSCR and TGET ASIS
ETSO will not cause unprintable characters to be translated to blanks.
Note: The command TTY OPT 1 is provided specifically for the use of
KERMIT (a file transfer program distributed by Columbia University
that transfers data between a PC and the mainframe).

6.5.7 Modifications to ERP to Use TTY BREAK

Member BTAMZAPS on the Advantage CA-Roscoe SAMPJCL library contains
a complete deck of ZAPs beginning with OS Release 20.
The ZAPs given in BTAMZAPS for transient ERP module IEG0304A

(Start/Stop ERP Intervention Required) are necessary for systems supporting
teletype (TWX) terminals if the use of the BREAK key as an ATTN (interrupt
output listing) is to be supported (see the Advantage CA-Roscoe Interactive
Environment Command Reference Guide). Without the modifications, the use of
the BREAK key will cause BTAM to disable (disconnect) the line. If the ZAP
was not applied, all teletype users should be informed to employ the software
BREAK command described in the Advantage CA-Roscoe Interactive Environment
Command Reference Guide.
The operation of BREAK, even with the ZAP to IGE0304A, will cause printing
out of message IEA000I at the operator's console display unit. The operator
may be instructed to disregard all such messages, or else the printing of the
message may be disabled by means of the ZAPs to IGE0304B and IGE0225.
The effect of these ZAPs is to suppress printing of the message IEA000I for all
telecommunications devices under all circumstances. The following side effect
should be noted: If an I/O error occurs on a data cell, no volume serial
number will be printed in the error message, even if one is available. The code
that replaces a 2321 UCB address with a sub UCB address and determines
whether the volume serial field of the sub UCB contains a valid volume serial
number is overlaid by the code that determines whether an error condition
arose on a telecommunications or non telecommunications device. The branch
that leads to the eliminated code is changed to a branch to the point at which
a determination has been made that no volume serial number is available.

Chapter 7. ROSCOE Communication Services (RCS)
ROSCOE Communication Services (RCS) provide the interface between

Advantage CA-Roscoe applications and the telecommunication access methods
used at a site.
This chapter discusses:

■ When an RCS network definition must be defined.
■ How to establish an RCS network definition.
Chapter 7. ROSCOE Communication Services (RCS) 7-1

7.1 Determining if the Default RCS Definition May Be Used
7.1 Determining if the Default RCS Definition May Be Used

Based on the way the communication network is defined, RCS will support
concurrent executions of:
■ VTAM
■ BTAM with both local and remote devices
■ External teleprocessing monitors, referred to in this manual as XTPM. (For
a description of XTPM seenthe chapter "XTPM Support".)
In addition, RCS supports a Batch Terminal Monitor which allows Advantage

CA-Roscoe to recognize a batch user session.
A default RCS Network Definition is distributed as the member RCSDEF on

the RO60OPT file. (During installation, a copy of this definition is saved as the
member RCSDEF in the library of the individual assigned the RO prefix.) The
default definition can be used by sites that use:
■ Only VTAM
■ Only XTPM
■ VTAM and XTPM
■ Only BTAM with local devices
An RCS Network Definition must be defined by sites that use:

■ Only BTAM with remote devices
■ BTAM remote devices and any other access method
Lastly, review the Advantage CA-Roscoe Interactive Environment Programs and

Utilities Guide for information about:
■ A batch user session
■ RCS related Advantage CA-Roscoe initialization parameters
■ Advantage CA-Roscoe DD statements needed by BTAM sites

7.2 Establishing an RCS Network Definition

A site using remote BTAM devices and/or mixed, concurrent access methods
must define its communication network to RCS.
The definition is accomplished through a series of RCS network definition

macros that are distributed on RO60MAC. Once the network is defined,
through the macros, it must be assembled to create the RCS Network
Definition. The definition must be established as a unique member on
RO60LIB. Sample JCL and an example of the RCS macros are presented at the
end of this chapter.
The RCS macros must be coded in the order in which they are described
following:
RCSGEN (Required.) Begins the network definition and defines the

access methods to be used.
RCSBTAMR Establishes both the number of remote 3270 line groups to be
controlled by Advantage CA-Roscoe, and the common error
recovery procedures.
RCSLINE Defines a line group. One RCSLINE macro is needed for every
line group to be handled by Advantage CA-Roscoe. Each
RCSLINE macro initiates a set of resource definitions which
are continued by the macros RCSCLSTR and RCSDVICE.
RCSCLSTR Defines a cluster on the line.
RCSDVICE Defines a device on the current cluster.
RCSGEND (Required.) Terminates the network definition.
RCSGEN and RCSGEND must always be coded. RCSBTAMR, RCSLINE,

RCSCLSTR and RCSDVICE need only be coded by BTAM sites using remote
devices.
RCS checks to ensure that the remote BTAM macros are defined in the correct
order. If a macro is coded out of order, an assembly warning is issued.
7.2.1 RCSGEN: Access Method Definition

The RCSGEN macro establishes the access methods to be used by Advantage
CA-Roscoe.

7.2.1.1 Syntax
ROSGEN Macro
──┬─────┬──ROSGEN──────────────────────────────────────────────
└─tag─┘
┌─,──────┐
─┬────┬─┴─)─┬──────────────────────────┬─────────
──AMETHS=(am──
└─am─┘ └─,MSG=─┬─C'text'───────┬──┘
├─X''─────────┤
└─(data-stream)─┘
tag Name to be assigned to the CSECT. If specified, it must

uniquely identify the Communication Network Definition. The
default is RCSDEF.
AMETHS= Access methods to be used by the site. One or more of the
following codes must be specified, The codes and their
meanings are:
VTAM VTAM
BTAMR BTAM with remote devices
BTAML BTAM with local devices or TTYs
XTPM External TP monitor (3270 terminals only)
BATCH Batch terminal monitor
MSG= (BTAM only.) BTAM 3270 type terminal message that is to
override the standard Advantage CA-Roscoe message,
specified as:
C'text' Character string that is to be displayed,
beginning in column 1 of row 1.
X'00' Null message is to be displayed.
data stream One or more multiple immediate data operands
in the form:
──┬──────────┬──C'text'─────────────
└─X'hex1',─┘
──┬──────────┬──────────────────────
└─,X'hex2'─┘
The text can contain any uppercase or lowercase

characters that are to be displayed.
The hexadecimal digits are used to supply the
SBA sequences that override the default starting
location of the message (hex1) or the position the

cursor (hex2) occupies after the text is displayed.

If hex1 is omitted, the message begins in column
1 of row 1. If hex2 is omitted, the cursor is
placed immediately following the message. For
example, to position the message WELCOME TO
ROSCOE to begin in column 1 of the first line
and to place the cursor immediately following it:
MSG=(X'11441D',C'WELCOME TOX
ROSCOE')
7.2.1.2 Notes
■ RCSGEN must be the first macro in the RCSDEF CSECT.

■ Access Methods:
– If multiple access methods are specified with AMETHS=, they must be
separated by commas with no intervening spaces.
– XTPM should be specified by sites planning to access Advantage
CA-Roscoe through: 1) terminals defined to CICS, 2) a TSO session, or
3) another Advantage CA-Roscoe session. (See the chapter "XTPM
Support" for additional information.)
– If BATCH is specified, Advantage CA-Roscoe reads input from a
special SYSIN file and writes output to a special SYSOUT file. (See the
Advantage CA-Roscoe Interactive Environment Programs and Utilities
Guide.)
■ BTAM Message:
– A standard Advantage CA-Roscoe terminal message is displayed at all
remote BTAM-3270 type terminals during Advantage CA-Roscoe
remote line initialization. The message is also displayed at both remote
and local 3270 type terminals following a terminal disconnect (that is,
Advantage CA-Roscoe OFF command). The MSG= operand allows
sites to modify this message.
– Unless the site has 3270-type terminals with uniform screen sizes, we
recommend that only the message text be modified. The message is
sent to all BTAM terminals regardless of the screen size and, therefore,
may be skewed if, for example, it has been set up for 80 column
screens and is sent to a Model 5 IBM 3270-type terminal.
– Advantage CA-Roscoe always brackets the MSG= data with an SBA
sequence for row 1 of column 1 and an insert cursor order. The data
should not contain any other control characters.
– Parentheses are required when multiple immediate data operands are
specified. Also, the operands must be contiguous if continued on the
next line; they are not sublist elements.

7.2.2 RCSBTAMR: Initiate Remote Table

The RCSBTAMR macro establishes: 1) the number of remote 3270 line groups
and 2) the common error thresholds.
7.2.2.1 Syntax
RCSBTAMR Macro
──┬─────┬──RCSBTAMR──NLINES=number──┬──────────────────────┬──
└─tag─┘ │ ┌─YES─┐ │
├─,LERB=─┴─NO──┴───────┤
├─,DELAY=number────────┤
│ ┌─2──────┐ │
├─,TMOUT=─┴─number─┴───┤
│ ┌─6──────┐ │
└─,IOEROR=─┴─number─┴──┘
tag Any valid assembler tag. It is ignored.

NLINES= Number of line groups to be controlled by Advantage
CA-Roscoe. This operand is required.
LERB= Defines whether the LERB facility should be generated for
every line group. If LERB= is omitted or specified as YES, line
error statistics are maintained by BTAM, and printed out
either when the BTAM control program has determined that
all standard LERB thresholds have been reached, or when the
Advantage CA-Roscoe operator enters an LERPRT command.
DELAY= Number of seconds that Advantage CA-Roscoe is to delay
before addressing a line that has not responded to polling.
The default is 3 seconds. If the delay is set to 0, there is no
delay in readdressing the line once control has been returned
from BTAM to Advantage CA-Roscoe.
TMOUT= Number of consecutive time outs that can occur before
Advantage CA-Roscoe records one irrecoverable error (see
IOEROR=). The default is 2.
IOEROR= Maximum number of consecutive irrecoverable I/O errors that
can occur on any remote line or cluster on a remote line
before the line or cluster is shut down. The number may be
between 1 and 255, inclusive. (Do not set the value to 0 as this
will cause unpredictable processing.) The default is 6.

7.2.2.2 Notes
■ The RCSBTAMR macro is required if remote devices are used at a BTAM

site. If RCSBTAMR is coded, it must follow the RCSGEN macro and
precede the RCSLINE, RCSCLSTR and RCSDVICE macros.
■ Error Handling:
Advantage CA-Roscoe will shut down a remote line (or cluster on a
remote line) if an uninterrupted series of irrecoverable errors is recorded
for that line (or cluster).
The most common line error is a time out. The usual cause of a time out is
a transient drop in the line connecting the TCU and a remote controller
such that no response is received from the polling. It is likely that the
modems will go out of synchronization when this occurs and will recover
quickly.
If a time out occurs, Advantage CA-Roscoe causes a processing delay of x
seconds (where x is the value of DELAY=) to occur before addressing the
line again. (This delay is in addition to the approximately 30-second delay
entailed by BTAM/TCU error recovery.) After delaying the specified
number of seconds, Advantage CA-Roscoe again addresses the line. If the
line does not respond to polling (that is, if there is not an intervening good
transmission), another processing delay occurs.
Advantage CA-Roscoe continues this procedure until the number of
consecutive processing delays equals the value specified with TMOUT=. At
that point, Advantage CA-Roscoe records one irrecoverable error.
When the number of consecutive irrecoverable errors equals the value
specified with IOEROR=, Advantage CA-Roscoe shuts the line down.
■ If the LERB= operand is omitted or specified as YES, line error statistics
are maintained by BTAM. The threshold values used by BTAM are
separate and distinct from the value used by Advantage CA-Roscoe for its
error recovery. The threshold values in the LERB, and the information
accumulated in it by the access method, are purely system programmer
information. The information may be obtained through the Advantage
CA-Roscoe Operator Command LERPRT (described in the Advantage
CA-Roscoe Interactive Environment System Commands Guide).
■ Remote 3270s are supported by BTAM in binary synchronous mode
(BSC3). The TCU is a 270x or 370x in emulation mode. Each binary
synchronous port on the TCU represents a line group. Each line can have
n clusters. Each cluster consists of a 3271 control unit with n devices, or a
3275 stand-alone unit. For definition of these terms, see the appropriate
IBM literature (BTAM SRL and 3270 Component Description manuals).

7.2.3 RCSLINE: Define a Line Group

The RCSLINE macro defines the beginning of a new line group.
7.2.3.1 Syntax
RCSLIBE Macro
──┬─────┬──RCSLINE──COUNT=number──┬─────────────────────┬─────
└─tag─┘ │ ┌─EBCDIC──┐ │
├─,CODE=─┴─USASCII─┴──┤
│ ┌─A─┐ │
├─,INTFACE=─┴─B─┴─────┤
│ ┌─A─┐ │
└─,TRAMS=─┴─B─┴───────┘

COUNT= Total number of devices in all clusters attached to the line.
This operand is required.
CODE= Transmission code used by the line group. EBCDIC is the
default, and USASCII is the only valid alternative.
INTFACE= Communications are to be through the 2701 Data Adapter
Unit's Dual Communications Interface A (default) or B. If the
TCU is not a 2701, or is not equipped with the Dual
Communications Interface, omit this operand.
TRAMS= Transmission code to be used, designated by the code A
(default) or B for the 2701 Dual Code Feature. If the TCU is
not a 2701, or if the feature is not present on the 2701, omit
this operand.
7.2.3.2 Notes
■ The RCSLINE macro must follow the RCSBTAMR macro or the final
RCSDVICE macro of the macro set defining the previous line group.
■ Each RCSLINE macro must be followed by sets of RCSCLSTR and
RCSDVICE macros, defining all clusters and devices attached to the line.
■ One RCSLINE macro must be coded for every line group to be handled by
Advantage CA-Roscoe (that is, for every UCB assignment of a BSC3 unit
defined by an IODEVICE macro at OS SYSGEN).
■ The number of RCSLINE macros in the table generation must be equal to
the value coded for the NLINES operand in the RCSBTAMR macro.
■ The line groups are identified to Advantage CA-Roscoe through the
RTERMn DD statement, where n is a numeric value that should start with
1 and be incremented by 1 for each successive RCSLINE definition.

■ The attachment of the 3270 clusters to the TCU is through a multi-point

non switched line, with appropriate modems at either end. Only 3270
system components may be attached to the line. The transmission code for
a line group may be EBCDIC or ASCII.
■ Sites that run more than one remote line group must assure that at OPEN
time the BTAM device I/O module IGG019PC is correctly loaded with
only a single copy called. This is accomplished by specifying that
IGG019PC be resident. If this is not done, results of remote 3270 activities
may be unpredictable.
7.2.4 RCSCLSTR: Define Cluster on a Line

The RCSCLSTR macro defines the start of a new cluster (control unit cluster)
on the line.
7.2.4.1 Syntax
RCSCLSTR Macro
──┬─────┬──RCLSCLSTR──number──────────────────────────────────
└─tag─┘

number Address of this cluster within the line group. This address is
used to determine the polling and selection CUAs for all
devices on the cluster. The number is the value (between 1
and 32, inclusive) corresponding to hardware addresses 0
through 31, respectively.
7.2.4.2 Notes
■ RCSCLSTR must follow either a RCSLINE macro or the final RCSDVICE

macro of the preceding RCSCLSTR definition.
■ Every cluster physically attached to the line group must be defined in
ascending order without omissions, even if the cluster contains no devices
that will be used by Advantage CA-Roscoe.
■ The cluster address is set in the hardware of the cluster control unit. If, for
example, the sixth cluster on a multi-point line is moved to a line where it
is the only cluster, either the hardware address must be changed for the
cluster control unit or the RCSCLSTR macro for the line must be coded as
RCSCLSTR 6.

7.2.5 RCSDVICE: Define a Device on the Cluster

The RCSDVICE macro defines a device attached to the current cluster.
7.2.5.1 Syntax
RCSDVICE Macro
──┬─────┬──RCSDVICE──dua──┬────────────────────┬──────────────
└─tag─┘ │ ┌─3277──┐ │
├─,TYPE=─┼─DUMMY─┼───┤
│ └─type──┘ │
│ ┌─2─────┐ │
├─,MODEL=─┴─model─┴──┤
├─,FEATUR1=feature───┤
├─,PRIMTX=row,col────┤
└─,ALTMTX=row,col────┘
tag For printers: A tag is required. It must match the name of a

printer coded in the RPS network environment definition (on
the RPSPRNTR and RPSDEST macros).
For terminals: A tag is optional. If a tag is specified, it must
match the name of a terminal coded in the RPSTERM macro,
so that the terminal will be authorized to use RPS. If RPS
default authorization is sufficient, no terminal name is
equired.
If a tag is not specified, a default name is generated. It
consists of the line number and sequence number of the
RCSDVICE under its RCSLINE. The form of the generated tag
is Nlllsss.
dua Address of this device within the current cluster. This 'device
unit address' is used to determine the polling and selection
DUA for the device. The number is a value between 1 and 32,
inclusive, and corresponds to hardware addresses 0 through
31, respectively. Every device attached to the controller of the
current cluster must be defined in ascending order without
omissions, even if the device is not one that will be controlled
by Advantage CA-Roscoe.
TYPE= Hardware type of the device, or the keyword TERMINAL or
DUMMY.
The valid hardware types are:
3262 3277 (default) 3286
327 3278 3287
3275 3279 3288
3276 3284 3289

Specify:
TERMINAL To identify 3270 type terminals that are not
identified in the preceding list.
DUMMY To generate a non-usable slot.
If TYPE= is omitted or specified as TYPE=3270 or TYPE=3277,
a 3277 Model 2 is assumed.
MODEL= Model number of the device. Valid model types are 2, 3, 4, 5
and QUERY. The default is 2.
MODEL=QUERY supports devices whose presentation size

can be altered by a local setup between Advantage CA-Roscoe
sessions or whose matrix is not the standard model 2 through
5 (that is, 3180 and 3290 device types). When QUERY is
coded, FEATUR1=QS is required and PRIMTX and ALTMTX
are ignored. QUERY may be omitted if the device's mode
does not change from session to session (for example, it is
always used as a model 2, 3, 4 or 5).
FEATUR1= The following device feature can be specified:
QS Device supports query structured fields.
PRIMTX= Number of rows and columns supported by the device when
it receives the Erase/Write command.
ALTMTX= Number of rows and columns supported by the device when
it receives the Erase/Write/Alternate command.
7.2.5.2 Notes
■ The RCSDVICE macro must follow either a RCSCLSTR macro or another

RCSDVICE macro.
■ Specifying Device Types:
When specifying device types,
– A 3275 must be the only device defined on a cluster.
– Only one 3276 may be specified per cluster and it must be the first
device on that cluster.
■ Every device on a cluster must be defined to Advantage CA-Roscoe, even
if that device type is not supported by Advantage CA-Roscoe. (Advantage
CA-Roscoe does not support devices that do not themselves support the
IBM 3270 data stream.) To define a non supported device to Advantage
CA-Roscoe, specify it as TYPE=DUMMY.

■ Using PRIMTX= And ALTMTX=:

PRIMTX and ALTMTX are needed only if the display matrix and printer
buffer sizes for the specified TYPE and MODEL differ from those listed
following.
Display Matrix
Display Display Primary Alternate

Types Model
3275 1 not supported not supported
3277 2 24x80
3276 1 not supported not supported
3278 2 24x80 24x80
3 24x80 32x80
4 24x80 43x80
5 24x80 27x132
3279 2 24x80 24x80
3 24x80 32x80
Printer Buffer Sizes
Printer Printer Primary Alternate

Types Model
3262 1 12x40 (480) 12x80 (960)
3287 2 24x80 (1920) 24x80 (1920)
3289 3 24x80 (1920) 32x80 (2560)
4 24x80 (1920) 43x80 (3440)
5 24x80 (1920) 27x132 (3564)
3284 1 12x40 (480)
3286 2 24x80 (1920)

7.2.6 RCSGEND: End Communication Network Definition

The RCSGEND macro terminates the communications definition.
7.2.6.1 Syntax
RCSGEND Macro
──┬─────┬──RCSGEND────────────────────────────────────────────
└─tag─┘
7.2.6.2 Notes
■ The RCSGEND macro must be the last macro coded and must not be
followed by the assembler END declarative.
■ The RCSGEND macro prints out either an error text pointing to previously
flagged incorrect macro definitions or an analysis of all resources defined
by the macros that preceded it.

7.3 JCL to Assemble and Link Edit

After the RCS macros are defined, they must be assembled and link edited into
the RO60LIB Advantage CA-Roscoe target library. This is accomplished by the
RECEIVE and APPLY of product USERMOD MRO6012, which is found in the
installation sample JCL library.
A sample RCS definition is placed in member RCSDEF in the RO60OPT data

set by the SMP/E APPLY of the base Advantage CA-Roscoe function SYSMOD
CRO6000.
The process to install MRO6012 has the following basic steps:

■ Modify the RCSDEF source in RO60OPT to meet your requirements.
■ Execute the product USERMOD. This will initiate an SMP/E RECEIVE and
APPLY. During the APPLY an assembly and link will take place which
will put an executable copy of RCSDEF into target library RO60LIB.
Note: Sites that are using VTAM, local BTAM, TTYS, XTPM or batch devices
can use the distributed RCS network definition, which is distributed in
the RO60LIB as member RCSDEF.

7.4 Sample RCSDEF Definition

The following example defines a site using both VTAM and BTAM. (The local
BTAM devices are defined through DD statements in the Advantage
CA-Roscoe JCL.)
The remote BTAM devices are defined through the following RCS definition
and by DD statements in the Advantage CA-Roscoe JCL. (One DD statement is
required for each remote line.)
■ The first line has two clusters. The first cluster consists of one terminal; the
second cluster consists of two terminals and one printer.
■ The second line also has two clusters. The first cluster consists of a
terminal. (Its hardware type is not included in the list of valid type and it
is a queriable terminal.) The second cluster consists of four terminals, one
of which is not to be used by Advantage CA-Roscoe.
Sample RCS Definition
RCSDEF RCSGEN AMETHS=(VTAM,BTAMR,BTAML)

SAMPLE1 RCSBTAMR NLINES=LERB=YES, X
DELAY=2,TMOUT=3,IOERROR=5
LINE1 RCSLINE COUNT=4,CODE=EBCDIC
CLUSTER1 RCSCLSTR 1
DEVICE1 RCSDVICE 1,TYPE=3278,MODEL=4
CLUSTER2 RCSCLSTR 2
DEVICE4 RCSDVICE 3,TYPE=3286
LINE2 RCSLINE COUNT=5,CODE=EBCDIC
CLUSTERA RCSCLSTR 1
DEVICEA RCSDVICE 1,TYPE=TERMINAL,MODEL=QUERY
CLUSTERB RCSCLSTR 2
DEVICEB RCSDVICE 1,TYPE=3278,MODEL=4
DEVICEC RCSDVICE 2,TYPE=DUMMY
DEVICED RCSDVICE 3,TYPE=3278,MODEL=4
DEVICEE RCSDVICE 4,TYPE=3278,MODEL=4
RCSGEND

7.4.1 Notes
■ The error recovery defined in the RCSBTAMR macro states that if a line or
cluster error should occur:
1. Advantage CA-Roscoe will wait two seconds before attempting to
address the line again. (This is in addition to the approximate 30
second delay entailed by BTAM/TCU error recovery.) If the line does
not respond, Advantage CA-Roscoe will again wait before polling
again.
2. Advantage CA-Roscoe repeats step 1 until the number of consecutive
delays equals 3 (the value specified with TMOUT). Advantage
CA-Roscoe then records one irrecoverable error.
3. When the number of consecutive irrecoverable errors equals 5 (the
value specified with IOERR), Advantage CA-Roscoe will shut the line
down.

Chapter 8. ROSCOE Printing Services (RPS)
The ROSCOE Printing Services (RPS) allow Advantage CA-Roscoe users to

print data at a 328x type printer or a system printer. To do this, sites must
define one or more printing network environments.

■ An overview of specific external and internal components of RPS, plus
definitions of RPS specific terms.
■ How to define an RPS printing network environment. This includes:
– Descriptions of the macros used to define an environment.
– Sample JCL that can be used to assemble and link edit an RPS
definition.
– Sample RPS definitions.
Chapter 8. ROSCOE Printing Services (RPS) 8-1

8.1 RPS Overview
8.1 RPS Overview

The commands provided with RPS allow individuals to schedule, monitor and
control the printing of data at specific printing locations. The data may consist
of the contents of the following:
■ Currently displayed screen
■ AWS
■ One or more library members or the Library Selection List
■ Currently attached job output file
■ Currently attached data set object
The Advantage CA-Roscoe Interactive Environment User Guide contains an

overview of how the RPS related commands may be used.
The Advantage CA-Roscoe Interactive Environment Command Reference Guide

contains detailed descriptions of each command available to all Advantage
CA-Roscoe users.
The Advantage CA-Roscoe Interactive Environment System Commands Guide

contains detailed descriptions of those commands that can only be issued by
individuals assigned privileged user IDs, or by individuals designated as
having alternate control authorization.
8.1.1 Operational Overview

■ During initialization, the RPSCSECT= initialization parameter is used to
determine which RPS printing network environment definition is to be
used. If this parameter is omitted or specified with no definition, RPS is
unavailable for this execution of Advantage CA-Roscoe.
If an invalid definition is specified, RPS is disabled until a PRINT START
or RPS START command is issued that identifies a valid definition.
If during the execution of Advantage CA-Roscoe, it becomes necessary to:
– Terminate RPS - Individuals assigned privileged user IDs or the
operator can issue the PRINT STOP or RPS STOP command.
– Change the definition - Individuals assigned privileged user IDs or the
operator can do so by issuing the PRINT RESTART or RPS RESTART
command with the appropriate definition.
Note: The commands listed previously are described in the Advantage
CA-Roscoe Interactive Environment System Commands Guide.

8.1 RPS Overview
■ When a terminal user executes the PRINT command, RPS first validates
the user's entry. If an error is detected (that is, an invalid destination is
specified), a message is returned to the user. If no error is detected, a copy
of the data to be printed is spooled to an RPS library member and an entry
is added to the print request queue. (Data that is scheduled for printing is
called a print request.) The print request queue keeps track of each
scheduled print request.
The actual printing takes place as a subtask of Advantage CA-Roscoe.
This frees the terminal for other work while print requests are being
serviced.
If an I/O error is detected during printing, the terminal user is not
notified. Advantage CA-Roscoe will retry the failing operation. If the error
is cleared, printing resumes. If the error is not cleared, the request is either
discarded or requeued (depending on the DISP= operand of the RPSGEN
macro). If the request is requeued, it is placed in the hold queue and must
be: 1) released when the printer is fixed, or 2) canceled if the user does not
wish to wait. The printer is released back to VTAM. Subsequent requests
that require the failed printer cause RPS to attempt reconnection. This will
occur when a new request is scheduled or a held request is released.
Note that at the beginning of each logical page of a request, the status of
the request is checkpointed. This is done to facilitate a warm start of RPS
and to allow the release of the request that may subsequently be held.
8.1.2 Advantage CA-Roscoe JCL Considerations

Review the descriptions of the RPS-related Advantage CA-Roscoe initialization
parameters in the Advantage CA-Roscoe Interactive Environment Programs and
Utilities Guide.
Also, review the description of the Advantage CA-Roscoe initialization

parameter ACCTREC= to determine whether accounting records are to be
gathered. These records contain information about how this facility is being
used at the site. Advantage CA-Earl, as described in the Advantage CA-Roscoe
Interactive Environment Programs and Utilities Guide, can be used to produce this
report.

8.1 RPS Overview
8.1.3 Definition of Terms

Destination One system printer or one or more 328x type printers that
are to be referenced by a single name.
When multiple 328x type printers are associated as a single
destination, the printers should be physically near each
other. If a user directs a request to that destination, the
request will be printed at the first available printer defined
as part of the destination.
Destination List One or more destinations that are to be referenced by a
single name.
Request Data (for example, a spool member and associated queue
element) that is to be printed for a terminal user.

8.2 328x Type Printer Considerations

This section describes specific VTAM and BTAM access method considerations
that should be reviewed when 328x-type printers will be used by RPS.
8.2.1 VTAM Considerations

■ Sharing printers between VTAM applications:
By default, RPS uses a VTAM RELREQ exit which is entered when a

printer is required by another VTAM application. RPS releases the printer
when all pending work for the printer is completed. When a new request
arrives, RPS attempts to acquire the printer by issuing a SIMLOGON
through VTAM. If the controlling application does not release the printer,
RPS can never acquire it.
Note:
– VTAM/CICS sites: To allow printers or terminals to be shared
with RPS, the CICS macro DFHTCT must include
RELREQ=(YES, YES).
– VTAM/IMS sites: An option similar to the CICS option must be
used when generating IMS.
When defining their printing network environment, sites have the option
of designating that specific printers are to be released to VTAM
immediately following the completion of the last print request waiting to
print at those printers.
■ Sharing printers with the local hardware copy function in an SNA
environment:
RPS brackets an entire print request. (The local copy is disabled during the
printing of an RPS request. Conversely, RPS waits for any active or queued
local copy request to complete before starting to print its request.) Sites
must ensure that their 3274 controllers have been optioned for
Between-Bracket-Sharing. (3276 controllers are hardwired for this.)
■ Sharing printers with the local hardware copy function in a non-SNA or
BTAM environment:
Not supported. The printer must not be used for local copy if the integrity
of the RPS printout is to be maintained.
■ Multi System Networking Facility (MSNF):
RPS issues a SIMLOGON to acquire a printer. Therefore, RPS depends on
there being a valid mode table entry and terminal definition for the printer
in the domain in which Advantage CA-Roscoe is executing. Sites using
MSNF must ensure that the appropriate cross domain resources and path
statements have been added to the VTAM definition.

8.2.2 BTAM Considerations

RPS supports both remote and local BTAM printers.
■ Remote printers are defined to RPS by their tag names specified in the
appropriate RCSDVICE macros. See the chapter on 'ROSCOE
Communication Services' for details.
■ Local printers are defined to RPS by their DD names as specified in the
Advantage CA-Roscoe JCL. (See the Advantage CA-Roscoe Interactive
Environment Programs and Utilities Guide for additional information.)
Advantage CA-Roscoe does not share terminals or printers between BTAM

applications. These devices are dedicated to Advantage CA-Roscoe use
throughout the current Advantage CA-Roscoe execution.
Note: The local copy function may cause unpredictable results and its use is
not recommended.

8.3 Establishing a Printing Network Environment

A printing network environment must be defined to use RPS. (A printing
network environment consists of assigning all appropriate printers to
'destinations' and then determining which destinations are to be accessible
from the site's terminals.)
Use the RPS macros, distributed in the RO60MAC target library, to define a
printing network. Once the network is defined, assemble it to create an RPS
definition. The definition must then be established as a unique member on the
RO60LIB target library.
A sample RPS definition and the JCL needed to assemble and link edit it is
added to the library of the individual assigned the RO prefix during
Advantage CA-Roscoe installation. (A copy of this member is also distributed
on the RO60OPT target library.) In both cases, the member name is #RPSENV.
Also, sample JCL and examples of the RPS macros are presented at the end of
this chapter.
The RPS macros must be coded in the order listed below:

RPSGEN Defines the global parameters.
RPSPRNTR Identifies features and attributes of 328x type printers that
differ from the RPS defaults.
JESPRNTR Identifies features and attributes of system printers that differ
from the RPS defaults.
RPSDEST Identifies:
1. The printers that are to comprise a destination and
establishes attributes for that destination.
2. Any alias assigned to a destination.
RPSDLIST Groups one or more destinations.
RPSTERM Identifies the terminals that are to be authorized to use RPS
and associates those terminals with a destination or group of
destinations.
RPSGEND Terminates the printing network environment definition.

A site may define multiple RPS definitions. The Advantage CA-Roscoe

initialization parameter RPSCSECT= identifies the name of the definition that
is to be used for that execution of Advantage CA-Roscoe.
If a site is executing multiple Advantage CA-Roscoes concurrently, the JCL for

each Advantage CA-Roscoe must include:
■ The RPSCSECT= initialization parameter identifying the name of the
printing network environment definition to be used. (Each Advantage
CA-Roscoe may use a unique or common definition.)
■ The RPSPREFIX= or RPSKEY= initialization parameter to identify the UPS
prefix or sign-on key that is to be used as the RPS spool queue. If the
multiple Advantage CA-Roscoes are sharing the same user libraries, the
UPS profile used as the spool queue must be unique for each Advantage
CA-Roscoe.
8.3.1 RPSGEN: Start the Network Definition

The RPSGEN macro defines information that is global to RPS. It must be the
first macro coded.
8.3.1.1 Syntax
RPSGEN Macro
──┬─────┬──RPSGEN──┬──────────────────────────┬───────────────
└─tag─┘ ├─,DLIST=destlistname──────┤
├─┬─,────────────────────┬─┤
│ │ ┌─RPS─┐ │ │
│ ├─Prefix=─┴─pfx─┴──────┤ │
│ │ ┌─ROSCOE.RPS─┐ │ │
│ └─KEY=─┴─key────────┴──┘ │
│ ┌─1─┐ │
├─,QSIZE=─┴─nn──┴──────────┤
├─,SPOOLIM=lines───────────┤
│ ┌─Q────┐ │
├─,DISP=─┴─disp─┴──────────┤
│ ┌─18─┐ │
└─,TIMEOUT=─┴─time─┴───────┘
tag If specified, the name must be #RPSENV.

DLIST= Tag (for example, destlistname) of the RPSDLIST macro that
defines the site default destination list.
PREFIX= Prefix associated with the user profile that is to be used as the
RPS spool queue. The default is RPS.
KEY= Sign on key associated with the user profile that is to be used
as the RPS spool queue. The default is ROSCOE.RPS.

QSIZE= Decimal value indicating the maximum number of print

requests that are to be queued. The minimum is 2 and the
maximum is 500. The default is 100.
SPOOLIM= Maximum number of lines allowed in the RPS spool at any
one time. This allows sites to specify how much of the
Advantage CA-Roscoe library can be used by RPS. The default
is no limit.
DISP= Action to be taken if a permanent printer error occurs. Specify:
NOQ Discard the request.
Q (Default.) Requeue the request that is active on the
printer when the error occurs.
TIMEOUT= Number of elapsed seconds permitted before RPS disables a
non-SNA printer in an intervention required state. If a request
had been printing, it is handled by the DISP parameter. The
default is 1800 seconds (for example, 30 minutes).
8.3.1.2 Notes
■ RPS Spool Queue Identification:

Sites have the option of identifying the UPS profile that is to be used as
the RPS spool queue by its prefix sign on or key. If neither is specified, the
default prefix (RPS) and the default sign on key (ROSCOE.RPS) are
assumed. Advantage CA-Roscoe initialization parameters (described in the
Advantage CA-Roscoe Interactive Environment Programs and Utilities Guide)
can be used to override these defaults on a per execution basis.
■ Multiple RPS Definitions:
A site may define one or more RPS definitions as long as each definition
has a unique name (for example, tag).
Sites executing multiple Advantage CA-Roscoes can either: 1) share the
same RPS definition, or 2) use a unique definition with each Advantage
CA-Roscoe.
If the user libraries are being shared by multiple, concurrently executing
Advantage CA-Roscoes, each definition must use the PREFIX= or KEY=
operand of the RPSGEN macro to identify a unique sign-on key. (If the
user libraries are not being shared, the sign on key need not be unique.)
See the preceding section for additional information.
■ Default Destinations:
If a site default destination list is specified, terminals not explicitly
assigned to a destination list use the default destination list. If a site
default destination list is not specified, RPS commands are not accepted
from unassigned terminals.

8.3.2 RPSPRNTR: Define 328x Type Printer Features

The RPSPRNTR macro is optional. Define it only when 328x-type printer
features and attributes differ from the RPS defaults.
8.3.2.1 Syntax
RPSPRNTR Macro
┌─,───┐
pname┴──┬──────────────────────┬────────
──┬─────┬──RPSPRNTR───
└─tag─┘ ├─,PRTDESC=description─┤
├─,DLOGMOD=name────────┤
│ ┌─,─┐ │
├─,CPEJECT=(─┴─x,y─┴─)─┤
│ ┌─,──┐ │
code┴─)──┤
├─,FEATUR1=(──
│ ┌─66─┐ │
├─,PAGLN=─┴─n──┴───────┤
│ ┌─132─┐ │
├─,PAGWD=─┴─n───┴──────┤
│ ┌─132─┐ │
├─,MPP=─┴─n───┴────────┤
│ ┌──┐ │
├─,TM=─┴─n─┴───────────┤
│ ┌──┐ │
├─,BM=─┴─n─┴───────────┤
├─,CHAR=string─────────┤
└─,CMPRESS=compress────┘

pname Name of printers to which the following features and
attributes are applicable, where:
VTAM Use the name associated with the VTAM LOCAL, LU
or TERMINAL macros.
Local BTAM
Use the DD name of the printer as it appears in the
Advantage CA-Roscoe JCL (for example, PRNTnnMX
DD).
Remote BTAM
Use the name associated with the RCSDVICE macro
used to define the printers.
The only limit in the number of printers that may be
identified per RPSPRNTR macro is that imposed by
the assembler.
PRTDESC= 1 to 32 character description of printers defined through this
macro. If the description includes spaces, it must be delimited.

DLOGMOD= Eight character name which is to be used to access an entry in

the VTAM logon mode table. (This operand overrides the
DLOGMOD entries for all printers identified through this
macro.)
CPEJECT= Controls line skipping. If omitted, the default is (0,0). Specify:
x Two-digit value indicating the number of lines to be
skipped between: 1) the starting separator and the
start of the text and 2) the end of the text and the
trailing separator. Zero causes an eject to the top of a
new page.
y Two-digit value indicating the number of lines to be
skipped between the trailing separator and the next
starting separator. Zero causes an eject to the top of a
new page.
FEATUR1= One or more of the following printer or printing features can
be specified:
CR Printer hardware recognizes a carriage return without
a line feed, for overprinting operations.
FF Printer supports form feed control character.
REL VTAM printers are to be released to VTAM
immediately upon completion of the last print
request waiting to print at the specified printer. If
omitted, Advantage CA-Roscoe retains ownership of
the printer until another application requests it
through a RELRQ.
SC Shared local hardware copy functions. This causes
RPS to issue a form feed (if the FF and CR codes are
specified) before and after each request to realign to
top of form in case a local copy was done between
RPS requests.
SHIFT RPS output lines are shifted one position to the right
to allow for compatibility with printers aligned for
CA-ETC output. The 1-column shift compensates for
the column of periods printed by CA-ETC for forms
alignment. Note: CA-ETC need not be running under
Advantage CA-Roscoe to use this feature.
The following three operands are mutually exclusive.
NOSEP Do not print starting and trailing separator pages.
RSEP Print separator pages. However, the user can
suppress them by including the NOSEP operand
with the PRINT command.

SEP CPEJECT= determines the printing of separator

pages.
If the CPEJECT x value is specified as 0, separator
pages are always printed. If the value is other than
0, the user can override the separators by including
the NOSEP operand with the PRINT command.
PAGLN= Two-digit value indicating the length of the paper normally
used at the printer. Specify a value between 1 and 99. If
omitted, the default is 66.
PAGWD= Three digit value indicating the width of the paper normally
MPP= Three digit value indicating the hardware defined maximum
print position. Specify a value between 1 and 255. If omitted,
the default is 132.
TM= Two digit value indicating the number of lines to be skipped
from the top of the page before printing begins (for example,
the top margin). Specify a value between 1 and 99. If omitted,
the default is 0.
BM= Two digit value indicating the number of lines that are to
remain blank at the bottom of each page (for example, the
bottom margin). Specify a value between 1 and 99. If omitted,
the default is 0.
CHAR= Language code (not exceeding 24 characters in length)
indicating the character set that the printer uses. If omitted or
if an unsupported code is specified, the site's default language
character set is assumed. (See the Advantage CA-Roscoe
Interactive Environment Programs and Utilities Guide for a list of
the valid language character set codes.)
CMPRESS= Designate whether or not data stream compression is to occur.
If omitted, the default is YES. Specify:
YES To have DSC and SCS data stream compression.
NO To prevent data stream compression.
8.3.2.2 Notes
■ PRTDESC= Operand:
The printer description defined through this macro is included in the
display produced when the PRINT DEVICE command is used to provide
information about a specific printer.

■ DLOGMOD= Operand:
When DLOGMOD= is specified, the override applies to all printers named
in the macro. If the override is to apply to an individual printer, specify
the DLOGMOD name with the RPSDEST macro.
See the IBM VTAM Installation Guide for a description of the logon mode
table.
■ FEATUR1= Operand:
– CR is provided for devices that have an added capability for carriage
return without line feed.
– If FF is specified, a form feed character is used in page eject operations
instead of issuing multiple line feeds.
– If SHIFT is specified and if the paper width (PAGWD) is less than 83,
no separator pages are printed. If SHIFT is omitted and the paper
width is less than 82, no separator pages are printed.
■ CMPRESS= Operand:
CMPRESS=NO should be specified if: 1) the printer's dlogmod does not
allow for compression, or 2) the printer cannot handle compressions
possibly as a result of a hardware problem.
■ Physical Page Size vs. Print Lines
Use PAGLN= to designate the physical length of the paper that is
normally used at the printer.
Use BM= and TM= to designate the default number of lines that are to be
printed per page. Note that:
– The sum of TM= and BM= may not equal or exceed the value of
PAGLN=.
– The user can use the TM or BM operands of the PRINT command to
override these values for a single print request.
■ Physical Printer Width vs. Paper Width
Use MPP= to define the maximum print position currently set by the
hardware device.
Use PAGEWD= to define the width of the paper that is normally used at
that printer. Note that the value specified with PAGEWD= must be less
than or equal to the value specified with MPP=.
■ Separator Pages:
RPS produces default separator pages. Sites have the option of changing
these pages through the RPS exit (RPSEXIT) described in the Advantage
CA-Roscoe Interactive Environment Extended Facilities for System Programmers
Guide.

8.3.3 JESPRNTR: Define System Printer Features

The JESPRNTR macro is optional. Define it only when system printer features
and attributes differ from the RPS defaults.
8.3.3.1 Syntax
JESPRNTR
┌─,───┐
pname┴──┬─────────────────────────┬─────
──┬─────┬──JESPRNTR───
└─tag─┘ ├─,PRTDESC=description────┤
│ ┌──┐ │
├─,CPEJECT=─┴─n─┴─────────┤
│ ┌─SEP────┐ │
│ │ ┌─,──┐ │ │
code┴─┴─)─┤
├─,FEATUR1=(─┴──
│ ┌─66─┐ │
├─,PAGLN=─┴─n──┴──────────┤
│ ┌─132─┐ │
├─,PAGWD=─┴─n───┴─────────┤
│ ┌──┐ │
├─,TM=─┴─n─┴──────────────┤
│ ┌──┐ │
├─,BM=─┴─n─┴──────────────┤
└─,CHAR=string────────────┘

pname Name of printers to which the following features and
attributes are applicable.
Each JES name may be 1-255 characters in length.
The only limit in the number of printer names that may be
identified per JESPRNTR macro is that imposed by the
assembler.
PRTDESC= One-32 character description of printers defined through this
macro. If the description includes spaces, it must be delimited.
CPEJECT= Two-digit value indicating the number of lines to be skipped
between: 1) the starting separator and the start of the text and
2) the end of the text and the trailing separator. If omitted, the
default is 0. (Zero causes an eject to the top of a new page.)
FEATUR1= One or more of the following printer or printing features can
be specified:
BURST Printer supports bursting. (Bursting occurs only if
the user specifies the BURST operand with the
PRINT command.) The following three operands
are mutually exclusive.
NOSEP Do not print starting and trailing separator pages.

RSEP Print separator pages. However, the user can

suppress them by including the NOSEP operand
with the PRINT command.
SEP CJEJECT= determines the printing of starting and
trailing separator pages (default).
If CPEJECT= is specified as 0, separator pages are
always printed.
If CPEJECT= is a value other than 0, the user can
override the separators by including the NOSEP
operand with the PRINT command.
PAGLN= Two digit value indicating the length of the paper normally
PAGWD= Three digit value indicating the width of the paper normally
TM= Two digit value indicating the number of lines to be skipped
from the top of the page before printing begins (for example,
the top margin). Specify a value between 1 and 99. If omitted,
the default is 0.
BM= Two digit value indicating the number of lines that are to
remain blank at the bottom of each page (for example, the
bottom margin). Specify a value between 1 and 99. If omitted,
the default is 0.
CHAR= Language code (not exceeding 24 characters in length)
indicating the character set that the printer uses. If omitted or
if an unsupported code is specified, the site's default language
character set is assumed. (See the Advantage CA-Roscoe
Interactive Environment Programs and Utilities Guide for a list of
the valid language character set codes.)
8.3.3.2 Notes
■ PRTDESC= Operand:
The printer description defined through this macro is included in the
display produced when the PRINT DEVICE command is used to provide
information about a specific printer.
■ Physical Page Size vs. Print Lines:
Use PAGLN= to designate the physical length of the paper that is
normally used at the printer.
Use BM= and TM= to designate the number of lines that are to be printed
per page. Note that:

– The user can use the TM and BM operands of the PRINT command to
override these values for a single print request.
– The sum of TM= and BM= may not equal or exceed the value of
PAGLN=.
■ Separator Pages:
RPS produces default separator pages. Sites have the option of changing
these pages through the Banner Page Exit (BANEXIT) described in the
Programmers Guide.
8.3.4 RPSDEST: Define Destinations

The RPSDEST macro is required. It identifies printers that are to be associated
with a specific destination and establishes attributes for that destination. It can
also be used to establish a destination as an alias for another destination.
8.3.4.1 Syntax
RPSDEST Macro
──destname──RPSDEST────────────────────────────────────────────
──┬────────────────────────────────────────┬───────────────────
│ ┌─,──────────────────────────────────┐ │
(pname1─┬─────────┬──┬───────────┬─)┴─┤
├──
│ └─,class1─┘ └─,dlogmod1─┘ │
├─┬─────────────────────┬────────────────┤
│ ├─,DEFCLAS=n──────────┤ │
│ │ ┌─NETWORK─┐ │ │
│ ├─,TYPE=─┴─JES─────┴──┤ │
│ ├─,DESC=description───┤ │
│ ├─,REJ=n──────────────┤ │
│ ├─,COPYLIM=n──────────┤ │
│ │ ┌─,─┐ │ │
aca┴─)──────┘
│ └─,ACA=(── │
└─ALIAS=destination──────────────────────┘
destname Name to be assigned to this destination. The name must be

unique within this destination, must be 1-8 characters in
| length, and must begin with an alphabetic or national
| character. (Sites accessing CA-ETC or CA-eMAIL+ through
Advantage CA-Roscoe must limit the name to a maximum of
four characters in length.)
pname Name of the printers to be associated with this destination.
With 328x Type Printers:
A maximum of 32 printer names may be specified per
RPSDEST macro, where:

VTAM Use the name associated with VTAM LOCAL, LU or

TERMINAL macros.
Local BTAM
Use the DD name of the printer as it appears in the
Advantage CA-Roscoe JCL (for example, PRNTnnMx
DD).
Remote BTAM
Use the name associated with the RCSDVICE macros
used to define the printers.
With System Printer:
Only one name or the keyword 'LOCAL' may be specified per
RPSDEST macro.
class Any combination of classes valid for the type of printer being
defined. The allowable classes are: 0 through 9, A through Z,
#, $ and @.
A maximum of eight classes may be assigned to a printer. If
more than one class is assigned to a printer, the classes must
be contiguous (for example, (PRT1,A4 ). If no classes are
assigned, the value associated with DEFCLAS= is used.
dlogmod (Use with 328x type VTAM printers.) 8 character name that
will be used to access an entry in the VTAM logon mode
table. This operand will override, for this printer, any
DLOGMOD operand specified on a preceding RPSPRNTR
macro or in the VTAM generation.
DEFCLAS= The print class that is to be used if the user issues a PRINT
command which does not include a print class. One of the
allowable classes 0-9, A-Z, #, $, or @ may be specified. If
omitted, the default is:
Class 0 (for requests directed to 328x-type printers), or
Class A (for system printers).
TYPE= Identify the type of printer(s) defined through this macro as:
JES This macro defines a single system printer.
NETWORK This macro defines 1 to 32 328x type printers.
If omitted, the default is NETWORK.
DESC= Description of destination that does not exceed 28 characters
in length and is bound by apostrophes. (This description is
displayed with the information supplied by the PRINT
LOCATION command.)

REJ= Maximum number of records allowed to be queued per

request. Specify a value between 1 and 999999.
If specified and the user exceeds this limit, the user receives
an explanatory message.
If omitted, there are no rejection criteria aside from the spool
limit size established by the SPOOLIM operand of the
RPSGEN macro.
COPYLIM= Maximum number of copies of a request that can be printed at
the destination. Specify a value between 1 and 255.
If specified, each copy of the request cannot exceed the REJ
limit.
If omitted, the total of all records for all copies of a request
cannot exceed the REJ limit.
ACA= Prefixes of the individuals to be allowed alternate control
authorization privileges. The maximum number of individuals
is limited by the assembler constraints on sublists. This
operand allows Advantage CA-Roscoe users, in addition to
individuals assigned privileged user IDs, to execute the RPS
privileged commands for this destination. The same prefix
may be assigned to more than one destination.
ALIAS= Tag of a previously coded RPSDEST macro. This destination
will become an alias for a previously defined destination.
8.3.4.2 Notes
■ Destinations:
A destination can consist of one or more printers. (The same printer may
not be assigned to more than one destination.)
– System Printers:
Only one system printer may be assigned to a destination.
– 328x Type Printers:
One or more 328x-type printers may be assigned to a destination.
The printers do not have to be attached to the same cluster controller
as the terminal issuing a request or to the same cluster controller as
other printers assigned to the same destination.
Each destination is managed as a pool of printers; a print request will
print on the first available printer at the destination. (If the user
specified a class, the request will print on the first available printer at
the destination that matches the specified class.)
Since users usually print to a destination, the printers at a destination
should be physically near each other.

■ Dlogmod Override:
If a DLOGMOD= operand is specified with RPSPRNTR, it is overridden by
the dlogmode name specified with this macro.
See the IBM VTAM Installation Guide for a description of the VTAM logon
mode table.
■ Print Classes:
One or more classes may be assigned to each printer. One of these classes
or a different class may be assigned as the default print class (through
DEFCLAS=). If the user issues a PRINT command with:
– No print class - the appropriate default class is used.
– A print class - the designated class is used.
WARNING
If the user specifies a valid class that is not defined for one of the
printers at that destination, the print request is placed in a READY
state and stays there until the designated class becomes valid for a
printer at that destination. For example, if the RPSDEST macro
contains:
SAMPLE RPSDEST PRT1,AZ,...DEFCLAS=B
and the user enters:
PRINT DEST SAMPLE CLASS C
The request is accepted because C is a valid class code; however, it
cannot be printed because the class is not defined for the printer at
that destination.
– If classes are established, it is suggested that a HELP member

describing each of the classed be created.
– Alternate Control Accounts (ACAs):
Individuals designated by the ACA= operand can issue the privileged
RPS commands/operands at those destinations to which their prefixes
have been associated. The same individual may have alternate control
authorization at multiple locations by coding that individual's prefix in
the ACA= operand of more than one RPSDEST macro. (The ACAs are
in addition to privileged user IDs.)
– Creating an Alias:
A destination may be assigned an alias through the ALIAS= operand.
If ALIAS= is used:
1. Do not include any other operands.
2. Place the RPSDEST macro establishing the alias immediately after
the RPSDEST macro defining the destination.

ALIAS= is useful when a site wants to: 1) create a destination that

combines the printers from two or more previously used destinations,
and 2) still allow their terminal users to refer to the now non-existent
destinations.
Example: Assume that users have been printing data the destinations
A1, B1 and C1 and the site wants to combine the printers from these
destinations into the single destination D1. The following definition
allows the users to continue to reference the destinations with which
they are familiar:
D1 RPSDEST printer definition
A1 RPSDEST ALIAS=D1
B1 RPSDEST ALIAS=D1
C1 RPSDEST ALIAS=B1
Notice that the destination identified as C1 is an alias for the
destination identified as B1 and that B1 is itself an alias for D1.
8.3.5 RPSDLIST: Destination List Generation

The RPSDLIST macro defines a list of one or more destinations that can be
referenced by a single name. (The name can then be used with the DLIST
operand of the RPSGEN and RPSTERM macros.)
8.3.5.1 Syntax
RPSDLIST Macro
┌─,──────┐
destname┴──┬────────────
──destlistname──RPSDLIST──┬──┬────┬───
│ └─,─┘ │
└─NONE─────────────────┘
destlistname Name to be assigned to the destination list. The name must

be unique, not duplicate a printer name and be 1 to 8
characters in length.
destname Specify one or more of the following:
destname Tag of a previously coded RPSDEST macro. The
only limit on the number of destnames is that
imposed by the assembler.
The first destname coded becomes the default
printing destination. To suppress the default
destination, specify zero as the destination name.
Zero will require the terminal user to specify a
destination when issuing the PRINT command. If
specified, it must be the first operand in the list.
NONE Terminals that reference this destlistname are
specifically excluded from using RPS. If specified,
it must be the only operand coded.

8.3.5.2 Notes
■ The RPSDLIST macro must follow all of the RPSDEST macros that are to
be included in the destination list.
Aside from the constraints imposed by the assembler, RPSDLIST permits
an unlimited number of destination names to be specified.
■ Using the destlistname:
When the destlistname of this macro is specified with the DLIST operand
of the:
– RPSGEN macro - This destination list becomes the default destination
list (for example, this is the printing location that will be used by any
terminals that are not explicitly assigned a destination).
– RPSTERM macro - This destination list becomes the explicit destination
list for all terminals defined with that RPSTERM macro. If multiple
destnames are specified, the first is the default (for example, the
destination used when a user enters PRINT with no DEST operand).
To use the other destinations in the list, the user must include the
DEST operand with the PRINT command.
(The RPSTERM macro permits a maximum of 16 destinations to be
explicitly assigned to a terminal; the RPSDLIST macro has only the
assembler limit on the number of destination names that can be
specified.)
8.3.6 RPSTERM: Terminal Authorization

The RPSTERM macro associates one or more terminals with one or more
printing destinations.
8.3.6.1 Syntax
RPSTERM Macro
┌─,───────┐
┬───────┬┴────────────────────
──termlistname──RPSTRERM──tname──
└─tname─┘
──┬────────────────────────────────────────┬───────────────────
├─,DLIST=destlistname─┬───────────────┬──┤
│ └─,DEF=destname─┘ │
│ ┌─,──────────┐ │
┬──────────┬┴─)───────┘
└─,DEST=(destname──
└─destname─┘
termlistname Name that is to be used to identify this group of terminals

and their destinations. The name must not duplicate a
destname, destlistname, terminal name or printer name.
tname Name of the terminal to be associated with the destination list.

VTAM Use the name associated with VTAM LOCAL,

LU or TERMINAL macros.
Local BTAM Use the DD name as it appears in the
Advantage CA-Roscoe JCL (for example,
TERMnn or TERMnnMx).
Remote BTAM Use the name associated with the RCSDVICE
macros used to define terminals.
XTPM Use the appropriate VTAM or BTAM terminal
ID to identify the terminals assigned to CICS,
TSO or another Advantage CA-Roscoe.
The name may include the wildcard characters:
? To represent any single character.
* To represent none, one or more characters.
+ 40 to represent none, one or more trailing characters.
DLIST= Destlistname of a previously coded RPSDLIST macro. (All of
the terminals identified in the current macro are associated
with the destination list specified in a previously coded
RPSDLIST macro.)
DEF= Destname of a previously coded RPSDEST macro. If this
operand is not coded, the default destination for these
terminals will be the first destination specified in the
RPSDLIST macro identified by the DLIST operand. This
operand can be used to override the default destination.
DEST= Destinations that the terminals can use, specified as:
destname
Tag of a previously coded RPSDEST macro. A
maximum of 16 destnames can be specified per
RPSTERM macro. The destination identified by the
first destname becomes the default destination for
the specified terminals.
NONE Specifically excludes the specified terminals from
using RPS.
8.3.6.2 Notes
■ Maximum Values:
– The maximum number of terminals that can be specified per
RPSTERM macro is restricted to the number of positional parameters
allowed by the assembler.
– A maximum of 5,000 terminals can be specified among all RPSTERM
macros.
■ Undefined Terminals:

If a terminal is not explicitly assigned a destination (for example, its tname

is not included in any RPSTERM macro), the site default destination list is
assumed.
If the majority of terminals at a site are to use the same destination, those
terminals need not be defined (through RPSTERM) if that destination is
defined in the site default destination list.
If a site default destination list is not specified, RPS commands are not
accepted from undefined terminals.
■ Using Wildcard Characters:
Multiple terminal names containing wildcard characters may be specified
in the same RPSTERM macro. Also, multiple RPSTERM macros may
contain terminal names which include wildcard characters. Wildcard
characters are useful when the names of multiple terminals contain a
common string of characters. For example, if the macro is specified as:
RPSTERM HCS,DLIST=...
all terminals whose names begin with 'HCS' will be associated with the
printing destinations identified by DLIST=.
When multiple terminal names containing wildcard characters are used,
the names should be defined so that the most specific names precede the
more general ones, as in:
RPSTERM HDSE,...
RPSTERM HDS,...
If these two macros were reversed, requests from the terminal identified as
HDSE320N may print at the wrong location.
■ Using the DLIST operand vs. the DEST operand:
Use the DLIST operand, instead of the DEST operand, when:
– More than 16 destinations are to be assigned to the terminals identified
by an RPSTERM macro.
– A site has multiple sets of terminals and multiple sets of printers. (The
RPSDLIST macro can be used to define all eligible printer destinations.
The DLIST operand can then be used to associate those destinations
with the terminals.)
8.3.7 RPSGEND: End the Network Definition

The RPSGEND macro must be the last macro coded. No Assembler END
statement is required.

8.3.7.1 Syntax
RPSGEND Macro
──┬─────┬──RPSGEND──┬───────────────┬─────────────────────────
└─tag─┘ │ ┌─NO─┐ │
└─MAXF=─┴─nn─┴──┘
tag Optional.
MAXF= Maximum number of consecutive stack storage failures
allowed before the print facility is shut down. Specify:
NO No shut down occurs if there are storage failures
(default), or
nn Shutdown occurs when storage failures reach the
number specified. The number specified must be a
positive integer.
8.3.7.2 Notes
■ Stack Storage Failures:

In the event of stack storage failures, the print facility requeues the request
being dispatched until the storage becomes available or the MAXF count is
reached. (A stack is the working storage used by a process executing under
the RPS subtask.)
If a shut down occurs, sites can attempt to restart RPS using the RPS
START command (described in the Advantage CA-Roscoe Interactive
Environment System Commands Guide). If storage remains unavailable, RPS
may shut down again.
■ Use MAXF=:
If MAXF=0 is specified, shutdown occurs on the first storage failure. If a
value is to be specified, the suggested value is 8 (for example, MAXF=8).


After the RPS macros are defined, they must be assembled and link edited into
the RO60LIB Advantage CA-Roscoe target library. This is accomplished by the
RECEIVE and APPLY of product USERMOD MRO6013, which is found in the
A sample RPS definition is placed in member #RPSENV in the RO60OPT data

set by the SMP/E APPLY of the base Advantage CA-Roscoe function SYSMOD
CRO6000.

■ Modify the #RPSENV source in RO60OPT to meet your requirements.
will put an executable copy of RPSDEF into target library RO60LIB.
8.4.1 Notes
■ See the Advantage CA-Roscoe Interactive Environment Messages and Codes
Guide for a description of the MNOTES that could be produced.
■ Alternate printing network environment definitions can also be defined for
use by concurrent or serial Advantage CA-Roscoe executions. Each
definition must be established as a unique member of the RO60LIB target
library.

8.5 Sample Printing Network Environment Definitions

The first sample RPS definition (shown below) assumes that a site has:
■ Three 328x type printers at two different locations (identified as PLOC1
with printers PRTR1 and PRTR2, and PLOC2 with printer PRTR3).
■ One system printer location (identified as SLOC1).
■ Three terminals (identified as GROUP1 with TERM1 and TERM2, and
GROUP2 with TERM3).
A user signed on to a GROUP1 terminal can print data at PLOC1 or at SLOC1.

(The default printer location is PLOC1.)
A user signed on to the GROUP2 terminal can print data at PLOC2, PLOC1 or
SLOC1. (The default printer location is PLOC2.)
Sample RPS Definition - 1
RPS1 RPSGEN
PLOC1 RPSDEST PRTR1,PRTR2
PLOC2 RPSDEST PRTR3
SLOC1 RPSDEST pname,TYPE=JES
DLIST1 RPSDLIST PLOC1,SLOC1
DLIST2 RPSDLIST PLOC2,PLOC1,SLOC1
GROUP1 RPSTERM TERM1,TERM2,DLIST=DLIST1
GROUP2 RPSTERM TERM3,DLIST=DLIST2
RPSGEND
The sample definition shown above uses only the required macros and macro
operands. Thus:
■ RPSGEN assigns the name RPS001 to the network definition and assumes
the default values of the macro operands.
■ RPSPRNTR is omitted - the RPS default 328x-type printer features and
attributes are used.
■ JESPRNTR is omitted - the RPS default system printer features and
attributes are used.
■ RPSDEST identifies the names and type of each printer that is to be
associated with each destination. The default destination attributes are
assumed.
The SLOC1 entry, a remote JES printer, can be given a symbolic name with
the DESTID JES startup parameter. This symbolic name can then be used
as the system destination.
■ RPSDLIST associates the destinations - establishing destination lists.

■ RPSTERM then associates the names of the terminals to the destination

lists.
■ RPSGEND terminates the network definition.
The next sample RPS definition (sample 2) assumes a site with a larger
network. This site has:
■ Five 328x-type printers at five different locations, where the locations and
printers are identified as:
PLOC1 with printers PRTR1 and PRTR2.
PLOC2 with printer PRTR3.
PLOC5 with no printer. (The site wants to maintain this destination
even though a printer is no longer available. Requests directed to this
destination are to be printed at PLOC3.)
■ One system printer location, identified as SLOC1.
■ 60 terminals. The first 46 terminals are to be unassigned. The remaining 14
terminals are to be assigned specific printing locations identified as:
GROUP1 with TERM1, TERM2 and TERM3.
GROUP2 with TERM4.
GROUP3 with TERM5.
GROUP4 with TERM6, TERM7, TERM8 and TERM9.
GROUP5 with TERM10, TERM11, TERM12, TERM13 and TERM14.
At this site, 46 terminals are to use printing destinations PLO1 and SLOC1.
Rather than assign these destinations to the terminals through RPSTERM
macros, the site has created a special destination list named SITEDFLT. Then,
using the RPSGEN macro, SITEDFLT is designated as the site default printing
location. (Remember that all unassigned terminals use the site default printing
location.)
A user signed on to a GROUP1 terminal can print data at destinations PLOC1

and PLOC2. (The default destination is PLOC1.)
A user signed on to the GROUP2 terminal can print data at destinations

PLOC1 and PLOC2. (The default destination is PLOC2.)
A user signed on to the GROUP3 terminal is from printing excluded data.
A user signed on to a GROUP4 terminal can print data at destinations PLOC1,

PLOC3, PLOC4 and PLOC5. (The default destination is PLOC3.)
A user signed on to a GROUP5 terminal can print data at PLOC1 and SLOC1.
(The default destination is SLOC1.)

Notice the use of the optional macros and macro operands in the following
RPS definition sample.
Sample RPS Definition - 2
#RPS2 RPSGEN DLIST=SITEDFLT,QSIZE=1,SPOOLIM=25

RPSPRNTR PRTR1,PRTR2,PRTR3 X
CPEJECT=(5,5),PAGLN=55,PAGWD=83
JESPRNTR PNAME,FEATUR1=BURST
PLOC1 RPSDEST PRTR1,PRTR2,DESC='GENERAL PRINT AREA', X
DEFCLAS=,TYPE=NETWORK, X
REJ=5,COPYLIM=1,ACA=ED
PLOC2 RPSDEST PRTR3,DESC='ACCOUNTING DEPT.', X
REJ=9999,COPYLIM=1,ACA=SN
PLOC3 RPSDEST (PRTR4,1357),DESC='PROGRAMMING AREA', X
REJ=1,COPYLIM=2,ACA=(ED,SN)
PLOC5 RPSDEST A:OAS=LOC3
PLOC4 RPSDEST (PRTR5,1357),DESC="WORD PROCESSING', X
DEFCLAS=,TYPE=NETWORK X
REJ=1,COPYLIM=2,ACA=(SN,ED)
SLOC1 RPSDEST PNAME,DEFCLAS=A,TYPE=JES
SITEDFLT RPSDLIST PLOC1,SLOC1
SPECIAL RPSDLIST PLOC1,PLOC2
DLIST1 RPSDLIST PLOC3,PLOC1,PLOC5,PLOC4
GROUP1 RPSTERM TERM1,TERM2,TERM3,DLIST=SPECIAL
GROUP2 RPSTERM TERM4,DLIST=SPECIAL,PDEF=LOC2
GROUP3 RPSTERM TERM5,DEST=NONE NOT ALLOWED TO PRINT
GROUP4 RPSTERM TERM6,TERM7,TERM8,TERM9,DLIST=DLIST1
GROUP5 RPSTERM TERM1,TERM11,TERM12,TERM13,TERM14 X
DLIST=SITEDFLT,DEF=SLOC1
RPSGEND MAXF=8
With this definition:

■ RPSGEN assigns the name #RPS002 to the network definition, designates
that the destination SITEDFLT is to be the site default destination list, and
overrides the default number of print requests to be queued and lines that
can be spooled.
■ RPSPRNTR and JESPRNTR define printer attributes that differ from the
RPS defaults.
■ JESPRNTR and RPSDEST used to define remote JES printers, can be given
a symbolic name with the DESTID JES startup parameter (shown as
pname). This symbolic name can then be used as the system destination.
■ RPSDEST identifies the names of the printers that are to be associated with
specific destinations, sets default printer classes and indicates whether the
printer is a 328x-type or system printer. It also establishes attributes for the
destinations that differ from the RPS defaults. (One of the RPSDEST
macros establishes PLOC5 as an alias for PLOC3. Notice that the alias
assignment immediately follows the definition of the destination.)

■ RPSDLIST groups destinations into destination lists. (The first destination

specified is to be the default destination for the destination list.)
Note that the third RPSDLIST macro (DLIST1) sets PLOC3 as the default
destination. PLOC5 is an alias for PLOC3. Therefore, the default
destination will be used if the terminal user enters either PLOC3 or
PLOC5.
■ RPSTERM then associates the name of the terminals with the specific
destinations or destination lists. These examples illustrate:
– How the DEF= operand is used to change the default destination, as
shown in GROUP2 and GROUP5.
– How to explicitly exclude terminals from using RPS, as shown in
GROUP3.

Chapter 9. VTAM Considerations
This chapter describes how to define Advantage CA-Roscoe to VTAM. It also

describes the operands of the VTAM macros that affect the installation of
Advantage CA-Roscoe. For a detailed description of these macros, see the
appropriate IBM VTAM System Programmer's Guide.
Chapter 9. VTAM Considerations 9-1

9.1 Defining Advantage CA-Roscoe to VTAM
9.1 Defining Advantage CA-Roscoe to VTAM
9.1.1 APPL Macro

An APPL macro must be coded in the VTAM generation for Advantage
CA-Roscoe.
9.1.1.1 Syntax
APPL Macro
──rosappl──APPL──AUTH=(ACQ,NOTSO,PASSO,...)────────────────────
──┬──────────────┬─────────────────────────────────────────────
└─PRTCT=ROSCOE─┘
rosappl The Advantage CA-Roscoe VTAM application name. If this

label is not used, the ACBNAME= operand of this APPL
macro must be specified.
AUTH= ACQ is required to allow ROSCOE Printing Services (RPS) to
acquire printers.
NOTSO is required.
PASSO is required if the site is going to allow terminal users
to bypass the VTAM screen when specifying the OFF
command. (See the Advantage CA-Roscoe Interactive Environment
Command Reference Guide for details.)
PRTCT= The Advantage CA-Roscoe password. If specified, the
recommended password is ROSCOE. If a different password is
used, use the Advantage CA-Roscoe initialization parameter
ROSPRTCT= to identify the password coded on this macro.
If PRTCT= is omitted, VTAM password verification will not
occur.
9.1.2 LOCAL Macro

Valid values for the TERM= operand are: 3275, 3277, 3284, 3286, or TWX.
The default model for 3270 devices is 1, which is not supported by Advantage
CA-Roscoe. Be sure to code the proper model on this macro.

9.2 Defining VTAM Session Parameters

There is no duplicate definition of VTAM devices to Advantage CA-Roscoe.
Advantage CA-Roscoe attempts to bind with the values presented to it by
VTAM. Therefore, the VTAM definition must represent the hardware.
Both the logmode table name (MODETAB= operand) and the logmode entry
name within the logmode table (DLOGMOD= operand) can be specified on
any of the following VTAM macros. Operands specified at a lower level
override the same operand specified at a higher level (for example, the IBM
sift down effect).
APPL
CLUSTER
GROUP
LINE
LOCAL or LU or TERMINAL
Session parameters are specified in the logmode table using MODEENT

macros and are completely controlled by the site system programmer. The
following tables are provided to assist sites in defining the MODEENT macro.
9.2.1 VTAM Session Parameters
MODEENT ISTDBIND 3270 3270 NTO/3767

Macro DSECT BSC SNA
Operand Relative NON-SNA
Location LOCAL
FMPROF Byte 1 X'02' X'03' X'03'
TSPROF Byte 2 X'02' X'03' X'03'
PRIPROT Byte 3 X'71' X'B1' X'B1'
SECPROT Byte 4 X'40' X'90' X'A0'
COMPROT Byte 5/6 X'2000' X'3080' X'3080'
RUSIZE Byte 9/10 see text see text see text
Logical Unit Byte 13 X'00' X'01' (SCS X'01'
Profile (PSERVIC Prntr)
Byte 1) X'02'
(Terminal)
X'03'
(Printer)
PSERVIC Bytes 19 thru 24 Yes Yes No
Matrix (PSERVIC Byte
7/11)

If the device is not defined as either an FM profile 2 or 3, Advantage

CA-Roscoe rejects the logon.
RCS will force bind area screen matrixes to have the:

■ Smallest screen size as the primary matrix.
■ Largest screen size as the alternate (or secondary) matrix.
9.2.2 VTAM PSERVIC Matrix Requirements
PSERVIC Bytes
7 8 9 10 11 Advantage CA-Roscoe Assumes
Def. Mat. Alt. Flag Device Row and Storage
Mat. BUFSIZE Column Buffer Size
Matrix Obtained By
Advantage
CA-Roscoe
'0000' '0000' '00'
0C28 '0000' 7E 480 12x40 2048
(Printer)*
'0000' '0000' 01
1850 '0000' 7E 2048
(Printer)
'0000' '0000' 02 1920 24x80 4096
(Terminal)*
'0000' '0000' '00'
1850 2050 7F 2650 32x80 4096
1850 2B50 7F 3440 43x80 4096
1850 1B84 7F 3564 27x132 4096
(Terminal)
1850 3EA0 7F 9920 62x160 10240
(Terminal)
0000 0000 03 Requires 3274 controllers have
Configuration Support Level D, Release 65.
Matrix and buffer size depends on setup
mode of terminal.
Note: * Default if matrixes and flag are zeros.

9.2.2.1 Presentation Size
In all cases, the presentation services field (coded in the PSERVIC operand of
MODENT) is used to determine the device's presentation size. The
presentation size values that Advantage CA-Roscoe supports are found in the
previous table (PSERVIC Matrix Requirements).
9.2.2.2 Outbound (to device) RUSIZE
Byte 2 of the RUSIZE= operand of the MODEENT macro determines the

maximum outbound RU size. If the high-order bit is 0, no maximum RU size is
defined. If the high-order bit is not 0, the outbound RU size, as defined in the
session parameters, is used by Advantage CA-Roscoe to limit the size of
elements in outbound chaining. It should be specified only to improve TP
throughput. (The division of outbound data into several chained elements may
permit interleaving of traffic on the line.)
A local or remote 3276 control unit does not require a maximum outbound RU
size. For the 3276, specify either no primary RU size or a size dictated by
network and line considerations. In the absence of a primary RU size,
Advantage CA-Roscoe will attempt to write as much data as will fit in the
device buffer with a single SEND request.
A channel-attached local 3274 requires an outbound RUSIZE of 1536 bytes or

less. Within this constraint, the size can be defined, as noted above, according
to site requirements.
A remote 3274 has no RUSIZE restriction.
9.2.2.3 Inbound (to Advantage CA-Roscoe) RUSIZE
Byte 1 of the RUSIZE= operand of the MODEENT macro determines the

inbound RUSIZE. For 3274 terminals, the inbound RUSIZE must not exceed
1024 bytes.
For 3276 terminals, the size must not exceed 2048 bytes.
If the specified value is coded as greater than the above inbound maximums,
VTAM uses the inbound maximum value.

9.2.2.4 MODEENT Example
The following sample MODEENT macro assumes an SNA Model 5 3270-type

terminal:
MODEENT FMPROF=X'3', X
TSPROF=X'3', X
PRIPROT=X'B1', X
SECPROT=X'9', X
COMPROT=X'38', X
PSERVIC= X'281851B847F'
where the PSERVIC bytes are set to:

1 ='02' (SNA terminal.)
2 ='80' (Extended data stream support. '00' is coded to indicate standard
data stream support.)
7/8 ='1850' (Primary matrix.)
9/10 ='1B84' (Alternate matrix.)
11 ='7F' (Largest buffer to be used for the initial bind.)

9.3 Defining USS Definition Table
9.3 Defining USS Definition Table

To facilitate Advantage CA-Roscoe logon requests, create a USS definition table
in which the following (sample) definitions are entered:
name USSTAB TABLE=TRANSTAB
...
LOGON USSCMD CMD=ROSCOE,REP=LOGON,FORMAT=BAL
USSPARM PARM=APPLID,DEFAULT=ROSCOE
USSPARM PARM=P1,REP=DATA
...
TRANSTAB DS OF
A 256 BYTE TRANSLATION TABLE IN WHICH ALL LOWER CASE

ALPHA WILL BE TRANSLATED TO UPPER CASE ALPHA.
...
END USSEND
This definition permits the terminal user to enter the single word 'ROSCOE' (in
uppercase or lower case) to request logon to Advantage CA-Roscoe. The word
is converted into the following command sequence:
LOGON APPLID(ROSCOE)
Enter the name of the USS definition table with the USSTAB= operand in the
LU, PU, GROUP, LINE, CLUSTER, or TERMINAL macro.
Use this USS definition table in place of, or in addition to, the standard IBM
table ISTINCDT. Refer to the appropriate SRL for your operating system for
further details.
To help the terminal user, message 10 should be included in the USS definition
table used for the 3276 and 3278 terminals. Message 10 should tell the terminal
user that the terminal is available for use and, perhaps, inform the user of the
valid application identifiers.

9.4 Defining an Interpret Table
9.4 Defining an Interpret Table

For local non-SNA, BSC and Start/Stop devices, an interpret table must be set
up or modified. The name of the table can be specified with the LOGTAB=
operand in the LOCAL, LU, PU, GROUP, LINE, CLUSTER, or TERMINAL
macro. The table entry should be coded as follows:
LOGTABA INTAB
LOGCHAR APPLID=(APPLICID,ROSCOE), X
SEQUENCE=ROSCOE
...
ENDINTAB
END
9.4.1 Notes
■ LOGTABA is an arbitrary name of the interpret table, to be used as the
value of LOGTAB in the LOCAL definition.
■ APPLID must contain the name assigned to the application program by an
APPL definition statement.
■ SEQUENCE must contain the string of characters that users enter to
request connection to Advantage CA-Roscoe. This string of characters can
be anything required by site conventions, including a PF key. We
recommend that the string be the same as the APPLID in uppercase and
lowercase. (The string 'ROSCOE' is used in the example.)

9.5 SNA Logons
9.5 SNA Logons

Advantage CA-Roscoe logon processing accepts the session parameters
associated with the pending logon. If the session parameters define the device
as LU type 2 with function management profile 3 (FM3), Advantage
CA-Roscoe assumes that the device is an SNA 3276 or 3278.
Sites should ensure that the following IBM Engineering Changes have been
applied:
EC # 850573 (for 3276 and 3278 terminals)

EC # 746809 (for 3274 and 3278 terminals)

9.6 Defining Control Characters to NCP for NTO Support
9.6 Defining Control Characters to NCP for NTO Support

For Advantage CA-Roscoe to support control characters (that is, CTRL-E) for
TTYs under VTAM-NTO, the characters must be defined to NCP in the
CHAREC operand of the GROUP macro. Consult the IBM manuals that
describe NTO installation and NCP generation.

9.7 Advantage CA-Roscoe/VTAM Stop/Start Processing

If, during initialization, Advantage CA-Roscoe cannot establish
communications with VTAM, a message is directed to the operator console.
(When appropriate, Advantage CA-Roscoe continues initialization to enable
users to access Advantage CA-Roscoe through terminals and printers defined
to BTAM or BTAM CICS.)
The message directed to the operator console explains the VTAM error
condition encountered.
■ If the error indicates a temporary condition (that is, VTAM is not active),
the message states that Advantage CA-Roscoe will continue to try to
establish communications with VTAM (through an OPEN ACB). At this
time, the operator may:
1. Terminate START processing (by entering TERM), or
2. Have Advantage CA-Roscoe retry with a different applid (by entering
a new applid).
If the operator chooses neither option, Advantage CA-Roscoe attempts to
establish communications at predefined intervals. If the OPEN again fails
and the error still indicates a temporary condition, the console message
remains displayed. If the OPEN succeeds, Advantage CA-Roscoe sends a
message to the console stating that the ACB is open and that users may
now sign on under the Advantage CA-Roscoe applid.
■ If the error indicates a serious condition (that is, the applid is invalid or is
currently in use), Advantage CA-Roscoe sends a message to the console
identifying the error. The operator may then:
1. Have Advantage CA-Roscoe continue attempts to establish
communications (by entering GO).
2. Terminate this attempt to establish communications (by entering
TERM).
3. Name a different Advantage CA-Roscoe applid. Advantage CA-Roscoe
will again attempt to establish communications with VTAM using the
new applid.
If the operator chooses none of these options, the message remains displayed.
Users are able to access Advantage CA-Roscoe through terminals defined to
BTAM or BTAM CICS.

If VTAM crashes or is brought down by the operator commands HALT, HALT

QUICK, or HALT CANCEL, Advantage CA-Roscoe is not shutdown. User
sessions on VTAM devices will be terminated but at sites using mixed access
methods, user sessions on BTAM or BTAM/CICS devices will continue.
Commands are provided that allow either the console operator or the owner of
the RO or AI prefix to:
■ Restart communications between Advantage CA-Roscoe and VTAM.
■ Stop the Advantage CA-Roscoe/VTAM communications network.
Advantage CA-Roscoe will continue to execute and will be accessible to
users at BTAM and/or BTAM/CICS devices.
■ Display Advantage CA-Roscoe/VTAM status information.
■ Alter the default setting of the time intervals that Advantage CA-Roscoe
uses when attempting to start or stop communications with VTAM.
For a detailed description of these commands, see the Advantage CA-Roscoe

System Commands Guide.

9.8 Balancing the Workload
RCS047I –RCS048I
|9.8 Balancing the Workload

| If the ROSGNAME= parameter is included in the Advantage CA-Roscoe
| SYSIN parameter list, Advantage CA-Roscoe will issue a SETLOGON
| OPTCD=GNAMEADD call during startup allowing the use of a VTAM
| Generic Resource in addition to the Roscoe Applid.
| The result of the SETLOGON OPTCD=GNAMEADD call is reported by one of

| the following messages:
|RCS047I GENERIC RESOURCE xxxxxxxx ADDED
| Reason: The VTAM Generic Resource specified in the ROSGNAME= parameter was
| successfully added. No action is necessary.
|RCS048I GENERIC RESOURCE ADD FAILED. xxxxxxxx

| R15=aaaaaaaa R0=bbbbbbbb RTNCD=cccc FDB2=dddd
| Reason: Where xxxxxxxx is the VTAM Generic Resource Name, aaaaaaaa is the contents
| of register 15, bbbbbbbb is the contents of register 0, and cccc and dddd are the VTAM
| return and feedback codes.
| Note: Advantage CA-Roscoe continues to initialize using only the VTAM applid
| specified by the ROSAPPL startup parameter. The VTAM Generic Resource is not
| available. Determine the problem using the VTAM register and return codes.
| Correct the problem and recycle Roscoe.
| Sites running multiple Advantage CA-Roscoe's can now balance their workload by
| inserting a ROSGNAME=xxxxxxxx in each of the Roscoe SYSIN streams and instructing
| each user to sign on to the VTAM Generic Resource "xxxxxxxx".

Chapter 10. XTPM Support
The XTPM (External Teleprocessing Monitor) component of Advantage

CA-Roscoe can be used to let users access Advantage CA-Roscoe from:
■ Terminals defined to CICS/VS
■ A TSO session
■ Another Advantage CA-Roscoe session
All of the XTPM components are unloaded as part of the Advantage

CA-Roscoe installation procedure. For information about installing these
components, see the Advantage CA-Roscoe Interactive Environment Installation
Guide. The Advantage CA-Roscoe Interactive Environment User Guide describes
how users can sign on to Advantage CA-Roscoe from CICS, TSO, or another
Chapter 10. XTPM Support 10-1

Chapter 11. ATTACH JOB, CONSOLE and DISPLAY
Requirements
This chapter describes the steps that a site must take to allow the use of the
ATTACH JOB command, AJOB command, CONSOLE Monitor command or
DISPLAY Monitor command. These steps include:
■ Defining a ROSGBL table.
■ For ATTACH JOB, establishing a special SYSOUT class to cause job output
to be held.
■ Defining the CONSOLE Monitor routine to Advantage CA-Roscoe and
determining whether the optional CONSOLE exit is needed.
■ Defining the DISPLAY Monitor routine to Advantage CA-Roscoe and
determining whether subcommand authorization is needed.
■ At JES2 SP4.1.0 or higher sites, adding the ROJES2XT exit.
■ At JES3 local sites, modifying the IATUX30 exit.
Note: We recommend that Advantage CA-Roscoe be run on the global
processor. In a global environment, Advantage CA-Roscoe has direct
access to the JES3 status areas and the spool queues. Thus, global access
is faster and less expensive than local access.
Chapter 11. ATTACH JOB, CONSOLE and DISPLAY Requirements 11-1

11.1 Defining ROSGBL

If the ATTACH JOB command, AJOB, CONSOLE Monitor command or
DISPLAY Monitor command are used, a ROSGBL table must be defined.
A ROSGBL table is generated by the ROSGBL macro. The macro is used to

define: 1) the site's environment, 2) DISPLAY-only requirements, and 3)
ATTACH JOB-related requirements. (Information specified when defining the
site's environment is also used by the CONSOLE Monitor routine.)
Once a table is defined, it must be assembled and linked to the Advantage

CA-Roscoe load library (the RO60LIB target library) with the name ROSGBL.
Sites have the option of defining multiple ROSGBL tables and then using the
ROSGBL= initialization parameter to specify which table is to be used during
the current execution of Advantage CA-Roscoe. To do this, the site must:
■ Assign a unique name to the load module when linking it. The name must
be in the form ROSGBLxx, where 'xx' is any one or two unique characters
(for example, ROSGBL1).
■ Specify the unique one or two characters with the ROSGBL= initialization
parameter to indicate which version is to be used. For example, assume
that a site has created two ROSGBL tables where one is named ROSGBL
and the other is named ROSGBL1. To use ROSGBL1, the Advantage
CA-Roscoe JCL needs the following initialization parameter:
ROSGBL=1
If this parameter is omitted, Advantage CA-Roscoe uses the default (that
is, the definition in the table named ROSGBL).
Two sample ROSGBL macro definitions are placed in the RO60OPT data set by
the SMP/E APPLY of the base Advantage CA-Roscoe function SYSMOD
CRO6000. The two sample definitions are ROSGBL2 for JES2, and ROSGBL3
for JES3.
After the ROSGBL macro is defined, it must be assembled and linked into the
RO60LIB Advantage CA-Roscoe target library. This is accomplished by the
RECEIVE and APPLY of product USERMOD MRO6010 for JES2, or MRO6011
for JES3, both of which are found in the installation sample JCL library.

11.1.1 Syntax
|
| ROSGBL Macro
| ──┬─────┬──ROSGBL──┤ Site Environment Operands ├───────────────
| └─tag─┘
| ──┤ DISPLAY-Only Operands ├──┤ Job-Relates Operands ├──────────
| Site Environment Operands:
| ├──┬────────────────────────┬────────────────────────────────────┤
| ├─,SYSTEM=system─────────┤
| ├─,MVSSPL=mvsspl─────────┤
| ├─,JES=jes───────────────┤
| ├─,JESSPL=jesspl─────────┤
| ├─,JESNAME=jesname───────┤
| └─,JES3OPT=───jes3opt────┘
| DISPLAY-Only Operands:
| ├──┬──────────────────────┬──────────────────────────────────────┤
| │ ┌─JOE─┐ │
| ├─,DISPRI=─┴─JQE─┴─────┤
| ├─,DISBUF=───disbuf────┤
| │ ┌─NO──┐ │
| ├─,DISACCT=─┴─YES─┴────┤
| ├─,CMDTAB=───cmdtab────┤
| └─,PREKEY=───prekey────┘
| Job-Related Operands:
| ├──┬────────────────────────┬────────────────────────────────────┤
| ├─,MEMORY=memory─────────┤
| ├─,LOGNAME=logname───────┤
| ├─,FILES=───number───────┤
| ├─,PAGES=───number───────┤
| ├─,NOTES=───number───────┤
| ├─,FINDCNT=───number─────┤
| ├─,MAXFIND=───number─────┤
| │ ┌─NOPRINT─┐ │
| ├─,FILEDSP=─┴─PRINT───┴──┤
| │ ┌─YES─┐ │
| ├─,PRINTAL=─┴─NO──┴──────┤
| └─,DUMMYC=class──────────┘
Site Environment Operands

SYSTEM= Operating system. See MRO6010 or MRO6011 for
acceptable values.
MVSSPL= MVS system product level. See MRO6010 or MRO6011 for
acceptable values.
JES= Job entry subsystem, specified as:
JES2 JES2
JES3 JES3

JESSPL= JES system product level. See MRO6010 or MRO6011 for

acceptable values.
JESNAME= Name of the job used to execute JES (for example, JES2,
JES3, JESL, and so on.).
JES3OPT= (JES3 only.) Type of processors on which Advantage
CA-Roscoe is to be executed. See MRO6011 for acceptable
values.
DISPLAY-Only Operands
DISPRI= (JES2 only.) Designates the source of the priority numbers to
be displayed when a job has ready SYSOUT files. Specify:
JQE DISPLAY is to use the job priority (0 through 15)
found in the JQE control block for the job.
JOE DISPLAY is to use the job priority number (0
through 15) found in the JQE control block until
the job has ready SYSOUT files. It is then to use
the priority numbers (1 through 255) for each
ready SYSOUT file obtained from the file's JOE
control block.
If omitted, the default is DISPRI=JOE.
DISBUF= Dynamic buffer length in KB (1024 bytes). The default is 8.
JES2: A buffer this size is acquired in subpool 239 (SQA) for
every execution of the DISPLAY command. During
termination, global messages are written indicating the
number of GETMAINs for DISPLAY and the number of
times that the buffer was too small. If the number of times
the buffer was too small is excessive, sites may want to
increase DISBUF=.
JES3 Local: The block size of the IATUX30 data set is used,
thus DISBUF= need not be specified.
JES3 Global: The size of the buffer determines the maximum
number of jobs the terminal user can display at any one time.
The formula used is:
(disbuf 124 - 28) / 34 = jobcnt
Using the default value with the formula, the following
example shows that each user can display a maximum of 240
jobs:
(8 124 - 28) / 34 = 24
DISACCT= Generation of accounting records is controlled by specifying
either of the following codes:

YES An accounting record is to be written every time

DISPLAY is executed.
NO No accounting records are to be written (default).
CMDTAB= Subcommands of DISPLAY that all users may enter without
being specifically authorized in the Authorization Table.
Specify:
$ALL All users are allowed to execute all subcommands
(default).
To permit only certain subcommands, specify one or more of
the following codes:
A ACTIVE
AR ACTIVE,remote
AS ACTIVE,TSO (STC)
AT ACTIVE,TASKS (TSO)
ALL ACTIVE,ALL
D DEVICES
I INIT
J JOB
M MASK
N NAME
NC NAME,class
NR NAME,remote
Q QUEUE
QC QUEUE,class
QR QUEUE,remote
If the code J is not specified, the JOB subcommand is not
authorized. Also, the terminal user will not be able to enter
DISPLAY with no operand and to display job status.
If multiple codes are specified, they must be enclosed in
parentheses and separated by commas with no intervening
spaces.
PREKEY= Identifies the starting location of the user's prefix or sign on
key within the job name. If omitted, the default is (1,0,3).
Note: When DISPLAY is entered with no subcommand, the
status of all jobs containing the user's prefix or key in
the designated location is displayed.
To specify the location and to designate whether the prefix or
key is to be used in the job name, specify:
(jobstart,keystart,len)
where:
jobstart One-digit value indicating the starting position of
the user's prefix or key within the job name.

keystart One-digit value indicating the starting position of

the characters in the user's sign on key that are to
be found in the job name. If 0, the prefix-not the
key-is used.
len One-digit value indicating the length of the prefix
or key. For prefix, the value can be either 2 or 3. If
3 is specified, 2- and 3-character prefixes are
recognized.
Examples:
To use a 3-character prefix, starting in the second
position of the job name:
PREKEY=(2,0,3)
To use the first two characters of the sign-on key,
starting in the first position of the job name:
PREKEY=(1,1,2)
ATTACH JOB-Related Operands
MEMORY= Maximum memory in KB (1024 bytes) to be allocated per user

of ATTACH JOB. The default is 36. (Advantage CA-Roscoe
acquires memory as needed, up to the defined maximum, to
hold the file, note and page tables.)
LOGNAME= Name of the system log. The default is SYSLOG. (Advantage
CA-Roscoe will not enqueue on this name. Thus, multiple
people can use the ATTACH JOB command (for example,
ATTACH JOB SYSLOG) to view the system log at the same
time.)
FILES= Number of file tables to be provided in the initial GETMAIN.
The number should represent the average number of files plus
LOG and SMBs for a 'typical' job. The default is 8.
Note: See the section 'Space Requirements and Usage' for
additional information about the initial GETMAIN.
PAGES= Number of physical output pages per file that are to be
provided in the initial GETMAIN. The default is 128.
NOTES= Number of 4 KB pages to be shared among all users as a
global note pad. The default is 1. If 0 is specified, the global
note pad facility is disabled. (Each 4 KB page holds 128 notes.)
FINDCNT= Default number of lines to be searched during a single
execution of an EXCL, FIRST, INCL, NEXT, LAST or PREV
command. The default is 100000.
MAXFIND= Maximum number of lines to be searched during a single
execution of an EXCL, FIRST, INCL, NEXT, LAST or PREV
command. If omitted, the default is 100000.

FILEDSP= Default file disposition for all job files designated as either:
PRINT Print files when job detached.
NOPRINT Delete files when job detached (default).
PRINTAL= Recognition of the ALL operand of the ALTER JOB command
is controlled by specifying either of the following codes:
YES ALL is recognized (default).
NO ALL is not recognized.
DUMMYC= (JES3 only.) Class to which the output files are reset when the
terminal user marks them for deletion.
11.1.2 Assemble and Link Edit ROSGBL

Two sample ROSGBL macro definitions are placed in the RO60OPT data set by
CRO6000. The two sample definitions are ROSGBL2 for JES2, and ROSGBL3
for JES3.
After the ROSGBL macro is defined, it must be assembled and linked into the
RO60LIB Advantage CA-Roscoe target library. This is accomplished by the
RECEIVE and APPLY of product USERMOD MRO6010 for JES2, or MRO6011
for JES3, both of which are found in the installation sample JCL library.
| The process to install ROSGBL has the following basic steps:

| ■ Modify the ROSGBL2 or ROSGBL3 source in RO60OPT to meet your
| needs.
| ■ Execute the USERMOD MRO6010 for JES2 or USERMOD MRO6011 for
| JES3. This will initiate an SMP/E RECEIVE and APPLY. During the
APPLY an assembly and link will take place which will put an executable
copy of ROSGBL into target library RO60LIB.
11.1.2.1 Notes
| ■ At all Sites:
| The High-Level Assembler must be used when assembling ROSGBL.
| ROSGBL must be linked as non-reentrant. An 0C4 occurs during
| Advantage CA-Roscoe initialization if ROSGBL is linked as reentrant.
■ SYSLIB Concatenation:
Any changes to the SYSLIB concatenation need to be made to SMP/E
procedure CAIRO60 so they will be referenced when product USERMODs
are executed. See the Advantage CA-Roscoe Interactive Environment
Installation Guide Chapter 4.11 "Customizing the SMP/E Procedure" for
information on the SYSLIB contatenation for OS/390, MVS/ESA and
MVS/XA systems.

11.2 ATTACH JOB Requirements

The ATTACH JOB command (described in the Advantage CA-Roscoe Interactive
Environment Command Reference Guide) allows users to examine job output at
their terminals. The type of output that can be viewed depends on the site's
environment, where:
■ JES2 Sites: The output files of a job can be examined at any time. (If the
attributes of the output files are to be modified, the job must have been
submitted with the site-defined SYSOUT class.) If the job is:
– AWAITING EXECUTION - The JCL and all SYSIN data can be viewed.
(This is the only time that this information will be displayed.)
– EXECUTING - The JCL and that much of the job log and SMB that is
currently written to the spool can be viewed, plus all available files. (If
a file is open and empty, only the end of file message is presented
when that file is displayed.)
– AWAITING PRINT - All SYSOUT files that have not yet been printed
or purged can be viewed.
■ JES3 Sites: The output files can be examined at any time, if output files
exist. Only the attributes of those files routed to SYSOUT classes held for
an external writer may be modified.
To Use This Command
To view job output, sites must:

1. Establish the ROSGBL table, described in this chapter.
2. Perform the system-dependent changes needed to accommodate holding
output. (See the next section for details.)
3. Perform the steps described in the section JES2 requirements.
4. Perform the steps described in the section JES3 Local Requirements, if
appropriate.
5. Determine whether the optional job output exit routine is to be used. (See
the Advantage CA-Roscoe Interactive Environment Extended Facilities for System
Programmers Guide for additional information.)

11.2.1 Causing a Job to be Held

Job output that is destined to be examined at the terminal must be routed to a
SYSOUT class that will cause job output to be held.
The SYSOUT class(es) that causes job output to be held are specified as part of
the JES2/3 initialization deck. For example:
$$x HOLD (with JES2)
SYSOUT,CLASS=x,HOLD=TSO (with JES3)
where x is the class to be held (for example, $$R HOLD). Note that JES3 sites
must not code TYPE=DSISO on the SYSOUT initialization parameter.
11.2.1.1 Notes
■ It is the site's responsibility to inform their Advantage CA-Roscoe users

what SYSOUT classes are in effect.
■ JES3 sites that want to use external writer held SYSOUT only should see
the member ZAPs on CRO60SLD. Note that if the ZAP described in this
member is applied some applications may not execute successfully under
ETSO.
11.2.2 Space Requirements and Usage

Advantage CA-Roscoe requires space to build internal tables that contain
pointers to:
■ Each file in the job output. (Each entry in the table is 96 bytes in length.)
File table entries are built when a job is first attached at the rate of one
entry for each SYSOUT file that will be processed. Each entry contains
such information as the location of the start of the data set on the spool,
the data set name, the number of records in the data set, the file number
and name, the SYSOUT class, the form number, and so on.
■ Output pages within a file. Each entry is 32 bytes in length. Initially, one
page table entry is created for each page in a file.
■ Each note name assigned by the terminal user. (Each entry is 32 bytes in
length.)
The actual amount of space initially obtained when a terminal user enters the
ATTACH JOB command is based on parameters specified in the ROSGBL
macro and on the size of the job. For example, assume that a site has specified
the ROSGBL parameters FILES=8 and PAGE=128 and has a spool buffer size
of 4096. During initialization, the following calculation is performed:
1. The number of files specified multiplied by 96. (8 * 96 = 768)
2. The number of pages specified multiplied by 32. (128 * 32 = 4096)

3. The addition of these two numbers added to the fixed constant of 1336
bytes. (This is the base memory requirement to attach and view a job.) (768
+ 4096 + 1336 = 6200)
4. The addition of this number to the size of the user's spool I/O buffer.
(6200 + 4096 = 10208)
5. The resulting total then rounded to the next highest 4 KB boundary. (12288
or 12 KB)
In this example, 12 KB is the amount of space that is initially GETMAINed.

Additional space is acquired in 4 KB increments until the specification of the
ROSGBL MEMORY= operand is exceeded. If MEMORY= is specified as less
than or equal to 12K, no secondary space is GETMAINed. (All space is
GETMAINed below the 16 MB line from subpool 0 of the Advantage
CA-Roscoe private address space.)
The MEMORY= parameter restricts the upper limit of the obtained memory.
We recommend that sites use the default of MEMORY=36K. The user who is
looking at small SYSOUT files will not get more memory than he needs (not
more than 12K), while the user who is looking at larger files will get much
better response.
To illustrate, assume that MEMORY=12K has been specified. From this space,
1336 bytes of the obtained space are reserved for use as a work area and 4096
bytes are reserved for spool I/O. The remaining space (1336 + 4096 = 6856) is
used for file tables, page tables and note entries.
File tables are created before the page tables and note entries. Obviously, the
more SYSOUT files that are to be processed, the more space that the file tables
will occupy.
While file tables must be obtained to process a SYSOUT data set, it is the page
tables that have the most significant effect on Advantage CA-Roscoe response.
To illustrate, assume that there are 11 SYSOUT files in a job. Advantage
CA-Roscoe will perform the calculation:
12288 bytes (MEMORY=12K)
- 1336 bytes (Work area)
- 496 bytes (Spool I/O buffer)
- 156 bytes (Space required for 11 file table
58 bytes entries 11 96 = 156)
To determine the number of page table entries, divide 5800 by 32 (the size of a
page table). The result allows 181 page table entries.
Advantage CA-Roscoe attempts to represent every page as a page table entry.

Thus, in this example, a page table entry is built for pages 1 through 181. If
there are more pages, Advantage CA-Roscoe rebuilds the page tables after
removing every other page from the tables (for example, page 2, 4, 6, and so
on are removed). This time, when Advantage CA-Roscoe gets to approximately

page 360, the number of page table entries is again exhausted. If there are
more pages, the page tables are rebuilt again by removing every other page
table entry. How does this page reduction affect the terminal user?
If the user wants to get to a specific page or line, Advantage CA-Roscoe must
position to the next lowest page represented in the page tables. (For example,
if a user wants to position to page 8 and there are page table entries for pages
5 and 9, Advantage CA-Roscoe positions to page 5.) Advantage CA-Roscoe
then starts reading spool data until the desired location is read. The more
pages there are in the job, the more I/Os must be performed for Advantage
CA-Roscoe to position to the desired location.
In this example, if the total amount of memory is small compared to the

number of pages in a file, positioning will involve more I/O operations and
longer response time. It is with this in mind that we recommend the higher
value for MEMORY=. The memory will only be used as needed by Advantage
CA-Roscoe.

11.3 CONSOLE Routine Requirements
11.3 CONSOLE Routine Requirements

The CONSOLE Monitor routine permits terminal users to execute operator
commands and display: 1) messages written to the master or a designated
console, 2) the OS/390 Master Trace Table, and 3) the address of currently
active consoles.
The CONSOLE Monitor routine has a pseudo-SPIE exit.
11.3.1 To Use This Routine

In addition to defining a ROSGBL table (described earlier in this chapter), the
CONSOLE routine must be defined to Advantage CA-Roscoe through the
RUN= initialization parameter, as in:
RUN=CON(S)
See the Advantage CA-Roscoe Interactive Environment System Commands Guide for
information about using the CONSOLE command to invoke this routine.
11.3.2 To Customize/Modify This Routine

The CONSOLE routine also calls a user exit. This user exit may be used to
control who can display console information or execute operator commands.
For additional information, see the Advantage CA-Roscoe Interactive Environment
Extended Facilities for System Programmers Guide.

11.4 DISPLAY Routine Requirements

The DISPLAY Monitor routine permits an Advantage CA-Roscoe user to
obtain information from the operating system about jobs in execution,
initiators, job queues and online devices.
DISPLAY has a pseudo-SPIE exit.

In addition to defining the ROSGBL table (described earlier in this chapter),
DISPLAY must be defined to Advantage CA-Roscoe through the RUN=
initialization parameter, as in:
RUN=DIS(S)
See the Advantage CA-Roscoe Interactive Environment Command Reference Guide

for information about using the DISPLAY command to invoke this routine.

As distributed, all users can issue all of the DISPLAY subcommands.
DISPLAY can be modified to restrict the use of specific subcommands. As
shown in the following diagram, any or none of the following restrictions can
be applied:
1. The CMDTAB= operand of the ROSGBL macro.
When a terminal user enters a DISPLAY subcommand, the CMDTAB=
operand is examined. (CMDTAB= defines the subcommands that all users
may enter without additional authorization.) If CMDTAB=:
■ Allows the subcommand, control transfers to the DISEXIT exit routine.
■ Does not allow the subcommand, the optional DISAUTHO
Authorization Table is examined.
2. The DISPLAY Authorization Table (defined by the DISAUTHO program
which is described in the Advantage CA-Roscoe Interactive Environment
Programs and Utilities Guide).
If this optional table is not present, controls transfers to the DISEXIT exit
routine.
If the DISAUTHO table is present, it is checked to see if the user is
authorized to execute the subcommand. If the user:
■ Is authorized, control transfers to the DISEXIT exit routine.
■ Is not authorized, the subcommand is rejected.

3. A DISEXIT exit routine (described in the Advantage CA-Roscoe Interactive

Environment Extended Facilities for System Programmers Guide).
This exit routine can be used to verify whether the user can execute the
subcommand then to either accept or reject it.
DISPLAY Subcommand Evaluation

┌───────────────┐
│ Does CMDTAB= │
│ (in ROSGLB) │yes
│ Allow Use Of ├───┐
│ Subcommand? │ │
└───────┬───────┘ │
│ │
no │
┌───────────────┐ │ ┌───────────────┐
│ Is There a │no │ │ Does Exit │ yes
│ DISAUTHO ├───┼── │ Routine Allow ├──── PROCESS
│ Table? │ │ │ Subcommand? │
└───────┬───────┘ │ └───────┬───────┘
│ │ │
yes │ no
┌───────────────┐ │
│ Does DISAUTHO │ │ REJECT
│ Allow Use Of ├───┘
│ Subcommand? │yes
└───────┬───────┘
│
no
REJECT

11.5 JES2 Requirements

This section details steps necessary to utilize the ATTACH JOB processing if
you are JES2 SP4.1.0 or higher.
11.5.1 Advantage CA-Roscoe JES2 EXIT5 Overview

The requirement:
With prior releases of JES2, Advantage CA-Roscoe output processing allowed

changes to the class, forms, destination and copies for any held sysout file.
With JES2 SP4.1, the grouping of held files into output groups is strict. It is no
longer possible, using standard Advantage CA-Roscoe processing, to change
characteristics of any two files belonging to the same output group in
conflicting ways. For example, if file1 and file2 belong to the same output
group, it is not possible to cause them both to be printed at separate
destinations or at the same destination with different sysout classes or forms.
Review your JES2 Initialization and Tuning Reference and Initialization and
Tuning Guide for detailed discussions on output groups.
The solution:
To allow end users the same flexibility as in prior releases, Advantage

CA-Roscoe will now dynamically build new output groups, and associated job
output elements (JOEs) during output processing to resolve any data set
alteration conflict in attach job processing.
Dynamic JOE creation occurs within a JES2 exit. The exit number is 5, which is
the CONSOLE exit. This exit RECEIVEs control from the JES2 module
HASPCOMM for each JES2 console command.
JES2 sites with ROSGBL JESSPL=SP410 or SP420 must assemble and link the
RO60OPT library member, ROJES2XT, with installation sample JCL member
MRO6029.
ROJES2XT contains RO$EXIT5, which is the JES exit 5 routine.
Note that the data set identified in the SYSLMOD DD must be an authorized
library and the member name must be ROJES2XT.
Whenever JES2 maintenance is applied at your site, source member ROJES2XT

must be reassembled and linked.

RO$EXIT5, in conjunction with an Advantage CA-Roscoe job, implements a

new parameter on the $TO console command. The parameter is ROSPARM=.
The value for the parameter is the virtual storage address (in display hex
EBCDIC) of a control block in E-SQA subpool 239. The storage area is
allocated by Advantage CA-Roscoe during DETACH JOB processing, when it
determines that a new output group is required.
The string passed on the SVC 34 by the Advantage CA-Roscoe job is of the
format:
$TO?Xxxx,ROSPARM=nnnnnnnn
where:
? is "s" for started tasks, "j" for jobs and "t" for TSO.
Xxxx is the job number of the job being processed.
Nnnnnnnn
is the virtual storage address of the control block.
The control block is mapped with the ROXJ25 dsect, delivered in the macro
file. It is used by the Advantage CA-Roscoe output processor and by
RO$EXIT5. The area is released after the call by the Advantage CA-Roscoe
output processor.
The size of the area is 428 decimal bytes.
Do NOT modify the ROXJ25 map.
Should you opt not to make use of the Advantage CA-Roscoe JES exit,
RO$EXIT5 in module ROJES2XT, your users will not be able, in some cases, to
redirect their output data sets to alternate classes or destinations. Depending
on your own site standards, and so on, this may be acceptable. However, in
this case, your users are still be able to view all output, as before. In addition,
they are able to alter destinations, classes, forms and copies for held output as
long as a given file alteration does not conflict with a prior alteration of a file
in the same output group.
11.5.2 JES2 Initialization Implications

The JES2 startup parameters should include the following:
| LOADMOD(ROJES2XT) STORAGE=xxx
The value for 'xxx' can be PVT, CSA or LPA. See the JES2 in the Customization
and Tuning Guide chapter for a discussion of the relationship between the
storage= operand and the data set in which the exit code should be placed.
| Refer to the JES2 Installation Exits Manual Section 7.2 (SC28-1793) for a
| description of the LOADMOD parameter.
| The size of ROJES2XT is approximately 4 KB bytes.

| EXIT(5) ROUTINES=(RO$EXIT5,xxxxxxxx,yyyyyyyy),
| STATUS=[ENABLED|DISABLED],TRACE=[YES|NO]
| The exit must be enabled. If there are multiple exits, the ROJES2XT must be
| specified first in the list as shown following.
| LOADMOD(ROJES2XT) STORAGE=CSA
| LOADMOD(xxxxxxxx) STORAGE=xxx
| EXIT(5) ROUTINES=(RO$EXIT5,xxxxxxxx),STATUS=ENABLED,TRACE=NO
The routine RO$EXIT5 should be the first routine in the list. If it is not,
Advantage CA-Roscoe will not attempt to create new job output elements.
Because Advantage CA-Roscoe is implementing a new parameter on the $TO
command, a prior exit may reject the command thereby causing RO$EXIT5 not
to get control.
The exit routine name (RO$EXIT5) should not be changed.
The JES2 Conversion Notebook in the Maintenance chapter suggests that your
installation may need to increase the JOENUM= parameter on the outdef
initialization statement. Due to the dynamic creation of new JOEs by EXIT5
processing, you may need to carefully watch the number of JOEs actually
needed.
11.5.2.1 Processing Overview
During Advantage CA-Roscoe initialization, for each attach job and for each
detach job during an Advantage CA-Roscoe job, a routine in ROSGBL is
executed that checks for the existence of the Advantage CA-Roscoe exit in the
proper place in the exit list. If the routine cannot find the Advantage
CA-Roscoe exit, or finds it, but it is not first in the list or is disabled, output
processing in Advantage CA-Roscoe will not allow conflicting file alterations.
If the exit exists but is disabled at Advantage CA-Roscoe startup, the warning
message will appear on the console. If the exit is subsequently enabled through
the JES2 command:
$T EXIT(5),STATUS=ENABLED
ROSCOE will note the fact and allow conflicting file alterations. If the exit is
then disabled through the JES2 command:
$T EXIT(5),STATUS=DISABLED
Advantage CA-Roscoe will note the fact and prohibit conflicting file
alterations.

11.5.2.2 RO$EXIT5 Processing
Execute entry logic and save registers.

■ Is this a $TOJ, $TOT, or $TOS command?
■ Does the ROSPARM= parameter appear in the command?
If the answer to any of these is "NO," the routine exits to HASPCOMM with
R15 = 0. This causes JES2 to either call the next exit or, if there are no more
exit routines at the EXIT5 point, to process the command.
1. Acquire a work area.
2. Establish a recovery environment.
3. ROSCOE control block validation
■ Is the address (EBCDIC format) a valid hex address?
■ Is the address even?
■ Is the address 31 bit (high byte is non zero)?
■ Is the virtual storage address for the proper length allocated in SQA
subpool 239?
■ Do the first 8 bytes of the control block contain the literal "ROXJ25"?
If the answer to any of these is "NO," the routine exits with an error
message.
4. Data relocation.
Fields from the ROXJ25 control block are relocated to the local work area.
■ TTR of the JES2 IOT
■ Advantage CA-Roscoe job name
■ Advantage CA-Roscoe user ID
■ Advantage CA-Roscoe ECB address in Advantage CA-Roscoe address
space
■ Advantage CA-Roscoe ASCB address
5. ASCB validation.
■ Is the ASCB address in SQA subpool 245?
■ Does the ASCBASCB field contain the literal 'ASCB'?
■ Is the ASCBASID field valid (checked using the ASVT)?
■ Is the ASCB address associated with the ASID the same as the ASCB
address passed?
■ Is the address space alive and well?
If the answer to any of these is "NO," the routine exits with an error
message.
6. Relocate the PDDB model from Advantage CA-Roscoe control block.

7. Verify passed job number (for example, $tojnnnn,rosparm=)

■ Are all characters in job number >=0 and <=9?
■ Does the job exist in JES2?
If the answer to any of these is "NO", the routine exits with an error
message.
8. Verify new OUTGRP name
■ Is the new output group name in the model PDDB unique for the job?
If the answer to this is "NO", the routine exits with an error message.
9. Build a work/char set of JOEs in the workarea ($#BLD).
10. Add the JOEs to the JES job output table (JOT) ($#ADD).
If the ADD function fails, exit with an error message.
11. Exit with success message.
11.5.2.3 Return Processing
All processing return points in RO$EXIT5, with the exception of number 0

(above), result in a message being issued to the console. In addition, register 15
is set to 8, causing JES2 to bypass other EXIT5 routines and not process the
command.
The message member contains the console messages that may appear.
Where possible, exit processing includes a cross-memory post of the waiting

Advantage CA-Roscoe user after setting a return code in the Advantage
CA-Roscoe control block.
The cases where that is not possible, and is therefore avoided, occur when the
Advantage CA-Roscoe control block cannot be validated or when the
Advantage CA-Roscoe ASCB address cannot be validated.
In these cases, if the requestor is Advantage CA-Roscoe, the user remains in a

wait state and will have to be flushed.

11.5.2.4 Recovery Processing
In the event that an abend occurs during exit processing, the EXIT5 recovery
routine will detect if the abend is due to a program check in the exit routine
itself. Any other abend, including program checks (which occur outside the
boundaries of the exit routine), will cause the recovery routine to "percolate" to
the next higher level. This will cause JES2 to terminate. JES2 can be warm
started if this occurs.
If the program check is in the EXIT5 routine, the address of the exit routine in
the JES2 exit tables is cleared so that the routine is not called anymore. The
exit point itself is not disabled because other exit routines may exist at the
EXIT5 point and we do not want to disable them. A retry routine is then
scheduled which puts out a message, attempts to post the user, and then exits
to JES2.
Output group names:
In the event that Advantage CA-Roscoe requires new output groups, it

generates names. The name is eight characters long and is of the format:
1-1 "r" Constant
2-6 (job number) The job number of the job being processed. If the length of
the job number is less than 5, byte 6 contains a C'0'.
7-8 (suffix) The suffix makes the name unique for the job. Its value
ranges from C'01'-C'99' and from C'aa'-C'zz'.

11.6 JES3 Local Requirements

JES3 sites that choose to run Advantage CA-Roscoe on a LOCAL processor
must code JES3OPT=LOCAL in the ROSGBL macro. Also, the following steps
must be performed before starting Advantage CA-Roscoe for the first time:
■ Assemble and link edit a JES3 IATUX30 exit from the source code
provided in RO60OPT (member IATUX30A or IATUX30B, depending on
JES3 release level) into all JES3 load libraries in use at the complex.
■ Create a BDAM data set for use by Advantage CA-Roscoe in transferring
data from one JES3 system to another.
■ Modify the JES3 started-task procedures on all systems and the JCL used
to execute Advantage CA-Roscoe so that they reference the BDAM data
set.
■ Restart JES3 with a "hot start" on all systems in the complex.
The following sections provide additional information about performing these

steps.
11.6.1 Assembling the IATUX30 Exit

The IATUX30 exit must be assembled and link edited into JES3 load libraries
in use at your complex. Use the SAMPJCL member MRO6015 to assemble
IATUX30.
1. Verify that the CAIRO60 SYSLIB concatenation is correct.
2. Select MRO6015 from SAMPJCL and modify the ++SRC statement.
"IATUX30X" must be that version of IATUX30 of the exit required for your
operating system. See the table in MRO6015 for the list of IATUX30
members and the appropriate systems.
3. If the site is executing Advantage CA-Roscoe with a jobname other than
"ROSCOE," the source code for the IATUX30 exit must be modified prior
to assembly and link edit.
To modify the source:
a. IMPORT selected IATUX30 member from the RO60OPT library. (See 2
above.)
b. Find the job name table that begins at label "ROJOBNM" and add the
name under which Advantage CA-Roscoe will execute.
c. Export the source back to the RO60OPT library after modifying the job
name table.
4. Modify the MRO6015 job statement and submit the job. This initiates an
SMP/E RECEIVE and APPLY. During the APPLY an assembly and
linkedit takes place which puts an executable copy of IATUX30 onto target
library RO60LIB.

11.6.2 Creating the BDAM Data Set

Advantage CA-Roscoe (through the IATUX30 exit) uses a BDAM data set to
transfer data between the JES3 GLOBAL processor and the JES3 LOCAL
processor on which it is running. This BDAM data set must be allocated prior
to starting Advantage CA-Roscoe for the first time and must be referenced in
both the JES3 started task procedures and the JCL used to execute Advantage
CA-Roscoe.
The block size of this data set depends on the amount of information the site
wants each user to have access to (that is, the number of jobs about which
information will be returned). The following table shows the block size by
device type that permits information about the maximum number of jobs to be
retrieved.
Device Type Block Size Number of Jobs

2314 7250 157
2319 7250 157
3330-1 13000 282
3330-11 13000 282
3340 8354 181
3350 19026 413
3375 32710 710
3380 32710 710
3390 32710 710
The following formula should be used to calculate the block size:
block size = (46 v) + 28
where "v" is the maximum number of jobs about which information is to be

returned. For example, to allow users to display information about a maximum
of 300 jobs, the formula would be as follows:
block size = (46 3) + 28 = 13828

One block must be allocated for each Advantage CA-Roscoe user. Thus, using
the example above (that is, 300 jobs) with 100 Advantage CA-Roscoe users, the
following JCL could be used to allocate the BDAM data set:
//ALLOC EXEC PGM=IEFBR14
//IATUX3 DD DSN=dsname,DISP=(NEW,CATLG),
// UNIT=unit,VOL=SER=volser,
// DCB=(DSORG=DA,RECFM=F,BLKSIZE=13828),
// SPACE=(13828,(1))
Once the BDAM data set has been allocated, the JES3 started task procedure
on each system in the complex must be changed to include the following DD
statement:
//ddname DD DSN=dsname,DISP=SHR,
// UNIT=unit,VOL=SER=volser
where ddname is the job name under which Advantage CA-Roscoe will
execute and dsname is the data set name of the BDAM data set. It is
recommended that unit and volume information also be included in the DD
statement.
The JCL used to execute Advantage CA-Roscoe should contain the following
DD statement to define the BDAM data set:
//IATUX3 DD DSN=dsname,DISP=SHR,
// UNIT=unit,VOL=SER=volser
The BDAM data set is automatically initialized at Advantage CA-Roscoe

start-up and need not be preformatted in any way. Note that the data set must
be allocated on a volume accessible to all JES3 systems in the complex.

Chapter 12. Data Set Facility Considerations
The Data Set Facility provides an easy way to work with OS data sets and
AllFusion CA-Librarian master files. For a detailed description of this facility,
see the Advantage CA-Roscoe Interactive Environment User Guide.
This chapter discusses:

■ Changes that must be made to the Advantage CA-Roscoe JCL
■ Security considerations
■ Data Set Facility space requirements and usage
■ Advantage CA-Roscoe enqueue logic
Chapter 12. Data Set Facility Considerations 12-1

12.1 Advantage CA-Roscoe JCL Changes
12.1 Advantage CA-Roscoe JCL Changes
12.1.1 Initialization Parameters

There are a number of initialization parameters sites can be used to customize
the Data Set Facility to meet your own needs. For a detailed description of
these parameters, see the Advantage CA-Roscoe Interactive Environment Programs
and Utilities Guide.
12.1.2 DD Statements
In addition to the information noted below, sites should also review the
Advantage CA-Roscoe DD statement requirements described in the Advantage
Advantage CA-Roscoe dynamically allocates the volumes containing data sets

that terminal users access to do reads (for example, IMPORT and ATTACH
DSN) and updates (for example, EXPORT and ALLOCATE DSN).
The volumes containing data sets that are frequently read should be defined in
the JCL to avoid unnecessary system overhead.
These volumes are defined by SYSUTnnn DD statements, where nnn is a

unique arbitrary suffix. The following examples illustrate allocating three DA
volumes:
//SYSUT1 DD UNIT=335,VOL=SER=MCT,DISP=SHR
//SYSUT2 DD VOL=REF=SYS1.PROCLIB,DISP=SHR
//SYSUT3 DD UNIT=333,VOL=SER=WRKPK1,DISP=SHR
No concatenated volumes are permitted. No DD parameters other than those

shown above may be supplied. The disposition may be coded as either OLD or
SHR; the Monitor routine enqueues data sets as appropriate for the terminal
user's requested action.

12.2 Security Considerations
12.2 Security Considerations

As distributed, Advantage CA-Roscoe controls the access to data sets through
external security. Please refer to the Advantage CA-Roscoe Interactive
Environment Security Administration Guide for complete information about data
set access security.
12.2.1 Sites Using AllFusion CA-Librarian:

■ The Advantage CA-Roscoe initialization parameter DSNLPRD2= can be
used to control whether PROD2 modules are included in the AllFusion
CA-Librarian Selection List if the user fails to provide the proper
management code.
If PROD2 modules are not to be included, Advantage CA-Roscoe must
read the index block of each module in the master file to determine
whether the module has PROD2 security status. This may be noticeable to
users when they request a QUICK display format for their Selection List.
(Normally, the response time for a QUICK display format is faster than for
SHORT or LONG, since considerably less I/O is involved.)
■ The initialization parameter DSNLPSWD= can be used to control whether
AllFusion CA-Librarian master file module password protection is to be
ignored for read operations.
Advantage CA-Roscoe initialization parameters are described in the Advantage


12.3 Space Requirements and Usage

The command DMS DSF (described in the Advantage CA-Roscoe Interactive
Environment System Commands Guide) can be used to display information about
the individuals using the Data Set Facility and the amount of storage they are
currently using.
12.3.1 Catalog Space Needs

The DSNCLIST= initialization parameter controls the size of the work area that
is initially GETMAINed for a catalog list request. The parameter is used to
designate the number of catalog entries the work area should be able to hold.
The actual size of the work area is then calculated using the formula:
8 + (45 dsnclist)
If the work area initially GETMAINed is insufficient, Advantage CA-Roscoe

will attempt to acquire the needed size.
It is suggested that sites start with the default value for DSNCLIST= (that is,
100). The information provided by the message ROS204I, which is issued at
Advantage CA-Roscoe shutdown, can then be used to determine if the value
should be changed. The message shows the: 1) value used to calculate the
work area, 2) number of times the work area was sufficient, and 3) the number
of times it was too small. In addition, the message shows the number of cat-
alog list requests and the average number of entries in each. The work area,
derived from the DSNCLIST= value, should be sufficient 70 to 90-percent of
the time but should not greatly exceed the average number of entries in each
catalog list requests.
Note: Due to IBM catalog management restrictions, the storage is acquired
below the 16 MB line on MVS/XA and MVS/ESA systems. It is,
however, used for a relatively short period of time.
12.3.2 Line Queue Elements

The DSNINDEX initialization parameter specifies the maximum amount of
storage that is to be acquired for Line Queue Elements (LQEs) when a
sequential data set, PDS member or AllFusion CA-Librarian module is
attached. These LQEs are used to minimize the amount of physical I/O
required to perform POINT operations and string search commands.
By default, Advantage CA-Roscoe acquires 8 KB of storage. (Note that the

value specified with the DSNINDEX parameter is rounded up to the nearest 4
KB boundary.) The storage is acquired on an as-needed basis in 4 KB blocks.
If the maximum amount of storage is reached, execution continues but the user
will not be able to assign NOTE names and performance may be adversely
affected.

The message ROS204I, which is issued at Advantage CA-Roscoe shutdown,

can be used to evaluate the validity of the value specified. The message shows
the number of times the maximum value was sufficient and the number of
times it was not. In general, sites should keep within a 1-to-2 ratio. Sites that
can afford to allocate more storage are advised to set the value higher than 8K
since the storage is acquired only as needed and has a direct affect on the
performance of the facility. (Note that on MVS/XA and MVS/ESA systems,
the storage is acquired above the 16 MB line.)

12.4 Enqueue Logic
12.4 Enqueue Logic

The ENQTYPE= initialization parameter specifies how Advantage CA-Roscoe
is to protect the integrity of partitioned data sets and AllFusion CA-Librarian
master files. (Advantage CA-Roscoe always provides exclusive control of
non-partitioned data sets.)
12.4.1 ENQTYPE=OS
This is the default setting. With this setting, Advantage CA-Roscoe uses
standard OS ENQ/DEQ logic when processing a data set. That is, Advantage
CA-Roscoe provides an individual with exclusive control of the data set is
being accessed.
Benefit: No other users can access the data set or AllFusion CA-Librarian
master file while the user has exclusive control.
Liability: Advantage CA-Roscoe cannot get exclusive control of a data set that
is under the control of another job, regardless of whether that job has shared
or exclusive control.
12.4.2 ENQTYPE=ISPF
This setting causes Advantage CA-Roscoe to use the IBM ISPF ENQ/DEQ
logic. With this, Advantage CA-Roscoe provides exclusive control of the
specific PDS member or AllFusion CA-Librarian module that the individual
wants to process. The data set itself is under shared control.
Note: The exclusive control of the specific PDS member or AllFusion

CA-Librarian module is in effect only at the time of an update, such as
EXPORT, RENAME, or DELETE. Read access such as IMPORT or
ATTACH will not provide exclusive control of the specific PDS member
or AllFusion CA-Librarian module.
Benefit: Advantage CA-Roscoe users can update PDS members and AllFusion
CA-Librarian modules that are under shared control of other jobs.
Liability: Sites that have batch programs or other online applications that
allocate PDSs or AllFusion CA-Librarian master files with a disposition of SHR
and do not follow the ISPF conventions may experience unpredictable results
when attempting to update a member/module. (Protection is provided in a
shared Advantage CA-Roscoe/ISPF environment as well as in an Advantage
CA-Roscoe/batch environment.)

12.4 Enqueue Logic
12.4.3 Considerations for Sites with ENQ/RESERVE Control Software

Sites that choose to specify ENQTYPE=ISPF and have an ENQ/RESERVE
control software product (such as GRS or MIM) installed should place the
major name SPFEDIT under the control of the product in such a way that any
RESERVEs issued with that major name are converted to globally known
ENQs. If this is not done, other users may experience unacceptable DASD
response times due to the length of the RESERVEs issued by various
Advantage CA-Roscoe components.

Chapter 13. DB2 Support
Advantage CA-Roscoe supports the IBM program product DATABASE 2

(DB2).
With basic Advantage CA-Roscoe, users can execute the DB2 command
processor.
With Advantage CA-Roscoe/DB2, users can dynamically execute SQL

statements, bind application plans, generate language-specific structures from
DB2 tables for inclusion in source programs, process DB2 commands and
interactively execute DB2 applications, all within their Advantage CA-Roscoe
session. For additional information, see:
■ The Advantage CA-Roscoe/DB2 User Guide for information about using this
option.
■ The Advantage CA-Roscoe/DB2 Installation Guide for information about
installing this option.
With both Advantage CA-Roscoe and Advantage CA-Roscoe/DB2, DB2 is

accessed using the standard DB2 TSO attachment facility. This requires that:
■ The standard DB2 connection manager authorization exit (DSN3@ATH) be
extended to ensure that Advantage CA-Roscoe and/or Advantage
CA-Roscoe/DB2 users are correctly identified during DB2 connection
processing.
See Advantage CA-Roscoe Extended Facilities for System Programmers Guide for
additional information about extending the DB2 authorization exit.
■ The DB2 Command Processor (DSN) must be added to the site ETSO
Eligible Program List (EPL). (The EPL entry is shown in the following
table.) The load library containing the DSN load module must be added to
the ETSOLIB DD statement.
Chapter 13. DB2 Support 13-1

Column Contents Meaning
1- 8 DSN Program entry point.
10-12 ' 20' Maximum number of concurrent application
executions. (Adjust this number as needed.)
14-17 ' 2000' Maximum number of CPU time slices.
19-24 ' 1024' Total amount of storage to be provided
below the 16MB line.
26-31 ' 512' Total amount of storage to be provided per
GETMAIN request below the 16MB line.
33-38 ' 5000' Total amount of storage to be provided above
the 16MB line.
40-45 ' 3000' Total amount of storage to be provided per
request above the 16MB line.
47 N Dump flag.
49 Y MODESET authorization flag.
51-52 CP Command Processor Flag.
With Advantage CA-Roscoe, users can execute the DB2 Command Processor
by issuing the following command:
CALL DSN 'SYSTEM(sub-sys)'
where 'sub-sys' is the OS/390 subsystem name of the DB2.
With Advantage CA-Roscoe/DB2, the CALL command to the DB2 Command

Processor is generated internally. DB2 linear syntax commands necessary to
perform the Advantage CA-Roscoe/DB2 functions are also generated. None of
these data streams appear at the user's terminal during a Advantage
CA-Roscoe/DB2 session.
DB2 subcommands and operator commands may be executed during the

Advantage CA-Roscoe or Advantage CA-Roscoe/DB2 session. Execution of the
DB2I ISPF dialogs, SPUFI and QMF are not supported and will return
unpredictable results due to their use of TSO CLISTs and address-space level
resource locking services to generate internal data and DB2 command
sequences.

Chapter 14. ETSO
ETSO (the Extended Time-Sharing Option) is an application execution system

that is distributed as part of Advantage CA-Roscoe. It permits multiple users
to execute a broad spectrum of purchased and/or site-written batch or
interactive applications under Advantage CA-Roscoe.
This chapter provides information to assist sites in:

1. Evaluating the types of applications that can be executed under ETSO.
2. Controlling the extent of resources the application can use.
3. Defining those applications to ETSO.
4. Writing and executing site-written applications.
Chapter 14. ETSO 14-1

14.1 Evaluating Applications

This section presents general information about the types of applications that
can be executed under ETSO. It also contains guidelines sites can use to
determine whether or not these applications should then be defined.
14.1.1 Application Considerations

A wide range of applications can be executed under ETSO with no
modification. These include:
■ Applications written in Assembler and such high-level languages as:
– COBOL (provided the module ILBOCOM0 is link edited as reusable
only).
– FORTRAN (provided the module IFYVLBCM (Version 4 FORTRAN) is
link edited as reusable only).
– PL/I
■ Applications that run under TSO using TPUT and TGET for terminal I/O.
■ Applications based on TSO command processors.
■ Applications which use the TSO Dialog Manager.
■ Applications which use CLISTs and REXX execs.
■ Applications using the following SVCs should be aware of the noted
limitations:
44 CHAP Not supported.
46 TTIMER All functions except TTIMER CANCELS are supported.
47 STIMER Only STIMER WAITS are supported, all other functions are
ignored.
100 FIB Not supported.
109 All functions except 10 and 11 are supported.
For additional information, the profile ROSCOE.MAINT contains a variety of

members that provide additional information about applications that execute
under ETSO.
Finally, sites should be aware that:

1. ETSO provides an LWA (Logon Work Area) that is chained from the
ASCB.
2. ETSO does not support the TSB control block. Some TSO programs and
command processors determine that they are running under TSO by
testing for the presence of this control block. If an application does not
run under ETSO but does run under TSO, check to see if the applications
is relying on the TSB.

3. Certain applications running under ETSO use the contents of the field
PSCBUSER in the TSO control block named PSCB. Under TSO, this field is
initialized to the TSO userid.
To permit these applications to execute, a global pseudo-PSCB is provided
which contains a PSCBUSER field. This field can be initialized by the
Advantage CA-Roscoe PSCBUSER= initialization parameter to the first
seven characters of the Advantage CA-Roscoe job name (the default) or
any one- to seven-character string the site specifies. (This parameter is
particularly important for JES3 sites using the local option.)
Note: Command processors are not passed the address of the global
pseudo-PSCB. They are passed the address of their own unique
pseudo-PSCB. The field PSCBUSER in each unique pseudo-PSCB
contains the user's prefix with the string 'ETSO' concatenated to it.
4. By default, SYSALLDA is the default unit name that is used by dynamic
allocation when an allocation request is received that requires a unit name
and none is specified. This name is placed in the PSCB control block
created by ETSO when a user executes a TSO command processor. The
Advantage CA-Roscoe initialization parameter PSCBUNIT= may be used
to change the default unit name.
5. By default, an individual may allocate a maximum of 19 files per session.
(This includes any combination of terminal, AWS, library member and/or
external data sets.) The Advantage CA-Roscoe initialization parameter
ETSOALLOC= may be use to set the maximum to a value between 1 and
32760.
| 6. ETSO supports a maximum of 10 files to be concatenated per ddname.
7. The ALLOCATE command uses SVC 99 to allocate all OS files. Sites have
the option of:
■ Defining frequently accessed files within the Advantage CA-Roscoe
JCL to eliminate the overhead involved in dynamic allocations. If this
option is used, tell the appropriate users the names of the DD
statements that define these data sets. They can then use these DD
names with the JCLDD= operand of the ALLOCATE command, as in:
ALLOCATE MYDD JCLDD=SITEDD
If users do not identify the file through the JCLDD= operand, the file
will be dynamically allocated.
■ Including text unit X'0061' in the SVC 99 parameters for all new data
sets created with a permanent data set name.
By default, text unit X'0061' is included only when the user issues the
ALLOCATE command with PROTECT=YES. Sites that want to
| implement this should contact the Advantage CA-Roscoe technical
| support staff for the USERMOD. If this change is made, users should
not use the PROTECT= operand of the ALLOCATE command.

8. ETSO contains an extension that allows users to easily switch between the
use of TSO facilities and native Advantage CA-Roscoe facilities. This TSO
compatibility mode provides an environment for the continued execution
of TSO commands, procedures, and products within Advantage
CA-Roscoe, including those which have no Advantage CA-Roscoe
counterpart.
Note: Applications such as ISPF/PDF can run under Advantage
CA-Roscoe, but sites remain responsible for those applications and
must provide the application/service for the user.
■ Using the Advantage CA-Roscoe TSO command from the command
line, or within an RPF, a user can invoke any TSO program or
command.
Note: For information on the use of the TSO command, see the
Advantage CA-Roscoe Interactive Environment Command Reference
Guide.
■ The ETSO compatibility mode allows these commands to be passed, as
is, to the Advantage CA-Roscoe Command Processor, ROSTMP, which
will invoke the appropriate TSO facility.
■ Advantage CA-Roscoe runs as an APF authorized task. The use of an
ISPLLIB or STEPLIB within either CLISTs or RPFs that call ISPF may
result in an S306-C abend in ISPMAIN. The data sets allocated in the
ISPLLIB or STEPLIB from a CLIST or RPF must be added to the
Advantage CA-Roscoe ETSOLIB concatenation. If your linklist is
authorized through LNKAUTH=LNKLST and ETSSRCH=ALL, no
pre-allocation of ISPLLIB or STEPLIB will be necessary if the load
library is found in the linklist.
| ■ LIBDEF and FILEDEF statements for load libraries are not supported
| by ETSO.
■ The Advantage CA-Roscoe Eligible Program List (EPL) must contain
an entry for any TSO command executed from the Advantage
CA-Roscoe command line or RPF. At least one EPL entry is required
for the pseudo command ROSTMP itself. The control values specified
for ROSTMP will serve as the defaults for commands invoked from the
Advantage CA-Roscoe command line or from an RPF if there is no
entry for the command in the EPL.
The EPL entry must have the CP flag turned ON to designate that it is
called as a TSO command processor.
Note: See the Advantage CA-Roscoe Interactive Environment Programs
and Utilities Guide for the initialization parameters necessary for
establishing this TSO compatibility environment.
■ Entering the Advantage CA-Roscoe TSO command activates ROSTMP
through an OS ATTACH; or if ROSTMP is already active, it is signaled
with new input. ROSTMP will invoke the appropriate TSO command
processor and pass to it the parameters passed in the (Advantage

CA-Roscoe) TSO command. ROSTMP remains active until TSO

LOGOFF is specified.
■ Advantage CA-Roscoe does not support the TSO TIME and TSO
LOGOFF commands when issued from a REXX exec. Attempting to
issue one of these commands within a REXX exec will result in a
return code of -3.
■ This facility will not replace existing ETSO facilities (and the CALL
command.) The ETSO CALL command will remain a more specialized
(and explicit) way to invoke a program in a TSO-compatible
environment.
■ This compatibility mode will provide for the execution of CLISTs as
well as REXX execs. Those procedures will be executable directly from
the command line, from within each other (nesting), and from within
ISPF dialogs. Both Explicit (EXEC) and Implicit (%) invocations are
supported.
| When invoking CLISTs, to prevent extraneous information (garbage)
| from being displayed on your screen, include the following in the
| CLIST:
| ISPEXEC CONTROL DISPLAY REFRESH
14.1.2 Site Considerations

After determining that an application will execute under ETSO, sites should
evaluate the impact of that application on their environment. The following
guidelines (Rules of Thumb) should be taken into consideration before a site
allows an application to run under ETSO.
1. Why install an application that performs a task which can be accomplished
using Advantage CA-Roscoe facilities? For example, the Advantage
CA-Roscoe SKETCH facility performs the same function as those
applications used to design screens for use in programs running under
CICS or IMS; the Advantage CA-Roscoe commands DISPLAY and
ATTACH JOB provide the same functions that are available with SDSF
(Spool Display and Search Facility).
2. Advantage CA-Roscoe is not TSO. Applications which rely on TSO control
blocks may not execute as expected under ETSO. Any questions about an
application or problems encountered with an application should be
directed to the Advantage CA-Roscoe Support Staff.
3. Advantage CA-Roscoe cannot make an application use fewer resources
than it already does. An application requiring 100K to execute under TSO,
for example, still requires 100K to execute under Advantage CA-Roscoe.
Certain efficiencies are gained, however, if the application is reentrant. In
this case, only one copy of the application need be loaded into the
Advantage CA-Roscoe address space. Multiple users can concurrently
execute the same reentrant application.

4. An application using CLISTs or REXX execs requires TSO/E 2.1 or above.

5. An application written through a special facility needs that facility to
execute under Advantage CA-Roscoe. For example, an application written
with the IBM Program Development Facility (PDF) requires ISPF/PDF to
execute under Advantage CA-Roscoe. Based on the second rule of thumb,
the same amount of space ISPF/PDF requires in TSO is required in
6. An address space has a finite amount of memory. The resources required
for an application to execute under ETSO come from the Advantage
CA-Roscoe address space. While ETSO enables a site to control through
the EPL the CPU time and memory allocated to an application, these
resources are not unlimited.
Sites can use the following formulas when deciding what applications to allow
under ETSO:
1. Determine the amount of memory available.
X = A - B - C
where:
A Size of Advantage CA-Roscoe address space.
B Amount of space required by Advantage CA-Roscoe.
C Amount of space required by the applications already allowed under
ETSO.
2. Determine the amount of memory required by the application.
Y = D + (E F)
where:
D Amount of space required by the application, provided the
application is reentrant.
E Amount of dynamic working storage (GETMAIN) required.
F Number of users expected to concurrently execute the application.
If the amount of space required by the application is greater than that

available, site management might consider:
■ Omitting the application from ETSO.
■ Determining if they can accept fewer concurrent users. (The more people
concurrently executing an application, the greater the resource usage.)
■ Executing a second Advantage CA-Roscoe that is in whole or in part
dedicated to ETSO applications. Since the Advantage CA-Roscoe library
system can be shared, user profile information and library members are
available to both Advantage CA-Roscoes.

14.2 Controlling Resources and Use

The resources (CPU time and memory) required for an application to run
under ETSO come from the Advantage CA-Roscoe address space. Applications
that require an excessive amount of CPU time or storage increase the
Advantage CA-Roscoe resource requirements. Sites are, therefore, provided
with the ability to control:
■ The applications that can be executed.
Applications that are to run under ETSO must be defined in the Eligible
Program List (EPL). (The EPL is described in the next section.)
■ The CPU and storage resources used by the application.
When defining an application in the EPL, sites can specify a maximum
number of CPU time slices that are to be provided to an application. When
the maximum number of time slices is used, the application is terminated.
Note: A time slice is the amount of time it takes to process a fixed
amount of work. By default, one time slice is equal to 5,000
microseconds. This value may be changed by the ETSSLICE
initialization parameter.
ETSO itself monitors the CPU usage of each executing application and
adjusts the priority of the applications to ensure that the applications do
not adversely affect other Advantage CA-Roscoe users. Thus, if one user is
executing a CPU-intensive application no other Advantage CA-Roscoe or
ETSO users are affected.
The application's EPL definition also allows sites to specify both the total
amount of storage the application is permitted to use and the maximum
amount that can be acquired by any one request. When an application
exceeds the total amount of storage assigned, the application is terminated.
ETSO frees any storage that the application acquired but did not free
before it terminated.
■ The number of people who can execute an application.
Sites can designate the maximum number of people that can concurrently
execute an application. This is useful when a large number of people want
to execute an application that requires substantial CPU and/or storage. For
example, if an application requires 400K of main storage and is not
reentrant, several users executing this application at the same time can
reduce the storage available to other users. Similarly, if an application
requires one minute of CPU time, the Advantage CA-Roscoe CPU
requirements increase. Thus, limiting the number of people who can
concurrently execute the application allows you to balance user needs.

Sites can also control:

■ Which individuals are allowed to execute an application.
The exit associated with the CALL command can be used to control who
may execute any or all applications. (The CLLEXIT exit is described in the
Advantage CA-Roscoe Extended Facilities for System Programmers Guide.)
■ The application's access to library members and external data sets.
If an application attempts to use a library member that does not belong to
the individual executing the application, Advantage CA-Roscoe
automatically checks the access authority of the security group to which
the user is assigned and compares it to the access attribute of the
designated library member. (See the description of the security groups in
the chapter on the 'User Profile System'.
As distributed, Advantage CA-Roscoe controls the access to data sets
through external security. Please refer to the Advantage CA-Roscoe Security
Administration Guide for complete information concerning data set access
security.

14.3 Defining Applications to ETSO

All applications that are to be executed under ETSO must be defined in: 1) a
library known to ETSO and 2) the Eligible Program List.
14.3.1 Loading Programs on ETSOLIB

By default, ETSO expects the applications to be in (or concatenated to) a data
set identified by the ETSOLIB DD statement. The following example illustrates
how the ETSOLIB DD statement might be defined in the Advantage
CA-Roscoe JCL.
//ROSCOE EXEC PGM=ROSCOE...

//STEPLIB DD DSN=CAI.RO6LIB,DISP=SHR
//ETSOLIB DD DSN=ROSCOE.ETSOLIB,DISP=SHR
// DD DSN=CAI.RO6LIB,DISP=SHR
// DD DSN=SYS1.LINKLIB,DISP=SHR
// DD DSN=SYS1.CMDLIB,DISP=SHR
When defining ETSOLIB, sites might want to:

■ Keep the applications executable under ETSO on a separate load library. In
the preceding JCL, this is represented by the ROSCOE.ETSOLIB file.
■ Include CAI.RO60LIB in the ETSOLIB concatenation. This allows programs
distributed with Advantage CA-Roscoe (for example, ROSDATA) to be
invoked by the CALL command.
Alternatively, sites can use the Advantage CA-Roscoe initialization parameter

ETSSRCH= to designate that application are in: ETSOLIB (or a data set
concatenated to it), JOBLIB/STEPLIB (or a data set concatenated to it), the Link
Pack Area, or a data set defined in a linklist concatenation. Either IEBCOPY or
standard linkage-editor procedures can be used to place the application in the
proper load library.

The following sample JCL assumes that the site has a load library named
ROSCOE.ETSOLIB in its ETSOLIB concatenation. The JCL shows how to
assemble and link edit an Assembler language program onto
ROSCOE.ETSOLIB.
| // ASSEMBLE INTO CA-ROSCOE OBJECT LIBRARY

| //ASM EXEC PG,=ASMA9,REGION=496K,PARM='XREF(SHORT),OBJECT,DECK'
| //SYSLIB DD DSN=SYS1.AHASMAC,DISP=SHR
| // DD DSN=ROSCOE.RO6MAC,DISP=SHR
| // DD DSN=SYS1.MACLIB,DISP=SHR
| // DD DSN=SYS1.MODGEN,DISP=SHR
| //SYSPRINT DD SYSOUT=
| //SYSTERM DD SYSOUT=
| //SYSPUNCH DD DUMMY
| //SYSUDUMP DD SYSOUT=
| //SYSUT1 DD UNIT=VIO,SPACE=(CYL,(14,1))
| //SYSLIN DD UNIT=VIO,SPACE=(TRK,(15,15)),DSN=&&TEMP,
| // DCB=(RECFM=FB,LRECL=8,BLKSIZE=312,DSORG=PS),
| // DISP=(,PASS)
| //SYSIN DD DSN=DSN=CAI.RO6OPT(mod-name),DISP=SHR
// LINK INTO ETSO LOAD LIBRARY
//LINK EXEC LKED,COND=(,NE),PARM='parms'
//LKED.SYSLMOD DD DSN=ROSCOE.ETSOLIB,DISP=SHR
//LKED.SYSLIB DD DSN=&&OBJ,DISP=SHR
//LKED.SYSIN DD
INCLUDE SYSLIB(mod-name)
ENTRY epname
NAME name(R)
/
After an application has been copied or link edited, the Eligible Program List
(EPL) must be updated. The EPL identifies the applications that are CALLable
under ETSO.
14.3.2 Defining Programs in the EPL

For an application to be CALLable by terminal users, it must be defined in the
EPL (Eligible Program List). Sites must ensure that:
■ The first line must contain the string VERSION2 in the first eight positions
of the line. (If VERSION2 is omitted, it is assumed the EPL does not
include fields provided with release 6.0 of Advantage CA-Roscoe.)
■ When adding applications to this list, make sure that:
– The list is arranged in ascending alphabetic order by program entry
point name. (Program names beginning with a special character must
be in EBCDIC order and be placed at the beginning of the list.)
– Each record comprising the list conforms to the format shown below.
Column Contents
1-8 Program entry point specified as a 1- to 8-character name
starting with an alphabetic character.
9 blank

Column Contents
10-12 Maximum number of concurrent executions of the
applications. Specify a value between 000 and 999, where
000 prevents anyone from executing the application and 999
places no restriction on the number of concurrent execution.
13 blank
14-17 Maximum number of CPU time slices to be provided before
the application is forced to terminate. (The default time
slice value is equal to 5,000 microseconds.) Specify a value
between 0000 and 9999, where 9999 prevents the application
from terminating.
18 blank
19-24 Maximum amount of storage (in K) that the application can
acquire. Specify a value between 000000 and 999999. The
storage is acquired below the 16MB line.
25 blank
acquire in any one variable length getmain request (for
example, an application limited to a maximum of 512KB can
be further restricted so that storage is provided in
increments of 32K). Specify a value between 000000 and
999999. The storage is acquired below the 16MB line.
32 blank
acquire above the 16MB line. Specify a value between
000000 and 999999. (For non-MVS/XA and non-MVS/ESA
sites, the value is validated and ignored.)
39 blank
acquire above the 16BM line in any one getmain request.
Specify a value between 000000 and 999999. (For
non-MVS/XA and non-MVS/ESA sites, the value is
validated and ignored.
46 blank
47 Dump flag used to control the production of a dump if the
application should abend. Specify:
Y - Produce dump. (Y and D are synonymous.)
N - Suppress dump.
48 blank

Column Contents
49 Authorization flag used to control the application's use of
SVC 107. Specify a Y if the application is to be authorized to
issue the MODESET SVC (that is, the application may go
into supervisor state (key 0)). A blank or any value other
than Y prevents the application from issuing the SVC.
50 blank
51-52 Command processor flag used to designate that the
application is to be called as a TSO command processor.
Specify CP if the application is to be called as a command
processor. A blank or any other value prevents the
application from being called as a command processor.
53-255 Ignored.
During installation, the library member ETSOPGMS is added to the library of

the individual assigned the RO prefix. This member contains the distributed
| EPL. As initially installed, the EPL contains an entry for the sample application
| MORTGAGE (This application is distributed on CAI.RO60OPT.)
■ MORTGAGE is a FORTRAN program which performs various calculations
associated with the rate, life, amount borrowed and monthly payments of
a mortgage loan. (See the Advantage CA-Roscoe Interactive Environment User
Guide for additional information about executing this program.)
Sites have the option of defining their EPL in a different library member. If the
EPL is not defined in RO.ETSOPGMS, the Advantage CA-Roscoe initialization
parameter ETSOPGMS must be used to identify the prefix and name of the
library member containing the EPL.

14.4 Writing and Executing Applications
14.4 Writing and Executing Applications

For information about:
■ Executing applications under ETSO, see the Advantage CA-Roscoe Interactive
Environment User Guide.
■ The ETSO commands that all Advantage CA-Roscoe users may use, see the
Advantage CA-Roscoe Interactive Environment Command Reference Guide.
■ Using ETSO commands within RPF programs to control the execution of
applications under ETSO, see the Advantage CA-Roscoe Interactive
Environment RPF Language Guide.
■ ETSO commands that are provided for the individual responsible for
maintaining Advantage CA-Roscoe, see the Advantage CA-Roscoe Interactive
Before beginning to develop an application for use under ETSO, review the
section in this manual entitled 'Evaluating Applications.' Also, review the
section, ETSO Application Programming Interface, in the Advantage CA-Roscoe
Interactive Environment Extended Development Tools Guide. This interface can be
used to allow the application to take advantage of Advantage CA-Roscoe
facilities. For example, the application can:
■ Query the environment to determine if the application is executing under
ETSO and to return such Advantage CA-Roscoe-specific information as the
user's sign-on key and prefix.
■ Allow RPF panels to be executed and access the associated panel variables.
■ Access all RPF variables and convert the format of the data if necessary.
■ Suspend the application to allow control to return to Advantage
CA-Roscoe. This allows the user (or controlling RPF program) to process
in native Advantage CA-Roscoe. For example, the user could edit and
submit data that has been written to the AWS by the suspended
application. The user can then issue the RESUME command to continue
application execution.

Chapter 15. BTSO
|
This chapter describes BTSO and how to evaluate and define applications to
| run under BTSO. BTSO (Batch Time Sharing Option) is an application
| execution routine that is distributed as part of Advantage CA-Roscoe.
| Most user applications are developed for a single user address space
| architecture (IBM TSO). In a single address space, allocation of resources such
| as storage and DASD are not a consideration. In a multi user address space,
| there are system constraints and limitations. BTSO can lessen some of these
| limitations. Terminal reads and writes requested by the BTSO applications are
| screened and directed back to the Advantage CA-Roscoe ETSO user. The SVC
| processing that exists under ETSO, for a BTSO application, is minimal since the
| SVCs are executed outside of Advantage CA-Roscoe.
| BTSO enables sites to execute purchased or user developed applications in an

| address space separate from Advantage CA-Roscoe. An Advantage CA-Roscoe
| user communicates with the BTSO address space through a 12K ETSO
| application. Since the application executes in its own region, there is virtually
| no restriction on memory or DASD.
| The Advantage CA-Roscoe BTSO facility consists of the following components:

| RTBETSO Runs within the Advantage CA-Roscoe address space
| RTBBATCH
| Runs in the newly created address space
| Note: Common storage is used to communicate between the two components.
Chapter 15. BTSO 15-1

15.1 Application Considerations
15.1 Application Considerations

| An application executing under BTSO does not have access to the Advantage
| CA-Roscoe libraries or to Advantage CA-Roscoe AWS.
| The BTSO job may be started as a JCL stream or as a started task. You must
| ensure that there is an initiator available for every BTSO user, it is suggested
| that you set aside a specific number of initiators in a specific job class for
| BTSO. Set the BTSO MAXUSERS= to specify the number of initiators.
| A program executing in a BTSO address space will be authorized only if it is

| in an APF authorized library and is linkedited with the APF authorization
| attribute (AC=1). Also, the program name must be included in the BTSO
| authorization table MR06090. See 15.2, “CSA Usage” on page 15-3 for
| additional information.

15.2 CSA Usage
15.2 CSA Usage

| Advantage CA-Roscoe BTSO uses the following amounts of CSA storage.
| ECSA SP 228 4K
| CSA SP 228 512 bytes/user maximum
| CSA SP 241 36K/user maximum

15.3 Installation
15.3 Installation
15.3.1 Define BTSO to CAIRIM

See SAMPJCL member RO60RIM to redefine the Advantage CA-Roscoe
RIMPARMS.
| PRODUCT(CA-ROSCOE) VERSION(RO6) INIT(RO6INIT) X
| PARM(INIT,MAXUSERS=nn,TIMEOUT=mm)
| If at any time you want to re-specify the BTSO initialization parameters, you
| must use the RIM REINIT parameter as shown following.
| PARM(REINIT,MAXUSERS=nn,TIMEOUT=mm)
| If you want to delete BTSO, you must specify the RIM DELETE parameter.
| PARM(DELETE)
INIT Build TSO main control block.
REINIT ECSA SP 228.
DELETE Deletes control block.
MAXUSERS=nn Maximum number of users permitted on system at one
time.
TIMEOUT=mm Maximum number of seconds Advantage CA-Roscoe will
wait for posting of new address space to be created.
Default 30 seconds.
CAIRIM must be restarted after the RIMPARMS have been redefined.
15.3.2 Define BTSO to ETSO

Add an entry to the EPL to define the BTSO interface program. The following
can be used as a sample definition.
| RTBETSO 5 2 496 372 5 3 N Y CA-ROSCOE BTSO
15.3.3 Authorization
USERMOD MR06090 in the SAMPJCL library must be received and applied to
create the Advantage CA-Roscoe BTSO Authorization Table. This table must
contain the names of all programs to be attached as APF Authorized.
| Note: Change member RTBATABL in the RO60OPT library to include all
| APF authorized members prior to executing MRO6090.

15.3 Installation
15.3.4 Copy Supplied RPFs

| Four RPFs, BTSO, BTSOOPT0, BTSOAPPL, and BTSOSTCA are supplied in the
| CAI.SAMPJCL file. These RPFs must be copied to your RPF execution library.
| Sign on to ROSCOE.CONTROL, import members BTSO, BTSOOPT0,
| BTSOSTCA, and BTSOAPPL from CAI.SAMPJCL and save each in the RPF
| execution library.
15.3.5 USERMOD MR06026 - Modify IRXISPRM for Advantage

CA-Roscoe CLIST/REXX Usage
If you have supplied MR06026 to modify IRXISPRM for Advantage CA-Roscoe
CLIST/REXX usage, the IRXISPRM is not compatible with BTSO. You must
either:
■ Steplib to the unmodified version of IRXISPRM in your BTSO application
steplib, or
■ Copy the following BTSO modules to their own APF authorized library,
RTBBATCH, RTBETSMM, RTBSCRN, RTBSTOP, and RTBSUBMT.
15.3.6 RPF Interface

Review the RPFs that have been supplied with the maintenance upgrade and
make the necessary modifications for your system. Customize the sample RPFs
BTSO, BTSOOPT0, and BTSOAPPL. Execute BTSOOPT0 to create a valid job
card paying special attention to the initiator class. Execute BTSOAPPL to
execute your application under BTSO.
Note: Make sure that you have added the JCL allocation DD statement before
execution.
15.3.7 Calling RTBETSO

| RTBETSO expects one of two different kinds of inputs:
| 1. JCL statements
| The JCL statements for the application must contain one and only one
| jobcard and one or more EXEC statements. However, there can be as many
| DD statements as necessary.
| RTBETSO changes the program name being executed to RTBATCH. The
| JCL is submitted through the internal reader where appropriate SUBEXIT
| calls are made.
| 2. Parameter statements to indicate that the job is to be a started task
| Required parameters are:
| PGM=
| PROC=
| PROCPARM=

15.3 Installation
| The PGM= parameter specifies the name of the program to be executed.

| The proc must include the parameter "BTSOCNTL".
| RTBETSO changes the program name being executed to RTBATCH. The JCL
| is submitted through the internal reader where appropriate SUBEXIT calls are
| made.
| TERMINAL DATASETS MUST BE DEFINED AS "SYSOUT=(,TERM)"
| The program name may contain the following to specify the type of program
| to be executed:
| Value Meaning
| (CP) Command processor
| (P) Problem program
| (SCP)
| Command processor with synchronized TPUTS
| The PROC= parameter specifies the name of the proc to be started.
| The PROCPARM= parameter allows the user to specify additional parameters

| to the proc.
| Start the BTSO session by calling the RTBETSO program using the Advantage
| CA-Roscoe ETSO facility. RTBETSO processes the parameters passed by the
| user and starts the BTSO address space. The module waits for the following
| feedback from the new address space:
| ■ Any TPUTs/TGETs from the BTSO address space are monitored and sent
| to the Advantage CA-Roscoe address space when the new address space
| terminates.
| ■ Ends the Advantage CA-Roscoe. ETSO session when the BTSO address
| space terminates.
15.3.8 RTB Monitor

The RTB monitor is supplied as a load module with this release to allow users
to view the status of BTSO. To activate the RTB monitor, you must first
include a RUN=RTB statement in the Advantage CA-Roscoe SYSIN stream.
The RTB monitor provides you with:
■ ETSM address
■ MAXUSERS= value
■ TIMEOUT= value
■ Current number of users
■ Maximum number of users since last IPL
■ Displays of the currently active programs executing under BTSO

15.3 Installation
|15.3.9 RTBEXIT
| RTBEXIT is the user exit provided for BTSO. A sample RTBEXIT is provided in
| the RO60OPT file. The exit may be assembled and linkedited using usermod
| MRO608B in SAMPJCL.
| The RTBEXIT call description is as follows:

| Initial call Called at the start of the BTSO program
| Verify call Called to issue the security signon
| Delete call Called to issue the security signoff
| Final call Called at the end of the BTSO program

Chapter 16. HELP Facility
The Help Facility is comprised of a series of Advantage CA-Roscoe library

members accessible online through the HELP command. The library members
contain basic information about the use of Advantage CA-Roscoe, RPF, and the
Monitor commands. The Help Facility is meant to provide assistance to the
terminal user during an Advantage CA-Roscoe session. It is not meant to be a
new-user training tool, but rather a quick, online reference.
Chapter 16. HELP Facility 16-1

16.1 Accessing Help Members
16.1 Accessing Help Members

Help members are accessed by name. For ease of use, the names of the
distributed Help members reflect the information contained within the
members (that is, the Help member named FETCH contains a description of
the FETCH command). The Help member names must conform to Advantage
CA-Roscoe naming conventions. (See the Note below.)
The HELP command accesses the named Help library member and interprets
for display the format codes contained within the member. For example,
| HELP FETCH displays the interpreted contents of the member named FETCH,
| while ATTACH pfx.FETCH displays the member with no interpretation. (The
HELP command itself is described in the member named HELP; the
description can be displayed by entering HELP or HELP HELP.) The syntax of
the HELP command is:
──HELP──┬───────────────────────────────────┬─────────────────
└─command─┬────────┬──┬─Function─┬──┘
└─levell─┘ ├─Syntax───┤
└─Levelx───┘
Note: The Help Facility does allow the terminal user to request help for
specific special characters that have a unique meaning within
Advantage CA-Roscoe. The use of these characters is not an exception
to the rule that member names must conform to Advantage CA-Roscoe
naming conventions. The Help Facility actually converts these special
characters to predefined library member names. The following list
shows the special characters that can be specified with HELP and the
predefined member names they are converted to:
HELP * Equivalent to HELP CHARASTR
HELP ,, Equivalent to HELP CHARCMMA
HELP : Equivalent to HELP CHARCOLN
HELP - Equivalent to HELP CHARMINS
HELP + Equivalent to HELP CHARPLUS
HELP ? Equivalent to CHARQUES

16.2 Scrolling Help Members
16.2 Scrolling Help Members

If a Help member exceeds the size of the terminal screen, PF keys must be
used to scroll backward and forward through the member.
With the Help Facility, the scrolling functions are hard-coded (that is, not
modifiable) and are assigned to:
PF7/PF19 Scrolls back to beginning of the current level.
PF8/PF20 Scrolls forward within a level.
PF10/PF22 Scrolls back to the previous level.
PF11/PF23 Scrolls forward to the next level.
If the scrolling function cannot be performed (that is, there is no next level),
the current level remains displayed.

16.3 Installing and Maintaining Help Members
16.3 Installing and Maintaining Help Members

| The library members constituting the Help Facility are distributed on
| CAI.RO60.KEYS. During installation, the profile for Help is created and the
members are restored to that profile. A site may use a profile with a different
prefix by changing the Advantage CA-Roscoe initialization parameter
HELPPFX=.
Any new or revised member must be stored under the HELP profile to be
accessed by the HELP command.
Each distributed Help member has a description associated with it. Use the
Library Facility under the HELP key to display a list of members and their
descriptions.

16.4 Creating Site-Specific Help Members

Sites may create their own Help members. When doing so, make sure that the
new members are saved under the HELP profile.
The members may include the formatting codes that are used with the
distributed Help members. The codes, which are not visible when the member
is displayed through the HELP command, are:
Code Meaning
T Title Identifier
F Function Identifier
S Syntax Identifier or Screen Break
@ End of Syntax Marker
C Level or Subcommand List Identifier
?name Level or Subcommand Label
A Alias Identifier
* Comment Identifier
¢ Highlight Identifier
The format codes must begin in the first position of a line. The alphabetic
codes may be entered in uppercase or lowercase.
The remainder of this section describes how these formatting codes can be
used.
16.4.1 Identifying Title, Function and Syntax/Screen Break
16.4.1.1 Title
The first line of a Help member should contain a title. A title line consists: 1)
the format code T (in the first position of the line), and 2) the title itself.
Any number of spaces can separate the format code from the title, allowing the
title to be centered on the line. The title need not be related to the library
member name. The title is displayed whether the user chooses to view an
entire Help member or a specific segment, level or subcommand.
16.4.1.2 Function
The function segment is usually a brief description of the subject explained in

the Help member.
The function format code (F) must appear in the first position of the line and
be separated by one or more spaces from the description. If the description
exceeds one line, additional F codes are not required on the succeeding line(s).
The end of the function segment is marked by the presence of the next format
code or the end of the member.

16.4.1.3 Syntax
The syntax segment, delimited by the format codes S and @ respectively,

should contain the syntax of the command being explained.
The syntax segment begins with the S format code, placed in the first position
of the line and separated by one or more spaces from the syntax. If the syntax
extends over one line, additional S codes should not be included on the
succeeding lines.
The syntax segment is ended by the @ format code. Place it in the first position
of the line immediately following the syntax; the remainder of the line must be
blank. This line cannot be used as a blank line separating the syntax from
subsequent information because it is not displayed when the HELP command
is used to display the member.
The following panel illustrates the use of the T, F, S and @ format codes:
Basic Help Member
T FETCH

F Function: Brings all or part of library member into AWS.
S Syntax: FETCH mem < p <q> >

@
mem Name of member to be brought into AWS.
p<q> First line (p) and last line (q) of member to be

fetched.
Short Form: F


Notes:
■ The command syntax, in the distributed Help members, is set up in a
linear manner to accommodate typewriter devices as well as 3270-type
terminals.
■ The choice of special characters used in the syntax notation was
determined by the characters available on the majority of keyboards. Thus,
– Angle brackets < > indicate optional operands.
– she slash / specifies alternative operands from which one must be
chosen.
– Apostrophes ' ' are used to delimit character strings.
– Parentheses ( ) designate that the operand is required if the
accompanying operand is specified.
16.4.1.4 Creating Screen Breaks (3270 only)
As noted, the first use of format code S indicates a syntax segment.

Subsequent uses of S designate specific screen display breaks.
To create a display break, place the S format code in the first position of a line
and leave the remainder of the line blank.
If display breaks are not included and a Help member exceeds the maximum
number of lines in the Execution Area, pressing PF8 (to scroll forward within
the level) causes the display to continue with the next line regardless of its
context within the display.
If display breaks are included, the display will continue with the first data line
that follows the last line containing an S format code. For example, assume a
Help member contains 50 lines and that 37 of those lines can be displayed in
the Execution Area. If display breaks are omitted, the display will begin with
line 38 when the member is scrolled forward. If a display break was coded on
line 35, the first data line following line 35 will be the first displayed line when
the member is scrolled forward.
Note that the S code is ignored when using the split-screen facility and the
active screen contains 17 lines or less. Instead, the last line displayed on the
current screen becomes the first displayed line on the next screen.

16.4.2 Creating Levels Within Help Members

There may be instances when it is appropriate to include subordinate
information within a Help member. For example, the descriptions of the
DISPLAY subcommands are included as individual subordinate entries within
the DISPLAY Help member. This allows the user to display information about
DISPLAY or any of its subcommands.
16.4.2.1 Level/Subcommand List
Use the list format code (C) to denote a list of levels or subcommands
contained within a Help member. It must be coded in the first position of the
line. The end of the segment is indicated by the next function code or the end
of the member. The following panel illustrates this.
Help Member With Level/Subcommand List
T DISPLAY

F Function: Displays information from operating system on jobs
in execution, initiators, job queues and online
devices.
S Syntax: DISPLAY < -A / -X > < string >
@
...
S
C Level: For information on subcommands, enter:
HELP DISPLAY ACTIVE (jobs currently active)

HELP DISPLAY AWS (subsequent output to AWS)
HELP DISPLAY DEVICES (devices online and mounted)
...

When the user includes the LEVEL keyword with the HELP command (that is,
HELP DISPLAY LEVEL), only the title of the member and the list of levels or
subcommands is displayed.
16.4.2.2 Level/Subcommand Labels
To create a subordinate entry within a Help member, use the level identifier
format code ?name where name is a word that the terminal user is to enter to
display the subordinate information. Using the preceding example to
illustrate, if the terminal user enters HELP DISPLAY DEVICES, the
information associated with that portion of the DISPLAY Help member is
displayed.

The format code (?) must be placed in the first position of the line and the
level name must immediately follow it with no intervening spaces. The
following panel consists of selected segments of the Help member DISPLAY
and demonstrates the use of the level identifier:
Help Member With Subordinate Subcommands
T DISPLAY

F Function: Displays information from operating system on jobs
in execution, initiators, job queues and online devices.
S Syntax: DISPLAY < -A / -X > < string >
@
...
S
C Level: For information on subcommands, enter:
...
?A
?ACTIVE
T ACTIVE Subcommand for DISPLAY
F Function: Shows jobs currently active in the system.

S Syntax: ACTIVE < ,ALL / ,string / ,STC / ,TSO >
...
Short Form: A
?AWS
T AWS Subcommand for DISPLAY
F Function: Directs all subsequent output to AWS.

...

Notice that the ACTIVE subcommand can be referenced as either HELP
DISPLAY ACTIVE or HELP DISPLAY A (where A is the short form of the
subcommand). Any number of level identifiers can be specified. Usually, one
is the true identifier (that is, ACTIVE) while the others are referred to as
aliases (that is, A).
In the following panel, the level identifiers are used to include associated
information within a Help member. Notice, again, that the terminal user can
enter either HELP TRAP CODE or HELP TRAP CODES:

Help Member With Subordinate Level
T TRAP

F Function: Enables or disables trap facility.
S Syntax: TRAP < OFF / ON >

@
...
?CODES
?CODE
T TRAP CODES
Use S.TC session variable to test value of trap code set by
execution of Advantage CA-Roscoe command.
Trap Message
Code Number Associated Message Text
(no error)
1 CMD18 NO LINES/MATCH FOUND IN RANGE
2 CMD11 FACILITY DOES NOT EXIST IN THIS SYSTEM

RPS11 PRINTING SERVICES NOT AVAILABLE
....

Notice also that secondary titles (format code T) can be included in Help
members. The primary title of a Help member will appear on the initial
display. It is overlaid by the secondary title, also coded T. In this manner,
levels and subcommands can be displayed with their individual titles. If a T
format code is not recoded after the ? format code, the previously coded title
of the member is displayed.
16.4.3 Specifying Aliases

The alias format code (A) permits a Help member to be accessed by more than
one name. For example, to display the list of manuals distributed with
Advantage CA-Roscoe, the terminal user can enter HELP DOCUMENT or
HELP MANUAL where MANUAL is an alias for DOCUMENT.
When an alias is used, it must be saved as a separate Help member. The

member must one line which begins with the A format code in the first
position of the line and the name of the member it is referencing. A space,
separating the format code from the name of the referenced member, is
optional. A comment may be included on that line. If it is, the comment must
follow the referenced member name by one or more spaces. For example, the
contents of the alias member for the MANUAL member is formatted as:
A DOCUMENT Alias Help Facility member named MANUAL
Any number of alias members referencing the same Help member can be
created.

The distributed Help library includes an alias member for every Advantage
CA-Roscoe or Monitor command that has a short or alternate form.
16.4.4 Commenting Help Members

The comment format code (*) permits comments to be added to a Help
member. The comments are not displayed when the HELP command is used
to display the contents of the Help member.
The * code must be placed in the first position of the line and may be followed
by text that does not exceed the length of the line. Any number of comment
lines may be included in a Help member, as long as each line begins with an *.
Comments may include any type of information, as in:
updated: 9/15/93 by user1 for rel. 6.
While comments may be included anywhere within a Help member, it is

suggested that they be placed at the end of the member.

16.4.5 Highlighting Lines (3270 Only)

The highlighting format code (¢) specifies which lines within a Help member
are to be highlighted when displayed. This is useful in emphasizing important
points and may be used to highlight any line within the text.
The title format code (T) and syntax format code (S) also cause lines to be
highlighted.
The distributed Help members use the ¢ format code to highlight syntax that
extends over one line. The first line of the syntax contains the S code and the
additional lines contain the ¢ code. For example, the Help member named
SAVE is formatted below in the following panel.
Highlighting Help Member
T SAVE

F Function: Places all or part of contents of AWS into library
as member.
S Syntax: SAVE mem < p <q> > < 'string' >

¢ < NOSEQ / SEQ < s <l> / COBOL > >
¢ < SHARED / EXECONLY / RESTRICTED >
@
mem Name to be assigned to member being created. Must
comply with naming conventions and not currently
exist in user's library.
...

When this member is displayed, the title and the two lines of syntax are
highlighted.

16.5 Customizing the Distributed Help Members
16.5 Customizing the Distributed Help Members

Sites should review the members distributed as part of the Help facility. After
the review, it may be determined that:
1. All or specific Advantage CA-Roscoe users should be informed that certain
members exist. For example, site may want:
■ All users to review the various components of the HELP member itself.
For example, issuing HELP HELP MEMBER displays information
about HELP members that may be of interest to all users. These
members include:
DOCUMENT A list of all documents that are applicable for the
current Advantage CA-Roscoe release.
MESSAGE Descriptions of all user and system messages.
NEW Information about the current Advantage CA-Roscoe
release.
| ■ New users to know about the members TRAINING and TUTORIAL
which describe the syntax needed to execute the interactive
applications which introduce RPF and Advantage CA-Roscoe,
respectively.
■ Specific users to know about the Help members related to such
privileged commands as DEBUG, OPERATOR and ROZAP.
2. Some of the members should be changed or deleted--to reflect how the site
is using Advantage CA-Roscoe. For example, sites may want to delete the
members BREAK, SCALE, TTY and WIDTH if the site is not using
typewriter devices.

Chapter 17. Job Submission and Notification
This chapter describes job submission and notification considerations.
Chapter 17. Job Submission and Notification 17-1

17.1 Internal Readers
17.1 Internal Readers

SUBMIT processing is handled as a subtask of Advantage CA-Roscoe. When a
terminal user executes the SUBMIT command, the subtask: 1) copies the job
stream from the AWS and/or user libraries to the output stream, and 2)
introduces the job stream to the job queues.
The output stream is a direct path to the host operating system job queues
when the internal reader facilities of JES2 or JES3 are used. Jobs are verified
and transferred directly into the scheduling queues. Thus, job stream
processing is completely automatic and no operator intervention is required.

17.2 Job Completion Notification
17.2 Job Completion Notification

Sites have the option of allowing their users to receive JES2/JES3 status
messages at their terminals when their jobs complete execution.
If this facility is to be used, sites must:

1. Add the NOTIFY initialization parameter to their Advantage CA-Roscoe
job stream. If NOTIFY is omitted, the facility is not enabled.
2. Ensure that the ROSID initialization parameter is included in their
Advantage CA-Roscoe job stream. (This is a required parameter.) The
parameter is specified in the form:
ROSID=code
where code is a unique four-character Advantage CA-Roscoe identification
(The first character of the code must be alphabetic or a currency symbol;
the remaining three characters can be any alphanumeric, for example,
ROSID=ROS1.)
If the site is executing multiple Advantage CA-Roscoes, each job must
include a ROSID= with a unique code.
3. Have the users add NOTIFY= to the JOB statement in their own job
streams. The parameter must be in the form:
NOTIFY=codepfx
where code is the four-character code identifying the Advantage
CA-Roscoe that they are signed on to and pfx is their Advantage
CA-Roscoe prefix (for example, NOTIFY=ROS1AAA).
Part or all of this parameter can be supplied by a SUBMIT exit routine. See
SUBEXIT in the Advantage CA-Roscoe Interactive Environment Extended
Facilities for System Programmers Guide.
When this facility is enabled, JES2/JES3 status messages are written to the
user's Response Line when his/her jobs complete execution. The messages are
also added to the user's library member named ZZZZZMSG.
Chapter 17. Job Submission and Notification 17-3

Chapter 18. Monitor Routines

■ Information that is common to all of the Monitor routines.
■ Information specific to the individual Monitor routines.
Chapter 18. Monitor Routines 18-1

18.1 Overview
18.1 Overview
Monitor routines provide extensions to Advantage CA-Roscoe that permit
terminal users to perform functions that are not currently part of the
Advantage CA-Roscoe command language. Monitor routines are executed via
Monitor commands. (The description of each Monitor routine indicates where
information may be obtained about using the Monitor command.) The
following list identifies the Monitor routines that are distributed with
AMS Executes IDCAMS interactively.
AWS Displays information about the AWS configuration, system and
performance.
| COB Syntax checks COBOL source programs (stabilized).
CONSOLE Executes operator commands and displays: 1) messages written to
the master or designated console, 2) the OS/390 Master Trace
Table, and 3) currently active console addresses.
DISPLAY Displays information from the operating system on jobs in
execution, initiators, job queues and devices.
DMS Display information about the current use of storage: 1) by the
Data Set Facility, 2) by the Library Facility, or 3) for RPF
programs.
| EXPORT Writes to an existing OS data set, AllFusion CA-Librarian master
| file, or AllFusion CA-Panvalet member from the AWS and/or one
| or more library members.
| IMPORT Copies all or part of an OS data set, AllFusion CA-Librarian
| master, or AllFusion CA-Panvalet member into the AWS.
JCK Verifies JCL using Unicenter CA-JCLCheck.
MONITOR Displays information about the Monitor routines defined for the
current execution of Advantage CA-Roscoe.
| PLI Syntax checks PL/I input statements (stabilized).
PURGE Cancels a job from the system queue.
ROS Provides Advantage CA-Roscoe system status information.
RTF Controls the use of the ROSCOE Trace Facility.

18.1 Overview
SORT Invokes a system utility to sort the contents of the AWS.

ZAP Permits superzap processing to be performed on OS data sets.
There are several Monitor routines which permit the use of other CA products
during an Advantage CA-Roscoe session. The following list of monitors are
not distributed with Advantage CA-Roscoe; refer to their product installation
instructions for information:
DDO Permits Advantage CA-Datacom/DB Datadictionary to be used
during an Advantage CA-Roscoe session.
ETC Permits CA-ETC to be used during an Advantage CA-Roscoe
session.
LOOK Permits Unicenter CA-SYSVIEW to be used during an Advantage
CA-Roscoe session.
MAIL Permits CA-eMAIL to be used during an Advantage CA-Roscoe
session.
TSS Permits an eTrust CA-Top Secret command execution from within
an Advantage CA-Roscoe session.
Enhancements to Advantage CA-Roscoe occasionally cause a Monitor routine

to be designated as 'functionally stabilized.' Routines that have been
designated as functionally stabilized are described in the last section of this
chapter.
Advantage CA-Roscoe also provides facilities so that sites can write their own
Monitor routines. Some of the currently distributed Monitor routines were
originally written by Advantage CA-Roscoe users and contributed by them to
the Advantage CA-Roscoe user community. For additional information about:
■ Writing your own Monitor routines, see the Advantage CA-Roscoe Extended
Facilities for System Programmers Guide.
■ User-contributed routines, see Chapter 22.
18.1.1 Common Distribution Information

Unless noted otherwise, the routines described in this chapter are installed as
load modules into the RO60LIB library. The names of the load modules are
always in the form:
RSSCxxxn
where xxx is the three-character routine identifier and, unless indicated

otherwise, n is 0.

18.1 Overview
18.1.2 Common Advantage CA-Roscoe JCL Changes

■ To be available for use, Monitor routines must be defined in the
Advantage CA-Roscoe JCL through the RUN= initialization parameter.
Each Monitor routine is identified by the first three characters of its name,
as in:
RUN=DIS
RUN=EXP
RUN=IMP
For additional information about the RUN= parameter, see the Advantage
■ Sites that are going to be using the EXPORT, IMPORT, VTOC and/or ZAP
Monitor routines should review the chapter 'Data Set Facility
Considerations' for information about DD statements that must be added
to the Advantage CA-Roscoe JCL.
18.1.3 Common Accounting Information

If the Advantage CA-Roscoe initialization parameter ACCTTREC=MON is
specified, accounting information about Monitor routines will be collected.
Advantage CA-Earl can then be used to produce a report about the collected
information. (For additional information about using Advantage CA-Earl to
produce Advantage CA-Roscoe accounting reports, see the Advantage

18.2 AMS Routine
18.2 AMS Routine

The AMS routine serves as an interface to the IBM Access Method Services
system utility (IDCAMS). It permits IDCAMS commands to be entered
interactively and executed from an Advantage CA-Roscoe terminal.
Note that IDCAMS must be authorized if the following IDCAMS commands

are to be used:
EXPORTRA
LISTCRA
PRINT When the object to be printed is a VSAM catalog.
REPRO When using the catalog or catalog unload/reload facility.

Define the AMS routine to Advantage CA-Roscoe through the RUN=
RUN=AMS

for information about using the AMS command to invoke this routine.

The AMS routine can be modified to:
1. Restrict use of the AMS command.
2. Change defaults.
The AMS routine also includes an exit. The exit is described in the Advantage
Guide.
18.2.3 AMSAUTH: Restricting Access

As distributed, any Advantage CA-Roscoe user may issue the AMS command.
Execution may be restricted to authorized users by modifying the table
AMSAUTH which is placed in the RO60OPT library by the SMP/E APPLY of
the base Advantage CA-Roscoe function SYSMOD CRO6000.
To authorize a user:
■ Add the user's prefix to the table. A three-character prefix is expected. To
specify a two-character prefix either:
– Specify the two-character prefix followed by a blank, or
– Specify the length of the field as three.

18.2 AMS Routine
■ End the table with a X'FF'. (If the table contains only a X'FF', access to
AMS is unrestricted.)
■ Reassemble the table and relink AMS, as described below.
The following example shows how the AMSAUTH table can be coded to allow
the owners of the RO, AI, AAA and BBB prefixes to use AMS:
...
AMSAUTH CSECT
DC C'RO '
DC CL3'AI'
DC C'AAA'
DC CL3'BBB'
DC X'FF'
END
Note the way that two-character prefixes are defined in the preceding table.
The prefixes could also have been specified as:
DC C'RO AI AAABBB'
After the AMSAUTH macro is defined as described above, it must be

assembled and linked into the RO60LIB Advantage CA-Roscoe target library.
This is accomplished by the RECEIVE and APPLY of product USERMOD
MRO602D, which is found in the installation sample JCL library.
The process to install MRO602D has the following basic steps:

■ Modify the AMSAUTH source in RO60OPT as described above.
■ Imbed the contents of the AMSTABLE source member following the
'++MAC' statement in the product USERMOD.
will put an executable copy of RSSCAMS0 into target library RO60LIB that
includes the modified AMSAUTH.
18.2.4 AMSDFLT: Changing Defaults

The AMS command, with no operands, reads input from the terminal and
writes output back to the terminal. To specify an alternate input source or
output destination, AMS must be entered with the Advantage CA-Roscoe RUN
command.

18.2 AMS Routine
The AMSTABLE in the Advantage CA-Roscoe target load library contains the
default values used when RUN AMS is entered. The following defaults may be
modified by replacing the AMSTABLE in the Advantage CA-Roscoe target
load library:
■ Alternate input suffix.
■ Primary command input sources.
■ IDCAMS output destination.
The name of the macro that generates the AMSTABLE is AMSDFLT. The
AMSDFLT macro generates a CSECT statement. The macro is coded as follows
(defaults are underlined):
18.2.4.1 Syntax
AMSDFLT Macro
──┬─────┬──AMSDFLT──┬───────────────────┬─────────────────────
└─tag─┘ │ ┌─A────┐ │
├─AWSCHAR─┴─char─┴──┤
│ ┌─T─┐ │
├─,IN=─┴─A─┴────────┤
│ ┌─T─┐ │
└─,OUT=─┴─A─┴───────┘

AWSCHAR= A single character that, if appended to the AMS command,
forces primary command input to be taken from the AWS or
the Advantage CA-Roscoe library member named in the RUN
command. Any suffix other than this character causes AMS
input to be taken from the default command input source
(normally the terminal). The default is A.
IN= Primary command input source when the AMS command is
not suffixed. Specify either of the following codes:
T (Default.) Terminal input.
A Alternate source which can be the AWS or an Advantage
CA-Roscoe library member.
OUT= Destination for the IDCAMS output, specified as either of the
following codes:
T (Default.) Terminal output.
A Alternate source which is the AWS.
The following is a sample AMSDFLT macro used to generate the AMSTABLE:

...
TITLE 'AMSDFLT TABLE GENERATION'
AMS AMSDFLT AWSCHAR=X,IN=T,OUT=A
END

18.2 AMS Routine
In the preceding example, the character X is to be the suffix character that

forces input to be read from the AWS or a library member, the default input
source of the command is to be the terminal and IDCAMS output is to be
written to the AWS. For example:
RUN AMS-X,AMSINPUT
causes the input to IDCAMS to be read from the library member AMSINPUT,
rather than from the terminal.
A sample AMSDFLT macro definition is placed in the RO60OPT data set by

CRO6000. The sample definition is named AMSDEFLT.
After the AMSDEFLT macro is defined as described above, it must be

MRO602E, which is found in the installation sample JCL library.
The process to install MRO602D has the following basic steps:

■ Modify the AMSDEFLT source in RO60OPT as described above.
■ Imbed the contents of the AMSDEFLT source member following the
will put an executable copy of RSSCAMS0 into target library RO60LIB that
includes the modified AMSTABLE.

18.3 AWS Routine
18.3 AWS Routine

The AWS Monitor command can be used to display the AWS configuration
and to monitor AWS status and performance.
AWS is reentrant.
As distributed, any Advantage CA-Roscoe user may execute the AWS

command.

Define the AWS routine to Advantage CA-Roscoe through the RUN=
RUN=AWS
information about using the AWS command to invoke this routine.

18.4 CONSOLE Routine
18.4 CONSOLE Routine

The CONSOLE routine permits the terminal user to display messages written
to the system console, and execute operator commands.
See the chapter 'ATTACH JOB, CONSOLE and DISPLAY Requirements' for
information about using and customizing this Monitor routine.

18.5 DISPLAY Routine
18.5 DISPLAY Routine

The DISPLAY routine permits an Advantage CA-Roscoe user to obtain
information from the operating system about jobs in execution, initiators, job
queues and online devices.
See the chapter 'ATTACH JOB, CONSOLE and DISPLAY Requirements' for
information about using and customizing this Monitor routine.

18.6 DMS Routine
18.6 DMS Routine

The DMS (Data Manager Statistics) routine provides statistical information
about the current use of storage by:
■ AWS,
■ Data Set Facility,
■ Library Facility, and/or
■ RPF program execution.
As distributed, any user may issue the DMS command.

Define the DMS routine to Advantage CA-Roscoe through the RUN=
RUN=DMS
information about using the DMS command to invoke this routine.

18.7 EXPORT Routine
18.7 EXPORT Routine

| The EXPORT routine permits terminal users to write to an existing OS data set,
| AllFusion CA-Librarian master file, or to a AllFusion CA-Panvalet member
from the AWS or from one or more Advantage CA-Roscoe library members.
Note: Information about Advantage CA-Roscoe/AllFusion CA-Librarian
installation is provided in the Advantage CA-Roscoe Interactive
Environment Installation Guide.

Define the EXPORT routine to Advantage CA-Roscoe through the RUN=
RUN=EXP

for information about using the EXPORT command to invoke this routine.

The EXPORT routine can be modified to:
1. Restrict data sets from being written to by EXPORT.
2. Suppress summary messages to the terminal.
The EXPORT routine also includes an exit which can be used to: 1) monitor
user requests, 2) control input records passed to The AllFusion CA-Librarian
Immediate Online Update (IOU) and/or 3) control the output records
generated by the IOU during update to AllFusion CA-Librarian master files.
The EXPORT exit is described in the Advantage CA-Roscoe Extended Facilities for
System Programmers Guide.
18.7.3 RSSCEXPU: Changing Defaults

The RSSCEXPU table defines the characteristics of the library member to
receive the EXPORT/IOU output. It also controls the display of summary
messages.
The macro that generates the RSSCEXPU table is also named RSSCEXPU. The
macro is coded as follows (defaults are underlined):

18.7 EXPORT Routine
18.7.3.1 Syntax
RSSCEXPU Macro
──┬─────┬──RSSCEXPU──┬─────────────────────┬──────────────────
└─tag─┘ │ ┌─LIBUPD─┐ │
├─,NAME=─┴─name───┴───┤
│ ┌─YES─┐ │
├─,REPLACE=─┴─NO──┴───┤
│ ┌─1──┐ │
├─,OUTLIM=─┴─value─┴──┤
│ ┌─YES─┐ │
└─,SUMMSG=─┴─NO──┴────┘

NAME= Name of the Advantage CA-Roscoe library member that is to
contain EXPORT/IOU output. The name may be 1 through 8
characters in length. (The member name is displayed to the
terminal user at the end of EXPORT execution and the
member becomes part of the terminal user's library.) The
default is LIBUPD.
REPLACE= Replacement of the output library member contents with each
EXPORT/IOU update is controlled by specifying either of the
following codes:
YES (Default.) Replace the contents of the library member
with each execution of EXPORT.
NO Do not replace the contents of the library member.
If NO is specified, a unique library member name is generated
for each EXPORT execution. The name is comprised of up to
the first 6 characters of the name (specified with NAME=) and
a 2-digit suffix generated at execution. Thus, if
NAME=NADELSON and REPLACE=NO are specified, the
first output member name is NADELS00, the second is
NADELS01 and so on. EXPORT always generates the lowest
suffix available at each execution. There can be a maximum
of 99 members for each terminal user. If necessary,
wrap-around from 99 to 00 occurs.
OUTLIM= Maximum number of records that can be written to the output
member. If the number of records from a single execution of
EXPORT exceeds this limit, EXPORT terminates with a
| message. The default is 10,000.
SUMMSG= Display of the summary messages EXP60, EXP68 and EXP69 is
controlled by specifying either of the following codes:
Code Meaning
YES Display the messages (default).
NO Suppress the messages.

18.7 EXPORT Routine
Notes
■ Use the program LIBSERVE to maintain the library members created
during execution of EXPORT. The LISTMON function of LIBSERVE lists all
library members created by output from EXPORT. These library members
may be purged from the system using the PURGE function of the
LIBSERVE program. LIBSERVE is described in the Advantage CA-Roscoe
■ To install a modified EXPORT default table:
A sample RSSCEXPU macro definition is placed in the RO60OPT data set
by the SMP/E APPLY of the base Advantage CA-Roscoe function
SYSMOD CRO6000. The sample definition is named EXPUTAB.
| After the EXPUTAB macro definition is modified to meet your
requirements, it must be assembled and linked into the RO60LIB
Advantage CA-Roscoe target library. This is accomplished by the RECEIVE
and APPLY of product USERMOD MRO602F, which is found in the
The process to install MRO602F has the following basic steps:
– Modify the EXPUTAB source in RO60OPT as described above.
– Imbed the contents of the EXPUTAB source member following the
– Execute the product USERMOD. This will initiate an SMP/E RECEIVE
and APPLY. During the APPLY an assembly and link will take place
which will put an executable copy of RSSCEXP0 into target library
RO60LIB that includes the modified RSSCEXPU table.
18.7.3.2 Example
The following shows a sample RSSCEXPU table definition and illustrates how
an exit routine is included in the assembly step:
...
//ASM.SYSIN DD
TITLE 'EXPORT DEFAULT TABLE'
RSSCEXPU NAME=LIBU,REPLACE=NO,OUTLIM=1
/
See the last section under EXPORT for the JCL to assemble RSSCEXPU and
relink EXPORT.

18.7 EXPORT Routine
18.7.4 ENAMES: Restricting Data Set Access

The name of the data set to be written to is examined before OPEN processing
to exclude certain files that are restricted from online access. The names of the
files (or data set high-level indexes) are contained in the separate CSECT
named ENAMES, which is generated by an Advantage CA-Roscoe macro also
named ENAMES. As distributed, only the following two data sets are present
in the list:
SYSCTLG This data set requires a special processor to read and format.
SYS1.PAGE This data set may cause an 80A abend.
Other data set names or indexes may be added to the list by reassembling
ENAMES and relinking EXPORT. The macro is coded as follows (the default is
underlined):
18.7.4.1 Syntax
ENAMES Macro
──┬─────┬──ENAMES──dsn──┬──────────────┬──────────────────────
└─tag─┘ │ ┌─DSN───┐ │
└─,─┴─INDEX─┴──┘

dsn Either a fully qualified data set name (for example, SYS1.MACLIB)
or a high-level data set index (for example, SYS1). Although the
terminating period on an index entry is not required, it should be
coded to avoid errors in systems that contain indexes such as SYS1.
and SYS1.TEST.
DSN The dsn is a fully qualified data set name. If specified, access to that
data set is to be restricted (default).
INDEX The dsn is a high-level data set index. If specified, access to all data
sets whose names begin with the index is forbidden.
The first time the ENAMES macro is invoked, a CSECT statement is generated
before the table entry for the dsn coded. After all data set names and indexes
are defined, the table end must be supplied by the following assembler coding:
DC X'FF'
This must be followed by the assembler END statement.

18.7 EXPORT Routine
18.7.5 To Install an ENAMES Table

A sample ENAMES macro definition is placed in the RO60OPT data set by the
SMP/E APPLY of the base Advantage CA-Roscoe function SYSMOD CRO6000.
The sample definition is named ENAME.
After the ENAME macro is modified to meet your requirements, it must be

MRO6030, which is found in the installation sample JCL library.

■ Modify the ENAME source in RO60OPT as described above.
■ Imbed the contents of the ENAME source member following the '++MAC'
statement in the product USERMOD.
will put an executable copy of RSSCEXP0 into target library RO60LIB that
includes the modified ENAMES table.

18.8 IMPORT Routine
18.8 IMPORT Routine

| The IMPORT routine permits terminal users to copy all or part of the contents
| of an OS data set, AllFusion CA-Librarian master file, or a AllFusion
| CA-Panvalet member into the AWS.
Note: Information about Advantage CA-Roscoe/AllFusion CA-Librarian
installation is provided in the Advantage CA-Roscoe Interactive
Environment Installation Guide.
IMPORT has a pseudo-SPIE exit.

Define the IMPORT routine to Advantage CA-Roscoe through the RUN=
RUN=IMP(S)

for information about using the IMPORT command to invoke this routine.
18.8.1.1 To Customize/Modify This Routine
The IMPORT routine can be modified to restrict data sets from being copied
by IMPORT.
The IMPORT routine also has an exit which can be used to: 1) monitor user
requests and/or 2) change the format of the PDS directory list. The IMPORT
exit is described in the Advantage CA-Roscoe Interactive Environment Extended
Facilities for System Programmers.
18.8.2 INAMES: Restricting Data Set Access

The name of the data set to be copied is examined before OPEN processing to
exclude certain files that are restricted from online access. The names of the
files (or data set high-level indexes) are contained in the separate CSECT
named INAMES, which is generated by an Advantage CA-Roscoe macro also
named INAMES. As distributed, only the following two data sets are present
in the list:
SYSCTLG This data set requires a special processor to read and format.
SYS1.PAGE This data set may cause an 80A abend.
Other data set names or indexes may be added to the list by reassembling
INAMES and relinking IMPORT. The macro is coded as follows (the default is
underlined):

18.8 IMPORT Routine
18.8.2.1 Syntax
INAMES Macro
──┬─────┬──INAMES──dsn──┬──────────────┬──────────────────────
└─tag─┘ │ ┌─DSN───┐ │
└─,─┴─INDEX─┴──┘

dsn Either a fully qualified data set name (for example, SYS1.MACLIB)
or a high-level data set index (for example, SYS1). Although the
terminating period on an index entry is not required, it should be
coded to avoid errors in systems that contain indexes such as SYS1.
and SYS1.TEST.
DSN The dsn is a fully qualified data set name. If specified, access to that
data set is to be restricted (default).
INDEX The dsn is a high-level data set index. If specified, access to all data
sets whose names begin with the index is forbidden.
The first time the INAMES macro is invoked, a CSECT statement is generated
before the table entry for the dsn coded. After all data set names and indexes
are defined, the table end must be supplied by the following assembler coding:
DC X'FF'
This must be followed by the assembler END statement.
See the next section to assemble INAMES and relink IMPORT.
18.8.3 To Install an INAMES Table

A sample INAMES macro definition is placed in the RO60OPT data set by the
The sample definition is named INAME.
| After the INAME macro definition is modified to meet your requirements, it

must be assembled and linked into the RO60LIB Advantage CA-Roscoe target
library. This is accomplished by the RECEIVE and APPLY of product
USERMOD MRO6031, which is found in the installation sample JCL library.

18.8 IMPORT Routine

■ Modify the INAME source in RO60OPT as described above.
■ Imbed the contents of the INAME source member following the '++MAC'
statement in the product USERMOD.
will put an executable copy of RSSCIMP0 into target library RO60LIB that
includes the modified INAMES table.

18.9 JCK Routine
18.9 JCK Routine

The JCK routine allows Advantage CA-Roscoe users to verify JCL using
Unicenter CA-JCLCheck. If Unicenter CA-JCLCheck is currently installed at
the site and it is:
■ Releases prior to 6.0, the JCK Monitor routine distributed with Advantage
CA-Roscoe must be used.
■ Version 6.0 or greater, the JCK Monitor routine distributed with Unicenter
CA-JCLCheck may be used. (All available Unicenter CA-JCLCheck facilities
are available to Advantage CA-Roscoe users.)
If Unicenter CA-JCLCheck is not currently installed at the site, the JCK

Monitor routine distributed with Advantage CA-Roscoe may be used. It
provides a limited version of the facilities available with Unicenter
CA-JCLCheck.

Define the JCK routine to Advantage CA-Roscoe through the RUN=
RUN=JCK(SX)
Then, review the description of the JCK command in the Advantage CA-Roscoe
Interactive Environment Command Reference Guide. If the DEQUE or VSAM
options are to be used, additional DD statements must be added to the
Advantage CA-Roscoe JCL. (These DD statements are described with the other
Advantage CA-Roscoe DD statements in the Advantage CA-Roscoe Interactive
Environment Programs and Utilities Guide.)
ATTENTION
The modifications below are only valid for the limited version of Unicenter
CA-JCLCheck. If the full Unicenter CA-JCLCheck product is installed, the
site may change the standard options by modifying the JCLDFLT CSECT.
(The procedure to specify options is described in the Unicenter CA-JCLCheck
OS/390 Systems Programmer Guide, under INSTALLATION OPTIONS.)

18.9 JCK Routine
As distributed, JCK uses the Unicenter CA-JCLCheck options AUTOPROC,

EASYPROC and TERM options. Sites can change these default Unicenter
CA-JCLCheck options. (The options available with the limited version of
Unicenter CA-JCLCheck are described with the JCK command in the Advantage
CA-Roscoe Interactive Environment Command Reference Guide.) To do so, the site
must:
| ■ Use RO60OPT member JCLOPTS as the input to the assembly of the
| Unicenter CA-JCLCheck options table module. You will note that the
| defaults options are "ROSC,AU,EA,TERM,NOLIST". The "ROSC" keyword
| is required, and must be specified first.
| For an explanation of these keywords and additional keywords that you
| can use, see sections 3.6 and 3.7 of the Unicenter CA-JCLCheck Reference
| Guide.
| You can add and delete keywords at your discression. However,
| Advantage CA-Roscoe support strongly advises that you do not remove
| the "NOLIST" parameter from the table.
| To reassemble the table, use Usermod MR06033 in the Advantage
| CA-Roscoe SAMPJCL.
■ Reassemble the table and relink JCK.
18.9.2 To Install a Modified JCLOPTS Table

A sample JCLOPTS macro definition is placed in the RO60OPT data set by the
The sample definition is named JCLOPTS.
| After the JCLOPTS macro definition is modified to meet your requirements, it


■ Modify the JCLopts source in RO60OPT as described above.
will put an executable copy of RSSCJCK0 into target library RO60LIB that
includes the modified JCLOPTS table.
| Note: To view the JCLOPTS table from online Advantage CA-Roscoe, issue
| the JCK-D command.

18.10 MONITOR Routine
18.10 MONITOR Routine

The MONITOR routine permits the user to display status information about
one or all of the Monitor routines that are defined for the current execution of

Define the MONITOR routine to Advantage CA-Roscoe through the RUN=
RUN=MON
information about using the MONITOR command to invoke this routine. Note:
As distributed, any Advantage CA-Roscoe user can issue the MONITOR
command.

18.11 PURGE Routine
18.11 PURGE Routine

The PURGE Monitor routine provides users with a way to cancel a job with an
S222 abend (operator cancel).
PURGE is reentrant.

This user-contributed Monitor routine must be defined to Advantage
CA-Roscoe using the RUN= initialization parameter, as in:
RUN=PUR
In addition to being distributed as the load module RSSCPUR0 in the RO60LIB

library, this routine is also distributed in source code as member RSSCPUR0 in
the RO60OPT library. If the source code is used, it must be assembled and link
edited into the Advantage CA-Roscoe target load library under the name
RSSCPUR0. Once the routine has been loaded, the RUN= parameter described
above should be added to the Advantage CA-Roscoe initialization member.
18.11.2 To Install RSSCPUR0

After the RSSCPUR0 source is modified to meet your requirements, it must be

■ Modify the RSSCPUR0 source in RO60OPT to meet your requirements.
will put an executable copy of RSSCPUR0 into target library RO60LIB.

for information about using the PURGE command to invoke this routine.

Sites can write an exit routine to restrict the use of the PURGE command. The
exit routine (which must be called JOBEXIT) is described in the Advantage
Guide. PURGE makes a weak external reference to this exit.
Note: The JOBEXIT must be linked directly into RSSCPUR0 with an
INCLUDE to the sample JCL for the JOBEXIT as well as for RSSCPUR0.

18.12 ROS Routine
18.12 ROS Routine

The ROS routine provides Advantage CA-Roscoe system status information.

Define the ROS routine to Advantage CA-Roscoe through the RUN=
RUN=ROS
information about using the ROS command to invoke this routine.

As distributed, use of the ROS command is not restricted.
The ROS routine can be modified to change the default output destination. As
distributed, the default destination is the terminal. To change this to the AWS,
ZAP the first byte of the CSECT RSSCROS1. The byte value is preset to C'T'
(for terminal); change it to C'A' (for AWS).

18.13 RTF Routine
18.13 RTF Routine

The RTF Monitor routine can be used to invoke the ROSCOE Trace Facility.

Define this routine to Advantage CA-Roscoe through the RUN= initialization
parameter, as in:
RUN=RTF
The following DD statement must be included in the Advantage CA-Roscoe

JCL:
//ROSTRACE DD DSN=tracedsn,DISP=SHR
The data set may be on tape or disk. The disposition should be MOD if tracing
is started and terminated multiple times within one execution of Advantage
CA-Roscoe. The following characteristics must be included in the DD
statement:
DCB=(RECFM=VB,LRECL=256,BLKSIZE=492,DSORG=PS)
(Although the minimum record size is 32 bytes and the maximum size is 96
bytes, the record length is reserved as 256 bytes for future enhancements.)
If the trace file overflows, tracing is terminated with a message to the operator.
See the Advantage CA-Roscoe Interactive Environment Programs and Utilities Guide
for a description of the TREPORT program which produces a report containing
information about each trace event.
information about using the RTF command to invoke this routine.

As distributed, only the owner of the RO or AI prefix can issue the RTF
command. A user exit is available which permits sites to authorize other
individuals to use RTF. The exit is described in the Advantage CA-Roscoe
Interactive Environment Extended Facilities for System Programmers Guide.

18.14 SORT Routine
18.14 SORT Routine

The SORT Monitor routine sorts the contents of the AWS by invoking the
system SORT package.

Define this user-contributed routine to Advantage CA-Roscoe through the
RUN=SOR
| In addition to being distributed as the load module RSSCSOR0 in the RO60LIB

library, this routine is also distributed in source code as member RSSCSOR0 in
RSSCSOR0. Once the routine has been loaded, add the RUN= initialization
parameter described about to the Advantage CA-Roscoe JCL.
18.14.2 To Install RSSCSOR0

After the RSSCSOR0 source is modified to meet your requirements, it must be

■ Modify the RSSCSOR0 source in RO60OPT to meet your requirements.
will put an executable copy of RSSCSOR0 into target library RO60LIB.

for information about using the SORT command to invoke this routine.
■ SOR attaches the system SORT package with a default work size of 200K.
Sites can change the work size by modifying the member RSSCSOR0 on
the RO60OPT library. The member must then be reassembled and link
edited.
■ Sites that use a SORT package that requires work files must add one or
more SORTWKxx DD statements to the Advantage CA-Roscoe JCL to
define these files. The number of DD statements to be added will depend
on the size of the files expected to be sorted.

18.15 ZAP Routine
18.15 ZAP Routine

The ZAP routine permits superzap processing to be performed on an OS data
set upon terminal command.

parameter, as in:
RUN=ZAP

for information about using the ZAP command to invoke this routine.

The ZAP routine can be modified to:
1. Change the default options of the SYSLIB statement.
2. Restrict the ability of some or all users to inspect or modify certain data
sets through an exit routine. The exit is described in the Advantage
Guide.
18.15.3 ZAPDEFLT: Processing Option and Default Table

A table of processing options and defaults may be inserted into ZAP to
accomplish the following:
■ Change the standard defaults of the operands in the SYSLIB statement.
■ Make it impossible for a user to override the default values of selected
SYSLIB statement operands.
■ Make it impossible for a user to access a volume table of contents by
specifying its name as FORMAT4.DSCB.
The table of processing options and defaults is a CSECT named ZAPDEFLT. If

this CSECT is absent from the RSSCZAP0 load module, standard processing
options and defaults are used. The table is assembled using the ZAPDEFLT
macro which is distributed on the RO60MAC library.
The macro is coded as follows (the defaults are underlined):

18.15 ZAP Routine
18.15.3.1 Syntax
ZAPDEFLT Macro
──┬─────┬──ZAPDEFLT────────────────────────────────────────────
└─tag─┘
──┬────────────────────────────────────────────┬───────────────
│ ┌─ACCESS──┐ │
├─,VTOC=(─┴─PROTEXT─┴─)──────────────────────┤
│ ┌─OLD─┐ │
├─,DISP=(─┴─SHR─┴──┬───────────────┬─)───────┤
│ └─,─┬─NOVRD──┬──┘ │
│ └─NOSPEC─┘ │
│ ┌─FLAG──┐ │
├─,SSI=(─┴─LEAVE─┴──┬───────────────┬─)──────┤
│ └─,─┬─NOVRD──┬──┘ │
│ ┌─ALWAYS─┐ │
├─,IDRUPDT=(─┴─DEMAND─┴──┬───────────────┬─)─┤
│ └─,─┬─NOVRD──┬──┘ │
├─,IDRFULL=(─┬─NOGO───┬──┬───────────────┬─)─┤
│ └─IGNORE─┘ └─,─┬─NOVRD──┬──┘ │
│ ┌─TRKSIZE─┐ │
└─,BUFL=(─┴─BLKSIZE─┴──┬───────────────┬─)───┘
└─,─┬─NOVRD──┬──┘
└─NOSPEC─┘

VTOC= Accessing a volume table of contents through the data set name
FORMAT4.DSCB is controlled by specifying either of the following:
ACCESS (Default.) Access permitted.
PROTECT Access prevented. Specification of FORMAT4.DSCB is
taken as a request to access a data set so named.
The DISP=, SSI=, IDRUPDT=, IDRFULL= and BUFL= keywords have two
positional operands. The following descriptions are of the first positional
operand of each keyword.
DISP= Designate whether control of the SYSLIB data set can be
shared with other tasks if the data set is to be updated.
Specify either of the following codes:
OLD Exclusive control of the data set is requested. ZAP
terminates if it cannot get control (default).
SHR Shared control of the data set is requested.
SSI= Designate whether, in the absence of a SETSSI statement, the
updating of a load module is to force the setting of the "local
fix" flag in the system status information field. Specify either
of the following codes:

18.15 ZAP Routine
FLAG The system status information is to be updated

(default).
LEAVE The system status information is not to be updated
unless explicitly requested.
IDRUPDT= Designate whether, in the absence of an IDRDATA statement,
the updating of a load module is to force the recording of
historic information in a csect identification record. Specify
either of the following codes:
ALWAYS An entry is to be placed in the superzap csect
identification record (default).
DEMAND No data is to be placed in the superzap csect
identification record unless explicitly requested.
IDRFULL= Designate whether a load module may be updated if all
superzap csect identification records that it contains are
already full. Specify either of the following codes:
NOGO REP statements are to be rejected. This does not
prevent processing of load modules that contain no
superzap csect identification records. It does
prevent replacing text when all of the load
module's superzap csect identification records are
full.
IGNORE Processing is unaffected except that no IDR data is
recorded.
BUFL= Designate the algorithm that is to be used for determining the
size of the SYSLIB input and output buffer. Specify either of
the following codes:
TRKSIZE Allocate a buffer large enough to hold as much
data as can fit on one track of the volume on
which the data set resides (default).
BLKSIZE Allocate a buffer large enough to hold the largest
block of data that is expected to be found in the
data set (based on the data set organization and
the block size).
The following describes the second positional operand that can be specified
with the DISP=, SSI=, IDRUPDT=, IDRFULL= and BUFL= keywords. This
operand designates what is to happen if a user enters a SYSLIB statement
keyword operand that is different from the default. If this positional operand
is omitted, the user can specify any valid value. If this operand is specified, it
must be either of the following:
NOVRD A SYSLIB keyword operand that is not a default value is changed
to the default and no message is sent to the user.

18.15 ZAP Routine
NOSPEC A message is sent to the user stating that the SYSLIB keyword
operand is not a default value; ZAP terminates.
Notes
■ If BLKSIZE is specified as the first operand of BUFL=, omit the second
positional operand. BUFL=(BLKSIZE,NOVRD) and
BUFL=(BLKSIZE,NOSPEC) are invalid.
■ If both positional operands of a keyword are coded, they must be enclosed
in parentheses (for example, DISP=(SHR,NOSPEC)).
See the next section for the JCL to assemble ZAPDEFLT and relink ZAP.
18.15.4 To Install a Modified ZAPDEFLT Table

A sample ZAPDEFLT macro definition is placed in the RO60OPT data set by
CRO6000. The sample definition is named ZAPDFLT.
| After the ZAPDFLT macro definition is modified to meet your requirements, it


■ Modify the ZAPDFLT source in RO60OPT as described above.
will put an executable copy of RSSCZAP0 into target library RO60LIB that
includes the modified ZAPDEFLT table.

18.16 CA Product Monitor Routines
18.16 CA Product Monitor Routines

The Monitor routines described in this section can be used to invoke the use of
the related product during an Advantage CA-Roscoe session.
18.16.1 DDO Routine

The DDO Monitor routine permits the use of Advantage CA-Datacom/DB
Datadictionary during a Advantage CA-Roscoe session.
18.16.1.1 To Use This Routine:
See the Advantage CA-Datacom/DB Datadictionary installation instructions

and system management documentation for distribution and installation
information.

for information about using the DDO command to invoke this routine.
18.16.2 ETC Routine

The ETC Monitor routine permits the use of CA-ETC during a Advantage
CA-Roscoe session. (CA-ETC is a text processing system that automates the
preparation, composition, updating, and maintenance of any textual material.)
See the CA-ETC OS Installation Guide for distribution and installation

information.

for information about using the ETC command to invoke this routine.
18.16.3 MAIL Routine

The MAIL Monitor routine permits the use of CA-eMAIL during a Advantage
CA-Roscoe session. (CA-eMAIL is an electronic mail system for sending,
receiving, storing, retrieving, and managing correspondence.)
See the CA-eMAIL OS Installation Guide for distribution and installation

information.

for information about using the MAIL command to invoke this routine.

Chapter 19. PF/PA Key Assignment Definitions
When Advantage CA-Roscoe is initially installed, the program attention keys

PA1, PA2 and PF1 through PF24 have default assignments.
This chapter describes how to change the site-default PF/PA key assignments
using the ROSPFUSE and ROSPCODE macros.
Chapter 19. PF/PA Key Assignment Definitions 19-1

19.1 Notes
19.1 Notes
■ Terminal users can, on an individual basis, override a PF and/or PA key
assignment. If the user does override the assignment for one or more keys,
the user's assignments are in effect only for the duration of the user's
session. (For additional information about how users can override the site-
defined PF/PA key assignments, see the Advantage CA-Roscoe Interactive
Environment User Guide.)
Also see the Advantage CA-Roscoe Interactive Environment User Guide for a
description of the processing hierarchy that is performed when a user
presses a PF or PA key.
■ Sites can assign values to PA1 through PA10, PF1 through PF24 and the
Enter key. (Terminal users cannot override the function assigned to the
Enter key.)
The CLEAR and TEST REQ keys cannot be assigned functions. CLEAR is
always an Advantage CA-Roscoe ATTN and TEST REQ is usually an
ATTN.
■ Sites using non-SNA VTAM and/or BTAM terminals have the option of
defining PA1, PA2 or PA3 as their site attention key. If this option is used,
the ROSPFUSE-assigned function for that key is overridden. See the section
'Attention Support' for additional information.

19.2 ROSPFUSE Macro
19.2 ROSPFUSE Macro

The ROSPFUSE macro assigns an Advantage CA-Roscoe command or
predefined function to a program attention key. It also designates whether a
ROSPCODE macro has been coded for that key.
When coding the ROSPFUSE macros, make sure that there is one macro for
each program attention key that is to be assigned a value. Each macro must
include the keyword operand PF= and at least one additional operand.
(Exception: Code a ROSPFUSE macro with no operands to indicate the end of
the definition.)
The first call on ROSPFUSE generates the CSECT statement.
19.2.1 Syntax
ROSPFUSE Macro
──┬─────┬──ROSPFUSE──PFkey──┬────────────────┬────────────────
└─tag─┘ ├─,TEXT='string'─┤
├─,AWS='string'──┤
├─,DSN='string'──┤
├─,JOB='string'──┤
├─,LIB='string'──┤
├─,CTECT=tag─────┤
└─,ENTER=scroll──┘

PF= Program attention key that is to be assigned a value, specified
in the form:
PAv (where 'v' may be 1 through 10), or
PFv (where 'v' may be 1 through 24).
The definitions may be coded in any order. Any PF or PA key
that is not defined through ROSPFUSE functions as an ATTN
(that is, changes made to the current frame are ignored and
attached data is detached).
TEXT='string' Command/function to be performed when the PF/PA key is
pressed and no AWS=, DSN=, JOB= or LIB= is specified for
that key.
AWS='string' Command/function to be performed when the AWS (or
nothing) is attached and a PF/PA key is de- pressed. AWS=
overrides the function specified with TEXT= for only the
AWS.

19.2 ROSPFUSE Macro
DSN='string' Command/function to be performed when a data set object is

attached and a PF/PA key is pressed. DSN= overrides the
function specified with TEXT= for only attached data set
objects.
JOB='string' Command/function to be performed when job output is
attached and a PF/PA key is pressed. JOB= overrides the
function specified with TEXT= for only job output.
LIB='string' Command/function to be performed when a library member
is attached and a PF/PA key is pressed. LIB= overrides the
function specified with TEXT= for only attached library
members.
CTEXT=tag Tag of a ROSPCODE macro, specified as:
CPAv (where 'v' may be 1 through 10), or
CPFv (where 'v' may be 1 through 24).
See the section 'ROSPCODE Macro' for additional information.
ENTER=scroll Scroll function that is to be performed when the Enter key is
pressed. If omitted, changes made to the current frame are
applied and the display is not repositioned.
If specified, ENTER= must be included with the first
ROSPFUSE macro coded. It can be assigned any scroll value.
It is strongly recommended that the Enter key not be defined.
Depending on how Enter is defined and what command(s) the
user enters, unpredictable results may occur.
The following sections describe how to assign commands and/or predefined

functions to PF/PA keys.
19.2.2 PF/PA Key Assignment Considerations

A PA key may be assigned one or more Advantage CA-Roscoe commands or
one of the predefined functions described later in this chapter.
A PF key may be assigned one or more Advantage CA-Roscoe commands or

any predefined function. When assigning commands and functions to the same
key, the assignment may include any number of commands but only one
function.

19.2 ROSPFUSE Macro
PA KEY WARNING
When a PA key is pressed, 3270 hardware limitations prevent Advantage
CA-Roscoe from knowing:
1) any of the changes made to the screen, and 2) the current position of the
cursor when split screens are in effect. It is strongly recommended,
therefore, that the default PA key assignments not be changed.
If PA key assignments are changed, only commands may be assigned to

PA keys (that is, no special-purpose functions may be assigned.) Exercise
care when assigning commands -- especially if users frequently split
screens.
Examples:
■ If "UPDATE *" is assigned to a PA key that is pressed, the command is
issued but changes made to the screen are not applied to the library
member (or to the AWS).
■ If "DETACH JOB" is assigned to a PA key and the user splits the screen
to attach two jobs, the wrong job may be detached when the PA key is
pressed. (Advantage CA-Roscoe uses the last known cursor position
(that is, where the cursor was placed for the last terminal write).
Advantage CA-Roscoe does not know if the user moved the cursor to a
different screen.
This section describes how to assign commands and/or functions to a PF/PA

key.
19.2.2.1 Assigning a Single Fixed Value
The value to be assigned must be delimited by apostrophes ('), as in:

ROSPFUSE PF= ...
TEXT='HELP PFKEYS',
...
Since TEXT= is specified, this assignment will be performed regardless of the

type of data attached at the time the key is pressed.
19.2.2.2 Assigning Multiple Values
WARNING
If multiple commands are assigned to a PF or PA key and one of the
commands causes a display, all subsequent commands are suspended and
displayed in the Command Area. If the assignment includes an RPF
program that contains a panel, the program is executed and any commands
that follow the program are lost. (The display of the panel overrides the
display of unexecuted commands.)

19.2 ROSPFUSE Macro
When multiple commands are assigned to a PF or PA key, the commands

must be separated by a slash (/) as in:
ROSPFUSE PF= ...
TEXT='RENUMBER 1 1/SUBMIT',
...
Note: This is the default delimiter. The PFKDELIM= initialization parameter
may be used to change this character.
19.2.2.3 Assigning Commands With String Operands
Commands that have string operands fall into two categories; those that
require the string be delimited and those that require the string be delimited
only if it could be confused for a key-word operand of that command.
When assigning commands with string operands, it is a good practice to

always delimit the string. The string delimiter can be any special character that
is NOT an apostrophe, the command delimiter or the PF/PA assignment
delimiter. In the following assignment, for example, the logical not sign (¬) is
used to delimit the string JOB.
ROSPFUSE PF= ...
AWS='SET DISPLAY NONUM/FIRST ¬JOB¬',
...
19.2.2.4 Assigning RPF Programs
RPF programs can be executed through a PF or PA key. The following

example illustrates various ways a program named WIDGET can be assigned.
ROSPFUSE PF= ...
TEXT='EXEC AAA.WIDGET',
AWS='AAA.WIDGET',
DSN='WIDGET',
...
If the RPF program name matches the name of a primary or Monitor

command, use either the EXEC command or '/' to cause explicit invocation of
the program. (If the program is in an Execution Library, the slash must be
used.) For example, to have the AWS renumbered and the program FETCH
executed, the assignment might look like:
ROSPFUSE PF= ...
AWS='RENUMBER//FETCH'
Note that the slashes in this example serve two purposes. The first slash is
used to separate the commands; the second slash is used to explicitly invoke
the program named FETCH.

19.2 ROSPFUSE Macro
19.2.2.5 Assigning Variable Values
PF and PA keys can be assigned functions that permit the terminal user to
supply variable information.
■ PA key assignments may include any RPF variable (for example, L1, P12,
etc.).
■ PF key assignments may include any RPF variable and/or one or more of
the Command Line variables C1 through C8.
When variables are used within an assignment, the assignment must begin
with a special character (a plus sign in these examples) that is also used to
delimit the variable portion of the assignment, as in:
ROSPFUSE PF=PF1,
TEXT='+FETCH +L1+',
AWS='+FETCH +C1+',
...
If the special character is omitted, the variable is not recognized.
IMPORTANT
When variables are used in an assignment, the length of the assignment,
after all variable substitution has been performed, plus any other
commands/data specified in the Command Area may not exceed 255
characters.
■ Using RPF Variables:

Any RPF system or storage variable may be used in a PF or PA key
definition. When a storage variable is used, it must be assigned a value
before the associated key is pressed. Using the preceding example to
illustrate, if the terminal user types:
LET L1 = 'WIDGET'
and then presses PA1, Advantage CA-Roscoe responds as though the user
entered:
FETCH WIDGET
If the storage variable does not contain a value or contains a value that is
inappropriate for the assignment, an error message is displayed.
■ Using Command Line Variables:
Command line variables (names C1 through C8) may only be assigned to
PF keys. When these variables are used in an assignment, the user must
provide information in the Command Area of the screen. For example,
assume the following assignment for PF4:

19.2 ROSPFUSE Macro
ROSPFUSE PF=PF4,
TEXT='+FETCH +C1+/ATTACH',
...
If the terminal user enters WIDGET in the Command Area and then
presses PF4, the assignment is treated as though the user entered:
FETCH WIDGET
ATTACH
When multiple Command Line variables are included in an assignment,
each one must be delimited by the same special character, as in:
ROSPFUSE PF=PF5,
AWS='+ATTACH +C1+ +C2+ +C3+ +C4+',
...
The values from the Command Area are assigned sequentially to these
variables. Variables to which values are not assigned are ignored. Thus,
with the preceding definition, the terminal user could type in the
Command Area:
JOB
and press PF5. Since only two values are specified, the assignment is
treated as though the user entered ATTACH JOB *. Since this is a valid
command, the variables C3 and C4 are ignored.
While the preceding examples use commands, the same principle applies
when coding any of the predefined functions. To illustrate, assume the
following definition:
ROSPFUSE PF=PF12,
TEXT='+SCROLL +C1+ C2+ +C3+'
...
With this definition, the terminal user could enter any of the following
values in the Command Area:
FORWARD
BACKWARD HALF
FORWARD 5 LINES
Finally, a key can be assigned a function that is comprised only of
variables, as in:
ROSPFUSE PF=PF15,
TEXT='+ +C1+ +L1+'
If the command FETCH is in the Command Area when the user presses
PF15, Advantage CA-Roscoe will attempt to copy the contents of the
variable L1 into the AWS (for example, if L1 contains WIDGET, Advantage
CA-Roscoe will attempt to FETCH WIDGET).

19.2 ROSPFUSE Macro
19.2.3 Assigning Predefined Functions

Predefined functions can be used to identify: 1) the location to which the
display is to be positioned, or 2) an action to be performed. The functions can
be specified as delimited strings or codes, where:
■ Strings are more flexible. They can be defined to allow variable
substitution by the terminal user.
■ The codes are more efficient. They are executed directly while the string
assignments must be parsed every time a PF key is pressed. Thus, the
codes should be used whenever variable substitution is not to be
performed by the user.
The functions shown in the following tables are grouped by their activity. Note
that abbreviations are in uppercase.
19.2.3.1 Predefined Functions - Position Display
Function String Format Code

'POSITION BOTtom' BOTTOM
'POSITION Top' TOP
'SCROLL BACK ' BS
'SCROLL BACK Csr' BC
'SCROLL BACK v FRames' BRv
'SCROLL BACK Full' BF
'SCROLL BACK Half' BH
'SCROLL BACK v [ Lines ] BLv
'SCROLL BACK Max' BM
'SCROLL BACK v Pages' BPv
'SCROLL FORWARD ' FS
'SCROLL FORWARD Csr' FC
'SCROLL FORWARD v FRames' FRv
'SCROLL FORWARD Full' FF
'SCROLL FORWARD Half' FH
'SCROLL FORWARD v <Lines>' FLv
'SCROLL FORWARD Max' FM
'SCROLL FORWARD v Pages' FPv
'SCROLL LEFT' LEFT

19.2 ROSPFUSE Macro

'SCROLL LEFT v' LEFTv
'SCROLL LEFT Max' LEFTM
'SCROLL RIGHT' RIGHT
'SCROLL RIGHT v' RIGHTv
'SCROLL RIGHT Max' RIGHTM
19.2.3.2 Predefined Functions - Split Screen

'END' END
'SPLIT' SPLIT
'SWAP' SWAP
19.2.3.3 Predefined Functions - Miscellaneous Functions

'ENTER' ENTER
'INPUT' INPUT
'QUIT' QUIT
'REPEAT' REPEAT
The following functions position the display. These functions may only be
assigned to PF keys. Also, unless noted otherwise, changes made to the current
frame are applied when the PF key is pressed. Note that a frame is equivalent
to the number of lines in the Execution Area.
BC The display is positioned so that the line at which the cursor is
positioned is the last displayed line. ('SCROLL BACK CSR')
BF The display is positioned backward one line less than the total
number of lines in the current frame (that is, the first line of the
new display is the last line of the old). If less than of a full frame
of lines precede the current frame, the action is identical to TOP.
('SCROLL BACK FULL')
BH The display is positioned back one-half frame. If less than a half
frame of lines precede the current frame, the action is identical to
TOP. ('SCROLL BACK HALF')

19.2 ROSPFUSE Macro
BLv The display is positioned backward v lines. If less than v lines

precede the current frame, the action is identical to TOP.
('SCROLL BACK v LINES')
BM Identical to TOP. ('SCROLL BACK MAX')
BOTTOM The display is positioned so that it ends with the last displayable
line. ('POSITION BOTTOM')
BPv Synonym for BRv. ('SCROLL BACK v PAGES')
BRv The display is positioned backward v frames. If less than v
frames precede the current frame, the action is identical to TOP.
('SCROLL BACK v FRAMES')
BS The display is positioned backward based on the value specified
in the SCRL field of the System Information Line. If the number
of remaining lines is less than the SCRL field value, the action is
identical to TOP. ('SCROLL BACK')
FC The display is positioned forward so that the line at which the
cursor is positioned is be first displayed line. ('SCROLL
FORWARD CSR')
FF The display is positioned forward one line less than the total
number of lines in the current frame (that is, the lsat line of the
new display is the first line of the old). If less than a full frame of
lines remain, the action is identical to BOTTOM. ('SCROLL
FORWARD FULL')
FH The display is positioned forward one-half frame. ('SCROLL
FORWARD HALF')
FLv The display is positioned forward v lines. If less than v lines
remain, the action is identical to BOTTOM. ('SCROLL FORWARD
v LINES')
FM Identical to BOTTOM. ('SCROLL FORWARD MAX')
FPv Synonym for FRv. ('SCROLL FORWARD v PAGES)
FRv The display is positioned forward v frames. If less than v frames
remain, the action is identical to BOTTOM. ('SCROLL FORWARD
v FRAMES')
FS The display is positioned forward based on the value specified in
the SCRL field of the System Information Line. If the number of
remaining lines is less than the SCRL field value, the action is
identical to BOTTOM. ('SCROLL FORWARD')
LEFT The extent of the left shift is determined by subtracting the left
margin value from the right margin value, as specified in the
COLS field of the System Information Line. This value is then
subtracted from the left margin and the frame is repositioned.
('SCROLL LEFT')

19.2 ROSPFUSE Macro
LEFTM The display is shifted left to begin with the first position of the
line. ('SCROLL LEFT MAX')
LEFTv The display is shifted left that number of positions. (It cannot be
shifted beyond column 1.) The value must be positive and
greater than 0. If zero is specified, no shifting occurs. ('SCROLL
LEFT v')
RIGHT The extent of the right shift is determined by subtracting the left
margin value from the right margin value, as specified in the
COLS field of the System Information Line. This value is then
added to the right margin and the frame is repositioned.
('SCROLL RIGHT')
RIGHTM The display is shifted right to end with the last position of the
line (for example, 255 when the AWS is attached or the LRECL
value when a data set is attached). ('SCROLL RIGHT MAX')
RIGHTv The display is shifted right that number of positions. (It cannot be
shifted beyond the rightmost margin for the type of data being
displayed (for example, 255 for the AWS).) The value must be
positive and greater than 0. If zero is specified, no shifting occurs.
('SCROLL RIGHT v')
TOP The display is positioned so that it begins with the first
displayable line. ('POSITION TOP')
The following functions control split-screen processing. They may only be

assigned to PF keys.
END Split-screen processing is terminated; the two logical screens are
returned to a single physical screen. ('END')
SPLIT Split-screen processing is invoked
the physical screen is divided into to logical screens. ('SPLIT')
SWAP Active and inactive split screens are interchanged; the cursor is
moved from one logical screen to the other. ('SWAP')
Finally, the following special-purpose functions are also available. All of these
functions may be assigned to PF keys; only INPUT and REPEAT may be
assigned to PA keys.
+ Displays the last executed command.
- Reexecutes the last executed command.
Note: See the Advantage CA-Roscoe Interactive Environment User
Guide for additional information on the '+' and '-' commands.
ENTER Changes made to the current frame are applied. The display retains
its position. If the ENTER= operand is also defined, the display is
positioned based on its specified scroll value. ('ENTER')

19.2 ROSPFUSE Macro
INPUT Changes made to the current frame are applied. If the cursor is in
the Execution Area, blank lines are inserted after the line at which
the cursor is positioned. If the cursor is not in the Execution Area,
blank lines are inserted before the first line displayed on the
current screen. ('INPUT')
QUIT Changes made to the current frame are ignored. The attached data
is detached. ('QUIT')
REPEAT Changes made to the current frame are ignored. No scrolling
occurs. Commands entered in the Command Area are executed.
('REPEAT')
19.2.4 Sample ROSPFUSE

The following panel illustrates how the ROSPFUSE table can be defined. A
copy of the default ROSPFUSE table is in the member PFUSETAB in the
RO60OPT library.
Sample ROSPFUSE Macro Definitions
PA1 ROSPFUSE PF=PA1, x

TEXT=REPEAT, ignore changes x
CTEXT=CPA1
...
PF1 ROSPFUSE PF=PF1, x
TEXT=SPLIT, split screen x
...
TEXT='EXEC PFK4', rpf program x
AWS='+ATTACH +L1+,,', var. sub. x
DSN='+ATTACH DSN +C1+', x
JOB='+ATTACH JOB FILE +C1+', x
LIB=FF1, scroll code x
CTEXT=CPF4
TEXT='EXEC PFK5', x
AWS='+SCROLL +C1+ +C2+ +C3+', x
...
TEXT=' + +C1+', enter anything x
...
TEXT=LEFTM, scroll code x
...


19.3 ROSPCODE Macro
19.3 ROSPCODE Macro

The ROSPCODE macro is used to define a code and the function to be
performed when that code is in effect.
There must be one set of ROSPCODE macros for every CTEXT= operand
coded in the ROSPFUSE table.
A set consists of one or more ROSPCODE macros which define codes for the
same PF or PA key. Although each set must be physically contiguous, one set
does not have to be physically contiguous to another set. (That is, each set may
be coded directly following the ROSPFUSE definition for a key, or each set
may be assembled separately as a separate CSECT. If the latter is done, the
value of the CTEXT keyword must be a symbol which is declared as an
EXTRN.)
The ROSPCODE macro is coded as follows:
19.3.1 Syntax
ROSPCODE Macro
──┬─────┬──ROSPCODE──CODE=code──,──────────────────────────────
└─tag─┘
──TEXT='processor-code-definition'─────────────────────────────
tag Tag that is the same as the value coded in the CTEXT keyword of
some ROSPFUSE definition. It must be used on the first
ROSPCODE call of a set. It defines the key for which this set is
intended.
CODE= 1- to 3-character code corresponding to a processor code or Monitor
command. The codes must be in EBCDIC ascending sequence
within each set.
TEXT= Character string to be returned or command to be executed. It must
be bound by apostrophes. To define multiple commands, separate
the commands with slashes.
To designate the end of a set, code a ROSPCODE macro with no operands.

19.3 ROSPCODE Macro
The following panel illustrates how the ROSPCODE macro sets can be defined.
(The distributed ROSPCODE macro sets are included with the ROSPFUSE
macro definitions on RO60OPT library as the member PFUSETAB.)
Sample ROSPCODE Macro Definitions
CPA1 EQU

A1 ROSPCODE CODE=LOO,TEXT='D LOOK'
ROSPCODE CODE=NUM,TEXT=''
ROSPCODE
CPA2 EQU
A2 ROSPCODE CODE=LOO,TEXT='END'
ROSPCODE CODE=NUM,TEXT=''
ROSPCODE
CPF1 EQU
F1 ROSPCODE CODE=LOO,TEXT='D WAIT'
ROSPCODE CODE=NUM,TEXT='1'
ROSPCODE
...
CPF6 EQU
F6 ROSPCODE CODE=LOO,TEXT='D CPU,ALL'
ROSPCODE CODE=NUM,TEXT='6'
ROSPCODE
...


19.4 To Modify the PF/PA Key Assignment Table
19.4 To Modify the PF/PA Key Assignment Table

A default set of PF/PA key assignments is placed in the RO60LIB data set by
CRO6000.
| A sample ROSPFUSE macro definition is placed in the RO60OPT data set by

CRO6000. The sample definition is named PFUSETAB.
| After the PFUSETAB macro definition is modified to meet your requirements,

it must be assembled and linked into the RO60LIB Advantage CA-Roscoe
target library. This is accomplished by the RECEIVE and APPLY of product
USERMOD MRO6019 which is found in the installation sample JCL library.

■ Modify the PFUSETAB source in RO60OPT to meet your needs.
■ Imbed the contents of the PFUSETAB source member following the
will put an executable copy of ROSPFUSE into target library RO60LIB that
includes the modified key assignments.

Chapter 20. ROSDATA
ROSDATA is one of the batch programs distributed with Advantage

CA-Roscoe. It allows terminal users to copy bulk data and source programs
into the Advantage CA-Roscoe user library from external data sets. Proto- type
JCL for ROSDATA is supplied on the installation sample JCL library. During
installation, the JCL is added as the member ROSDATA to the library of the
individual assigned the RO prefix. This JCL should be modified as needed and
then added to the site procedure library.
For additional information about using ROSDATA and all of the batch
program distributed with Advantage CA-Roscoe, see the Advantage CA-Roscoe
Chapter 20. ROSDATA 20-1

20.1 Changing ROSDATA Default Values

Library members created by ROSDATA are given default attributes.
The CSECT ROSCONS in the load module ROSDATA contains the table of the
default attribute values. Sites can change these values by using the ROSDATA
macro to generate a new table. Once the new table is defined, it must be
assembled and link edited.
The ROSDATA macro is in the Advantage CA-Roscoe macro library

RO60MAC and is coded as follows:
20.1.1 Syntax
ROSDATA Macro
──┬─────┬──ROSDATA──┬────────────────────────┬────────────────
└─tag─┘ │ ┌─$────┐ │
├─CONTROL=─┴─char─┴──────┤
│ ┌─ALL──┐ │
├─,LIST─┴─list─┴─────────┤
│ ┌─ON──────┐ │
├─,MAXSIZE=─┴─maxsize─┴──┤
│ ┌─1─┐ │
├─,MAX=─┴─max──┴─────────┤
│ ┌─1──┐ │
├─,SEQ1=─┴─seq1─┴────────┤
│ ┌─1──┐ │
├─,INCR=─┴─incr─┴────────┤
│ ┌─1,6─┐ │
├─,SEQ=─┴─seq─┴──────────┤
├─,NOSEQ=noseq───────────┤
│ ┌─5────┐ │
└─,LINES=─┴─lines─┴──────┘

CONTROL= Any single special character that is to be used to mark the
beginning of control statements (for example, $ADD). It may be
any non-numeric, non-alphabetic or non-blank character that
can be conveniently keypunched or entered on a terminal. The
default is $.
No validation of this special character is made during macro
expansion.
This option permits varying the ROSDATA control character to
avoid conflict with other programs, the input to which may be
stored in Advantage CA-Roscoe through ROSDATA.

LIST= The information written to SYSPRINT is controlled by

specifying one of the following:
ALL All input data, control statements and error
diagnostics are listed (default).
CONTROL Only control statements and diagnostics are listed.
NONE Only diagnostics are listed.
MAXSIZE= Automatic segmentation is controlled by specifying either of
the following:
ON Segmentation is to occur when the MAX= value is
reached (default).
OFF No segmentation is performed.
If segmentation is disabled and a line number greater than
999999 is generated, ROSDATA terminates.
MAX= Automatic segmentation limit (that is, maximum number of
lines to be included in a member). The value may be any
unsigned integer not exceeding 32767. The default is 1000.
If this value is set greater than the AWS size, members will be
created that cannot be fetched into the AWS in their entirety,
but must be segmented by specifying line numbers.
SEQ1= Default starting sequence number. The default is 100.
INCR= Default increment value when ROSDATA generates sequence
numbers. The default is 100.
SEQ= Location of the sequence number field, designated as either:
COBOL Field in columns 1 through 6 (default).
(s,l) Field starts in column s for a length of l.
The output members from ROSDATA are given the initial
attribute of sequenced.
As distributed, ROSDATA assumes the sequence number field
begins in column 73 for a length of 8. If the ROSCONS table is
reassembled and this operand is not respecified as (73,8), the
default of COBOL is assumed.
NOSEQ= Specify YES if the output members are not to be given an
initial attribute of sequenced.
SEQ and NOSEQ are redundant and are intended to prevent
definition errors.
LINES= Number of lines to be printed per page. The minimum number
of lines is 10. The maximum is 99. The default is 50.
Chapter 20. ROSDATA 20-3


| A default ROSDATA macro definition is placed in the RO60OPT data set by
CRO6000. The sample definition is named DATATAB.
| After the DATATAB macro definition is modified to meet your requirements,

it must be assembled and linked into the RO60LIB Advantage CA-Roscoe
target library. This is accomplished by the execution of member RDATINST in
the installation sample JCL library.
20.2.1 Notes
■ The ROSDATA macro generates the necessary INCLUDE and ENTRY
statements for the link edit step.

Chapter 21. Security/Accounting Exit Facilities
Advantage CA-Roscoe includes a variety of exits that can be used for site
security and accountability. While the individual exits are described in detail in
the Advantage CA-Roscoe Interactive Environment Extended Facilities for System
Programmers Guide, the following list indicates some of the facilities provided.
Chapter 21. Security/Accounting Exit Facilities 21-1

21.1 Security Exits
21.1 Security Exits

Two online exits and one batch exit are provided to assist sites in establishing
their security environment. These exits are:
ACFEXIT This online exit is used to control access to Advantage
CA-Roscoe.
DSAEXIT This online exit is used to verify that a terminal user is
authorized to access a requested data set.
BEXEXIT This batch exit is used to verify that the batch programs
LIBSERVE, ROSCOPY and ROSDATA may continue to execute.

21.2 Exits Taken at Critical Moments During Advantage CA-Roscoe Execution
21.2 Exits Taken at Critical Moments During Advantage

CA-Roscoe Execution
AUTEXIT This exit can be used to control the Advantage CA-Roscoe
automatic terminal processing facilities. These facilities include
the: 1) automatic sign-off facility that forces a terminal off if
there is no activity within a site-specified time period, and 2)
automatic terminal lock facility that displays the Terminal Lock
screen.
CLLEXIT This exit is called whenever the CALL command is executed.
CALL is the command used to execute an ETSO application.
CMDEXIT|CMDEXIT2
These two exits are invoked during the interpretation of every
Advantage CA-Roscoe and RPF command. They can be used to
restrict Advantage CA-Roscoe command usage to certain users,
or permit the use of commands whose names are unknown to
DSFEXIT This exit can be used to exercise a degree of control over certain
aspects of processing performed by the Data Set Facility.
LIBEXIT This exit can be used to control certain aspects of the processing
performed by the Library Facility.
OUTEXIT This exit can be used to control the terminal user's ability to
attach and view job output.
SIGEXIT This exit is invoked during sign-on. A SIGEXIT routine can
converse with the terminal user, refuse sign-on and write user
records to the Advantage CA-Roscoe accounting file.
SMFEXIT This exit is invoked at system initialization and thereafter
whenever Advantage CA-Roscoe writes an accounting record. A
SMFEXIT routine can permit user code to replace or supplement
the distributed accounting routines.
SUBEXIT This exit is invoked at SUBMIT time. A SUBEXIT routine can
permit users to pass input records unchanged, or to modify or
replace input records with site-defined information.
Chapter 21. Security/Accounting Exit Facilities 21-3

21.3 Monitor Routine Exits
21.3 Monitor Routine Exits

The majority of the distributed Monitor routines include exit facilities to permit
sites to provide additional security or obtain additional accounting
information.
All Monitor routines usage can be controlled by MONEXIT. This exit receives
control whenever a Monitor command is invoked. A MONEXIT routine can be
used to modify the input to the routine or suppress execution of the command.
The Monitor routines that include exit facilities are:

AMS An AMS exit routine can be used to filter input to and/or
output from AMS.
CONSOLE A CONSOLE exit routine can be used to control who may
display console messages and/or execute operator commands.
DISPLAY A DISPLAY exit routine can be used to restrict terminal users
from executing DISPLAY subcommands.
EXPORT An EXPORT exit routine can be used to: 1) check user's requests,
2) examine input records passed to the Immediate Online
Update (IOU) of The LIBRARIAN, and 3) suppress or permit
spooling of EXPORT/ROSCOE/IOU output.
IMPORT An IMPORT exit routine can be used to: 1) accept, modify or
change a user's requests and 2) change the format of the PDS
directory listing.
ZAP A ZAP exit routine can verify the authorization of the terminal
user to access or update a data set.

Chapter 22. TRAINING (RPF)
TRAINING is an interactive application that introduces the ROSCOE

Programming Facility (RPF). It was created using the Dialog Management
Facility (DMF).
Note: For a description of DMF, see the Advantage CA-Roscoe Interactive
Environment RPF Language Guide
TRAINING consists of two primary segments.

■ Part 1 presents general information about RPF commands and facilities. It
also prompts the terminal user to perform specific tasks based on the
information presented. The user's responses are then used to generate a
simple, executable RPF program.
■ Part 2 contains advanced information about RPF and introduces the user to
more complex RPF structures. It includes a variety of information ranging
from accessing AWS data and job output to demonstrating how to
generate a panel definition dynamically.
The terminal user can stop and restart TRAINING at any time. When
TRAINING is restarted, the user is presented with a panel that lists the
topics already covered. The user can choose to review a specific topic
before continuing from where he/she had been. When the user stops
TRAINING, the generated RPF program can be executed. (If the user stops
TRAINING during any of the debugging sections, the program may not
execute successfully. TRAINING discusses and corrects the problems
introduced to the program.)
Chapter 22. TRAINING (RPF) 22-1

22.1 Installing and Maintaining the TRAINING RPF
22.1 Installing and Maintaining the TRAINING RPF

| The library members comprising the TRAINING are distributed as the member
| RPFINFO on CAI.RO60.KEYS. During installation, the profile for the
TRAINING is created and the members are restored to that profile.
The TRAINING members must be stored under the Advantage CA-Roscoe

profile reserved for them. The members are maintained under this profile. Any
new or revised TRAINING members must be stored under this profile to be
accessed.
22.1.1 Notes
■ TRAINING is designed for use at 3270-type terminals that have a
minimum of 24 lines and 12 PF keys.
■ TRAINING expects that 32 RPF permanent variables are available for use.
Check the PERMVARS= initialization parameter in the Advantage
CA-Roscoe JCL to ensure that it is specified with a value of 32.
■ TRAINING requires that a minimum of 16 elements are be able to be
DECLAREd for a local variable. Check the ARRAYMAX= initialization
parameter in the Advantage CA-Roscoe JCL to ensure it is specified with a
value of 16 or greater.
■ Finally, the language specified with the CHARSET= initialization
parameter in the Advantage CA-Roscoe JCL must be USENGLISH.

22.2 System Components

This section describes the conventions used in naming the members added to
the profile RPFTRAIN. It also describes members that are added to the user's
library when executing TRAINING.
22.2.1 Naming Conventions

Part 1 of TRAINING is divided into three primary segments. Part 2 is divided
into five. The names of the members within a segment conform to the name of
the primary member. Each of the names is suffixed with a two-digit value
(shown as xx in the following table) which indicates its position within the
segment.
Part 1 Subordinate PART 2 Subordinate

Primary Primary
SETUPxx cSETUPxx ATTACHxx cATTCHxx
PROCINxx cPROCNxx BRANCHxx cBRANCxx
RESPONxx cRESPNxx PRGRMxx cPRGRMxx
SCROLLxx cSCROLxx
SUBMITxx cSUBMTxx
The code 'c' is used to indicate the type of information in the subordinate
member. If the code is:
E The member contains a panel that is used to present additional
information about a subject.
I The member contains an initialization RPF program.
X The member contains an execution RPF program.
22.2.1.1 Help Panels
Help panels provide additional comments on command syntax or other

specialized information. The first character of the name of every Help panel is
H. This is followed by the name (or abbreviation) of the subject to which the
Help panel applies. For example, HSUBSTR is the Help panel for the SUBSTR
function.

22.2.1.2 Summary Panels
Some of the subjects discussed have summary panels associated with them.
These summary panels are prefixed with the character S, followed by the
subject name (or abbreviation). For example, SATTACH contains summary
information about attaching data.
22.2.1.3 Additional Members in TRAINING
TRAINING This member initiates execution of TRAINING based on

whether the user is starting or restarting the application.
START This member contains the 'Welcome Back' panel used by Part
1.
START2 This member contains the 'Welcome Back' panel used by Part
2.
START and START2 provide a summary of the topics covered in their

respective parts and allow the user to restart TRAINING from the beginning of
a part or to resume execution.
INTRO01 This member provides the overall introduction to TRAINING.
(Additional members include: INTRO02, INTRO03 and
INTRO04.)
INTRO101 This member introduces Part 1 of TRAINING. (An additional
member is INTRO102).
INTRO201 This member introduces Part 2 of TRAINING. (Additional
members include: INTRO202 and INTRO203).
UCANDOIT This member contains suggestions as to how the user can
modify ZZZZLIBR. It can be used to provide the user with
advanced RPF exercises.
ZZZZATCH This member contains that portion of the RPF program
ZZZZLIBR that has been generated thus far in Part 2 of the
TRAINING.
ZZZZBRNC This member contains that portion of the RPF program
TRAINING.
ZZZZPRGM This member contains that portion of the RPF program
TRAINING.
ZZZZSCRL This member contains that portion of the RPF program
TRAINING.
ZZZZSUBT This member contains that portion of the RPF program
TRAINING.

22.2.2 Assigned Variables

The only permanent variable used by the programs comprising TRAINING is
P20.
The following local variables are used by Part 2 of TRAINING:

L1 AWS counter (for scrolling and reading).
L2 Contains 1) data read from the AWS, or 2) new member name (for
RENAME).
L3 Contains panel array variable.
L4 Contains member name.
L5 Contains requested function for branching.
L6 Contains member description (for ALTER).
L7 Contains function for AWS write.
L8 Contains data line written to L10.
L10 Used as a place holder for AWS write.
22.2.3 Members Added to User's Library

The following members are added to a user's library when that individual
executes Part 1 of the TRAINING:
ZZZZGAME This member contains the program that is generated
during the course of executing Part 1. It also includes
information that is used to properly reestablish the
terminal user who resumes executing TRAINING after a
break. This member should never be modified by the
user.
ZZZZGAMZ This member is called by the program ZZZZGAME. It is
created to explain EXEC, argument variables and return
variables. This member should never be modified by the
user.
ZZZZGAMX This member is created by the member ZZZZGAMZ.
The following members are added to a user's library as a result of executing

Part 2 of the TRAINING:
ZZZZLIBH This member contains the Help panel that is used by the
program ZZZZLIBR. It should never be modified by the user.
ZZZZLIBP This member contains the panel that is used by the program
ZZZZLIBR. It is dynamically generated during the execution of
Part 2. It should never be modified by the user.

ZZZZLIBR This member contains the program that is generated while

executing Part 2. This member should never be modified by the
user.
If the terminal user should execute this program, the following
additional members will be added to that individual's library:
$$$$FUNC To execute all ALTER and RENAME requests.
$$$$$DEL To execute all confirmed DELETE requests.
ZZZZRJCL This member contains the core JCL needed to
execute ROSCOPY. This member should never
be modified by the user.

22.3 Processing Technique

One of the members comprising TRAINING is CMDEVAL. This member is
called by each RPF that evaluates a primary command entry. It strips out
blanks and returns the user entry to the calling program as uppercase.
The TRAINING is presented as two unique parts. The first part is divided into
the following three segments:
1. SETUP introduces the user to labels, reads and writes to the terminal, local
variables, system variables, comments, LET, DECLARE, SUBSTR,
LENGTH, INDEX and the Advantage CA-Roscoe PUSH and POP
commands.
2. PROCESS introduces the user to IF, LOOP, SELECT, CONFORM, GOTO,
VERIFY, RESPONSE, TRT, concatenation and debugging techniques.
3. RESPOND introduces the user to panels, using Advantage CA-Roscoe
commands in an RPF, reads and writes to the AWS, PAUSE (for
debugging), the trap facility, variable substitution, argument and return
variables and issuing the EXEC command from within an RPF program.
The second part of TRAINING is divided into the following five segments:
1. SCROLL introduces how to evaluate PF keys, positions within the AWS,
modify AWS data, and modify TAG character attributes in an active panel.
2. BRANCH introduces how to generate a function table using variable
substitution for the GOTO label names. It also discusses direct line
generation vs. the WRITE AWS command.
3. PROGRAM shows how the AWS can be used to build an RPF program
dynamically. This segment also describes how panels can be dynamically
generated.
4. ATTACH introduces how data in the AWS can be displayed and modified
while maintaining program control.
5. SUBMIT shows how to generate JCL in the AWS, modify the base JCL
variable substitution, submit the job, follows its progress through the
system (using the DISPLAY Monitor command), access the job output and
change the print status of the output through the ALTER command.

22.4 Customizing the TRAINING
22.4 Customizing the TRAINING
22.4.1 Verifying DMF Prefix

If DMF is assigned the default prefix, TRAINING can be executed as
distributed.
If DMF is assigned any other prefix, fetch the library member named
TRAINING and change the default DMF prefix to the prefix being used at the
site.
22.4.2 Reviewing Distributed JCL

Part 2 of TRAINING generates JCL to execute ROSCOPY. Site management
must review the members:
1. ZZZZRJCL and modify it to suit their needs. (Note that the strings
$$JNAME, $$ACCT and $$KEY are used by the generated program
ZZZZLIBR to supply the job name, accounting information and KEY
PARM field option.)
2. XSUBMT13 and modify it to suit their needs. This member writes JCL
statements to ZZZZLIBR which are then used to modify the JCL in
ZZZZRJCL.

22.5 Executing TRAINING
22.5 Executing TRAINING

The syntax to execute TRAINING is:
Executing TRAINING
──┬──────┬──pfx.TRAINING──┬─────────────┬──┬──────┬────────────
└─EXEC─┘ └─MENU──┬───┬─┘ └─NAME─┘
└─v─┘
──┬───────┬────────────────────────────────────────────────────
└─NOMSG─┘
where:
pfx Prefix assigned to the TRAINING key. The default prefix is RPF.
MENU If omitted, execution begins with the first panel in the application. If
specified, execution begins with the primary selection list.
Execution can be further qualified by specifying:
v Number of an option on the primary selection list. If specified,
execution will begin with that option.
NAME Causes the name of the panel being displayed to appear at the
bottom center of the panel. If omitted, the member name of the
panel is not displayed.
NOMSG Causes the termination message to be suppressed when the user
terminates TRAINING. If omitted, the termination message is
displayed.
22.5.1 Notes
■ Before attempting to execute TRAINING, fetch the member TRAINING on
that key. Verify that the appropriate prefix is being used for DMF. (This
member contains an RPF program which validates the user's entry and
builds the correct statement to initiate execution of TRAINING.)
■ The parameters can be entered in upper- or lowercase. They can be
specified in any order, as in:
EXEC pfx.TRAINING NAME MENU 3
exec pfx.training menu nomsg.
■ NAME is provided as a debugging tool. If a problem should be
encountered with TRAINING, reexecute the application using the NAME
parameter. The name of the member containing the panel is displayed at
the bottom center of the panel; thus, permitting the site to determine the
specific panel(s) that need to be reviewed.

Chapter 23. TUTORIAL (Advantage CA-Roscoe)
The TUTORIAL is an interactive application created using the Dialog

Management Facility (DMF). It simulates a 'typical' Advantage CA-Roscoe
session and is designed to acquaint a new user with Advantage CA-Roscoe.
The TUTORIAL describes the variety of facilities available with Advantage
CA-Roscoe. In particular, it describes the 3270 screen format, command entry,
data entry and data manipulation.
Note: For a description of DMF, see the Advantage CA-Roscoe Interactive
Environment RPF Language Guide.
The basic operations performed during an Advantage CA-Roscoe session are

presented as a series of topics. Although any topic can be skipped or repeated,
skipping topics is not recommended. Each topic contains information handled
in a previous section and assumes that the material has been covered. The
topics include:
Basic Advantage CA-Roscoe Definitions
Advantage CA-Roscoe Screen Format
Establishing Session Variables
Entering and Saving Data
Retrieving and Displaying Data
Modifying and Updating Data
Printing Data
Submitting Data and Viewing Output
Obtaining User Information
Split Screen Facility
Assigning Functions to PF Keys
Accessing External Data Sets
Each topic contains a series of panels. The panels discuss an aspect of the topic
and request that the user perform some task. The tasks include data entry,
command entry and scrolling. The user's entry is evaluated. If it is correct, the
next panel in the series is displayed. If it is not, a message prompts the user
for the correct entry.
Chapter 23. TUTORIAL (Advantage CA-Roscoe) 23-1

23.1 Installing and Maintaining the TUTORIAL
23.1 Installing and Maintaining the TUTORIAL

The library members comprising the TUTORIAL are distributed as the member
TUTORIAL on CAI.RO60.KEYS. During installation, the profile for the
TUTORIAL is created and the members are restored to that profile.
The TUTORIAL members must be stored under the Advantage CA-Roscoe

profile reserved for them. The members are maintained under this profile. Any
new or revised TUTORIAL members must be stored under this profile to be
accessed.
23.1.1 Notes
■ The TUTORIAL is designed for use at 3270-type terminals that have a
minimum of 24 lines and 12 PF keys.
■ The TUTORIAL expects that 32 RPF permanent variables are available for
use. Check the PERMVARS= initialization parameter in the Advantage
CA-Roscoe JCL to ensure that a value of 32 is specified.
■ Finally, the language specified with the CHARSET= initialization
parameter in the Advantage CA-Roscoe JCL must be USENGLISH.

23.2 Naming Conventions
23.2 Naming Conventions

Each member containing a panel has a subject name followed by a two-digit
value indicating its position in the subject series. For example, PRINT04 is the
fourth panel in the series for PRINT. When the length of the subject name
exceeds six characters, an appropriate abbreviation is used. For example,
SESVAR10 is the tenth panel in the series for Session Variables.
Most panels have an initializing RPF program and an execution RPF program
associated with it. All initializing RPF programs begin with the characters IN.
All execution RPF programs begin with EX. The next three characters of the
member name are an abbreviated form of the panel name. The two-digit suffix
is taken from the panel name and is used as the last two characters. For
example, the panel named PRINT04 has an initializing RPF program named
INPRT04 and an execution RPF program named EXPRT04.
Help panels are included to provide additional comments on command syntax

or other specialized information. The first character of the name of every help
panel is H. This is followed by the command name, abbreviated when
necessary, or some character string pertinent to the contents. For example,
HPRINT describes the PRINT command and HNAMING describes Advantage
CA-Roscoe naming conventions. Several commands require more than one
panel to cover the information. In this case, the number 1 or 2 is appended to
the base name. For example, HPRINT is the first panel discussing the PRINT
command and HPRINT2 is the second.


There are two types of common processing called by the execution RPF
programs. The first, CMDEVAL, is called by each execution RPF that evaluates
a primary command entry. The RPF program CMDEVAL strips out extra
blanks and returns the user entry as uppercase. The second, ERROR, is called
only when the user entry for a line command is incorrect. ERROR is a DMF
panel with accompanying initialization and execution RPF programs. Since the
number of lines in the Execution Area varies in the TUTORIAL; ERROR is
displayed for a three-line Execution Area, ERROR4 for four-line, and ERROR5
for five-line. As with ERROR, ERROR4 and ERROR5 have initialization and
execution RPF programs associated with them. The initialization RPF program
sets the Execution Area; the execution RPF program returns to the panel in
which the error occurred.
The panels named TUTOR, TUTOR01 and TUTOR02 contain the introduction
to the TUTORIAL and explain how to use it. The panel named SUBJ is a
selection list of the available topics.

23.4 Customizing the TUTORIAL
23.4 Customizing the TUTORIAL

Topics may be added to or deleted from the TUTORIAL. Using DMF on the
TUTORIAL key, access the panel named SUBJ and delete the unwanted topic
or insert the new topic. If a topic is deleted from this selection list, it cannot be
accessed by the TUTORIAL. If a topic is added to the selection list, the
accompanying panels must be generated using DMF on the key assigned to
the TUTORIAL. In addition, any necessary initialization or execution RPF
programs must be created.
If AllFusion CA-Librarian is not available, the section of the TUTORIAL that

discusses the commands to access AllFusion CA-Librarian master files can be
deleted. To do so, using DMF on the TUTORIAL key, access the selection
panel named DSN00. Delete the second selection list entry (entitled More about
LIBRARIAN Master Files) and regenerate the panel.
The TUTORIAL includes a discussion of commands for managing OS data

sets. To remove this section from the TUTORIAL, using DMF on the
TUTORIAL key, access the selection panel DSN00. Delete the third selection
entry (entitled Performing Data Management Functions) and regenerate the
panel.
Note: Although the order in which the topics are listed and the number the
user enters to access that topic can be changed, do not modify the panel
name assigned to each.

23.5 Executing the TUTORIAL
23.5 Executing the TUTORIAL
23.5.1 Syntax
The syntax to execute TUTORIAL is:
Executing the Tutorial

──┬──────┬──pfx.TUTORIAL──┬─────────────┬──┬──────┬────────────
└─EXEC─┘ └─MENU─┬───┬──┘ └─NAME─┘
└─v─┘
──┬───────┬────────────────────────────────────────────────────
└─NOMSG─┘
pfx Prefix assigned to TUTORIAL key. The default prefix is RTU.

MENU If omitted, execution begins with the first panel in the application. If
specified, execution begins with the primary selection list.
Execution can be further qualified by specifying:
v Number of an option on the primary selection list. If specified,
execution will begin with that option.
NAME Causes the name of the panel being displayed to be shown at the
bottom center of the panel. If omitted, the member name of the
panel is not displayed.
NOMSG Causes the termination message to be suppressed when the user
terminates TUTORIAL. If omitted, the termination message is
displayed.
23.5.2 Notes
■ Before attempting to execute TUTORIAL, fetch the member TUTORIAL on
that key. Verify that the appropriate prefix is being used for DMF. (This
member contains an RPF program which validates the user's entry and
builds the correct statement to initiate execution of TUTORIAL.)
■ The parameters may be entered in upper- or lowercase. They may be
specified in any order, as in:
EXEC pfx.TUTORIAL NAME MENU 3
exec pfx.tutorial menu nomsg.
■ NAME is provided as a debugging tool. If a problem should be
encountered with TUTORIAL, reexecute the application using the NAME
parameter. The name of the member containing the panel is displayed at
the bottom center of the panel; thus, permitting the site to determine the
specific panels that need to be reviewed.

Chapter 24. BulletinBoard System (BBS) Support
With basic Advantage CA-Roscoe, users can execute the BulletinBoard System
(BBS).
The BulletinBoard System is an online message system, established to support

the interchange of technical information between Advantage CA-Roscoe users.
| Most facilities provided with BBS can be used by all Advantage CA-Roscoe
| users, and can be performed in conjunction with other Advantage CA-Roscoe
| activities.
You can use the BulletinBoard System to:

■ View general news announcements that are broadcast by your site
■ View posted message threads and any thread entries they contain
■ Create new threads
■ Add entries(replys) to existing threads
■ Send messages to other Advantage CA-Roscoe users
Users can execute the BulletinBoard System by executing the BBSX RPF from
the BulletinBoard execution account.
| To add or create a thread, you must be a Library Administrator.
The BulletinBoard System follows CUA standards. It is a mode dependent

system, so you must move from one mode to another to perform each task. All
tasks associated with a BulletinBoard component are PF key functions, and are
listed on the bottom of each screen.
For additional information, see:

■ The Advantage CA-Roscoe Interactive Environment User Guide for information
about using BBS.
■ Step 15 in the Advantage CA-Roscoe Interactive Environment Installation Guide
for information about installing BBS under the user prefix RBX.
Chapter 24. BulletinBoard System (BBS) Support 24-1

24.1.1 BulletinBoard System Prefixes
During installation, two prefixes are created for the BulletinBoard System. The
prefixes are:
RBX This will contain the Advantage CA-Roscoe/BulletinBoard System.
RBS This holds all of the message threads created by the Advantage
CA-Roscoe/BulletinBoard System.
The RBX account will contain a control member, BBSCTL. This control
member contains a single record specifying the default message thread prefix,
RBS. To change this default prefix, simply change the prefix in the BBSCTL
| member. You will need to add a new account for this prefix using
| UPSMNT60. We recommend using the default prefix RBS.
24.1.2 BulletinBoard System Initialization Parameter Requirement

The BulletinBoard System is an RPF driven system. To expedite RPF execution,
it uses the SET STMTCNT RESET command. To use this command, the
Advantage CA-Roscoe SYSIN must contain LOOPRST=YES. If your SYSIN
does not contain this initialization parameter, you will need to add it.

24.1.3 BulletinBoard System ETSO EPL Requirement
The load module BBSSERV must be added to the site ETSO Eligible Program
List (EPL). Member BBSEPL under the RBX prefix contains the ETSO EPL
entry for BBSSERV. After adding this EPL entry, the load library containing
the BBSSERV load module must be added to the ETSOLIB DD statement.
The BBS EPL entry is shown following:
Column Contents Meaning

1- 8 BBSSERV Program entry point.
10-12 10 Maximum number of concurrent application
executions. (Adjust this number as needed.)
14-17 5000 Maximum number of CPU time slices.
19-24 768 Total amount of storage to be provided
below the 16 MB line.
26-31 512 Total amount of storage to be provided per
GETMAIN request below the 16 MB line.
33-38 5000 Total amount of storage to be provided above
the 16 MB line.
40-45 3000 Total amount of storage to be provided per
request above the 16 MB line.
47 N Dump flag.
49 MODESET authorization flag.
51-52 Command Processor Flag.
Chapter 24. BulletinBoard System (BBS) Support 24-3

Chapter 25. User-Contributed Routines
User-contributed routines are written by Advantage CA-Roscoe users and

contributed by them to the Advantage CA-Roscoe user community. The
routines include Monitor routines, RPF programs and a variety of batch
programs. The routines are submitted to the user community through the
National Advantage CA-Roscoe User's Group (NARUG). The Advantage
CA-Roscoe staff reserves the right to review the routines and categorize them
as Class A or Class B routines, where:
Class A Routines
Routines that appear to have general appeal to a large segment of
the Advantage CA-Roscoe user community. These routines are
described in Advantage CA-Roscoe manuals and are distributed "as
is." No warranty, either expressed or implied, is made for them.
Neither the Advantage CA-Roscoe staff nor members of the
NARUG can guarantee that the routines are free of errors or that
errors will be corrected if any are found. The Advantage CA-Roscoe
staff will make such efforts as are deemed reasonable, however, to
maintain the integrity, performance and documentation of these
| routines. Class A routines are distributed on the Advantage
| CA-Roscoe ROxxOPT (OPTIONS) library (xx=the applicable
| Advantage CA-Roscoe Release).
Class B Routines
Routines that are distributed under the direction of the National
Advantage CA-Roscoe User's Group (NARUG). At their request,
| these routines are distributed as the twelfth file (CAI.ROxx.UCR) on
| the Advantage CA-Roscoe installation/maintenance tape. This file is
| a LIBUTIL backup of an Advantage CA-Roscoe library containing
| only UCR materials. Member ROxxRUCR distributed in the
| Advantage CA-Roscoe SAMPJCL library contains the JCL to unload
| the UCR RPF system, written and maintained by NARUG. This
| RPF system allows selective review of the contents of the UCR and
| will generate JCL for selective restoration of items of interest. (To
| execute this system once it has been restored, execute its root RPF,
| UCR. UCR may be executed from any key unless its use of PF keys
| is to be modified; if so, run it from its own key or a key with direct
| update authority.)
Chapter 25. User-Contributed Routines 25-1

Advantage CA-Roscoe customers are encouraged to share their own materials
with other users. Procedures for gathering materials and offloading them to
tape are included as part of the UCR RPF system and where possible should
be used. If there should be any problems or questions regarding contribution
procedures, the name, address, and telephone number of the current NARUG
UCR Coordinator are available from the UCR RPF. Note that all contributed
materials MUST be provided in LIBUTIL backup format and that all members
must have member descriptions provided.

Chapter 26. Functionally Stabilized Routines
|
| The Monitor routines described in this chapter are FUNCTIONALLY

| STABILIZED and include the following:
| ■ ACCTREPT
| ■ CAT
| ■ COB
| ■ LOOK
| ■ PLI
| ■ UTILITY
| ■ VCAT
A routine receives this designation when the function it provides is either

obsolete or provided by another command or facility within Advantage
CA-Roscoe.
In such cases, the components continue to be distributed and corrections for

reported errors are provided as long as such corrections do not involve
extensive redesign of the components. The components will not be involved in
future development efforts. We strongly recommended that sites migrate from
the stabilized routines to the new commands or facilities as quickly as possible.
Chapter 26. Functionally Stabilized Routines 26-1

26.1 ACCTREPT Routine
26.1 ACCTREPT Routine

The ACCTREPT routine extracts data from the OUTPUT1 file (created by the
ACCTDUMP program) to produce reports about:
1. AWS statistics
2. Monitor command and ETSO usage
3. Activity of selected or all Advantage CA-Roscoe users
4. Response-Time Monitor (RTM) statistics.
Note: The ACCTREPT routine should no longer be used to produce the above
reports. Advantage CA-Earl can produce each of these reports and
should be used instead of ACCTREPT.

26.2 CAT Routine
26.2 CAT Routine

The CAT Monitor routine provides users with a means of examining entries in
an OS CVOL catalog. Supplied with a data set index, CAT writes to the AWS
all entries that have the specified index, plus entries that have the index with
an additional level of qualification.
CAT is reentrant.
26.2.1 To Use This Routine:

RUN=CAT
In addition to being distributed as the load module RSSCCAT0 in the RO60LIB

library, this routine is also distributed in source code as member RSSCCAT0 in
RSSCCAT0. Once the routine has been loaded, add the RUN= initialization
parameter previously described to the Advantage CA-Roscoe JCL.
26.2.2 To Install RSSCCAT0

After the RSSCCAT0 source is modified to meet your requirements, it must be

■ Modify the RSSCCAT0 source in RO60OPT to meet your requirements.
■ Imbed the contents of the RSSCCAT0 source member following the
will put an executable copy of RSSCCAT0 into target library RO60LIB.

for information about this the CAT command to invoke this routine.

26.2 CAT Routine

As distributed, every Advantage CA-Roscoe user can execute CAT. Sites that
wish to restrict the use of this routine should use the MONEXIT exit
(described in the Advantage CA-Roscoe Extended Facilities for System Programmers
Guide).

26.3 COB Routine
26.3 COB Routine

The COB Monitor routine can be used to syntax check a COBOL program.
COB has a pseudo-SPIE exit.

Define the COB routine to Advantage CA-Roscoe through the RUN=
RUN=COB(S)

for information about using the COB command to invoke this routine.

26.4 LOOK Routine
26.4 LOOK Routine

The LOOK Monitor routine permits the use of Unicenter CA-SYSVIEW during
a Advantage CA-Roscoe terminal session.
26.4.1 To Use This Routine:

See the Unicenter CA-SYSVIEW Customization Guide for distribution and
installation information.

for information about using the LOOK command to invoke this routine.

26.5 PLI Routine
26.5 PLI Routine

The PLI Monitor routine can be used to syntax check a PL/I program.
PLI has a pseudo-SPIE exit.

Define the PLI routine to Advantage CA-Roscoe through the RUN=
RUN=PLI(S)

for information about using the PLI command to invoke this routine.

26.6 UTILITY Routine

The UTILITY routine permits OS data management functions to be performed
online.
UTILITY is reentrant and has a pseudo-SPIE exit.

parameter, as in:
RUN=UTI(S)

for information about using the UTILITY command to invoke this routine.

The UTILITY routine can be modified to:
■ Establish defaults for the operands of the ALLOCATE and CREATE
subcommands.
■ Add and delete subcommands from UTILITY and establish subcommand
protection levels.
■ Restrict use of subcommands by assigning passwords to the protection
levels.
■ Provide index-level protection of data sets.
■ Establish special names for unit devices and control dynamic allocation.
The modifications are made by using product USERMODs which are described
on the next several pages.
The load module contains both the UTILITY main task and its subtask. The
main task contains all tables and scanning logic to interpret the terminal input,
handle the interface with Advantage CA-Roscoe, attach the subtask and
coordinate execution of the main task with Advantage CA-Roscoe. The
subtask, which is identified before being attached, is a set of data management
routines that perform the subcommands. Users should retain their modified
object modules from release to release of Advantage CA-Roscoe to preserve
their modifications.
The UTILITY command also has an exit which is described in the Advantage
Guide.

26.6.3 DEFAULT: Changing Defaults

Site default values can be defined for most of the operands of the ALLOCATE
and CREATE subcommands. The defaults are placed in the DEFAULT table in
CSECT DEFAULT, which is generated by the DEFAULT macro. The table is
also mapped by the DEFAULT macro. The macro generates a CSECT or
DSECT statement as required.
The DEFAULT macro is placed in the RO60MAC library and the generation
source DFLTAB is placed in the RO60OPT library by the SMP/E APPLY of the
base Advantage CA-Roscoe function SYSMOD CRO6000. The DEFAULT macro
is coded as follows:
26.6.4 Syntax
{YES}
[tag] DEFAULT DSECT={NO }
[,BLKSI=blksi]
[,DIREC=direc]
[,DSORG=dsorg]
[,INDEX=basename]
[,PRIME=prime]
[,RECFM=FB]
[,RETPD=ndays]
[,SECOND=second]
[,SPACE=trkcyl]
[,VOLSER=volser]

DSECT= Generation of a DSECT or CSECT statement is controlled by
specifying either of the following codes:
YES A DSECT mapping the default table is generated. (The
DSECT name is ROSUTDEF.) Do not specify any other
operands of this macro.
NO A CSECT with the name DEFAULT is generated Specify
the other operands of this macro as appropriate.
BLKSI= Default block size.
DIREC= Number of directory blocks to be requested for a new PDS. If
SPACE= is coded, this operand is required. If DSORG=PS is
coded, this operand should not be coded.
DSORG= Data set organization, specified as PS, PO or DA.

INDEX= Base name to be used to make a default DSNAME for the data
set being allocated. The base name can be a maximum of 26
characters in length, in standard OS naming format. For example:
SYSDA.ROSCOE.USER
The DSNAME is formed by appending the user's prefix, time and
date to the index value. For example:
SYSDA.ROSCOE.USER.AL.Thhmmss,Dyydd
PRIME= Amount of units to be in the SPACE= operand for the data set
being allocated. This operand is required if SPACE= is coded.
RECFM= Type of record format desired. If this keyword is omitted, the
default is FB. To force the terminal user to enter a record format,
code RECFM= with no operand.
RETPD= An unsigned integer between 0 and 999, inclusive, which is to be
added to the current date to obtain the expiration date of the data
set. If 0 is coded, a 1-day period is forced. If RETPD= is specified
with no value, an expiration date of 00000 is created.
SECOND= Secondary space allocation. It may be omitted if no secondary
allocation is desired.
SPACE= Default unit of space allocation, specified as either TRK or CYL.
VOLSER= Serial number of the pack to be used for UTILITY allocations.
The omission of any operand causes that option to be removed from the table;
that is, the terminal user must enter the corresponding parameter as part of the
ALLOCATE or CREATE subcommand, or will be prompted to do so.
Operands are omitted either by not coding them or by coding them with a null
value. (RECFM is the only parameter that must be coded 'RECFM=' to force no
default.)
26.6.5 To Install a Modified DEFAULT Table

A sample DEFAULT macro definition is placed in the RO60OPT data set by
CRO6000. The sample definition is named DFLTAB.
After the DFLTAB macro is modified to meet your requirements, it must be



■ Modify the DFLTAB source in RO60OPT as described above.
will put an executable copy of RSSCUTI0 into target library RO60LIB that
includes the modified DEFAULT table.
26.6.6 ROSTABLE: Modifying Subcommand Table

ROSTABLE is the lookup table for UTILITY subcommands. This table must be
modified to add new subcommands to or remove subcommands from
UTILITY. Every subcommand has associated with it the following three items:
■ A name, such as ALLOCATE.
■ A protection level, corresponding to a protection level of a PASSWORD.
■ An offset, corresponding to the position of the VCON for the subcommand
processor in the VECTOR table. (The offsets start at 0 and increment by 1.)
The ROSTABLE macro is found online in the source module ROSTABLE. The
first occurrence of the macro generates an appropriate CSECT statement. The
macro is coded as follows:
26.6.7 Syntax
[tag] ROSTABLE subcmd,[prtlvl],offset

subcmd UTILITY subcommand (for example, WRITE, SCRATCH).
prtlvl Protection level as an unsigned integer between 0 and 255,
inclusive. If 0 is coded or if prtlvl is omitted, no protection level is
associated with the subcommand.
offset Offset defined by Advantage CA-Roscoe. It must not be altered.
(The sample ROSTABLE in the RO60OPT library shows how the
offsets must be specified.)
26.6.7.1 Notes
■ The END and PASSWORD subcommand must not be assigned a

protection level.
■ The end-of-table is designated by an asterisk (*) coded as the only
ROSTABLE operand. ROSTABLE * must appear at the end of the table.
■ Removing a ROSTABLE macro call effectively removes the subcommand
from the system. It is best to remove a subcommand definition by marking
the macro call as a comment.

■ The distributed ROSTABLE has all 0-level protection (that is, all users can
issue all subcommands). See the description of the ROSPASS macro for an
explanation of protection levels.
26.6.8 To Install a Modified Subcommand Table

A sample ROSTABLE macro definition is placed in the RO60OPT data set by
CRO6000. The sample definition is named UTITAB.
After the UTITAB macro is modified to meet your requirements, it must be


■ Modify the UTITAB source in RO60OPT as previously described.
includes the modified subcommand table.
26.6.9 ROSPASS: Modifying Password Table

Every UTILITY subcommand (except for PASSWORD and END) may be
password-protected. If a user enters a password-protected subcommand,
UTILITY determines if a password with a high enough protection level was
previously entered. If no password was entered or if the password did not
have an appropriate protection level, UTILITY prompts for a password.
Every password has associated with it an arbitrary protection level which must
be as high as the protection level of the desired subcommand itself. (As
distributed, all subcommands are unprotected.) To enable password
protection, the ROSPASS table must be reassembled. It is generated by a macro
also named ROSPASS, which is found online in the ROSPASS source code. The
first occurrence of the macro generates the appropriate CSECT statement. The
macro is coded as follows:
26.6.10 Syntax
[tag] ROSPASS password[,prtlvl]

password Alphanumeric string of any length with no intervening spaces.
Lowercase alphabetics should not be used.

prtlvl Protection level as an unsigned integer between 0 and 255,

inclusive. If 0 is coded or if prtlvl is omitted, no protection level is
associated with the password.
26.6.10.1 Notes
■ The END and PASSWORD subcommands must not be assigned

passwords.
■ There is no limit to the number of passwords that may be specified by
separate macro calls.
■ The protection levels specified with ROSPASS should correspond to the
protection levels specified in the Subcommand Table (ROSTABLE).
■ The protection level defined by the password can also be used as the
authorization level in the Index Table (ROSUTNDX).
■ The end-of-table is designated by an asterisk (*) coded as the only
ROSPASS operand. ROSPASS * must appear at the end of the table.
To illustrate the use of password protection, assume that the RENAME and
SCRATCH subcommands have been assigned (through ROSTABLE) a
protection level of 10 and that ALLOCATE and WRITE have been assigned a
protection level of 20. If a terminal user enters the password for a 10-level
subcommand (for example, PLAY), all subcommands with that protection level
can be executed; another password must be entered for the user to execute a
subcommand in a higher level. If a terminal user enters a password for a
20-level subcommand, the user is implicitly authorized to execute all
subcommands that have a protection level of 20 or less.
26.6.11 To Install a Modified Password Table

A sample ROSPASS macro definition is placed in the RO60OPT data set by the
The sample definition is named UTIPASS.
After the UTIPASS macro is modified to meet your requirements, it must be


■ Modify the UTIPASS source in RO60OPT as previously described.
includes the modified password table.

26.6.12 ROSUTNDX: Protecting Data Sets

ROSUTNDX contains a list of data set indexes to protected. The protection can
be by operation or authorization level. If the protection is by operation, the
operations to restrict must be defined. If the protection is by authorization
level, a level which corresponds to a protection level defined in the Password
Table (established by ROSPASS) must be assigned. Any index in the list may
be associated with both types of protection; with the authorization level
overriding the operation level. For example, if scratch operations are forbidden
for SYS1 data sets but SYS1 has an authorization level of 200, any user who
enters a password associated with the protection level of 200 is permitted to
perform the scratch on SYS1 data sets.
Note: As opposed to password-protected subcommands, no prompt is issued
if the user does not enter a password or enters a password associated
with a lower protection level.
The ROSUTNDX table is generated by the UTINDEX macro. The first

occurrence of the macro generates the table entries and the appropriate CSECT
statement. The macro is coded as follows:
26.6.13 Syntax
[tag] UTINDEX INDEX=index
[,USE=usecodes]
[,PROTECT=prtlvl]

INDEX= Data set index. If the index is qualified (that is, contains a period),
the index must be enclosed in apostrophes.
USE= Type of operations to be restricted are controlled by specifying one
or more of the following codes:
ALL All operations forbidden
A ALLOCATE operations forbidden
C CATALOG operations forbidden
D DLTNDX operations forbidden
R RENAME operations forbidden
S SCRATCH operations forbidden
U UNCATALOG operations forbidden
W WRITE operations forbidden
The codes may be specified in any order, separated by commas
with no intervening spaces. If more than one is specified, they must
be enclosed in parentheses. Duplicate or invalid codes are flagged
by an MNOTE. If USE= is omitted, no operations are restricted.

PROTECT=
Unsigned integer between 0 and 255, inclusive. This establishes the
authorization level for operations on data sets with this index. If
PROTECT= is omitted or 0 is coded, no authorization level is
associated with the command.
Note: The end-of-table is designated by an asterisk (*) which is coded as the
only value of the INDEX= operand. UTINDEX INDEX=* must appear
at the end of the table.
26.6.14 To Modify ROSUTNDX to Protect Data Sets

A sample UTINDEX macro definition is placed in the RO60OPT data set by
CRO6000. The sample definition is named UTINDX.
After the UTINDX macro is modified to meet your requirements, it must be

MRO602C, which is found in the installation sample JCL library.
The process to install MRO602C has the following basic steps:

■ Modify the UTINDX source in RO60OPT as previously described.
includes the modified ROSUTNDX.
26.6.15 PUNITL: Unit Definition and Dynamic Allocation

The PUNITL table performs the following two functions:
1. It is the lookup table for UNIT values recognized by the ALLOCATE,
CATALOG, CREATE, LISTVTOC, RENAME, SCRATCH and WRITE
subcommands of UTILITY.
A UNIT value can be either a standard unit designation or a site-defined
special name. Special names should be defined when:
■ Sites want to assign generic names (for example, ROSDA) to disk
packs.
■ Users of UTILITY are going to reference non-mounted volumes. For
example, the CATALOG subcommand permits cataloging on
non-mounted volumes when a special name is specified.
■ Users are going to reference data sets that are on mass storage devices
and are not cataloged.
2. PUNITL contains the control flag for the use of OS/390 dynamic
allocation. If the final volume determination for an ALLOCATE, CREATE

or WRITE subcommand indicates that the volume is not defined in the

Advantage CA-Roscoe JCL and the operating system is MVS, the PUNITL
table is referenced to determine if dynamic allocation may be used.
The special names defined in the table in CSECT PUNITL are not generated by
a macro. Each item in the table must be defined using the following format:
offset Length Contents

'0' '1' Length of unit name - 1.
'1' '1' Flag byte containing one of the following:
X'01'
Not a special name; the MATCHSER routine
determines the serial number.
X'02'
Non-mounted volume type for CATALOG. Both
UNIT= and VOL= operands are required in the
CATALOG subcommand.
X'80'
Special name for allocation; a six-character serial
number is appended to the unit name field.
2 4 UCB device-type code.
6 variable Unit name (for example, 3380, 3390, DISK, SYSDA,
TAPE). If the flag byte is X'80' a six-character volume
serial number of a special pack for UTILITY
allocations is appended.
26.6.15.1 Notes
■ The special name is a site option. If taken, any number of special names of
any kind can be added to the table. Each name must have a volume serial
number associated with it.
■ As many special names and non-mounted unit types as desired can be
defined. (The definitions must be made known to the users of UTILITY.)
These names do not have any connection to names defined at SYSGEN in
the OS UNITNAME macro.
■ The distributed PUNITL code is found on the RO60OPT library and
defines a variety of device types. Sample code for special names and
non-mounted devices is shown in the source.
■ The list must end with an X'FF' marker.

■ MVS dynamic allocation can be controlled by a site-written UTIEXIT

routine (see the Advantage CA-Roscoe Extended Facilities for System
Programmers Guide for details). If no UTIEXIT routine is present, dynamic
allocation is always allowed.
Examples:
■ Defining 2311s:
DC AL1(3) Length - 1 of 2311.
DC AL1(1) Flag byte (no special appendage).
DC XL4'321' UCB device-type for 2311 disk.
DC CL4'2311' Unit designation.
■ Defining non-mounted units:
DC AL1(3) Length - 1 of TAPE.
DC AL1(2) Flag byte (non-mounted volume).
DC XL4'34281' 9-track dual density 24 tape.
DC C'TAPE' Unit designation.
■ Defining special names
DC AL1(4) Length - 1 of SYSDA.
DC AL1(128) Flag byte (special name flag set).
DC XL4'3C28' Special pack is a 2314.
DC CL5'SYSDA' Special name.
DC CL6'WRK4' Allocations to be made on pack WRK4.
SPACE
DC AL1(4) Length - 1 of ROSDA.
DC AL1(128) Flag byte (special name flag set).
DC XL4'3529' Special pack is a 2314.
DC CL5'ROSDA' Special name.
DC CL6'ROS' Allocations to be made on pack ROS.
26.6.16 To Modify the Unit Definition Table

Sample PUNITL source is placed in the RO60OPT data set by the SMP/E
APPLY of the base Advantage CA-Roscoe function SYSMOD CRO6000. The
sample definition is named PUNITL.
After the PUNITL source is modified to meet your requirements, it must be

MRO6017 which is found in the installation sample JCL library.

1. Modify the PUNITL source in RO60OPT as previously described.
2. Execute the product USERMOD. This will initiate an SMP/E RECEIVE and
includes the modified unit table.

26.7 VCAT Routine
26.7 VCAT Routine

The VCAT Monitor routine scans VSAM system or user catalogs, ICF catalogs
and OS CVOL catalogs and displays all entries that match the specified node,
cluster or data set name.

RUN=VCA(S)
In addition to being distributed as the load module RSSCVCA0 in the

RO60LIB library, this routine is also distributed in source code as member
RSSCVCA0 in the RO60OPT library. If the source code is used, it must be
assembled and link edited into the Advantage CA-Roscoe target load library
under the name RSSCVCA0. Once the routine has been loaded, add the RUN=
initialization parameter previsously described to the Advantage CA-Roscoe
JCL.
26.7.2 To Install RSSCVCA0

After the RSSCVCA0 source is modified to meet your requirements, it must be
MRO604A, which is found in the installation sample JCL library.
The process to install MRO604A has the following basic steps:

■ Modify the RSSCVCA0 source in RO60OPT to meet your requirements.
will put an executable copy of RSSCVCA0 into target library RO60LIB.

for information about using the VCAT command to invoke this routine.

26.7 VCAT Routine

■ VCAT uses IDCAMS (the IBM Access Method Services system utility) to
obtain catalog information. It is possible that users may experience delays
if VCAT is used to obtain information about a large number of catalog
entries. Because VCAT attaches IDCAMS as a subtask of Advantage
CA-Roscoe, these delays affect only the individual user. If the site uses OS
CVOL catalog and the user wishes to obtain information about non-VSAM
data sets contained in these CVOL catalogs, it is suggested that the CAT
Monitor command be used for better performance.
■ To improve VCAT's performance, it may be advisable to place the
IDCAMS module in LPA. Sites should verify that IDCAMS has been link
edited as reentrant in their systems. (IBM APARs OZ57172 and OZ72723
describe errors where IDCAMS may be distributed as non-reentrant.) If
IDCAMS has been installed as non-reentrant, the directory entry for it can
be zapped to indicate that the module is actually reentrant.
■ Users should be advised to request catalog information only from catalogs
that are mounted and online. If a volume containing a catalog required by
VCAT is not currently mounted and online, the system message IEF238D
or IEF455D is issued to the master console and waits for the volume to be
mounted. This can cause unacceptable delays for the VCAT user. If the
operator replies "CANCEL" to message IEF238D or "NO" to message
IEF455D, the VCAT command is terminated with a VCA11 message.

26.7 VCAT Routine

Appendix A. Advantage CA-Roscoe System
Extensions
This Appendix provides information about system extensions implemented in

Advantage CA-Roscoe Version 6.0. These extensions involve Advantage
CA-Roscoe use of OS/390 Cross-Memory Services (ROXMS) and the
Advantage CA-Roscoe Support Address Space (ROSAS.)
The information is meant for the system programmer responsible for installing
Advantage CA-Roscoe and for any individuals involved in the integration of
vendor products into an Advantage CA-Roscoe environment.
Appendix A. Advantage CA-Roscoe System Extensions A-1

A.1 Use of OS/390 Cross-Memory Services

Cross-Memory Services appeared with IBM MVS/System Product Version 1
Release 2 (IBM MVS/SP1.2). This facility comprises a set of IBM System/370
instructions and a set of macros to manipulate the environment required by
these instructions. (The IBM System/370 Dual Address Space (DAS) extensions
are required on the processor where Cross-Memory Services are to be
executed.) Advantage CA-Roscoe makes extensive use of OS/390
Cross-Memory Services during the course of an execution. The Advantage
CA-Roscoe component ROXMS provides the following OS/390 Cross-Memory
facilities:
1. Access of data in more than one address space.
2. Movement of data between address spaces.
3. Causes programs to be called to run in another address space.
4. Causes programs to be called to run in the current address space but with
increased authority.
Each Advantage CA-Roscoe executing in a single physical complex acquires

the following Cross-Memory elements:
1. A normal Authorization Index (AX) (AX > 1) for the Advantage
CA-Roscoe job.
2. One or more non-system Linkage Index (LX) elements.
3. One or more Program Call Entry Table (ET) elements.
During the initialization of an instance of an Advantage CA-Roscoe,

identification requests to ROSAS cause granting of access to ROSAS-managed
global Cross-Memory Facilities. (The ROSAS component is discussed in the
Section 'Support Address Space'.) These Program Call (PC) routines provide
access to facilities that are of a global scope and must exist for an Advantage
CA-Roscoe to properly execute. When the Advantage CA-Roscoe job
terminates access to these global PC routines is revoked.
Depending on the options in effect for the execution of an instance of

Advantage CA-Roscoe, local PC routines are created at system initialization.
Advantage CA-Roscoe uses both Program Call Current Primary (PC-CP) and
Program Call Space Switch (PC-SS) routines. These routines implement
facilities that are private to a specific Advantage CA-Roscoe execution. The
local PC routines are destroyed at the termination of the creating Advantage
CA-Roscoe job.
To meet OS/390 restrictions, Advantage CA-Roscoe initialization automatically

sets the address space to NONSWAP if local PC-SS routines or multiple
address space data movement routines are included in the current execution.
Failure of Advantage CA-Roscoe and associated address spaces may occur due
to the address space becoming SWAP eligible.
A-2 System Reference Guide

Important
Site operations personnel should ensure that the Advantage CA-Roscoe
system is maintained in the NONSWAP state.
Access to ROXMS data structures and execution facilities is managed internal

to Advantage CA-Roscoe. Appropriate security and integrity controls prevent
unauthorized access to these services. ROXMS facilities are not available to site
or vendor applications. The Advantage CA-Roscoe main processing task is
defined as the OS/390 Cross-Memory Resource Owner (CMRO). Attempts by
site applications and other vender applications to create cross-memory owner
environments will cause abnormal termination of the application. Site or
vendor applications may make use of Cross-Memory facilities created by
applications in other address spaces. In general, a site or vender application
may use PC routines created by another system but must not attempt to use
the AXRES, LXRES, and ETCRE macros that define a new set of Cross-Memory
facilities.

A.2 Support Address Space (ROSAS)

To better manage the OS/390 Cross-Memory facilities and as a basis for future
system enhancements, Advantage CA-Roscoe creates and manages an MVS
System Address Space. This address space is an extension of the current
Advantage CA-Roscoe subsystem. It is started automatically as part of
Advantage CA-Roscoe subsystem creation and initialization.
An Advantage CA-Roscoe subsystem is created for each release level of the

system. The subsystem name is a four-character value in the form Rxxx, where
'xxx' is the Advantage CA-Roscoe version number. Listed below are examples
of Advantage CA-Roscoe subsystem names and their release associations:
R55 - Advantage CA-Roscoe Release 5.5
Subsystem and support address space creation occurs with the first instance of
an Advantage CA-Roscoe for a given release after an OS/390 Initial Program
Load (IPL). The address space remains in the system for the duration of the
OS/390 IPL. It is identified by the name RSASxxxx, where 'xxxx' is the name of
the Advantage CA-Roscoe subsystem for a particular release. As an example,
RSASR60 is the name of the Support Address Space for any Advantage
CA-Roscoe running at Version 6.0. One RSASxxxx address space exists for each
Advantage CA-Roscoe release executing in a machine. (Multiple Advantage
CA-Roscoe jobs at the same release level share a single RSASxxxx.) No
Advantage CA-Roscoe subsystem before R57 causes an RSASxxx address space
to be created.
The attributes of ROSAS are those of a limited function OS/390 System

Address Space that has never completed started task intialization. After
initialization by the ROSAS resource manager, no execution is ever performed
under the OS/390 TCB's in the address space. Display of the RSASxxxx
address space using system performance monitors shows an endless wait
condition. This is the normal mode for a limited function system address
space. Certain MVS created system address spaces also exhibit this endless
wait characteristic. The specific OS/390 attributes associated with the ASID in
use are:
1. Permanently exempt from system non-dispatchability
2. Exempt from RTM MEMTERM
3. L2 preferred user NONSWAP
4. Non-urgent
5. Privileged.
6. Exempt from CANCEL.
7. Exempt from FORCE.

A ROSAS address space: 1) contains all data structures necessary to manage

global Advantage CA-Roscoe Cross-Memory facilities, and 2) provides a
repository for information regarding multiple use of resources. These data
structures are maintained in pageable storage within the ROSAS private area.
ROSAS data structures are acquired based on OS/390 system values specified
for maximum address spaces. The maximum size of the ROSAS data structures
that can be created is 370,000 bytes. This storage value is exclusive of storage
required by OS/390 system components and the actual ROSAS initialization
program. The address space size should not exceed 512 KB in the most
extreme cases. Normal sizes are in the 350 KB range.
To manage global Cross-Memory facilities, ROSAS acquires and manages the

following OS/390 Cross-Memory elements:
1. The System Authorization Index(AX), (AX=1).
2. One System Linkage Index(SYSTEM LX).
3. One or more non-system Linkage Index (LX) elements.
4. One or more Program Call Entry Table (ET) elements.
The System LX value is owned by ROSAS for the duration of the OS/390 IPL.
Sites must ensure that a SYSTEM LX is available for use by ROSAS. Due to the
acquisition of a SYSTEM LX, the OS/390 ASID associated with the RSASxxx
address space can never be reused should RSASxxx terminate. In addition, if
RSASxxx terminates, the address space enters a disabled mode. This is a
normal situation given the characteristics of a limited function system address
space. Consult the appropriate IBM OS/390 documentation for the particular
release of OS/390 executing at your site for specific information on the
allocation of SYSTEM LX numbers.
After ROSAS has initialized, accesses to its data structures are effected through
PC-SS routines. Advantage CA-Roscoe components request ROSAS services
through internal mechanisms. ROSAS services are not available to site or
vender applications. The ROSAS address space is protected by a local ESTAE
recovery environment. During Advantage CA-Roscoe component access to
ROSAS data structures through PC-SS routines, protection is provided through
SETFFR routines. Failures during PC-SS access cause an SVCDUMP to be
requested for both the calling address space and the ROSAS address space.
ROSAS strictly observes MVS Data Integrity requirements. Attempts to access

ROSAS facilities by unauthorized users leads to abnormal termination of the
calling environment. No facilities are provided or intended that allow ROSAS
facilities to be externalized.

WARNING
Under no circumstances should site personnel attempt to alter ROSAS
programs or modify ROSAS data structures and Global Cross-Memory
elements. Abnormal termination of the entire OS/390 complex and
potential severe system damage may occur.
As noted by the OS/390 attributes of the RSASxxxx address space, it is exempt

from standard OS/390 CANCEL or FORCE commands and RTM MEMTERM.
Certain system performance products are available that will attempt to
terminate an address space without regard to these exemptions. Attempts to
terminate a ROSAS address space will lead to abnormal termination of all
active Advantage CA-Roscoe systems and any system that has outstanding
XTPM sessions in other address spaces. In addition, due to the ownership of a
SYSTEM LX by ROSAS, abnormal termination of the entire OS/390 complex is
possible. Under no circumstances should site personnel attempt to remove a
ROSAS address space.

Index
Access Methods
Special Characters Defining to RCS (RCSGEN) 7-3, 7-4
? (Level Identifier) Format Code (HELP Residency Requirements 6-3
Facility) 16-9 Accounting
@ (Syntax) Format Code (HELP Facility) 16-6 Files
* (Comment) Format Code (HELP Facility) 16-11 Description 2-3, 2-4
#RPSENV CSECT (RPS) 8-7 Maintaining 2-6
Space Requirements 2-5, 2-6
Numerics Summary of Requirements 2-2
Overview 1-10, 1-11
3270-Type Devices
Reports 1-11
Defining
ACCTDUMP Program
Advantage CA-Roscoe to VTAM (APPL
As Part of Daily Maintenance 3-3
Macro) 9-2
With Accounting 2-6
Advantage CA-Roscoe to VTAM (LOCAL
ACCTREPT routine 26-2
Macro) 9-2
ACCTTREC= Initialization Parameter
Local BTAM Devices 7-2
Enabling Monitor Routine Accounting
Remote BTAM Devices 7-2
Records 18-4
RPS to VTAM 9-2
ACFEXIT Exit
VTAM Interpret Table 9-8
List of Distributed Exits 21-2
VTAM Session Parameters 9-3—9-6
Add
VTAM USS Definition Table 9-7
Profile to UPS
Devices Supported 5-4
Using UPSBLKnn 4-11—4-14
Error Recovery
Using UPSMNTnn 4-5—4-9
Local Devices 6-5
Address Space
Remote Devices 6-5
ROSAS A-4, A-6
Threshold Variables (RCSBTAMR Macro) 7-6,
Advantage CA-Earl
7-7
As Part of Weekly Maintenance 3-4
LOPEN (IECTLOPN) Module 6-5
Advantage CA-Roscoe
see RCS, Communication Services 9-2
Authorization Requirement 2-1
see RPS, Printing Services 9-2
Command Processor (ROSTMP) 14-4
SNA
Console Log, Controlling Advantage CA-Roscoe
Logons 9-9
Messages 3-5
Support 5-5
File Summary 2-2
JCL Changes
A Data Set Facility 12-2
A (Alias) Format Code (HELP Facility) 16-10 Overview Of 1-1—1-12
ACA= Operand (RPSDEST Macro) 8-18 Printing Services
See RPS
Index X-1
Advantage CA-Roscoe (continued) AUTH= Operand (VTAM APPL Macro) 9-2
ROSTMP 14-4 Authorization Requirement
Sample File Layouts 2-2 For Advantage CA-Roscoe 2-1
see HELP Facility 3-2 IDCAMS Commands 18-5—18-7
see Libraries, User 3-2 Autospeed (IGG019MP Modification) 6-7
see Maintenance 3-3 AWS
see RCS, Communications Services 3-2 Cache Facility 2-7
see TUTORIAL 3-2 Defining 2-9, 2-10
Shutting Down 3-2 Description Of 2-7
Sign-On Format (FAWSDS Program) 2-12
Message 3-6 Maintenance 2-12
RPF Program 3-7 Recovery
Starting 3-2 Using SAVEAWS Program 2-11
Stopping 3-2 Space Requirements
System Address Space, Use of A-4, A-6 Data Files 2-9, 2-10
Advantage CA-Roscoe DB2 13-1 Index Files 2-9, 2-10
AI Prefix Structure 2-7
Privileges 4-21 Summary of Requirements 2-2
ALIAS= Operand (RPSDEST Macro) 8-18 AWS Routine
ALLOCATE Subcommand Defaults (UTILITY Defining to Advantage CA-Roscoe
Routine) 26-9, 26-10 Alone 18-9
Allocating Files With Other Routines 18-4
Accounting Files 2-5, 2-6 Description of 18-9
AWS Files 2-9, 2-10 AWS= Operand (ROSPFUSE Macro) 19-3
User Libraries 2-14, 2-15 AWSCACHE= Initialization Parameter 2-8
ALTMTX= Operand (RCSDVICE Macro) 7-11 AWSCHAR= Operand (AMSDFLT Macro) 18-7
AMETHS= Operand (RCSGEN Macro) 7-4 AWSLIM= Initialization Parameter 2-11
AMS Routine AWSSPACE (RPF Program) 2-9, 2-10, 2-11
AMSAUTH CSECT 18-5
AMSDFLT Macro 18-6
Changing Defaults 18-6 B
Defining to Advantage CA-Roscoe Backup Procedures
Alone 18-5 Accounting Files 2-6
With Other Routines 18-4 As Required 3-4
Description of 18-5 AWS 2-12
Exit 21-4 Daily 3-3
Restricting Access To 18-5 User Libraries (General) 2-16—2-19
AMSAUTH CSECT (AMS Routine) 18-5 Weekly 3-4
AMSDFLT Macro (AMS Routine) 18-6 BBS
APF execution library 15-5 See BulletinBoard System 24-1
APPL Macro, VTAM BBSCTL Member 24-2
Advantage CA-Roscoe Requirements 9-2 BBSSERV Load Module 24-3
RPS Requirements 9-2 BDAM
Arithmetic symbols (syntax diagrams) xxiii Required I/O Device Modules 6-4
ATTACH JOB Command Residency Requirements 6-3
ROSGBL Requirements 11-2—11-7 BEXEXIT Exit
Space Requirements 11-9, 11-10 List of Distributed Exits 21-2
SYSOUT Requirements 11-9 BLKSI= Operand (DEFAULT Macro) 26-9
Attention (Key) Support 5-2 BM= Operand
AUTEXIT Exit JESPRNTR Macro 8-15
List of Distributed Exits 21-3 RPSPRNTR Macro 8-12
X-2 System Reference Guide

BREAK
Modification to ERP (BTAM) 6-13 C
BTAM C (List) Format Code (HELP Facility) 16-8
3270s CA Product Monitor Routines, List of 18-32
Error Recovery, Local Devices 6-5 Cache Facility
Error Recovery, Remote Devices 6-5 AWS 2-7
Defining Library, Description 2-14
Local Devices 7-2 Calculate Space
Remote Devices 7-2 Accounting Files 2-5, 2-6
Devices Supported 5-4 AWS 2-9, 2-10
Line Protocol Supported 5-5 User Libraries 2-14, 2-15
Required I/O Device Modules 6-4 CAT Routine
Residency Requirements 6-3 Defining to Advantage CA-Roscoe
TTYs Alone 26-3
ID Verification 6-10 With Other Routines 18-4
Modification for Autospeed 6-7 Description of 26-3
Modification to ERP to Use BREAK 6-13 CHAR= Operand
Modification to Suppress Time-Out 6-7 JESPRNTR Macro 8-15
Multispeed Considerations 6-8 RPSPRNTR Macro 8-12
Speed Table 6-8, 6-9, 6-10 CICS
Transmission Control 6-11, 6-12, 6-13 Defining to RCS (RCSGEN Macro) 7-3, 7-4
BTAMZAPS (on SOURCE) 6-13 Defining to RPS 8-5
BTSO CLISTs
activate RTB monitor 15-6 Executing 14-5
APF execution library 15-5 CLLEXIT Exit
application considerations 15-2 List of Distributed Exits 21-3
authorization table 15-2, 15-4 CMDEXIT Exit
Batch Time Sharing Option 15-1 List of Distributed Exits 21-3
calling RTBETSO 15-6 CMDEXIT2 Exit
copy supplied RPFs 15-5 List of Distributed Exits 21-3
CSA storage 15-3 CMDTAB= Operand (ROSGBL Macro) 11-4
define to CAIRIM 15-4 CMPRESS= Operand (RPSPRNTR Macro) 8-12
define to ETSO 15-4 COB Routine
Description Of 15-1 COBOL Syntax Checker 26-5
execute BTSOAPPL 15-5 Defining to Advantage CA-Roscoe
initiators 15-2 Alone 26-5
Installation 15-4 Description of 26-5
IRIXSPRM 15-5 CODE= Operand (RCSLINE Macro) 7-8
MAXUSERS= 15-2 Color Support 5-3
RPF interface 15-5 Comma
RTB monitor 15-6 repeat symbol, use in xxvi
user exit, RTBEXIT 15-7 COMTEN Support 6-5
USERMOD MR06026 15-5 CONSOLE Routine
BUFL= Operand (ZAPDEFLT Macro) 18-30 Defining to Advantage CA-Roscoe
BulletinBoard System Alone 11-12, 18-10
EPL Entry, Required 24-3 With Other Routines 18-4
Initialization Parameter, Required 24-2 Description of 11-12, 18-10
Overview 24-1 Exit 21-4
Prefixes 24-2 ROSGBL Requirements 11-2—11-7
CONTROL= Operand (ROSDATA Macro) 20-2
Index X-3
COPYLIM= Operand (RPSDEST Macro) 8-18
COUNT= Operand (RCSLINE Macro) 7-8 D
CPEJECT= Operand Daily Maintenance Procedures 3-3
JESPRNTR Macro 8-14 Data Files
RPSPRNTR Macro 8-11 Block Size (AWS) 2-9, 2-10
CREATE Subcommand Defaults (UTILITY Number of (AWS) 2-9, 2-10
Routine) 26-9, 26-10 Data Set Facility
Cross-Memory Services A-2 Enqueue Logic 12-6
CSA usage 15-3 Exit (See DSFEXIT) 21-3
CSECTs/Macros JCL Requirements 12-2
#RPSxx (ROSCOE Printing Services) 8-7 Security Considerations 12-3
AMSAUTH (AMS Authorization) 18-5 Space Requirements 12-4
AMSDFLT (AMS Defaults) 18-6 Data Stream
DEFAULT (UTILITY ALLOCATE/CREATE Compression (With RPS) 8-12
Defaults) 26-9 Support 5-3
ENAMES (Restricting Data Set Access) 18-16 DB2 Support
INAMES (Restricting Data Set Access) 18-18 Overview 13-1
JCLOPTS (Unicenter CA-JCLCheck Required EPL Entry 13-1, 13-2
Options) 18-22 Using DB2 Command Processor 13-2
JESPRNTR (System Printer Definition) 8-14, 8-15 DD Statements
Macros 9-2 ETSOLIB 14-9
RCSBTAMR (Number of Lines/Error ROSACTnn 2-2
Thresholds) 7-6, 7-7 ROSLIBnn 2-13—2-15
RCSCLSTR (Cluster Definition) 7-9 ROSTRACE 18-26
RCSDEF (ROSCOE Communications SYSAWSn 2-7
Services) 7-3 SYSAWSP 2-7
RCSDVICE (Devices on Cluster) 7-10 SYSUTnn 12-2
RCSGEN (Access Methods) 7-3, 7-4 DDO Routine
RCSGEND (End Definition) 7-13 Description of 18-32
RCSLINE (Line Definition) 7-8 DEF= Operand (RPSTERM Macro) 8-22
ROSDATA (ROSDATA Defaults) 20-2 DEFAULT Macro (UTILITY Routine) 26-9
ROSGBL (DISPLAY/Job Output Defaults) 11-2 Default values (syntax diagrams) xxvii
ROSPASS (UTILITY Passwords) 26-12 DEFCLAS= Operand (RPSDEST Macro) 8-17
ROSPCODE (Processor Code) 19-14 DELAY= Operand (RCSBTAMR Macro) 7-6
ROSPFUSE (PA/PF Key Assignments) 19-3 Deleting
ROSTABLE (UTILITY Subcommands) 26-11 Profiles
ROSTTY (Speed Table) 6-8, 6-9, 6-10 Using UPSBLKnn 4-14
ROSTTYID (ID Verification) 6-10 Using UPSMNTnn 4-7
ROSUTNDX (UTILITY Data Set Delimiters
Protection) 26-14 syntax diagrams, use in xxiv
RPSDEST (Printing Locations) 8-16—8-19 DESC= Operand (RPSDEST Macro) 8-17
RPSDLIST (Destination List) 8-20, 8-21 DEST= Operand (RPSTERM Macro) 8-22
RPSGEN (Global Parameters) 8-8 Devices Supported 5-4
RPSGEND (End of Definition) 8-23 DIREC= Operand (DEFAULT Macro) 26-9
RPSPRNTR (328x-Type Printer DISACCT= Operand (ROSGBL Macro) 11-4
Definition) 8-10—8-13 DISBUF= Operand (ROSGBL Macro) 11-4
RPSTERM (Terminals with DISEXIT Exit
Destinations) 8-21—8-23 List of Distributed Exits 21-4
RSSCEXPU (EXPORT Defaults) 18-13 DISP= Operand
UTINDEX (UTILITY Data Set Protection) 26-14 RPSGEN Macro 8-8
ZAPDEFLT (ZAP Processing ZAPDEFLT Macro 18-29
Options/Defaults) 18-28

DISPLAY Routine ENQTYPE= Initialization Parameter
Authorization Table 11-13 Description of Options 12-6
Defining to Advantage CA-Roscoe Enqueue Logic, Data Set 12-6
Alone 11-13, 18-11 EPL
With Other Routines 18-4 See Eligible Program List 24-3
Description of 11-13, 18-11 ERP Modifications for TTY BREAK 6-13
DISAUTHO Table 11-13 Error Recovery, 3270
Exit 21-4 Defining Thresholds 7-6, 7-7
ROSGBL Requirements 11-2—11-7 Local Devices 6-5
DISPRI= Operand (ROSGBL Macro) 11-4 Remote Devices 6-5
DLIST= Operand ETC Routine
RPSGEN Macro 8-8 Description of 18-32
RPSTERM Macro 8-22 Required RPS Features 8-10—8-13
DLOGMOD= Operand (RPSPRNTR Macro) 8-11 ETSO
DMS Routine Applications
Defining to Advantage CA-Roscoe Application Considerations 14-2
Alone 18-12 Controlling Resources 14-7, 14-8
With Other Routines 18-4 Controlling Use of 14-7, 14-8
Description of 18-12 Defining EPL 14-10
With Data Set Facility 12-4 Defining ETSOLIB 14-9
DSAEXIT Exit Site Specific Considerations 14-5, 14-6
List of Distributed Exits 21-2 Writing/Executing 14-13
DSC Support 5-3 Commands
DSFEXIT Exit Information About 14-13
List of Distributed Exits 21-3 Description Of 14-1
DSN= Operand (ROSPFUSE Macro) 19-4 Eligible Program List (EPL) 14-10
DSN3@ATH Installing 14-5
DB2 Requirement 13-1 ROSTMP 14-4
DSNCLIST= Initialization Parameter TSO Exec Processing 14-4
Catalog Space Needs 12-4 ETSO application 15-1
DSNINDEX= Initialization Parameter ETSOALLOC= Initialization Parameter 14-3
Line Queue Elements 12-4 ETSOPGMS= Initialization Parameter
DSNLPRD2= Initialization Parameter Defining EPL 14-10
Security Consideration 12-3 ETSSLICE= Initialization Parameter
DSNLPSWD= Initialization Parameter Defining Time Slice 14-7, 14-8
Security Consideration 12-3 ETSSRCH= Initialization Parameter
DSORG= Operand (DEFAULT Macro) 26-9 Defining Load Library Requirement 14-9
DUMMYC= Operand (ROSGBL Macro) 11-7 Exit Facilities
Dynamic Allocation Control (UTILITY Monitor 21-4
Routine) 26-15, 26-16 Online 21-2
Security 21-2
UPS 4-18
E WTO Exits 3-5
Eligible Program List (EPL) Explicit Partition Support 5-3
BBS Requirement 24-3 EXPORT Routine
DB2 Requirement 13-1, 13-2 Changing Defaults 18-13, 18-14
Description 14-10 Defining to Advantage CA-Roscoe
ROSTMP (Advantage CA-Roscoe Command Alone 18-13
Processor) Requirement 14-4 With Other Routines 18-4
ENAMES Macro (EXPORT Routine) 18-16 Description of 18-13
ENAMES Macro 18-16
Index X-5
EXPORT Routine (continued) HELP Facility (continued)
Exit 21-4 Command to Use 16-2
Restricting Data Set Access 18-16 Commenting Member 16-11
RSSCEXPU Macro 18-13, 18-14 Creating Members 16-5—16-9
Extended Customizing 16-13
Data Stream Support 5-3 Description Of 16-1
see ETSO, Time Sharing Option 5-3, 14-1 Display Breaks 16-7
Format Codes
? (Level Identifier) 16-9
F @ (Syntax) 16-6
F (Function) Format Code (HELP Facility) 16-5 ¢ (Highlight) 16-12
FAWSDS Program * (Comment) 16-11
As Part of Weekly Maintenance 3-4 A (Alias) 16-10
With AWS 2-12 C (List) 16-8
FEATUR1= Operand F (Function) 16-5
JESPRNTR Macro 8-14 S (Display Break) 16-7
RCSDVICE Macro 7-11 S (Syntax) 16-6
RPSPRNTR Macro 8-11 T (Title) 16-5
FILEDSP= Operand (ROSGBL Macro) 11-7 Function Segment 16-5
Files Highlighting Lines 16-12
Accounting Data Sets 2-3, 2-4 Installation 16-4
Active Work Space (AWSnn) 2-7 Levels Within Members 16-8
Authorization Requirement 2-1 List Within Members 16-8
Load Library (ROSLIB) 2-2 Maintaining Members 16-4
Sample Layouts 2-2 Predefined Member Names 16-2
Summary of Requirements 2-2 Scrolling Within Members 16-3
User Libraries (ROSLIBnn) 2-13—2-19 Syntax Segment 16-5
FILES= Operand (ROSGBL Macro) 11-6 Title Segment 16-5
FINDCNT= Operand (ROSGBL Macro) 11-6 Using 16-2
Formal Key, Assigning User HELP Prefix, Changing 16-4
Using UPSBLKnn 4-12 HELPPFX= Initialization Parameter
Using UPSMNTnn 4-9 Change Default Prefix 16-4
Functionally Stabilized Monitor Routines, Definition Highlighting Support 5-3
of 26-1 Holding
Jobs 11-9
G
GBLACC= Operand (GROUP) 4-24 I
Global Sign-on Program 3-7 IDCAMS
Global signoff 3-8 Command Authorization (AMS Routine) 18-5
GROUPS Member (UPS) 4-23—4-28 IDRFULL= Operand (ZAPDEFLT Macro) 18-30
GRPACC= Operand (GROUP) 4-24, 4-25, 4-26 IDRUPDT= Operand (ZAPDEFLT Macro) 18-30
IECTLOPN Module 6-5
H IEG0304A Module Modification 6-13
IGG019MA (BTAM Read/Write) 6-3
HELLO Message 3-6
IGG019MP Modifications
HELLO= Initialization Parameter 3-6
Autospeed 6-7
HELP Command 16-2
Multispeed Terminals 6-8
HELP Facility
Suppress Time-Out 6-7
Accessing Members 16-2
IGG019PC (I/O Module)
Alias for Level/Subcommand 16-10
With Multi-Remote Lines 7-9
Alias for Member 16-10

IMPORT Routine Internal Reader (JES) 17-2
Defining to Advantage CA-Roscoe INTFACE= Operand (RCSLINE Macro) 7-8
Alone 18-18—18-19 IODEVICE Requirements 6-2
With Other Routines 18-4 IOEROR= Operand (RCSBTAMR Macro) 7-6
Description of 18-18 IRIXSPRM 15-5
Exit 21-4 ISPF Enqueue Logic 12-6
INAMES Macro 18-18
Restricting Data Set Access 18-18
To Assemble/Link 18-19 J
IMS Support 8-5 JCK Routine
IN= Operand (AMSDFLT Macro) 18-7 Defining to Advantage CA-Roscoe
INAMES Macro (IMPORT Routine) 18-18 Alone 18-21, 18-22
INAMES Table Description of 18-21
Install 18-19 see JCL Syntax Checker 18-21
INDEX= Operand see Unicenter CA-JCLCheck 18-22
DEFAULT Macro 26-10 Unicenter CA-JCLCheck 18-21
UTINDEX Macro 26-14 JCL, Sample
Installation ROSCONS, Assemble/Link 20-4
3270 ROSDATA, Assemble/Link 20-4
BTAM Line Definitions (RCSDEF) 7-2 JCLOPTS Table 18-22
Error Recovery, Local Devices 6-5 JES= Operand (ROSGBL Macro) 11-3
Error Recovery, Remote Devices 6-5 JES2
Authorization Requirement 2-1 EXIT5 Requirements 11-15
BTAM Holding Output 11-9
Autospeed (TTY) 6-7 Initialization (EXIT5) 11-16
ID Verification (TTY) 6-10 Internal Reader 17-2
Multispeed Support (TTY) 6-8 Job Completion Notification 17-3
Resident Access Method Requirements 6-3 Requirements (4.1.0) 11-15
Speed Table (TTY) 6-8, 6-9, 6-10 Return processing (RO$EXIT5) 11-19
Suppress Time-Out (TTY) 6-7 JES3
Transmission Control (TTY) 6-11 Holding Output 11-9
Devices Supported 5-4 IATUX30 Modification 11-21
ETSO 14-12 Internal Reader 17-2
HELP Facility 16-4 Job Completion Notification 17-3
JES2/JES3 Internal Reader 17-2 JES3OPT= Operand (ROSGBL Macro) 11-3
Monitor Routines JESNAME= Operand (ROSGBL Macro) 11-3
General 18-3 JESPRNTR Macro (RPS) 8-14, 8-15
OS SYSGEN Requirements 6-2 JESSPL= Operand (ROSGBL Macro) 11-3
Protocol Support 5-5 Job Completion Notification 17-3
see Descriptions of Individual Routines, Monitor Job Output
Routines 18-3 Viewing
see RCS, Communication Services 7-2 Description 11-8
see RPS, Printing Services Space Requirements 11-9, 11-10
TRAINING, RPF 22-2 SYSOUT Requirements 11-9
TUTORIAL, Advantage CA-Roscoe 23-2 Job Submission 17-1
VTAM JOB= Operand (ROSPFUSE Macro) 19-4
Data Stream Support 5-3
Defining Advantage CA-Roscoe To 9-2
Defining to Advantage CA-Roscoe 7-2
K
KERMIT, Using 6-12
Interpret Table 9-8
Session Parameters 9-3—9-6
USS Definition Table 9-7
Index X-7
KEY= Operand (RPSGEN Macro) 8-8 Logmode Table, VTAM 9-3—9-6
Keywords (syntax diagrams) xxiii LOGNAME= Operand (ROSGBL Macro) 11-6
LOOK Routine
Description of 26-6
L LOOPRST= Initialization Parameter 24-2
LERB= Operand (RCSBTAMR Macro) 7-6 LOPEN (IECTLOPN) Module 6-5
LIB= Operand (ROSPFUSE Macro) 19-4
LIBBKUP Program
As Part of Daily Maintenance 3-3 M
With Advantage CA-Roscoe Libraries 2-17 MAIL Routine
LIBCACHE= Initialization Parameter 2-14 Description of 18-32
LIBEXIT Exit Maintenance
List of Distributed Exits 21-3 Accounting Files 2-6
Libraries, user As-Needed 3-4
Allocation Of 2-14, 2-15 AWS 2-12
Backup Warning 2-16, 2-17 Daily Procedures 3-3
Cache Facility General 3-1
Description 2-14 HELP Members 16-4
Current Lines in 4-9 Periodic 3-4
Description Of 2-13 Procedures 3-3, 3-4
Maintenance 2-16—2-19 Scheduling 3-2
Maximum Lines Allowed TRAINING, RPF 22-2
Set by UPSBLKnn 4-12 TUTORIAL, Advantage CA-Roscoe 23-2
Set by UPSMNTnn 4-9 User Libraries 2-16—2-19
Restore Warning 2-16, 2-17 User Profiles 4-5
Security Groups 4-23—4-28 Weekly Procedures 3-4
see Index File of Libraries 2-2 MAX= Operand (ROSDATA Macro) 20-3
see ROSLIBnn 2-13 MAXF= Operand (RPSGEND Macro) 8-24
Sharing 2-16 MAXFIND= Operand (ROSGBL Macro) 11-7
Space Requirements MAXSIZE= Operand (ROSDATA Macro) 20-3
Index File 2-14, 2-15 MAXUSERS= 15-2
Online Files 2-14, 2-15 MEMORY= Operand (ROSGBL Macro) 11-6
Summary of Requirements 2-2 MODEENT Macro, VTAM 9-3—9-6
Library Facility MODEL= Operand (RCSDVICE Macro) 7-11
Exit 21-3 MODETAB= Operand (VTAM APPL Macro) 9-3
Library Members Modify
Read/Write Protection 4-23, ebd IGG019MA 6-3
LIBSERVE Program IGG019MP
As Part of Weekly Maintenance 3-4 Autospeed 6-7
With Advantage CA-Roscoe Libraries 2-18, 2-19 Multispeed Terminals 6-8
LIBUTIL Program Suppress Time-Out 6-7
As Part of Daily Maintenance 3-3 MONITOR Routine
As Part of Weekly Maintenance 3-4 Defining to Advantage CA-Roscoe
With Advantage CA-Roscoe Libraries 2-17 Alone 18-23
Line Protocol Support 5-5 With Other Routines 18-4
LINES= Operand (ROSDATA Macro) 20-3 Description of 18-23
LIST= Operand (ROSDATA Macro) 20-3 Monitor Routines
Load Modules Accounting Information 18-4
BBSSERV 24-3 Advantage CA-Roscoe JCL Changes 18-4
LOCAL Macro, VTAM 9-2 AMS Routine 18-5
AWS Routine 18-9

Monitor Routines (continued) NLINES= Operand (RCSBTAMR Macro) 7-6
CA Products 18-32 NOSEQ= Operand (ROSDATA Macro) 20-3
CAT Routine 26-3 NOSPEC Operand (ZAPDEFLT Macro) 18-31
COB Routine 26-5 NOTES= Operand (ROSGBL Macro) 11-6
CONSOLE Routine 11-12, 18-10 Notification Of Job Completion 17-3
DDO Routine 18-32 NOTIFY Initialization Parameter 17-3
Defining to Advantage CA-Roscoe NOVRD Operand (ZAPDEFLT Macro) 18-30
Alone 18-16 NTO
With Other Routines 18-4 Control Character Support 9-10
DISPLAY Routine 11-13, 18-11 Protocol Support 5-5
Distribution of 18-3 Number of Remote Lines, Defining 7-6, 7-7
DMS Routine 18-12
ETC Routine 18-32
Exit (MONEXIT) 21-4 O
EXPORT Routine 18-13—18-16 Operating System
Functionally Stabilized 26-1 Generation 6-2
IMPORT Routine 18-18—18-19 Operations
JCK Routine 18-21 General 3-1
List of 18-2, 18-3 Procedures 3-3, 3-4
LOOK Routine 26-6 Schedule 3-2
MAIL Routine 18-32 Operator 7-3
MONITOR Routine 18-23 Communications 7-3
Naming Conventions 18-3 Communications With Advantage
PLI Routine 26-7 CA-Roscoe 3-5
PURGE Routine 18-24 Communications With Users
ROS Routine 18-25 At Sign-on 3-6, 3-7
RTF Routine 18-26 During Execution 3-5
SORT Routine 18-27 Console Operator 6-2
UTILITY Routine 26-8—26-17 Scheduling Maintenance 3-2
VCAT Routine 26-18, 26-19 Starting Advantage CA-Roscoe 3-2
ZAP Routine 18-28—18-31 Stopping Advantage CA-Roscoe 3-2
Monitor writing VTAM Command Restrictions 3-5
Defining to Advantage CA-Roscoe OS Enqueue Logic 12-6
With Other Routines 18-4 OUT= Operand (AMSDFLT Macro) 18-7
MPP= Operand (RPSPRNTR Macro) 8-12 OUTEXIT Exit
MSG= Operand (RCSGEN Macro) 7-4 List of Distributed Exits 21-3
MSNF Considerations 8-5 OUTLIM= Operand (RSSCEXPU Macro) 18-14
Multi-System Networking Facility 8-5 Overview
Multispeed TTY-Compatible Terminals (IGG019MP AWS 2-7
Modification) 6-8 Library System 2-13
MVS Operating System
Cross-Memory Services A-2
System Address Space A-4, A-6
P
PAGES= Operand (ROSGBL Macro) 11-6
MVSSPL= Operand (ROSGBL Macro) 11-3
PAGLN= Operand
JESPRNTR Macro 8-15
N RPSPRNTR Macro 8-12
NAME= Operand (RSSCEXPU Macro) 18-14 PAGWD= Operand
Newsletter Facility JESPRNTR Macro 8-15
Creating/Maintaining 3-6 RPSPRNTR Macro 8-12
Index X-9
Parentheses Protocol Support 5-5
syntax diagrams, use in xxiv PRTCT= Operand (VTAM APPL Macro) 9-2
Partition Support 5-3 PRTDESC= Operand
Password JESPRNTR Macro 8-14
Assigning User RPSPRNTR Macro 8-10
Using UPSBLKnn 4-12 PSCBUNIT= Initialization Parameter
Using UPSMNTnn 4-9 Defining Default Unit 14-3
Table (UTILITY) 26-12, 26-13 PSERVIC Operand (VTAM MODENT Macro) 9-3
Universal (On ROSLIB00) 2-13 Punctuation marks (syntax diagrams) xxiii
PF/PA Keys PUNITL Table (UTILITY Routine) 26-15, 26-16
Assignment PURGE Routine
General (Defaults) 19-1 Defining to Advantage CA-Roscoe
Defining Alone 18-24
General (Defaults) 19-1 With Other Routines 18-4
Special Considerations, PA Keys 19-4 Description of 18-24
Using Fixed Values 19-5
Using Functions 19-9—19-12
Using ROSPFUSE Macro 19-3 Q
Using Variable Values 19-7 QSIZE= Operand (RPSGEN Macro) 8-8
see PA Keys 19-1
see Program Attention Keys 19-1
PF= Operand (ROSPFUSE Macro) 19-3
R
RACF
PLI Routine
Sign-on Key Considerations 4-8
Defining to Advantage CA-Roscoe
RBS Prefix 24-2
Alone 26-7
RBX Prefix 24-2
Description of 26-7
RCS
Prefix, Assigning User
Communications Services 7-3
Using UPSBLKnn 4-12
Defining
Using UPSMNTnn 4-9
Access Methods (RCSGEN Macro) 7-3, 7-4
PREFIX= Operand (RPSGEN Macro) 8-8
Clusters on Line (RCSCLSTR Macro) 7-9
PREKEY= Operand (ROSGBL Macro) 11-5
Device on Cluster (RCSDVICE Macro) 7-10
Presentation Size, VTAM 9-3—9-6
End of Definition (RCSGEND Macro) 7-13
PRIME= Operand (DEFAULT Macro) 26-10
Error Thresholds (RCSBTAMR Macro) 7-6,
PRIMTX= Operand (RCSDVICE Macro) 7-11
7-7
PRINTAL= Operand (ROSGBL Macro) 11-7
Number of Remote Lines (RCSBTAMR
Printing Locations (RPSDEST) 8-16
Macro) 7-6, 7-7
Privileged Commands
Remote Lines (RCSLINE Macro) 7-8
UPSBLKnn 4-13
Establishing Definition 7-3
UPSMNTnn 4-10
JCL To Assemble/Link Definition 7-14
Processor Codes, Defining (ROSPCODE
Overview 7-2
Macro) 19-14
Sample Definition 7-15
Profiles, User 4-2
RCSBTAMR Macro (RCS) 7-6, 7-7
Programs
RCSCLSTR Macro (RCS) 7-9
comma
RCSDEF CSECT 7-3
repeat symbol, use in xxvi
RCSDVICE Macro (RCS) 7-10
parentheses
RCSGEN Macro (RCS) 7-3, 7-4
syntax diagrams, use in xxiv
RCSGEND Macro (RCS) 7-13
punctuation
RCSLINE Macro (RCS) 7-8
syntax diagrams, use in xxiii
RCSRBTLH Table 6-5
Protection, Library Member 4-23—4-28

Read ROSDATA Program (continued)
Protection of Library Members 4-23—4-28 Overview 20-1
Readers, JES2/JES3 17-2 With Advantage CA-Roscoe Libraries 2-18, 2-19
RECFM= Operand (DEFAULT Macro) 26-10 ROSGBL Macro 11-2—11-7
REJ= Operand (RPSDEST Macro) 8-18 ROSGNAME= parameter
REPLACE= Operand (RSSCEXPU Macro) 18-14 VTAM Balancing the Workload 9-13
Requirements ROSID Initialization Parameter 17-3
Installation Authorization 2-2 ROSLOG= Initialization Parameter
Requirements, Installation Using To Control Console Messages 3-5
Device I/O Modules 6-4 ROSMAILS Program
Reserved As Part of Weekly Maintenance 3-4
Profile Names 4-22 With Advantage CA-Roscoe Libraries 2-18, 2-19
Resident Access Methods 6-3 ROSPASS Macro (UTILITY Routine) 26-12
Restore ROSPCODE Macro
User Libraries 2-17 Description 19-14
Restricted Users Sample 19-16
Controlling 4-15, 4-16, 4-17 Sample Macro 19-15
Establishing ROSPFUSE Macro
Via UPSBLKnn 4-13 Defining PA/PF Keys 19-3
Via UPSMNTnn 4-10 Fixed Values 19-5
RETPD= Operand (DEFAULT Macro) 26-10 Functions 19-9—19-12
REXX Execs Variable Values 19-7
Executing 14-5 Sample 19-16
RO Prefix Sample Macro 19-13
See also ? Special Considerations
Privileges 4-21 PA Keys 19-4
Reserved 4-22 ROSTABLE Macro (UTILITY Routine) 26-11
RO.#RPSENV Member 8-7 ROSTAT Program
RO.ETSOPGMS Member 14-12 As Part of Daily Maintenance 3-3
RO.HELLO Member 3-6 With Advantage CA-Roscoe Libraries 2-18, 2-19
RO.ROSDATA Member 20-1 ROSTMP 14-4
RO.ROSGBLnn Member 11-2 EPL requirements 14-4
RO$EXIT5 Processing 11-18 ROSTRACE DD Statement 18-26
ROS Routine ROSTTY Macro
Defining to Advantage CA-Roscoe Description 6-8
Alone 18-25 ROSTTY Table 6-8, 6-9, 6-10
With Other Routines 18-4 ROSTTYID CSECT 6-10
Description of 18-25 ROSTTYID Macro
ROSACTnn DD Statements 2-3 Description 6-10
ROSAPF Member on ROSCOE.SAMPJCL 2-1 JCL, Sample 6-11
ROSAS (Support Address Space) A-4, A-6 ROSUTNDX Macro (UTILITY Routine) 26-14
ROSCOE.KEYS 16-4 ROXMS Component
ROSCOE.ROSACTnn 2-3 Cross-Memory Services A-2
ROSCOE.ROSLIB RPF
Authorization 2-1 RPF interface 15-5
File Requirements 2-2 RPF Programs
ROSCONS CSECT 20-2, 20-3 Global Sign-on Program 3-7
ROSCOPY Program RPS
With Advantage CA-Roscoe Libraries 2-18, 2-19 Access Method Considerations
ROSDATA Program BTAM 8-6
Changing Defaults 20-2 MSNF 8-5
VTAM 8-5
Index X-11
RPS (continued) RUN Initialization Parameter with (continued)
Accounting Information, Gathering 8-3 LOOK Routine 26-6
Defining MAIL Routine 18-32
328x-Type Printer Attributes MONITOR Routine 18-23
(RPSPRNTR) 8-10 PLI Routine 26-7
Destination List (RPSDLIST) 8-20, 8-21 PURGE Routine 18-24
End of Definition (RPSGEND) 8-23 ROS Routine 18-25
Global Parameters (RPSGEN) 8-8 RTF Routine 18-26
Printing Locations (RPSDEST) 8-19 SORT Routine 18-27
System Printer Attributes (JESPRNTR) 8-14, UTILITY Routine 26-8—26-17
8-15 VCAT Routine 26-18, 26-19
Terminals with Destinations ZAP Routine 18-28—18-31
(RPSTERM) 8-21, 8-22, 8-23 RUSIZE Operand (VTAM MODENT
Establishing Definition 8-7 Macro) 9-3—9-6
JCL to Assemble/Link Definition 8-25
Overview Of 8-2, 8-3
Printing Services 8-2 S
Sample Definition 8-26—8-28 S (Display Break) Format Code (HELP
Sharing Definitions 8-7 Facility) 16-7
VTAM APPL Macro Requirements 9-2 S (Syntax) Format Code (HELP Facility) 16-6
RPSCSECT= Initialization Parameter 8-2 Sample Macro
RPSDEST Macro (RPS) 8-16—8-19 #RPSxxx, Assemble/Link 8-25
RPSDLIST Macro (RPS) 8-20, 8-21 INAMES, Assemble/Link 18-19
RPSGEN Macro (RPS) 8-8 JCLOPTS, Assemble/Link 18-22
RPSGEND Macro (RPS) 8-23 PUNITL, Assemble/Link 26-17
RPSKEY= Initialization Parameter 8-8 RCSDEF, Assemble/Link 7-14
RPSPREFIX= Initialization Parameter 8-8 ROSGBL 11-2—11-7
RPSPRNTR Macro (RPS) 8-10 ROSPASS, Assemble/Link 26-17
RPSTERM Macro (RPS) 8-21, 8-22, 8-23 ROSPCODE, Assemble/Link 19-16
RSSCEXPU (EXPORT) Macro 18-13 ROSPFUSE, Assemble/Link 19-16
RSSCEXPU Macro (EXPORT Routine) 18-14 ROSTABLE, Assemble/Link 26-17
RTBEXIT ROSTTYID, Assemble/Link 6-11
BTSO user exit 15-7 ROSUTNDX, Assemble/Link 26-17
RTF Routine RPSDEF, Assemble/Link 8-25
Defining to Advantage CA-Roscoe ZAPDEFLT, Assemble/Link 18-31
Alone 18-26 SAVEAWS Program
With Other Routines 18-4 As Part of Daily Maintenance 3-3
Description of 18-26 With AWS 2-11
RUN Initialization Parameter with SCREEN Command
AMS Routine 18-5 Requirements for Use of 5-3
AWS Routine 18-9 SCREXIT Exit 5-3
CAT Routine 26-3 SCS Data Stream
COB Routine 26-5 Compression (With RPS) 8-12
CONSOLE Routine 11-12, 18-10 Support 5-3
DDO Routine 18-32 SECOND= Operand (DEFAULT Macro) 26-10
DISPLAY Routine 11-13, 18-11 Security Groups
DMS Routine 18-12 Assigning Users To
ETC Routine 18-32 Via UPSBLKnn 4-12
EXPORT Routine 18-13—18-16 Via UPSMNTnn 4-10
IMPORT Routine 18-18—18-19 Description 4-23
JCK Routine 18-21, 18-22 Establishing
Default Access 4-24

Security Groups (continued) Space Requirements (continued)
Establishing (continued) see Memory Requirements 2-5
Group Definitions 4-24 User Libraries
Example Of 4-27 ROSLIBnn 2-14, 2-15
UPSVER Command 4-27 SPACE= Operand (DEFAULT Macro) 26-10
SEND= Initialization Parameter 3-6 Speed Table For TTY-Compatible Terminals 6-8,
SEQ= Operand (ROSDATA Macro) 20-3 6-9, 6-10
SEQ1= Operand (ROSDATA Macro) 20-3 SPOOLIM= Operand (RPSGEN Macro) 8-8
Sharing SSI= Operand (ZAPDEFLT Macro) 18-29
Advantage CA-Roscoe Libraries Start/Stop Devices Under VTAM 9-8
General 2-16 Starting
With UPS 4-5 Advantage CA-Roscoe 3-2
RPS Definitions 8-7 VTAM Start/Stop Processing 9-11, 9-12
Shutdown Process 3-2 Startup Time, Advantage CA-Roscoe 3-2
SIGEXIT Exit Stopping
List of Distributed Exits 21-3 Advantage CA-Roscoe 3-2
Sign-On VTAM Start/Stop Processing 9-11, 9-12
Execution Hierarchy 3-7 SUBEXIT Exit
Formal Keys, Assign List of Distributed Exits 21-3
Using UPSBLKnn 4-12 SUMMSG= Operand (RSSCEXPU Macro) 18-14
Using UPSMNTnn 4-9 Support
Informal Keys, Assign Attention (Key) 5-2
Using UPSBLKnn 4-12 Data Stream 5-3
Using UPSMNTnn 4-8 Device 5-4
Keys, Reserved 4-22 Line Protocol 5-5
Messages Support Address Space (ROSAS) A-4, A-6
Types Of 3-6 Suppress Time-Out (IGG019MP Modification) 6-7
Password Syntax diagrams
Set by UPSBLKnn 4-12 reading (how to) xxiii—xxviii
Set by UPSMNTnn 4-9 SYSGEN Requirements 6-2
Procedure SYSTEM= Operand (ROSGBL Macro) 11-3
Global 3-7
User, Set by UPSBLKnn 4-12
User, Set by UPSMNTnn 4-9 T
Restricting Users 4-15, 4-16, 4-17 T (Title) Format Code (HELP Facility) 16-5
Signoff RPF Program 3-8 Terminals 6-8
SMFEXIT Exit Attention (Key) Support 5-2
List of Distributed Exits 21-3 Color Support 5-3
SNA Defining Devices to Advantage CA-Roscoe
Logons 9-9 Local BTAM 7-2
Protocol Support 5-5 Remote BTAM 7-2
SONMSG= Initialization Parameter 3-6 VTAM 9-2
SORT Routine Device Types Supported 5-4
Defining to Advantage CA-Roscoe Extended Data Stream Support 5-3
Alone 18-27 Highlighting Support 5-3
With Other Routines 18-4 Partition Support 5-3
Description of 18-27 TERMSO= Initialization Parameter 2-11
Space Requirements TEXT= Operand
Accounting Files 2-5, 2-6 ROSPCODE Macro 19-14
AWS 2-9, 2-10 ROSPFUSE Macro 19-3
Job Output 11-9, 11-10
Index X-13
TIMEOUT= Operand (RPSGEN Macro) 8-8 UPS
TM= Operand Adding Profiles
JESPRNTR Macro 8-15 Single, Through UPSMNTnn 4-5—4-9
RPSPRNTR Macro 8-12 Changing Profiles
TMOUT= Operand (RCSBTAMR Macro) 7-6 Single, Through UPSMNTnn 4-5—4-9
TRAINING, RPF UPS (User Profile System) 4-12, 4-13
Customizing 22-8 Adding Profiles
Description Of 22-1 Multiple, Through UPSBLKnn 4-11
Executing 22-9 Using Default With UPSBLKnn 4-14
Installing 22-2 Using Default With UPSBLKnn 1 4-11
Maintaining 22-2 Changing Profiles 4-12
Member Naming Conventions 22-3 Multiple, Through UPSBLKnn 4-11—4-14
Members Added to Users Library' 22-5 Contents of Profiles 4-2, 4-3
Processing Techniques 22-7 Defining Library Member Access 4-23—4-28
Variables Used 22-5 Deleting Profiles
TRAMS= Operand (RCSLINE Macro) 7-8 Multiple, Through UPSBLKnn 4-11—4-14
Transmission Control, TTY 6-11—6-13 Single, Through UPSMNTnn 4-6
TSO Description 4-1
Exec Processing (Advantage CA-Roscoe) Distributed Profiles 4-19
Using ROSTMP 14-4 Exit 4-18
TTY (And Compatible) Terminals GBLACC= Operand (GROUP) 4-24
Autospeed Modification 6-7 GRPACC= Operand (GROUP) 4-24, 4-25, 4-26
Defining Maintenance Programs 4-5
To ROSCOE Communication Services Reserved Profile Names 4-22
(RCS) 7-3, 7-4 Restricting Users 4-15, 4-16, 4-17
Under VTAM-NTO 9-10 RO/AI Privileges 4-21
VTAM LOCAL Macro Requirements 9-2 Security Groups 4-23—4-28
ERP Modifications To Use BREAK 6-13 UPSBLKnn (RPF Program)
ID Verification 6-10 Description 4-11, 4-12, 4-13
Multispeed Terminals 6-8 UPS (User Profile System) 4-13
Speed Table 6-8—6-10 Overview 4-5
Time-Out Suppression 6-7 Sample 4-14
Transmission Control 6-11—6-13 UPSLIST Program
TTY and 3270 Devices As Part of Weekly Maintenance 3-4
TTY Command 6-8—6-10 UPSMEXIT Member 4-18
TUTORIAL, Advantage CA-Roscoe UPSMNTnn (RPF Program)
Customizing 23-5 Description 4-5—4-9
Description Of 23-1 Overview 4-5
Executing 23-6 USE= Operand (UTINDEX Macro) 26-14
Installing 23-2 User-Contributed Routines
Maintaining 23-2 Overview 25-1
Member Naming Conventions 23-3 USS Definition Table, VTAM 9-7
Processing Techniques 23-4 USSTAB Macro, VTAM 9-7
TYPE= Operand UTIEXIT Exit
RCSDVICE Macro 7-10 Dynamic Allocation Control 26-17
RPSDEST Macro 8-17 UTILITY Routine
Controlling Dynamic Allocation 26-15, 26-16
DEFAULT Macro 26-9
U Defining to Advantage CA-Roscoe
Unit Values for UTILITY Routine 26-15, 26-16 Alone 26-8
Defining Units 26-15, 26-16

UTILITY Routine (continued) VTOC= Operand (ZAPDEFLT Macro) 18-29
Description of 26-8
JCL to Assemble/Link 26-17
Modifying W
Password Table 26-12 Writing
Subcommand Defaults 26-9 Protection of Library Members 4-23—4-28
Subcommand Table 26-11 WTO Exits 3-5
Protecting Data Sets 26-14
PUNITL Macro 26-15, 26-16
ROSPASS Macro 26-12
X
XALTER= Operand (GROUP) 4-26
ROSTABLE Macro 26-11
XDELETE= Operand (GROUP) 4-26
ROSUTNDX Macro 26-14
XEXEC= Operand (GROUP) 4-26
XNONE= Operand (GROUP) 4-26
V XREAD= Operand (GROUP) 4-26
Variables (syntax diagrams) xxiii XTPM
VCAT Routine Introduction 10-1
Defining to Advantage CA-Roscoe XUPDATE= Operand (GROUP) 4-26
Alone 26-18, 26-19
Description of 26-18, 26-19
VOLSER= Operand (DEFAULT Macro) 26-10
Z
ZAP Routine
VTAM
Changing
APPL Macro Requirements
Defaults 18-28
For Advantage CA-Roscoe 9-2
Processing Options 18-28
For RPS 9-2
Defining to Advantage CA-Roscoe
Attention (Key) Support 5-2
Alone 18-28—18-31
Balancing the Workload
With Other Routines 18-4
ROSGNAME= parameter 9-13
Description of 18-28
Data Stream Support 5-3
Exit 21-4
Defining
ZAPDEFLT Macro 18-28—18-31
Advantage CA-Roscoe To 9-2
ZAPDEFLT CSECT (ZAP Routine) 18-28
Interpret Table 9-8
Session Parameters 9-3—9-6
To Advantage CA-Roscoe 7-2
USS Definition Table 9-7
Devices Supported 5-4
Line Protocol Support 5-5
LOCAL Macro 9-2
Logmode Table 9-3—9-6
MODEENT Macro 9-3—9-6
Presentation Size 9-3—9-6
PSERVIC 9-3—9-6
RUSIZE 9-3—9-6
see RCS, Communications Services 7-3
See RPS Printing Services 9-3
see RPS, Printing Services 9-3
SNA Logons 9-9
Start/Stop Devices 9-8
Start/Stop Processing 9-11, 9-12
USSTAB Macro 9-7
Index X-15

ROSCOE - B001723e - System Reference Guide

Uploaded by

Copyright:

Available Formats

You might also like

ROSCOE - B001723e - System Reference Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ROSCOE - B001723e - System Reference Guide

Uploaded by

Copyright:

Available Formats

Advantage CA-Roscoe

System Reference Guide

The manufacturer of this Documentation is CA.

Copyright  2005 CA. All rights reserved.

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Chapter 1. Advantage CA-Roscoe Overview . . . . . . . . . . . . . . . . . 1-1

Chapter 2. File Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Chapter 3. Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Chapter 4. User Profile System (UPS) . . . . . . . . . . . . . . . . . . . . . 4-1

Chapter 5. General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

iv System Reference Guide

Chapter 7. ROSCOE Communication Services (RCS) . . . . . . . . . . . 7-1

Chapter 8. ROSCOE Printing Services (RPS) . . . . . . . . . . . . . . . . . 8-1

Chapter 9. VTAM Considerations . . . . . . . . . . . . . . . . . . . . . . . 9-1

Chapter 10. XTPM Support . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

Chapter 11. ATTACH JOB, CONSOLE and DISPLAY Requirements . 11-1

vi System Reference Guide

Chapter 12. Data Set Facility Considerations . . . . . . . . . . . . . . . . 12-1

Chapter 13. DB2 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1

Chapter 14. ETSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

Chapter 16. HELP Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1

Chapter 17. Job Submission and Notification . . . . . . . . . . . . . . . 17-1

Chapter 18. Monitor Routines . . . . . . . . . . . . . . . . . . . . . . . . . 18-1

viii System Reference Guide

Chapter 19. PF/PA Key Assignment Definitions . . . . . . . . . . . . . . 19-1

Chapter 20. ROSDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1

Chapter 21. Security/Accounting Exit Facilities . . . . . . . . . . . . . . 21-1

Chapter 22. TRAINING (RPF) . . . . . . . . . . . . . . . . . . . . . . . . . 22-1

Chapter 23. TUTORIAL (Advantage CA-Roscoe) . . . . . . . . . . . . . 23-1

x System Reference Guide

Chapter 24. BulletinBoard System (BBS) Support . . . . . . . . . . . . . 24-1

Chapter 25. User-Contributed Routines . . . . . . . . . . . . . . . . . . . 25-1

| Chapter 26. Functionally Stabilized Routines . . . . . . . . . . . . . . . 26-1

Appendix A. Advantage CA-Roscoe System Extensions . . . . . . . . . A-1

xii System Reference Guide

About This Guide xiii

xiv System Reference Guide

About This Guide xv

Summary of Revisions for Service Pack 7

Summary of Revisions for Service Pack 6

Summary of Revisions for Service Pack 5

xvi System Reference Guide

Changed the definition for destname in 8.3.4, “RPSDEST: Define Destinations”

About This Guide xvii

xviii System Reference Guide

User Series Contents

About This Guide xix

xx System Reference Guide

The following manuals relate to Advantage CA-Roscoe and are on

About This Guide xxi

Licensing Management Program (LMP)

Advantage CA-Roscoe now interfaces with CAIRIM services to determine

xxii System Reference Guide

The following terminology, symbols, and concepts are used in syntax

Keywords: Appear in uppercase letters, for example, COMMAND or PARM.

Variables: Appear in italicized lowercase letters, for example, variable.

Required Keywords and Variables: Appear on a main line.

Optional Keywords and Variables: Appear below a main line.