ROSCOE - B001632e - Extended Facilities For System Programmers Guide

Advantage CA-Roscoe
 
Interactive Environment
Extended Facilities for

System Programmers 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Chapter 1. Advantage CA-Roscoe Data Areas . . . . . . . . . . . . . . . . 1-1

1.1 Roscoe Online Table (ROT) . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.2 Session Level Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.2.1 ATT1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.2.2 SCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.2.3 PCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Chapter 2. Monitor Routine Facilities . . . . . . . . . . . . . . . . . . . . . 2-1

2.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
2.1.1 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
2.1.2 Load Module Requirements . . . . . . . . . . . . . . . . . . . . . . . 2-2
2.1.3 Defining Monitor Routines to Advantage CA-Roscoe . . . . . . . 2-3
2.1.4 Passing Parameters to Monitor Routines . . . . . . . . . . . . . . . 2-4
2.2 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Chapter 3. Monitor Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.1 $CALL Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
3.2 $GBL and $GBLEND Macros . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.3 MONM Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3.4 $MONMSG Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
3.5 $PRM and $PRMEND Macros . . . . . . . . . . . . . . . . . . . . . . . 3-10
3.6 $PROC Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
3.7 $PROCEND Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
3.8 $RETURN Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
3.9 $ROSCOE Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
3.9.1 Description of $ROSCOE Functions . . . . . . . . . . . . . . . . . 3-18
3.9.1.1 FINAL Function . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19
3.9.1.2 GETAWS Function . . . . . . . . . . . . . . . . . . . . . . . . 3-19
3.9.1.3 GETAWSX Function . . . . . . . . . . . . . . . . . . . . . . . . 3-20
3.9.1.4 GETTERM Function . . . . . . . . . . . . . . . . . . . . . . . . 3-21
3.9.1.5 PAUSE Function . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
3.9.1.6 PUTAWS Function . . . . . . . . . . . . . . . . . . . . . . . . 3-23
3.9.1.7 PUTAWSX Function . . . . . . . . . . . . . . . . . . . . . . . . 3-23
3.9.1.8 PUTMSG Function . . . . . . . . . . . . . . . . . . . . . . . . . 3-24
3.9.1.9 PUTTERM Function . . . . . . . . . . . . . . . . . . . . . . . . 3-26
3.9.1.10 PVR Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27
3.9.1.11 REALWAIT Function . . . . . . . . . . . . . . . . . . . . . . 3-28
Contents iii
3.9.1.12 SESSION Function . . . . . . . . . . . . . . . . . . . . . . . . 3-29
3.9.1.13 SPIE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
3.9.1.14 TIMEOUT Function . . . . . . . . . . . . . . . . . . . . . . . 3-31
3.9.2 Exception Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
3.10 $WRK and $WRKEND Macros . . . . . . . . . . . . . . . . . . . . . . 3-34
Chapter 4. AWS Interface (AWSI) . . . . . . . . . . . . . . . . . . . . . . . 4-1

4.1 Using the AWSI Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
4.2 Coding the AWSI Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
4.3 Description of AWSI Functions . . . . . . . . . . . . . . . . . . . . . . . 4-6
4.3.1 ACTIVATE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
4.3.2 CKPTIO Function (Checkpoint I/O) . . . . . . . . . . . . . . . . . . 4-7
4.3.3 COPY Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8
4.3.4 DELETE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
4.3.5 FREE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
4.3.6 GET Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
4.3.7 INFO Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
4.3.8 INIT Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
4.3.9 MOVE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
4.3.10 POINT Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
4.3.11 PUT Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
4.3.12 RENUMBER Function . . . . . . . . . . . . . . . . . . . . . . . . 4-19
4.3.13 RESETI Function (Terminate Insert Mode) . . . . . . . . . . . . 4-19
4.3.14 SETI Function (Set Insert Mode) . . . . . . . . . . . . . . . . . . 4-20
4.3.15 STATUS Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
4.3.16 TERM Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
4.4 AWS Request Block (AWSRB) . . . . . . . . . . . . . . . . . . . . . . . 4-22
4.5 Exception Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
Chapter 5. User Library Interface (LIBI) . . . . . . . . . . . . . . . . . . . . 5-1

5.1 Using the LIBI Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
5.2 Coding the LIBI Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.3 Description of LIBI Functions . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.3.1 ACTIVATE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
5.3.2 ADD Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
5.3.3 ALTER Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
5.3.4 DEL Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.3.5 FIND Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.3.6 FREE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.3.7 GET Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.3.8 GETKEY Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
5.3.9 GETPFX Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
5.3.10 INFO Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
5.3.11 INIT Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
5.3.12 INITX Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
5.3.13 LIB Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
5.3.14 NOTE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
5.3.15 POINT Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
5.3.16 PUT Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
5.3.17 RENAME Function . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
5.3.18 SPACE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
iv Extended Facilities for System Programmers Guide

5.3.19 STATUS Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
5.3.20 TERM Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
5.4 Library Parameter Definition Macro (LBPMDEF) . . . . . . . . . . . . 5-18
5.5 Library Request Block (LBRB) . . . . . . . . . . . . . . . . . . . . . . . 5-19
5.6 Exception Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20
Chapter 6. Exit Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

6.1 Exit Types and Call Order . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
6.1.1 Exit Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
6.1.1.1 Accounting Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
6.1.1.2 Command and Command-Related Exits . . . . . . . . . . . . . 6-2
6.1.1.3 Security Exits and Considerations . . . . . . . . . . . . . . . . 6-3
6.1.1.4 Session-Oriented Exits . . . . . . . . . . . . . . . . . . . . . . . 6-5
6.1.2 Exit Call Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
6.1.2.1 Sign-on Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
6.1.2.2 General Command Processing . . . . . . . . . . . . . . . . . . . 6-6
6.1.2.3 Individual Command Processing . . . . . . . . . . . . . . . . . 6-7
6.1.2.4 Monitor Command Processing . . . . . . . . . . . . . . . . . . 6-8
Chapter 7. Information Common to all Exit Routines . . . . . . . . . . . 7-1

7.1 Common Coding Conventions . . . . . . . . . . . . . . . . . . . . . . . . 7-2
7.2 Common Register Conventions . . . . . . . . . . . . . . . . . . . . . . . 7-3
7.3 Common Data Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
7.3.1 Using the UXDSECT Macro . . . . . . . . . . . . . . . . . . . . . . . 7-4
7.3.2 UXDSECT Data Area Descriptions . . . . . . . . . . . . . . . . . . . 7-4
7.4 Common Reentrancy Macros . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
7.4.1 Using the UXENTER Macro . . . . . . . . . . . . . . . . . . . . . . . 7-8
7.4.2 Using the UXEXIT Macro . . . . . . . . . . . . . . . . . . . . . . . . 7-8
7.5 Testing a Site-written Exit Routine . . . . . . . . . . . . . . . . . . . . 7-10
7.5.1 Installing the SHOW Macro . . . . . . . . . . . . . . . . . . . . . . 7-10
7.6 To Assemble and Link-Edit Exit Routines . . . . . . . . . . . . . . . . 7-12
Chapter 8. Exit Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

8.1 ACCTDUMP Program Exit . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
8.2 ACFEXIT: Access Control Facility Exit . . . . . . . . . . . . . . . . . . . 8-3
8.3 AMSEXIT: AMS Routine Exit . . . . . . . . . . . . . . . . . . . . . . . . 8-9
8.4 AUTEXIT: Automatic Exit . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
8.5 BANEXIT: Banner Page Exit . . . . . . . . . . . . . . . . . . . . . . . . 8-15
8.6 BEXEXIT: Batch Access Authorization Exit . . . . . . . . . . . . . . . 8-18
8.6.1 Implementing BEXEXIT . . . . . . . . . . . . . . . . . . . . . . . . 8-20
8.7 CLLEXIT: ETSO Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
8.8 CMDEXIT and CMDEXIT2: Command Exits . . . . . . . . . . . . . . 8-25
8.9 CONEXIT: CONSOLE Routine Exit . . . . . . . . . . . . . . . . . . . . 8-29
8.10 DISEXIT: DISPLAY Routine Exit . . . . . . . . . . . . . . . . . . . . . 8-32
8.11 DSAEXIT: Data Set Access Exit . . . . . . . . . . . . . . . . . . . . . . 8-35
8.12 DSFEXIT: Data Set Facility Exit . . . . . . . . . . . . . . . . . . . . . . 8-41
8.13 EXPEXIT: EXPORT Routine Exit . . . . . . . . . . . . . . . . . . . . . 8-51
8.14 IMPEXIT: IMPORT Routine Exit . . . . . . . . . . . . . . . . . . . . . 8-57
8.15 JOBEXIT: PURGE Routine Exit . . . . . . . . . . . . . . . . . . . . . . 8-63
8.16 LIBEXIT: Library Facility Exit . . . . . . . . . . . . . . . . . . . . . . . 8-64
Contents v
8.17 MONEXIT: Monitor Invocation Exit . . . . . . . . . . . . . . . . . . . 8-70
8.18 OUTEXIT: Job Output Exit . . . . . . . . . . . . . . . . . . . . . . . . 8-73
8.19 RCSEXIT: Roscoe Communication Services . . . . . . . . . . . . . . 8-77
8.20 RDSEXIT: ROSCOE Communication Services . . . . . . . . . . . . . 8-79
8.21 ROSMAILS Program Exit . . . . . . . . . . . . . . . . . . . . . . . . . 8-81
8.22 ROS3@ATH: DB2 Authorization Exit . . . . . . . . . . . . . . . . . . 8-82
8.23 RPSEXIT: Roscoe Printing Services Exit . . . . . . . . . . . . . . . . . 8-88
8.24 RPVEXIT: PRINT Command Exit . . . . . . . . . . . . . . . . . . . . 8-95
8.25 RTFEXIT: RTF Routine Exit . . . . . . . . . . . . . . . . . . . . . . . . 8-101
8.26 SCREXIT: SCREEN Command Exit . . . . . . . . . . . . . . . . . . . 8-103
8.27 SETEXIT: SET Commands Exit . . . . . . . . . . . . . . . . . . . . . . 8-105
8.28 SIGEXIT: Sign-on Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-108
8.29 SMFEXIT: Accounting Exit . . . . . . . . . . . . . . . . . . . . . . . . 8-112
8.30 SUBEXIT: Submit Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-115
8.31 UPSMEXIT: The UPS Exit . . . . . . . . . . . . . . . . . . . . . . . . . 8-119
8.32 ZAPEXIT: ZAP Routine Exit . . . . . . . . . . . . . . . . . . . . . . . 8-122
| Chapter 9. Service Routines and Load Modules . . . . . . . . . . . . . . . 9-1

9.1 IAJTODAY Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
9.2 LIBSIEVE Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
9.3 ROSXINIT Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
9.4 ROSXTERM Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
9.5 UPSREAD Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Appendix A. Monitor Linkage Conventions . . . . . . . . . . . . . . . . A-1

A.1 Entrance Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
A.2 Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
A.3 Pause State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
A.4 Monitor SPIE/ESPIE Handling . . . . . . . . . . . . . . . . . . . . . . A-12
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1
vi Extended Facilities for System Programmers Guide

About This Guide
The Advantage CA-Roscoe Interactive Environment Extended Facilities for System

Programmers Guide describes how sites can make extensions to their Advantage
CA-Roscoe system. This includes creating site-written Monitor routines and
customizing security and other online exits.
About This Guide vii

Organization
CHAPTER DESCRIPTION
1 Describes Advantage CA-Roscoe data areas that are
available for site use.
2 Describes site-written Monitor routine requirements and
restrictions.
3 Describes the distributed macros that can be used to handle
Monitor routine linkage conventions, subtasking and
reentrancy, etc.
4 Describes the AWS Interface (AWSI) and how it can be used
by site-written Monitor routines.
5 Describes the Library Interface (LIBI) and how it can be
used by site-written Monitor routines.
6 Describes the types of exits and their call order.
7 Describes information and conventions that should be used
by all site-written exit routines.
8 Describes the individual exits, including when exit calls
occur, exit routine coding conventions, entrance parameters,
data areas and return codes.
9 Describes the load modules and service routines that can be
used in site-written Monitor routines, exit routines and/or
programs.
Appendix A Describes functionally stabilized Monitor routine linkage
conventions that are now handled by the distributed
Monitor macros.
Index Provides a quick way to locate specific information.
viii Extended Facilities for System Programmers Guide

Summary of Revisions for Service Pack 6
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.
About This Guide ix

Summary of Revisions for Service Pack 5
The CONVACCT that was used to convert accounting records from their
pre-Advantage CA-Roscoe Release 5.5 SESSION format to the SRECORD
format has been removed.
Editorial and minor technical changes have been made throughout this
manual.
x Extended Facilities for System Programmers Guide

Summary of Revisions
Advantage CA-Roscoe Data Areas

■ No known changes.
Monitor Routine Facilities

■ No known changes.
Exit Facilities
■ BEXEXIT: This exit can now be used to provide security for the Advantage
CA-Roscoe user library system through the LIBUTIL program.
■ UPSMEXIT: Two new indicators were included for two new user
privileges:
92 UPS Administrator privileges indicator.
93 Library Administrator privileges indicator.
Miscellaneous
■ Editorial and minor technical changes have been made throughout this
manual.
About This Guide xi

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
Advantage CA-Roscoe.
xii Extended Facilities for System Programmers Guide

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.
About This Guide xiii

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.
xiv Extended Facilities for System Programmers Guide

CA Common Services for z/OS
CA Common Services for z/OS 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.
About This Guide xv

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
xvi Extended Facilities for System Programmers Guide

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
About This Guide xvii

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
xviii Extended Facilities for System Programmers Guide

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─┘
About This Guide xix

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.
xx Extended Facilities for System Programmers Guide

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.
About This Guide xxi

xxii Extended Facilities for System Programmers Guide
Chapter 1. Advantage CA-Roscoe Data Areas
When you are writing online exit routines or Monitor routines you may need
information that is either global to the online system or local to a terminal
user, in addition to such information as is passed in parameter lists. The
following sections give a brief description of the Advantage CA-Roscoe data
areas from which such information may be obtained.
Except as noted in the descriptions, all of the data areas described in this
chapter are read-only to site-written code.
Caution
The Advantage CA-Roscoe staff retains the right to change or delete any or
all undocumented data areas.
Chapter 1. Advantage CA-Roscoe Data Areas 1-1

1.1 Roscoe Online Table (ROT)

The Roscoe Online Table (ROT) is the Advantage CA-Roscoe main task anchor
point. It contains run-time variables and points to other Advantage CA-Roscoe
data areas. It is constructed during Advantage CA-Roscoe initialization and its
address is stored in the first word of the first problem program save area
pointed to by the field TCBFSA in the Advantage CA-Roscoe main task TCB.
The initial portion of the ROT consists of two contiguous save areas.
Advantage CA-Roscoe never uses these areas, but they are retained for
compatibility with existing routines.
The address of the ROT is contained in:

■ Register 11 in most Advantage CA-Roscoe online modules.
■ Register 13 on entry to Monitor routines.
■ UXROTADR in UXDSECT on entry to exit routines.
The following fields may be used by site-written routines:

ECBLIST is the address of the list of active terminals (or ATT1s). Each
entry is a fullword containing the address of an ATT1. The last
entry has its high-order bit set and contains the address of the
console operator's pseudo-ATT1.
ECBLISTX is the address of a vector used by Advantage CA-Roscoe
during terminal allocation. The vector consists of a set of 1-byte
entries equal in number to TERMSO+2, with an unused byte as
the first entry and the final byte set to X'E7' to indicate
end-of-list.
If an entry (other than the first or last) is X'FF', it represents an
active terminal. If an entry is X'00', it represents an inactive
terminal. The offset of each entry from the list origin is the
logical line number of the terminal it represents.
LASTATT is the address of the currently active terminal (ATT1). (See 1-4
for an explanation of the ATT1.) This field contains meaningful
information only when interrogated at the main task level.
LASTECB is a fullword into which the contents of field ECB of the last
ATT1 dispatched are copied by the Advantage CA-Roscoe
dispatcher. The ECB in ATT1 is then zeroed.
Any Monitor routine requesting a real wait from Advantage
CA-Roscoe must check this field on completion of the wait
rather than the ECB in ATT1.
ROTn identifies a set of flag bytes (ROT1 through ROT9) that contain
such information as the current operation system, terminal
access method, user options, etc. A listing of the DSECT
contains a symbolic definition and explanation of each flag.
1-2 Extended Facilities for System Programmers Guide

ROTUSERn identifies six fullwords (named ROTUSER1 through

ROTUSER6) that are available for site purposes. They are
initialized to binary zeros and never modified by Advantage
CA-Roscoe.
TERMSO is a halfword binary field containing the number of concurrent
Advantage CA-Roscoe subsessions that can be active.
(Subsessions consist of the number of users signed on plus the
number of users who have split the screen.) There are TERMSO
sets of buffers that are connected to sessions at sign-on.
TERMTO is a halfword binary field containing the number of terminals
that are defined to Advantage CA-Roscoe. This includes all
remove and local BTAM devices plus the number of devices
specified by the VTAM= and XTPM= initialization parameters.
There are TERMTO+1 SCBs, where the extra one is for the
operator.
Notes
■ With the exception of the fields ROTUSER1 through ROTUSER6, the ROT
is read-only to site-written code.
■ The Advantage CA-Roscoe staff retains the right to change or delete any or
all undocumented fields in the ROT.

1.2 Session Level Control Blocks

The three session level control blocks for each connectable terminal are the
ATT1, SCB and PCB.
1.2.1 ATT1
The ATT1 (Active Terminal Table 1) is a DECB used for all event
synchronization for a user session. A chain field (CHAINTO2) connects the
ATT1 to its corresponding SCB.
On entry to a Monitor routine, register 7 points to the ATT1. Monitor routines

can use the ATT1 for event synchronization.
1.2.2 SCB
The SCB (Session Control Block) contains information global to a user session.
On entry to a Monitor routine, register 5 points the SCB.
On entry to an exit routine, the address of the SCB is in UXSCBADR of

UXDSECT.
The following fields may be used by site-written routines:

ACCNUM is a 22-byte field containing the user's sign-on key.
ACCSONT is a fullword, as received from TIME SVC, containing the
starting time of the user's current session.
CHAINTO1 is a fullword containing the address of the corresponding
ATT1. (See the preceding section.)
PREFIX is a three-byte field containing the user's prefix. (If the prefix
is two characters in length, it is followed by a blank.)
SCBACFB is a fullword containing the address of ACEE. The area
identified as ACEE is used to contain the address of control
block(s) established by an ACFEXIT exit routine and
referenced by a DSAEXIT exit routine.
SCBAMETH is a halfword defining the terminal access method. The
access methods, in decimal, are:
04 VTAM
08 BTAMR (remote BTAM)
12 BTAML (local BTAM)
16 XTPM (external TP method)
20 WTOM
24 BSIM
28 VTPM

SCBDEVT is a halfword defining the terminal type. The type, in

decimal, are:
1 3270
2 reserved
3 3767
4 TTY
SCBFKEY is a 22-byte field containing the user's formal key.
SCBGROUP is a field containing the name of the UPS group to which the
user is assigned, padded to eight characters.
SCBPCB is a vector of fullword pointers to PCBs. The last PCB is
indicated by a X'80' in the first byte of the pointer.
SCBPCBCU is a fullword containing the address of the current PCB.
SCBSENV is a fullword containing the address of the user's RACF
ACEE. (This field is valid only when the initialization
parameter EXTSEC=RACF is specified and when the site's
ACFEXIT routine places the address in this field.)
SCBTRMNM is the terminal ID, padded to eight characters.
With VTAM, the terminal ID is the VTAM identification.
With BTAM remote 3270-type terminals, the ID is the label
specified on the RCSDVICE macro in the RCSGEN. (If there
is no RCSDVICE label for a terminal, the ID will be a unique
name generated internally by the macro.)
With BTAM local 3270-type terminals and dial-up TTYs, the
ID is the DD name specified on the statement included in the
Advantage CA-Roscoe JCL.
With XTPM terminals, the ID is in the appropriate VTAM or
BTAM terminal ID.
SCBUAF is a 20-byte field that initially contains zeros. This field can
be used to include site-specific information in accounting
records. The information will be included in the accounting
reports when the SELECT (UAF) SYSIN control statement is
specified with the ACCTREPT program.
SCBUNVPW is a one-byte field that can be used to determine if the
terminal user signed on using the Advantage CA-Roscoe
universal password. The field initially contains 00 and is set
to 01 if the universal password is used.
SCBUSERn identifies four consecutive fullwords (named SCBUSER1
through SCBUSER4) that are cleared at sign-on and not
modified until sign-off.
TERMNUM is a one-byte binary value giving the user's logical line
number. This value is assigned at sign-on time and lost at
sign-off time.

TERMTYPE equates to SCBDEVT.

USERWDn identifies three fullwords (named USERWD0 through
USERWD2) that are reserved for use by Monitor routines.
(These words are employed for other purposes when no
Monitor routine is being executed.)
1.2.3 PCB
Each SCB has two PCBs. A PCB (Presentation Area Control Block) controls a
presentation area.
On entry to a Monitor routine, register 9 contains the address of the active

PCB.
On entry to an exit routine, UXPCBADR of UXDSECT contains the address of

the active PCB.
The following fields may be of interest:

PCBUSERn identifies two fullwords (named PCBUSER1 and PCBUSER2) that
are available for site purposes. At sign-on, the fullwords
associated with the active PCB are cleared to binary zeros. If the
user invokes split-screen processing, the second PCB becomes
active and its two fullwords are cleared to binary zeros.

Chapter 2. Monitor Routine Facilities
This segment of the manual describes the facilities provided to assist sites in
writing Monitor routines. These facilities include:
■ Information about Monitor routine requirements and restrictions.
■ Monitor macros, which can be used to handle such areas as linkage
conventions, subtasking and reentrancy plus reading from and writing to
the terminal, an AWS or library member.
■ The AWS Interface, which can be used to create, edit and/or delete data in
an AWS.
■ The User Library Interface, which can be used to find, create, delete,
rename and alter library members.
These facilities can be used by Monitor routines to:

■ Create a new AWS or library member.
■ Read from an AWS or a member in the user libraries.
■ Recover from interrupts with system code 0Cx.
■ Permit simultaneous multiple use.
■ Provide two-way communications with the terminal user.
■ Write accounting records.
Chapter 2. Monitor Routine Facilities 2-1

2.1 Requirements
2.1 Requirements
This section describes how site-written Monitor routines must:
■ Conform to specific naming conventions.
■ Exist in the Advantage CA-Roscoe load library.
■ Be defined in the Advantage CA-Roscoe JCL.
It also describes how parameters can be passed using a Monitor command to a

Monitor routine.
To clarify terms, a Monitor routine is an assembly language program that

permits terminal users to perform functions that are currently part of
Advantage CA-Roscoe. Examples of Monitor routines distributed with
Advantage CA-Roscoe include IMPORT, EXPORT and ZAP. The System
Reference Guide contains descriptions of the Advantage CA-Roscoe-written and
site-written Monitor routines that are distributed with Advantage CA-Roscoe.
A Monitor routine is invoked by a Monitor command. The Command Reference

Guide contains detailed information about all of the Monitor commands
distributed with Advantage CA-Roscoe.
2.1.1 Naming Conventions

The name of a Monitor routine must be at least three and no more than eight
alphabetic characters in length. The first three characters are the command
identifier and must be unique. For example, the IMPORT Monitor routine can
be invoked by issuing just the characters IMP.
2.1.2 Load Module Requirements

The first three characters of the Monitor routine name are also used to create a
unique module name in the Advantage CA-Roscoe load library. The name of
the load module must be in the form RSSCxxx0, where 'xxx' is the command
identifier. For example, the load module name of the IMPORT Monitor routine
is RSSCIMP0.
The load module must be reusable or reentrant.

2.1 Requirements
The following sample JCL can be used to assemble and link-edit a site-written
monitor routine.
// ASSEMBLE SITE-MONITOR ROUTINE

| //ASM EXEC PGM=ASMA9,REGION=496K,PARM='XREF(SHORT),OBJECT,DECK'
//SYSLIB DD DSN=CAI.RO6MAC,DISP=SHR
// DD DSN=SYS1.MACLIB,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=USER.SOURCE.LIB(RSSCXXX),DISP=SHR
// LINK SITE-WRITTEN MONITOR ROUTINE INTO CA-ROSCOE TARGET LIBRARY
//LINK EXEC PGM=IEWL,PARM='XREF,LIST,RENT'
//SYSLMOD DD DSN=CAI.RO6LIB,DISP=SHR
//SYSLIB DD DSN=&&OBJ,DISP=(OLD,DELETE)
//SYSIN DD
INCLUDE SYSLIB(RSSCXXX)
ENTRY RSSCXXX
NAME RSSCXXX(R)
/
Notes
| ■ You must use the IBM High Level Assembler as shown in the preceding
| sample.
■ The Advantage CA-Roscoe macro library (CAI.CRO60MAC) is always
concatenated as the first element with SYS1.MACLIB as ASM.SYSLIB. The
assembly should pass the temporary object module output into the link
step. The linkage-editor procedure uses the temporary object module
output as SYSLIB to resolve external references.
As described in the Advantage CA-Roscoe Installation and System Reference
guides, Advantage CA-Roscoe provides product usermods (MRO60xx
installation sample JCL members) for user modifications to some of the
distributed monitor routines.
2.1.3 Defining Monitor Routines to Advantage CA-Roscoe

Monitor routines are defined to Advantage CA-Roscoe by the initialization
parameter RUN= (as described in the Programs and Utilities Guide). Include
only the unique three characters of the Monitor routine name on the RUN=
parameter, as in RUN=IMP. During initialization, the routines so identified are
placed in a list of names that are searched during interpretation of command
input.

2.1 Requirements
2.1.4 Passing Parameters to Monitor Routines

When a terminal user enters a Monitor command, the first character of the
command is passed to the Monitor routine. If specified by the user, the fourth
character and the one-character appendage are also passed to the routine. For
example, if the user wants to execute the COBOL Syntax Checker and enters:
COBV-P
the COB Monitor routine is passed the characters C, V and P.
A string, not exceeding 200 characters in length, can also be passed to the
routine.
If the RUN command is used to initiate execution of the Monitor routine (for
example, RUN COB...), additional information may be passed to the Monitor
routine. RUN enables the Monitor routine to process both a character string
and a library member name (allowing input from a source other than the
terminal). See the Command Reference Guidefor a detailed description of the
RUN command.

2.2 Restrictions
2.2 Restrictions
The following rules are applicable to all site-written Monitor routines.
■ Currently, the Monitor facility only recognizes AMODE24.
■ A Monitor routine must be established as a subtask if it uses the AWSI
and/or LIBI Interfaces and/or performs any I/O to data sets. (The $PROC
macro can be used to establish subtasking.)
If the routine is not established as a subtask:
– All dispatching of other Advantage CA-Roscoe activity is suspended
until the return from the routine.
– The following partial list of system facilities may not be used if the
routine is not a subtask. If such facilities are requested, the results are
unpredictable and may cause a system crash or lock-out.
ABEND (unless for testing)
CHAP
CHKPT
CIRB
CPUTIMER
ESPIE
ESTAE
GETMAIN (unconditional form)
SPIE
SNAP (unless for testing)
STAE
STIMER
SYNCH
TTIMER
WTOR
XCTL
■ Monitor routines may not access Advantage CA-Roscoe library members
or terminals by any means other than those provided by the Advantage
CA-Roscoe Monitor facilities.
■ I/O should, if possible, be unbuffered. It is the responsibility of the user to
ensure that sufficient memory is available if buffered I/O is used. The use
of dynamic buffering should be avoided.

2.2 Restrictions
■ Monitor routines must be reusable and should be reentrant. (If a Monitor

routine is not reentrant, its use is serialized by Advantage CA-Roscoe. The
$PROC macro can be used to establish reentrancy.)
■ DD statements for files used by Monitor routines must be placed in the
Advantage CA-Roscoe JCL.
■ The system programmer is responsible for assuring that any site-written
routines do not inconvenience other Advantage CA-Roscoe users.
Before being included in the production Advantage CA-Roscoe system,
Monitor commands should be thoroughly tested using the batch
Advantage CA-Roscoe program. This program, which simulates a single
terminal Advantage CA-Roscoe system, is described in the Programs and
Utilities Guide.

Chapter 3. Monitor Macros
This chapter describes macros that are provided to assist sites writing their
own Monitor routines. The macros can be used to handle the linkage
conventions between Advantage CA-Roscoe and the Monitor routine or
between the Monitor routine and any subroutine. They also assist in such areas
as subtasking and establishing reentrancy. The macros are distributed on
CAI.CRO60MLD and include:
$PROC establishes the entry point interface for the Monitor routine
and, optionally, establishes the routine as a subtask of
Advantage CA-Roscoe. If subtasking is not established, all
dispatching of other Advantage CA-Roscoe activity is
suspended until the return from the Monitor routine. $PROC
must be the first macro used in the routine.
$ROSCOE handles the communications between the Monitor routine
and Advantage CA-Roscoe.
$WRK indicates the beginning of the routine's local work area.
$WRKEND indicates the end of the local work area.
MONM generates static messages that are to be written by the
Monitor routine to the terminal.
$MONMSG generates static and variable messages that are to be written
to the terminal.
$PROCEND indicates the physical end of the routine. This macro must be
the last instruction of the routine.
The following macros are useful in transferring control between routines:

$CALL handles passing control from one routine to another routine.
Control is passed to the label associated with the first $PROC
macro in the called routine.
$PRM indicates the beginning of the area in the called routine that
is to be used to hold parameters passed to the routine.
$PRMEND indicates the end of the parameter area.
$GBL indicates the beginning of the routine's global work area.
$GBLEND indicates the end of the global work area.
Chapter 3. Monitor Macros 3-1

$RETURN returns control from the called routine.

3.1 $CALL Macro
3.1 $CALL Macro

The $CALL macro issues a CALL to a routine and dynamically sets up the
parameter list.
$CALL Macro
──┬─────┬──$CALL──ROUTINE=─┬─(,label)─┬───────────────────────
└─tag─┘ └─(reg)─────┘
──┬──────────────────┬──┬──────────────┬───────────────────────
│ ┌─,──┐ │ └─,ERROR=label─┘
parm┴─)─┘
└─,PARM=(──
tag is any valid assembler label. It is ignored.

ROUTINE= is a pointer to the first $PROC macro in the routine to which
control is to be passed.
PARM=parm is a parameter that is to be passed to the called routine. A
maximum of seven parameters can be specified, as either:
(,label) or (reg)
If omitted, register 1 is cleared to zeros.
ERROR=label is a label of an instruction within the calling routine to which
control is to be transferred if an error occurs in the called
routine (register 15 is not equal to 0). If omitted, register 15 is
not checked.
Notes
■ The $CALL macro reserves registers 0, 1, 14 and 15.
■ Notation used in the macro description:
(,label) generates L Rx,label
(reg) generates LR Rx,reg
where the value of 'x' is generated by the macro.
■ Control is returned to the calling routine by the $RETURN macro.
■ If a code of 0 is returned by the called routine, execution begins with the
instruction immediately following the $CALL macro.
If a code other than 0 is returned, control transfers to the instruction
associated with the label identified by ERROR=.

3.1 $CALL Macro
Example: In the following example, the routine FIRST calls the routine
SECOND and passes two parameters to SECOND:
FIRST $PROC MODE=ROSCOE,ASYNC=YES...

...
LA R5,AFIELD
...
L R2,=V(SECOND)
...
ERROR1 EQU
...
AFIELD DS ...
...
SECOND $PROC MODE=ROSUB,WORK=WAREA,PARM=BPARM
...
$RETURN R15=...
...
$PRM
ROTADDR DS A
R5VALUE DS F
$PRMEND
$WRK
...
The routine FIRST loads the address of the data area AFIELD into register 5.
When SECOND is called, the address of the ROT is placed in the area
ROTADDR and the contents of register 5 is placed in the area R5VALUE.
When SECOND has completed its task, control returns to FIRST by the
$RETURN macro. If register 15 contains a value other than 0 on return to
FIRST, control is transferred to the area identified as ERROR01.

3.2 $GBL and $GBLEND Macros

The $GBL macro indicates the beginning of the routine's global work area.
The $GBLEND macro indicates the end of the work area.
$GBL Macro
──┬─────┬──$GBL───────────────────────────────────────────────
└─tag─┘
$GBLEND Macro
──&GBLEND─────────────────────────────────────────────────────
tag is the name to be used with the generated DSECT. If omitted, the
name specified with the GLOBAL= parameter of the $PROC
macro is used.
Notes
■ Data that is to be known and/or modified by multiple routines must be
defined between a $GBL and $GBLEND macro.
The area between $GBL and $GBLEND is cleared to binary zeros initially
and not modified during the execution of the Monitor routine. With the
$WRK and $WRKEND macros, the area is cleared to zeros every time the
routine is called. Therefore, the $GBL and $GBLEND macros should be
used to define a work area that is to be known to the routine in which it
appears and to all routines calling or called by the routine.
■ A DSECT is generated immediately following the $GBL macro.
Example: Assume that the routine GBLTEST contains the following code:
GBLTEST $PROC MODE=ROSUB,ASYNC=YES,GLOBAL=GAREA...

...
NAME1 DS F
NAME2 DS F
PROCEND
The code generated by the $GBL and $GBLEND macros would be like:
$GBL
+GAREA DSECT
NAME1 DS F
NAME2 DS F
$GBLEND
+ DS D
+GAREALN EQU -GAREA

Since no tag was specified on the $GBL macro, the generated code uses the
name specified with the GLOBAL= parameter of the $PROC macro.

3.3 MONM Macro
3.3 MONM Macro

The MONM macro can be used in generating messages to be written by
Monitor routines. The messages generated by MONM are static; that is, they
are not intended to be modified by the routine with variable information.
MONM and $GBLEND Macro

┌─,──────┐
┬──────┬┴────────────────────────────────
──tag──MONML──text───
└─text─┘
tag is the name by which the message will be referred to in the

routine.
text is the one to 255 character message to be generated. Any number
of lines of text can be generated. Each line must be enclosed in
apostrophes.
Notes
■ If the tag is specified with the MSGLIST= parameter of the $ROSCOE
macro, the $ROSCOE macro will generate the code necessary to write the
message to the terminal or the active AWS.
■ Use the $MONMSG macro to send a variable-text message.
Examples
1. The following example shows how static messages must be set up when
the label of the MONM macro is not referenced by a $ROSCOE macro.
LA R15,4 SET FUNCTION CODE

LA R1,MSG1 SET REGISTER
BAL R14,WRITERM WRITE HEADER LINE
...
MSG1 MONM 'NAME ADDRESS'
2. The following example shows how the same static message is written
when the label of a MONM macro is referenced by the $ROSCOE macro,
using the PUTTERM function.
GETKEY EQU
$ROSCOE FUNC=PUTTERM,MSGLIST=MSG1
...
MSG1 MONM 'NAME ADDRESS'

3.4 $MONMSG Macro
3.4 $MONMSG Macro

The $MONMSG macro can be used to generate a message that is to be written
to the terminal. The message can contain both static and variable text.
$MONMSG Macro
──tag──$MONMSG──'text',(V,'var-text.)...──┬─────────┬──────────
└─,TRAP=v─┘
──┬────────────────────┬───────────────────────────────────────
│ ┌─ERROR─┐ │
└─,LEVEL=─┴─INFO──┴──┘
tag is a one to six character label.

text is the static portion of the text that is to be written to the
terminal.
var-text is the variable portion of text that is to be written to the terminal.
Represent this text by including the appropriate number of
blanks, bound by apostrophes (for example, V' ').
TRAP=v is a value between 0 and 254 that is to be used as as a trap code.
If omitted or specified as TRAP=0, no trap code is set.
LEVEL= designates the type of message to be sent. If omitted, the default
is ERROR. Specify as:
ERROR message is to be written to the terminal regardless of
the SET MONLEVEL setting.
INFO message is to be written to the terminal only if SET
MONLEVEL INFO is in effect.
Notes
■ A maximum of four combinations of static and variable text may be
included in a single message.
■ Use the PUTMSG function of $ROSCOE macro to write the message to the
terminal.
■ All consecutive blanks in the text or variable text segment are compressed
out.

3.4 $MONMSG Macro
Example: In the following example, the value INIT is loaded into LIBFUNC.
If an error should occur when the LIBI function is attempted, control transfers
to LIBFAIL. The FUNCT=PUTMSG of the $ROSCOE macro is then used to
indicate the location of both the error message (AAA01) and the variable text
(LIBFUNC) that is to be included in that message.
LIBINIT MVC LIBFUNC,=CL8'INIT'

LIBI FUNC=INIT,...ERROR=LIBFAIL
...
LIBFAIL $ROSCOE FUNC=PUTMSG,MSGLIST=AAA1,SUB=LIBFUNC
...
LIBFUNC DS CL8
AAA1 $MONMSG 'AAA1 INTERNAL ERROR:#LIBI FUNC=', X
(V,' '),'- CONTACT SYSTEMS', X
TRAP=254,LEVEL=ERROR

3.5 $PRM and $PRMEND Macros
3.5 $PRM and $PRMEND Macros

The $PRM macro marks the beginning of the area that is to hold the address of
the parameters passed by a $CALL macro. The $PRMEND macro marks the
end of the area.
$PRM Macro
──$PRM────────────────────────────────────────────────────────
$PRMEND Macro
──$PRMEND─────────────────────────────────────────────────────
Example: In the following example, the addresses of ABC and DEF are
passed by the $CALL macro to ABCADDR and DEFADDR in the routine
identified as NEXT:
FIRST $PROC MODE=ROSCOE,ASYNC=YES...

...
$CALL ROUTINE=NEXT,PARM=(ABC,DEF),...
...
NEXT $PROC PARM=BPARM,...
...
$RETURN R15=...
...
$PRM
ABCADDR DS A
DEFADDR DS A
$PRMEND

3.6 $PROC Macro
3.6 $PROC Macro

The $PROC macro establishes the entry point interface for the routine. $PROC
can also be used to establish the routine as a subtask of Advantage CA-Roscoe.
$PROC Macro
──tag──$PROC──MODE=─┬─ROSCOE─┬───┬──────────────────┬──────────
└─ROSSUB─┘ │ ┌─NO──┐ │
└─,ASYNC=─┴─YES─┴──┘
──┬─────────────┬──┬─────────────┬──┬──────────────┬────────────
└─,WORK=label─┘ └─,PARM=label─┘ └─,GLOBALlabel─┘
──┬───────────────────┬──┬────────────┬─────────────────────────
│ ┌─-───┐ │ └─,ISA=bytes─┘
└─ERROR=─┴─label─┴──┘
──┬───────────────────┬────────────────────────────────────────
│ ┌─NOGEN─┐ │
└─PRINT=─┴─GEN───┴──┘
tag is a one to eight character name of the Monitor routine. On

the initial $PROC macro, the name must be in the form
RSSCxxx0, where xxx is site-defined. On any other $PROC
macro, the name may be any valid assembler tag.
MODE= designate the routine entry point as either:
ROSCOE initial entry point to Monitor routine.
ROSSUB entry point of any routine that is called by the
$CALL macro.
ASYNC= designate whether code to handle subtasking is to be
generated. If omitted, the default is NO. Specify either:
YES generate subtasking code
NO do not generate code
WORK=label is a one to six character name indicating the beginning of the
routine's local work area as defined by the $WRK macro.
PARM=label is a one to six character name indicating the beginning of an
area (designated by a $PRM macro) that is to hold the
address of a parameter list. This parameter may only be used
when the routine is to be called (MODE=ROSSUB is
specified).
GLOBAL=label is a one to six character name indicating the beginning of the
routine's global work area as defined by the $GBL macro.
ERROR=label is the label of an instruction that is to receive control if there
is insufficient memory to execute the routine. If omitted, an
*-* is the default, causing the routine to abend with an S0C1.

3.6 $PROC Macro
ISA=bytes is the size of the storage area needed by the routine, specified
in bytes. If omitted, the default is 4096 (4K).
PRINT= designate whether the code generated by the $PROC macro
is to be printed. If omitted, the default is NOGEN. Specify
either:
GEN print expanded code
NOGEN do not print expanded code
Notes
■ The $PROC and $PROCEND macros are required if the $ROSCOE macro
is used.
■ $PROC generates the linkage necessary to handle the communications
between the Advantage CA-Roscoe main task and the routine. If it is
used, it must be the first macro in the routine. (All of the code for the
routine follow the $PROC macro and precede the $PROCEND macro.)
■ $PROC reserves the following registers:
Register Use
12 Routine's base address register.
13 Base address register for DSECT generated for the local
work area.
11 Base address register for DSECT generated if GLOBAL= is
specified.
10 Base address register for DSECT generated if PARM= is
specified.
■ After execution of the $PROC macro containing MODE=ROSCOE, register

0 will contain the following:
Location Contents
Byte 1 X'00'
Byte 2 First character of the command identifier (for example, I
for IMPORT).
Byte 3 Fourth character of the routing name. It is not specified, a
binary zero is presented.
Byte 4 Optional appendage to the identifier (for example, B in
(ZAP-B). If there is no appendage, the byte i set to X'00'.
■ Also after the $PROC macro containing MODE=ROSCOE is executed,

register 1 will contain the address of the string, if a string was present in

3.6 $PROC Macro
the invoking command. The format is a 1-byte length followed by n

characters; n will not exceed 200.
Use of the X Attribute:
When a Monitor routine is defined in the Advantage CA-Roscoe JCL by
the RUN= initialization parameter, one of the Monitor routine attributes
that can be specified is X, as in RUN=IMP(X).* If the terminal user enters a
Monitor command and:
– The X attribute was specified when defining the routine to Advantage
CA-Roscoe, bytes 2 and 3 will contain uppercase characters. Byte 4 and
the string in register 1 will contain the data in the form entered by the
user.
– The X attribute was not specified, bytes 2, 3 and 4 and the string are
translated to uppercase.
Note: See the Advantage CA-Roscoe Interactive Environment Programs and
Utilities Guide for a description of the RUN= initialization
parameter.
■ ASYNC=YES is required if the Monitor routine uses the AWSI or LIBI
interface and performs any I/O to data sets.
If ASYNC=YES is specified, code is generated to establish the routine as a
subtask of Advantage CA-Roscoe. The generated code causes the subtask
to be attached and then returns to Advantage CA-Roscoe so that
Advantage CA-Roscoe and the subtask can execute concurrently. One
advantage of establishing the Monitor routine as a subtask is that if the
Monitor routine should abend, it will not bring Advantage CA-Roscoe
down with it.
■ If WORK= is specified, $PROC generates the name to be used in setting up
addressability to the DSECT. The name is then passed to the $WRK macro
so that $WRK can generate the actual DSECT statement.
■ By default, 4K of memory is allocated for the Monitor routine. The routine
containing the $PROC macro with MODE=ROSCOE uses the space for all
global data areas, its local work area and a 128-byte save area. Subsequent
routines use the remainder of the space for their local work and save areas.
If additional space is required, it is allocated in 4K blocks. (The space is
initially cleared to binary zeros.) If a routine requires more than 4K, the
ISA= parameter must be specified. If the space requirement for any routine
is greater than the ISA= value or 4K, the routine will abend.
■ If PRINT=GEN is specified, the generated code includes the:
– ROT DSECT
– SCB DSECT
– Save Area DSECT
– DSECT of the global area if MODE=ROSCOE is specified
– $$ROSCOE CSECT (called by the $ROSCOE macro to save status and
return to Advantage CA-Roscoe)

3.6 $PROC Macro
– $$ROSASY CSECT (called by the $ROSCOE macro when ASYNC=YES

is specified)
Example: This $PROC macro will generate a CSECT named RSSCALL0,

register equates and code to handle subtasking.
RSSCALL $PROC MODE=ROSCOE,ASYNC=YES,WORK=WAREA,PRINT=NOGEN

ST R,RSTORE SAVE COMMAND
CLI FOURTHCH,C'M' CHECK FOURTH CHAR. OF COMMAND
...
process
...
$WRK
RSTORE DS F
FOURTHCH EQU RSTORE+2
POPT EQU RSTORE+3
...
$WRKEND
$PROCEND
On entrance to the routine, register 0 contains the Monitor command entered

by the user. In the preceding example, the routine saves the contents of
register 0 in the local work area that is delimited by the $WRK and $WRKEND
macros. The $PROCEND macro indicates the end of the routine.

3.7 $PROCEND Macro
3.7 $PROCEND Macro

The $PROCEND macro designates the end of the routine. A $PROCEND
macro must be coded if a $PROC macro is specified.
$PROCEND Macro
┌─NOGEN─┐
──$PROCEND──PRINT=─┴─GEN───┴──────────────────────────────────
PRINT= designate whether the code generated by the $PROCEND macro

is to be printed. If omitted, the default is NOGEN. Specify either:
NOGEN do not print expanded code.
GEN print expanded code.
Notes
■ The $PROCEND macro must be specified if the $PROC macro is also
specified. It must be the last statement of the routine.

3.8 $RETURN Macro
3.8 $RETURN Macro

The $RETURN macro returns control to the calling routine.
$RETURN Macro
──┬─────┬──$RETURN──┬─────────────────────┬───────────────────
└─tag─┘ └─R15=─┬─label─────┬──┘
├─(,label)─┤
└─(reg)─────┘
tag is a one- to six-character label. It is ignored.

R15= is a label containing the return code that is to be passed back to
the calling routine. If omitted, the current value of register 15 is
returned.
Notes
■ $RETURN restores registers before passing control back from the called to
the calling routine.
■ The $RETURN macro reserves registers 0, 1, 14 and 15.
■ Notation used in macro description:
label generates LA Rx,label
(reg) generates LA Rx,reg
■ See the $CALL macro for an example of $RETURN.

3.9 $ROSCOE Macro
3.9 $ROSCOE Macro

The $ROSCOE macro can be used to pass information to and request
information from Advantage CA-Roscoe.
$ROSCOE Macro
──tag──$ROSCOE──┬─┬────────────────────────────────┬─┬────────
│ └─FUNC=function─┬─────────────┬──┘ │
│ └─,ATTN=label─┘ │
├─┬─────────┬────────────────────────┤
│ └─DROP=Rn─┘ │
└─┬────────┬──┬───────────────────┬──┘
└─USE=Rn─┘ └─,BLOCK=─┬─ROS──┬──┘
├─ATTI─┤
├─SCB──┤
└─PCB──┘
tag is any valid assembler tag. It is ignored.

FUNC=function is the $ROSCOE function to be performed. (The functions are
described in the next section.)
ATTN=label is the label of an instruction identifying an error-handling
routine. (Additional information is provided with each
function description in the next section.)
DROP=Rn is the number of the register that is no longer to be used as a
base register.
USE=Rn is the number of the register to be used to contain the
address of the specified Advantage CA-Roscoe control block.
It cannot be register 0, 1, 12, 13, 14 or 15.
BLOCK= is the control block whose address is to be placed in the
register identified by USE=.
Notes

3.9 $ROSCOE Macro
3.9.1 Description of $ROSCOE Functions

When a function is specified, $ROSCOE generates the code necessary to pass
information back to Advantage CA-Roscoe. The functions can be compared to
the meanings of the return codes that Monitor routines pass back to
After execution of a function, control returns to the code immediately

following the $ROSCOE macro or to the instruction identified by ATTN=
parameter if an error occurred (register 0 does not contain 0).
The following list introduces the $ROSCOE functions. The functions are
described alphabetically in the remainder of this section.
Function Purpose
GETTERM reads a line from the terminal.
PUTTERM writes a line to the terminal.
PUTMSG writes a message containing both static and variable text to
the terminal.
GETAWS gets the next 80-character line from the AWS or library
member.
PUTAWS writes an 80-character line to the active AWS.
GETAWSX reads the next line from the active AWS or library member.
PUTAWSX writes a line to the active AWS.
SPIE passes Advantage CA-Roscoe the address of a pseudo-SPIE
exit routine.
PAUSE causes a Pause State.
TIMEOUT causes a time-out.
REALWAIT causes the Monitor to return control to Advantage
CA-Roscoe which waits on the user's ATT1 ECB.
SESSION writes an accounting record.
PVR puts or gets data from the Advantage CA-Roscoe Program
Variable Pool.
FINAL designates the final return. The routine is terminated.

3.9 $ROSCOE Macro
3.9.1.1 FINAL Function
FINAL designates the final return. The routine is terminated.
FINAL Function
──tag──$ROSCOE──FUNC=FINAL──┬─────────────┬───────────────────
└─,ATTN=label─┘

ATTN=label is the label of an instruction to which control is to be
transferred if execution of the designated function is
unsuccessful (register 0 contains an exception code). See 3-32
for additional information.
Notes
■ On return, the value in the low-order two bytes of register 0 is taken as a
return code.
■ The return code is set to 998 if the Monitor routine is made unavailable
because of an 0Cx exception or an invalid parameter returned to
■ The return code may be accessed by RPF programs as the value of the
session variable S.RC. This variable is reset to 0 when a RUN command is
executed or a Monitor routine is invoked. (See the Advantage CA-Roscoe
Interactive Environment RPF Language Guide for additional information.)
■ After this function is executed, there are no further calls to the Monitor
routine.
3.9.1.2 GETAWS Function
GETAWS reads the next 80-character line from an active AWS or library
member.
GETAWS Function
──tag──$ROSCOE──FUNC=GETAWS──┬─────────────┬──────────────────


3.9 $ROSCOE Macro
Notes
■ On return:
– Register 0 will contain binary zero.
– Register 1 will contain either 0 (no data passed from Advantage
CA-Roscoe to the routine) or the address of the line of the active AWS
or library member being read.
■ Record format: 74 characters of data followed by the six-digit sequence
number (as a binary fullword).
■ A Monitor routine may direct Advantage CA-Roscoe to pass data from the
active AWS or a library member without overlaying the contents of
columns 75 through 80 with the sequence number by ORing X'40' into
SWITCH06 in the SCB. This switch setting is reset before initial entrance to
a Monitor routine, but is not reset by Advantage CA-Roscoe during
execution of the routine.
■ Use GETAWSX when sequentially reading lines that do not exceed 255
characters in length.
■ Use the AWSI or LIBI Interface when the access to the AWS or library
member is other than sequential.
3.9.1.3 GETAWSX Function
GETAWSX reads the next variable-length line from an active AWS or library
member.
GETAWSX Function
──tag──$ROSCOE──FUNC=GETAWSX──┬─────────────┬─────────────────

Notes
■ On return:
– Register 1 will contain the address of the active AWS or library
member record being read.
■ Record format: An eight-byte header precedes the data. The header
consists of a length field (containing the length of the data plus eight

3.9 $ROSCOE Macro
bytes), the sequence number (as a binary fullword) and a halfword of

binary zeros. The format is:
1 3 7 9 263
┌────────┬──────────┬────┬─────────────┐
│ │ │ │ │
│ length │ seq. no. │ │ data (255) │
└────────┴──────────┴────┴─────────────┘
If the record contains no data, the length field will contain 8, the length of
the header.
■ Use GETAWS when sequentially reading 80-character lines.
3.9.1.4 GETTERM Function
GETTERM reads a line from the terminal.
GETTERM Function
──tag──$ROSCOE──FUNC=GETTERM──┬─────────────┬─────────────────

Notes
■ On return:
– Register 1 will contain the address of a 200-byte area containing the
reply from the terminal. (If the area contains all blanks, the terminal
user pressed the ENTER key with no reply.). The length of the reply
can be determined by scanning backward for a nonblank character. All
terminal control characters will have been deleted.

3.9 $ROSCOE Macro
3.9.1.5 PAUSE Function
PAUSE causes a PAUSE state.
PAUSE Function
──tag──$ROSCOE──FUNC=PAUSE──┬─────────────┬───────────────────

Notes
■ PAUSE can be used by CPU-bound Monitor routines executing at the main
task level.
■ When PAUSE is specified and control returns to Advantage CA-Roscoe,
the Monitor routine is reentered (dispatched) again only when all pending
work for the other terminals has come to a break point. (The purpose of
the pause state is to allow other users to dispatch in this fashion.) Pending
work is represented to Advantage CA-Roscoe by an ECB that is posted to
indicate completion of some request (for example, I/O). A break point
means that the user last dispatched has reentered a wait state (for example,
pending completion of an I/O request). If a Monitor routine returns in a
pause state when there is no pending work for any other user of the
system, the Monitor routine is immediately redispatched.
■ After some number of consecutive pause-state returns from the Monitor
routine, the terminal user is permitted to terminate execution of the
Monitor routine when the following message is issued:
PAUSE ... ENTER "STOP" TO TERMINATE
The value of the pause limit is preset to 120. It may be changed in two
ways:
– With the Advantage CA-Roscoe initialization parameter PAUSE, as
defined in the Programs and Utilities Guide.
– by the ROZAP command, as described in the Advantage CA-Roscoe
Interactive Environment System Commands Guide.
■ The $ROSCOE macro provides additional facilities for delaying the
reentrance to the Monitor routine. These facilities, TIMEOUT and
REALWAIT, are mutually exclusive (for a single return from the Monitor
routine) and are designed for different purposes. Each facility can be used
only when the Monitor returns in a pause state.

3.9 $ROSCOE Macro
3.9.1.6 PUTAWS Function
PUTAWS writes an 80-character line to the active AWS.
PUTAWS Function
──tag──$ROSCOE──FUNC=PUTAWS──,MSGLIST=label──┬─────────────┬──

MSGLIST= identifies the address of the line to be written to the active
AWS. It may be specified as either:
(R1) means that the Monitor routine must load the
address of an address list into register 1 before the
$ROSCOE macro is executed.
label is the label of a MONM macro or of an address
list. The $ROSCOE macro loads the address in
register 1.
Notes
■ Lines written to the AWS are assigned sequence numbers beginning with
one and incrementing by one. When a Monitor routine makes its first
request to write to the active AWS, the previous contents of that AWS are
lost.
■ Use PUTAWSX when sequentially writing lines that do not exceed 255
characters in length.
■ the AWSI or LIBI Interface when the access to the AWS or library member
is other than sequential.
3.9.1.7 PUTAWSX Function
PUTAWSX writes a variable-length line to the active AWS.
PUTAWSX Function
──tag──$ROSCOE──FUNC=PUTAWSX──,MSGLIST=label───────────────────
──┬─────────────┬──────────────────────────────────────────────

3.9 $ROSCOE Macro

address of an address list into register 1 before the
label is the label of a MONM macro or of an address
list. The $ROSCOE macro loads the address in
register 1.
Notes
■ The first byte of the MSGLIST= address list must contain a X'80' and the
address must point to the record to be written. The format of the record is:
1 3 7 9 263
┌────────┬──────────┬────┬─────────────┐
│ │ │ │ │
└────────┴──────────┴────┴─────────────┘
Lines written to the AWS are assigned sequence numbers beginning with
one and incrementing by one. When a Monitor routine makes its first
request to write to the active AWS, the previous contents of that AWS are
lost.
■ Use PUTAWS when sequentially writing 80-character lines.
3.9.1.8 PUTMSG Function
PUTMSG writes a variable-length line to the terminal.
PUTMSG Function
──tag──$ROSCOE──FUNC=PUTMSG──,MSGLIST=label────────────────────
──┬─────────────────┬──┬──────────────────┬─────────────────────
│ ┌─,──┐ │ │ ┌─NO──┐ │
addr┴─)─┘ └─,ALARM=─┴─YES─┴──┘
└─,SUB=(──
──┬─────────────────┬──┬─────────────┬─────────────────────────
│ ┌─NO──┐ │ └─,ATTN=label─┘
└─,MASK=─┴─YES─┴──┘

3.9 $ROSCOE Macro
MSGLIST= identifies the address of the line to be written to the terminal.

It may be specified as either:
address of a $MONMSG macro into register 1
before the $ROSCOE macro is executed.
label is the label of a $MONMSG macro. The associated
address is automatically placed in register 1. No
line of data to be sent to the terminal may exceed
255 characters in length, not may it contain any
control characters or other characters that cannot
be printed or displayed on a terminal.
SUB=addr contains a list of one to four addresses. The addresses point
to segments of variable text that are to be inserted into the
generated by a $MONMSG macro. (A null segment can be
indicated by including a 0 or comma, as in:
SUB=(,SEG2,,SEG4)
where the first and third segments are null.)
ALARM= controls sounding the alarm at 3270-type terminals. If
omitted, the default is NO. Specify either:
NO alarm is not to be sounded when the message is
written to the terminal.
YES alarm is to be sounded.
MASK= designates whether the terminal user's response is to be
displayed at 3270-type terminals. If omitted, the default is
NO. Specify either:
NO terminal user's response is to be displayed.
YES terminal user's response is to be masked (not
displayed).
Notes
■ Messages written by the PUTMSG function observe the terminal user's use
of the SET MONLEVEL and SET MONTRAP commands (or the site
default values for these commands).

3.9 $ROSCOE Macro
3.9.1.9 PUTTERM Function
PUTTERM writes a line to the terminal.
PUTTERM Function
──tag──$ROSCOE──FUNC=PUTTERM──,MSGLIST=label───────────────────
──┬──────────────────┬──┬─────────────────┬──┬─────────────┬───
│ ┌─NO──┐ │ │ ┌─NO──┐ │ └─,ATTN=label─┘
└─,ALARM=─┴─YES─┴──┘ └─,MASK=─┴─YES─┴──┘

address of a MONM macro into register 1 before the
label is the label of a MONM macro. The associated
address is automatically placed in register 1. No line
of data to be sent to the terminal may exceed 255
characters in length, not may it contain any control
characters or other characters that cannot be printed
or displayed on a terminal.
ALARM= controls sounding the alarm at 3270-type terminals. If omitted,
the default is NO. Specify either:
NO alarm is not to be sounded when the message is
written to the terminal.
YES alarm is to be sounded.
MASK= designates whether the terminal user's response is to be
displayed at 3270-type terminals. If omitted, the default is NO.
Specify either:
NO terminal user's response is to be displayed.
YES terminal user's response is to be masked (not
displayed).

3.9 $ROSCOE Macro
3.9.1.10 PVR Function
PVR puts data into or gets data from the Advantage CA-Roscoe Program
Variable Pool.
PVR Function
──tag──$ROSCOE──FUNC=PVR──,PARM=label──┬─────────────┬────────

PARM=label identifies the address of an address list.
Notes
■ Any valid RPF variable may be specified with this function, as in:
... DC C'L1' Local variable
... DC C'S.SEQ' Session variable
... DC C'D.DSN' Data Set variable
... DC C'P.name' Panel variable
... DC C'NAME<5>' User-defined index variable.
Note that when referencing panel variables, the panel must be active.
■ Get Data:
To get data from the Advantage CA-Roscoe Program Variable Pool,
PARM= must contain the address of an address list, as in:
$ROSCOE FUNC=PVR,PARM=GET
MVC DATA1(26),1(R1)
The address list must contain the address of the request to get the data.
For example, the code to obtain the contents of local variable L1 might
look like:
GET DS F POINTS TO ACTION REQUESTED
VARNAME DS F POINTS TO VARIABLE
...
ACTION DC F'1' GET REQUESTED
VARIABLL DC AL1(L'VARA') VARIABLE LENGTH
VARA DC C'L1 VARIABLE NAME
On return, register 1 will contain the address of the data formatted as a
1-byte length field immediately followed by the data.
■ Put Data:
If data is to be placed into the Advantage CA-Roscoe Program Variable
Pool, PARM= must contain the address of an address list, as in:

3.9 $ROSCOE Macro
$ROSCOE FUNC=PVR,PARM=PUT
The address list must contain the address of the request to place the data,
the variable containing the data and the data itself. The following example
illustrates how data may be placed into a variable:
PUT DS F POINTS TO ACTION REQUESTED
VARNAME DS F POINTS TO VARIABLE
DATAADR DS F POINTS TO DATA DATA
...
ACTION DC F'2' PUT REQUESTED
VARIABLL DC AL1(L'VARB') VARIABLE LENGTH
VARB DC C'P.COMMENT' VARIABLE NAME
DATA DC AL1(L'DATA1') DATA LENGTH
DATA1 DC C'DATA TO BE PUT IN VARIABLE'
3.9.1.11 REALWAIT Function
REALWAIT causes the Monitor routine to return to Advantage CA-Roscoe

which adds the user's ATT1 ECB to Advantage CA-Roscoe's EVENTS queue.
REALWAIT Function
──tag──$ROSCOE──FUNC=REALWAIT──┬─────────────┬────────────────

Notes
■ If ASYNC=YES is coded in the $PROC macro associated with this
$ROSCOE macro, the REALWAIT function cannot be used. Instead, the
routine should use the OS WAIT macro.
If ASYNC=NO is coded in the $PROC macro, the REALWAIT function
should be used after issuing any I/O macros. With the REALWAIT
function, SWITCH02 in the SCB is ORed with X'02'. Advantage CA-Roscoe
does not return to dispatch the Monitor routine until the user's ATT1 ECB
is posted. This facility is also designed for subtask communications
between the Monitor routine and its subroutines. If the Monitor routine
attaches a subtask and then has nothing to do until completion of the
subtask (or of a request by the subtask for input, and so forth), it should
pass to the subtask the address of the field ECB in the ATT1. The subtask
should then post the ECB when appropriate. The Monitor routine is
meanwhile in a wait state which ends only when the ECB is posted. Once
the ECB is posted, Advantage CA-Roscoe: 1) copies the contents of field
ECB into field LASTECB in the ROT, 2) clears the ECB and 3) dispatches
the Monitor routine.

3.9 $ROSCOE Macro
■ If the Monitor routine does not ensure that the ECB is eventually posted,
the terminal will be locked out until Advantage CA-Roscoe is shut down.
For some subtasks, particularly those which perform no input or output
operations, the ECB may be specified as the operand of the ECB= keyword
of ATTACH. Normally, though, this ECB is needed to control ongoing
communication between the Monitor routine and the subtask; it is then
necessary to specify an exit routine address (using the ETXR=keyword of
ATTACH) and arrange for the specified exit routine to notify the Monitor
routine when the subtask has completed.
■ After a Monitor routine is entered with the must-stop condition (R0 =
X'FF000000'), it is permitted to request a real wait before making its final
return. This is to permit orderly disposal of subtasks and the like. It is the
responsibility of the Monitor routine to ensure against a processing loop in
this state.
3.9.1.12 SESSION Function
SESSION writes a record to the accounting files.
SESSION Function
──tag──$ROSCOE──FUNC=SESSION──,RECORD=(req)──┬─────────────┬──

RECORD=(reg) is the negative address of the area containing the record that
is to be written to the accounting file. The area must be
between a $WRK and $WRKEND macro and be
fullword-aligned.
The format of the record can be mapped by the Advantage
CA-Roscoe macro SRECORD, which generates the full record
format.
Note: If the address is positive, the record is assumed to be
in the format used prior to Advantage CA-Roscoe
Release 5.5.

3.9 $ROSCOE Macro
3.9.1.13 SPIE Function
SPIE designates the address of a pseudo-SPIE exit routine.
SPIE Function
──tag──$ROSCOE──FUNC=SPIE──,PARM=label──┬─────────────┬───────

PARM= is the address of the pseudo-SPIE exit routine, which may be
specified as either:
address of the SPIE routine into register 1 before the
label is the label of the pseudo-SPIE routine, The
associated address is automatically placed in register
1.
Notes
■ Advantage CA-Roscoe intercepts all program exception interrupts (except
significance) occurring under the first PRB of the Advantage CA-Roscoe
job-step task with its own SPIE/ESPIE exit routine. (Interruption occurring
in subtasks or under SVRBs are not intercepted.)
■ If ASYNC=YES is coded on the $PROC macro, the routine is a subtask.
FUNC=SPIE cannot be specified. The Monitor routine should, therefore,
provide its own SPIE or ESPIE exit routine. If a program exception
interrupt should occur and the Monitor routine does not have an exit
routine, only the subtask will abend.
If ASYNC=NO is coded on the $PROC macro, the routine is running at the
main-task level. FUNC=SPIE should be designated on the first call to
Advantage CA-Roscoe following the $PROC macro. (The SPIE function
and associated address are ignored if the S subparameter is not coded on
the Advantage CA-Roscoe RUN= initialization parameter for the Monitor.)
■ If the Monitor routine has its own pseudo-SPIE exit, Advantage CA-Roscoe
passes it control after having intercepted an interrupt. A pseudo-SPIE exit
routine is simply a SPIE exit routine written according to all conventions
defined by OS. The contents of the registers and linkage conventions are
precisely as though the pseudo-SPIE exit had received control directly
from the operating system. Advantage CA-Roscoe always invokes the exit
routine with a parameter list that is identical to that provided for a SPIE

3.9 $ROSCOE Macro
routine, regardless of whether Advantage CA-Roscoe is running in an MVS

or MVS/XA environment. It should be noted, however, that no PICA
address is provided when running under MVS/XA.
Note that Monitor routines running at the main-task level may not issue a
SPIE, ESPIE, STAE or ESTAE SVC at any time.
■ If a Monitor routine without a pseudo-SPIE exit is interrupted by a
program exception,
1. The Monitor routine is disabled for the remainder of the current
Advantage CA-Roscoe execution and the message:
CMD7 COMMAND TERMINATED DUE TO PROGRAM EXECUTION
is displayed. Subsequent attempts to use the same command fail with
the message:
CMD24 REQUESTED MONITOR COMMAND NO LONGER AVAILABLE
Note that the Monitor routine can be reactivated by the ROZAP
UNLOCK command.
2. The MONABXIT routine in invoked. MONABXIT writes: 1) a snap
dump to a SYSOUT file and 2) a diagnostic message to the console.
3.9.1.14 TIMEOUT Function
TIMEOUT causes the Monitor routine to be placed in a WAIT state for

approximately one-tenth of a second.
TIMEOUT Function
──tag──$ROSCOE──FUNC=TIMEOUT──┬─────────────┬─────────────────

Notes
■ Advantage CA-Roscoe will not dispatch the Monitor routine again until
one-tenth of a second has elapsed. The reentrance may be somewhat
delayed if there are many users with work pending on the dispatching list.
It may also occur earlier if a timer request is already pending for another
user.

3.9 $ROSCOE Macro
3.9.2 Exception Conditions

ATTN= parameter identifies the label of the first instruction in an
error-handling routine that is to receive control if an exception condition
occurs during the execution of a $ROSCOE function.
On entrance to that routine, register 0 will contain:
Location Contents
Byte 1 X'FF'
Byte 2 X'00'
Byte 3 X'00'
Byte 4 Code identifying the type of exception condition.
The exception condition will be represented as one of the following codes:

Code Meaning
X'00' Forced termination due to I/O error or sign off. The Monitor
routine must terminate. After a Monitor routine is entered with
this 'must-stop' condition (R0 = X'FF000000'), it is permitted to
request a real wait before taking the final exit. If such a real wait
is requested, the next entry to the routine will not occur until
after completion of the awaited event; this permits an orderly
disposal of subtasks and the like. It is the responsibility of the
Monitor routine to ensure against a processing loop in this state.
C'N' End-of-file on input from the AWS or a library member. This
condition does not require termination of the Monitor routine.
C'O' The AWS has overflowed on the last PUTAWS exit. The Monitor
routine need not terminate.
C'S' An ATTN was received from the terminal during I/O. Normally,
an ATTN causes the current routine to terminate and the stop
switch to be set to place an RPF program in pause mode.
However, the Monitor routine may ignore this condition and
continue processing. In this case, the pending stop condition is
purged. If, however, the Monitor routine returns immediately
after this with FUNC=FINAL, the stop condition is reinstated.
C'T' A message could not be sent to the terminal because of the
terminal user's use of the SET MONLEVEL and SET MONTRAP
commands. The message has been placed in the RPF session
variable S.LASTERR.
C'V' The variable request could not be completed due to an error. This
condition does not require termination of the Monitor routine.
Register 1 points to a message that can be used for debugging.

3.9 $ROSCOE Macro
Examples
1. This example shows how the PUTTERM function causes the address of
MSG1 to be loaded into register 1 and a return code of 4 to be placed in
register 15. The message is then written to the terminal. The GETAWS
function is then used to obtain the user's response and place it in register
1.
GETKEY $ROSCOE FUNC=PUTTERM,MSGLIST=MSG1

$ROSCOE FUNC=GETTERM
CLI (R1),C' '
BE GETKEY
...
MSG1 MONM 'ALL1: ENTER DESIRED ROSCOE KEY'
2. This example shows how the address of NEXTLINE is loaded into register
1, which allows R1 to be specified with the PUTAWS function. This causes
the function to use the address in register 1 and place the return code into
register 15.
LA R1,NEXTLINE
$ROSCOE FUNC=PUTAWS,MSGLIST=(R1)
...
NEXTLINE MONM ' ROSCOE '
3. This example shows how the address of a Advantage CA-Roscoe control

block can be made available to a Monitor routine.
GETROT EQU
$ROSCOE USE=R5,BLOCK=ROT
4. In this example, if an error should occur when the INIT function of LIBI is
attempted, control transfers to LIBFAIL. The PUTMSG function notes the
location of the error message (AAA01) and the variable text (LIBFUNC)
that is to be included in that message.
LIBINIT MVC LIBFUNC,=CL8'INIT'

LIBI FUNC=INIT,PARM=LBPMAROT,LBRB=LIBRB, X
ERROR=LIBFAIL
...
LIBFAIL $ROSCOE FUNC=PUTMSG,MSGLIST=AAA1,SUB=LIBFUNC, X
ALARM=YES,ATTN=ATTN
B FINAL
...
LIBFUNC DS CL8
AAA1 $MONMSG 'AAA1 INTERNAL ERROR: LIBI FUNC=', X
(V,' '),'- CONTACT SYSTEMS', X
TRAP=254,LEVEL=ERROR

3.10 $WRK and $WRKEND Macros
3.10 $WRK and $WRKEND Macros

The $WRK macro marks the beginning of the routine's local work area. The
$WRKEND macro marks the end of the work area.
$WRK Macro
──$WRK────────────────────────────────────────────────────────
$WRKEND Macro
──$WRKEND─────────────────────────────────────────────────────
Notes
■ A DSECT is generated immediately following the $WRK macro. Its name
is the name specified with the WORK= parameter of the $PROC macro. It
is a 128-byte area and contains the OS save area. Any data areas that may
be modified must be defined within this area.
■ Every time a $PROC macro is executed, the area between the $WRK and
$WRKEND macros is cleared to binary zeros.
■ Data areas that may be referenced or modified by multiple routines should
be defined between a $GBL and $GBLEND macro. These macros maintain
the data across calls.
Example
$PROC ... WORK=WAREA

...
NAME1 DS ...
NAME2 DS ...
$PROCEND
The code generated by these $WRK and $WRKEND macros would be:
...
$WRK
+WAREA DSECT
+ DS XL($$SVLN) SAVE AREA
NAME1 DS ...
NAME2 DS ...
$WRKEND
+ DS D
+WAREALN EQU -WAREA
...

Chapter 4. AWS Interface (AWSI)
AWS (Active Work Space) editing functions are supported by a subsystem

called AWSMGR. AWSMGR is resident during Advantage CA-Roscoe
execution. It provides facilities for creating, manipulating and deleting records
sequenced by a numeric key. The records can be a maximum of 255 bytes in
length. The sequence numbers have no inherent meaning and only serve to
order the data.
At sign-on time, AWSMGR creates an AWS for the terminal user. An AWS is
initially empty, and expands and contracts as records are added and deleted.
The maximum number of records in an AWS is established by site
management as described in the Advantage CA-Roscoe Interactive Environment
System Reference Guide. (The INFO function of AWSI can be used to obtain this
value.)
A subtask attached during the execution of a Monitor routine can make

requests on the AWSMGR through the AWSI Interface to access a user's AWS
for input and output, and also to allocate new AWSs for use by the subtask as
work files.
The AWSI Interface consists of:

■ The AWSI macro (distributed on CAI.CRO60MLD), and
■ An AWSI routine (distributed on CAI.CRO60MLD).
Individuals using the Interface need only concern themselves with the AWSI
macro.
Chapter 4. AWS Interface (AWSI) 4-1

4.1 Using the AWSI Interface

The AWSI macro calls the AWSI routine. Each call specifies an AWSI function
(for example, GET, PUT) that is to be performed by the AWSMGR. The
routine validates the AWSI macro before passing control to AWSMGR. (AWSI
obtains the address of the the AWSMGR from the ROT, along with the
addresses of the global control blocks needed by the AWSMGR.) The Interface
routine also uses WAIT and STIMER to synchronize with the AWSMGR.
Therefore, it must never be used at the Advantage CA-Roscoe main task level.
Record Format: The AWSI Interface accepts data in either of two formats.
Use the XRF= parameter of the AWSI macro to designate which format of the
data you want to work with.
When XRF=NO is specified, 80-byte EBCDIC records followed by a

hexadecimal sequence number are expected. The format is:
1 81 82 84
┌──────────────────┬───┬─────────┐
│ │ │ │
│ data (length 8) │ │ seq.no. │
└──────────────────┴───┴─────────┘
When XRF=YES is specified, records not exceeding 263 bytes in length are
expected. The length field includes the length of the data plus eight bytes. The
format is:
1 2 7 9 263
┌────────────┬──────────────┬────┬───────────────────┐
│ │ │ │ │
│ hex length │ hex seq. no. │ │ EBCDIC data (255) │
└────────────┴──────────────┴────┴───────────────────┘
Data Areas: The AWSI macro uses two data areas which must be defined in
the program or in dynamically obtained storage. The two areas are:
1. The AWSRB (AWS Request Block) is required for all functions. It is a
32-byte communication aligned on a fullword boundary. The area must be
obtained before the first call on AWSI and must remain intact until the
final call. A DSECT mapping the AWSRB is generated by the Advantage
CA-Roscoe macro AWSRB.
2. The AWSPB (AWS Parameter Block) is required by the Interface for many
function calls. It is a variable-length parameter list. The list is used in
conjunction with the AWSI macro to specify the function to be performed
by the AWSMGR. (The parameter list can be mapped by the AWSPB
DSECT generated by the Advantage CA-Roscoe macro AWSPB.)
All code generated by the Interface is reentrant. If reentrancy is to be observed

in the calling Monitor routine, data areas and parameter lists provided by the

calling program must be placed in dynamically obtained storage (such areas

are modified by the AWSMGR).
Working with Multiple AWSs: It is possible, using the AWSI Interface, to

work simultaneously with more than one AWS. This allows Monitor routines
to use the data in the terminal user's AWS as input to a function that then
produces a new AWS for the terminal user.
When the AWSI Interface is initially invoked, the contents of the field
AWSRNBPT in the AWSRB identifies the terminal user's AWS. If another
AWS is needed, the contents of this field must be saved before activating the
new AWS. This is because the result of activating a new AWS causes the prior
contents of AWSRNBPT to be overlaid with information identifying the new
AWS.
Points to Remember:
■ The AWSI Interface expects the field AWSRNBPT to identify the current
AWS. When working with multiple AWSs, be sure to save and restore the
contents of this field so that the appropriate AWS is always identified.
■ When the processing of an AWS is completed, use the FREE function of
AWSI to release it to the AWSMGR. Be very careful not to inadvertently
release:
1. The wrong AWS, or
2. An AWS controlled by the main task.
■ Working with multiple AWSs is limited by the number of AWSs defined
by the site.
Linkage Conventions
■ Standard OS linkage conventions must be observed when using AWSI.
Register 13 must point to an 18-fullword save area.
■ On return from AWSI, the contents of registers 2 through 13 are restored.
Register 15 contains a return code of:
0 No errors or exception condition.
4 Error or exception condition. The field AWSRXRC in the
AWSRB contains a one-byte extended return code permitting an
exact determination of the nature of the exception. It is the
responsibility of the caller to take appropriate action after an
exception occurs.

4.2 Coding the AWSI Macro

The syntax of the AWSI macro is:
AWSI Macro
──┬─────┬──AWSI──FUNC=─┬──────────┬───,AWSRB=─┬─label─────┬────
└─tag─┘ ├─ACTIVATE─┤ ├─(,label)─┤
├─CKPTIO───┤ └─(reg)─────┘
├─Copy─────┤
├─DELETE───┤
├─FREE─────┤
├─GET──────┤
├─INFO─────┤
├─INIT─────┤
├─MOVE─────┤
├─POINT────┤
├─PUT──────┤
├─RENUMBER─┤
├─RESETI───┤
├─SETI─────┤
├─STATUS───┤
└─TERM─────┘
──┬───────────────────────┬──┬────────────────────┬─────────────
└─,PARM=─┬─label─────┬──┘ └─,ERROR=─┬─+4───┬──┘
├─(,label)─┤ └─label─┘
└─(reg)─────┘
──┬────────────────┬───────────────────────────────────────────
└─,XRF=─┬─NO──┬──┘
└─YES─┘

FUNC=function
is the AWSMGR function to be performed by AWSI. (The
functions are described in the next section.)
AWSRB= is the address of the AWSRB. The AWSI macro loads this address
into register 1.
PARM= is the address of a function-dependent parameter list. The AWSI
macro loads this address into register 0. If omitted, a value of
zero is placed in register 0.
ERROR= is the label of an instruction to which control is to be transferred
on an exception condition. If omitted, the return from AWSI after
an error or exception condition (such as end-of-file on a GET) is
to the next instruction, and the calling routine must test register
15 for non-zero return codes.
XRF= designate whether the extended record format is to be used. If
omitted, the default is NO. Specify either:
NO 80-byte records are to be used

YES 255-byte records are to be used.

XRF= must be specified for the first call. The format remains set
until changed by the caller.
Notes
where the value of 'x' is generated by the macro. If (reg) is coded and is
equal to the register generated by AWSI, no instruction is generated.
■ The AWSI macro generates code to do the following:
– Load the address of the PARM into register 0.
– Load the address of the AWSRB into register 1.
– Move an entry code into the AWSRB.
– Load a pointer (from AWSRB to the AWSI) into register 15.
– Call the Interface (AWSI) using a BALR 14,15.
■ AWSI is dynamically loaded on the INIT call and freed on the TERM call.

4.3 Description of AWSI Functions

The following list introduces the AWSMGR functions that can be specified
using the AWSI macro. The functions are described alphabetically in the
remainder of this section.
Function Purpose
INIT establishes communication between the Interface and the
AWSMGR. It must be specified in the first call on AWSI.
ACTIVATE allocates an additional AWS for use by the caller (for example,
as a work file or staging file).
FREE releases an AWS previously allocated by ACTIVATE.
POINT defines the position within an AWS at which the next operation
will be performed.
GET retrieves a record from the AWS.
PUT places a record into the AWS.
DELETE purges lines from an AWS.
COPY repositions data within an AWS without deleting the data from
its original location.
MOVE repositions data within an AWS and deletes the data from its
original location.
SETI establishes an insert operation. Subsequent records PUT to the
AWS are inserted after a given record.
RESETI terminates an insert operation.
RENUMBER assigns new sequence numbers to an AWS.
INFO returns information describing the AWS.
STATUS returns information about the current status of an AWS.
CKPTIO causes the AWSMGR to write immediately all modified buffers
associated with an AWS.
TERM terminates use of the AWSMGR. It must be specified in the last
call on AWSI.

4.3.1 ACTIVATE Function

ACTIVATE allocates a new AWS and readies it for other operation.
Parameters
AWSPM set the first halfword of AWSPM to the terminal user's protect
code. (This can be obtained from the SCB field ACCNUMX.) Set
the next three bytes to the user's prefix (contained in the SCB
field PREFIX). The remaining three bytes are reserved and must
contain blanks.
Parameter Representation
AWSPM: PROTECT CODE PREFIX X'404040'
Notes
■ This information is used during SAVEAWS processing.
■ On a successful return from ACTIVATE, the contents of the field
AWSRNBPT in the AWSRB uniquely identifies the newly created AWS.
(Before executing this function, be sure to have saved the contents of
AWSRNBPT.)
Position in AWS
Not Applicable.
4.3.2 CKPTIO Function (Checkpoint I/O)

CKPTIO causes any and all modified buffers to be written out to disk.
Parameters
None
Notes
■ The purpose of this function is to guarantee the integrity of AWS data. If
CKPTIO is not used, all modified buffers are written to disk when any
buffer becomes full.
■ If the application fills the buffers quickly (as with a FETCH command), it
is unnecessary and wasteful to force a checkpoint. If, however, the
application fills the buffers slowly, with each line being added after a
comparatively lengthy computational process, or if the application
continuously modifies data lines which are all in the same block, it may be
advisable to invoke the CKPTIO function from time to time.

Position in AWS
Not Applicable.
4.3.3 COPY Function

COPY duplicates a record or range of records from one section of the AWS to
another.
Parameters
AWSPM specify the start of the range to be copied as a sequence number
or positional value.
AWSPN specify the end of the range to be copied as a sequence number
or a record count.
AWSPO specify the destination of the operation as a sequence number or
positional expression.
AWSPP specify the increment to be used when inserting records at their
destination. If this optional parameter is omitted, an increment
value of 1 is used. If specified, the increment must be a positive
value. If 0 is specified, it is treated as though 1 is specified.
AWSPQ specify the duplication count to be used when inserting multiple
copies of a record or records at the destination. If this optional
parameter is omitted, a duplication value of 1 is assumed. If
specified, it must be a positive value. If 0 is specified, it is
treated as though 1 is specified.
AWSPM: 0 start of range to insert

AWSPN: 0 end of range to insert
AWSPO: 0 insert point
AWSPP: 0 increment value
AWSPQ: 0 duplication value
Notes
■ If both the source range (AWSPM and AWSPN) and the destination
(AWSPO) are positional expressions, the original current position is used
to calculate both actual locations.
See the description of the POINT function for information about specifying
a range of sequence numbers or a relative position.

Examples
1. Copy records 10 through 30 after record 200, using 5 as the increment:
AWSPM: 0 10
AWSPN: 0 30
AWSPO: 0 200
AWSPP: 0 5
AWSPQ: 0 0
2. Copy records 500 through 600 after the current record, using 1 as the
increment, duplicating the records 3 times:
AWSPM: 0 500
AWSPN: 0 600
AWSPO: 0 0
AWSPP: 0 1
AWSPQ: 0 3
3. Copy the ten records, beginning with the tenth record preceding the
current record, to after the tenth record following the current record, using
10 as the increment.
AWSPM: 0 10
AWSPN: 0 10
AWSPO: 0 10
AWSPP: 0 10
AWSPQ: 0 0
The destination (AWSPO) may not lie within the source range. For
example, 10, 100, and 50 constitute invalid values for AWSPM, AWSPN
and AWSPO, respectively.
Position in AWS
At last record copied.

4.3.4 DELETE Function

DELETE deletes a record or range of records from the AWS.
Parameters
AWSPM specify the start of the range to be deleted as a sequence number
AWSPN specify the end of the range to be deleted as a sequence number
or a record count.
AWSPM: 0 start of range

AWSPN: 0 end of range
Notes
■ AWSPM and AWSPN must define the entire range of records to be
deleted. A description of how to specify sequence numbers and a
description of how to specify relative positioning are given under POINT.
■ The entire AWS may be deleted by omitting the parameter, as in:
AWSI FUNC=DELETE,AWSRB=awsrb,ERROR=error
Examples
1. Delete record 10:
AWSPM: 0 10
AWSPN: 0 10
2. Delete the current record:
AWSPM: 0 0
AWSPN: 0 1

3. Delete records 30 through 100:
AWSPM: 0 30
AWSPN: 0 100
4. Delete four records beginning with the fifth record preceding the current
one:
AWSPM: 0 5
AWSPN: 0 4
5. To delete two records beginning with the seventh record following the
current one:
AWSPM: 0 7
AWSPN: 0 2
Position in AWS: At record following last record deleted if there is one; at

last record of AWS if not.
4.3.5 FREE Function

FREE releases an AWS that was allocated by ACTIVATE.
Parameters: Two different parameter formats may be used:

1. For simple release: None
2. When exchanging AWSs: Contents of the AWSRNBPT identifying the AWS
to be retained.
Notes
■ For a simple release, no parameters are passed. The AWSMGR will free the
AWS identified by the contents of the AWSRNBPT field of the AWSRB.
■ When exchanging AWSs, the parameter must be the contents of the
AWSRNBPT that identifies the AWS to be retained. (The contents of the
field AWSRNBPT of the AWSRB must identify the AWS to be freed (the
AWS originally owned by the main task).)
Exchanging AWSs occurs when a new AWS created by the subtask is to
replace the terminal user's AWS. The terminal user's AWS is released and
the new AWS is returned to the main task for use by the terminal user.
■ All AWSs activated by the caller must be freed. Be sure you do not
inadvertently free the AWS owned by the main task. The AWS released by

FREE is the one identified by the contents of the AWSRNBPT field in the
AWSRB when FREE is invoked.
Position in AWS
Not Applicable.
4.3.6 GET Function

GET retrieves a record from the AWS.
Parameters: Two different parameter formats may be used:

1. To retrieve next record: None
2. To set logical end-of-AWS:
AWSPM specify the sequence number of the record to be read.
AWSPM: 0 sequence number
Notes
■ To retrieve the next record beginning at the current position, no
parameters are passed.
■ Setting a logical end-of-AWS limits the action of a GET. With this action,
data in the AWS can be partitioned into logical segments defined by
sequence numbers. These sequence numbers define an inclusive segment.
■ GET returns the appropriate information unless the end of the AWS has
been reached. The end-of-AWS condition can be forced when a parameter
is passed limiting the retrieval range.
■ The format of the record depends on the XRPF= parameter specified with
the AWSI macro.
– If XRF=YES is specified, GET returns the address of the record in the
field AWSRPARM in the AWSRB. The first two bytes of the record
contain the length of the record and represent the actual data length
plus eight bytes. The data can be a maximum of 255 bytes in length.
(See the PUT function for a description of the record format.)
– If XRF=NO is specified, GET returns the address of the record in the
AWSRPARM field. If the record exceeds 80 bytes in length, only the
first 80 are available. (See the PUT function for a description of the
record format.)

Example: Assume the following sequence of AWSI calls on an AWS

consisting of records 10, 20 and 30:
POINT 10 (No record is returned. The current position is set to record 10.)
GET (Record 10 is returned.)
PUT line 25 (No record is returned. The current position is set at record 25.)
GET (No record is returned. The end-of-file exception code
returned.)
Position in AWS
At record obtained.
4.3.7 INFO Function

INFO retrieves information about the current AWS configuration.
Parameters
addr pointer to an AWS Information Block (AWSIB). The block is eight
bytes long, and is mapped by the Advantage CA-Roscoe macro
AWSIB. The caller must set the first two bytes to X'0308' before
issuing an INFO request.
Notes
■ On return from AWSI, the second halfword of AWSIB will contain a value
equal to the maximum number of records allowed in the AWS (AWSSIZE).
The second word will contain the highest possible sequence number
permitted (99999999).
0 AWSIBKID AWSIBKLN AWSIMXLN

BLOCK ID BLOCK LENGTH MAXIMUM NUMBER
= X'03' = AL1(8) OF LINES IN AWS
4 AWSIMXSQ MAXIMUM SEQUENCE NUMBER IN AWS
Position in AWS
Not Applicable.

4.3.8 INIT Function

INIT initializes the AWSI Interface. It must be issued before all other calls. This
function is executed entirely within the AWSI module.
Parameters
AWSPM specify the ROT address.
AWSPN specify address of the ATT1. Subsequent AWS operations are
performed on the AWS maintained for the terminal user by the
main task
AWSPM: 0 A(ROT)
AWSPN: 0 A(ATT1)
Notes
■ The AWSRB must be initialized to binary zeros before the INIT function is
invoked. After the INIT function completes, the contents of the
AWSRNBPT field in the AWSRB uniquely identify the terminal user's
AWS.
Position in AWS
Not Applicable.
4.3.9 MOVE Function

MOVE duplicates a record or range of records from one section of the AWS to
another and the original records are deleted.
Parameters
AWSPM specify the start of the range to be moved as a sequence number
AWSPM specify the end of the range to be moved as a sequence number
or record count.
AWSPO specify the destination of the operation as a sequence number or
positional expression.
AWSPP specify the increment to be used when inserting records at their
destination. If this optional parameter is omitted, an increment
value of 1 is used. If specified, it must be a positive value. If 0 is
specified, it is treated as though the value 1 is specified.

AWSPM: 0 start of range to insert

AWSPN: 0 end of range to insert
AWSPO: 0 insert point
AWSPP: 0 increment value
Notes
■ If both the source range (AWSPM and AWSPN) and the destination
(AWSPO) are positional values, the original current position is used to
calculate both actual locations.
See the description of the POINT function for information about specifying
sequence numbers and how to specify relative positioning.
Examples
1. Move records 10 through 30 after record 200, using 5 as the increment:
AWSPM: 0 0
AWSPN: 0 30
AWSPO: 0 200
AWSPP: 0 5
2. Move records 500 through 600 after the current record, using 1 as the
increment:
AWSPM: 0 500
AWSPN: 0 600
AWSPO: 0 0
AWSPP: 0 1
3. Move the ten records, beginning with the tenth record preceding the
current record, to after the tenth record following the current record, using
10 as the increment.
AWSPM: 0 10
AWSPN: 0 10
AWSPO: 0 10
AWSPP: 0 10

The destination may not lie within the source range (10, 100, and 50
constitute invalid values for AWSPM, AWSPN and AWSPO, respectively).
Position in AWS
At last record moved.
4.3.10 POINT Function

POINT positions the AWS pointer to the record having the lowest sequence
number within a specified range or to a record that precedes or follows, by a
specified number of records, the current record.
Parameters: Three different parameter list formats may be used:

1. To point to the first record of those whose sequence numbers lie within a
specified range:
AWSPM specify the low sequence number (start) of the range.
AWSPN specify the high sequence number (end) of the range, or 0 to
indicate that the range continues through end of the AWS.
AWSPM: 0 start of range

AWSPN: 0 end of range
2. To point forward a specified number of records from the current position:

AWSPM set byte 1 to X'04' to indicate forward positioning. Bytes 2
through 4 must contain the number of records to advance
from the current position.
AWSPM: 4 number of lines
3. To point backward a specified number of records from the current

position:
AWSPM set byte 1 to X'080' to indicate backward positioning. Bytes 2
through 4 must contain the number of records to back up
from the current position.
AWSPM: 8 number of lines
Notes
■ When using the first parameter list format:

The high-order byte of AWSPM and the high-order byte of AWSPN must
be 0. The AWS is searched for the first record whose sequence number
lies within the specified range.
– If a record is found, the return code is 0 and AWSRPARM in the
AWSRB contains the sequence number.
– If no record is found, the return code contains a non-zero value.
If the specified range begins after the last line of the AWS, the return code
is 0 and AWSRPARM contains a zero.
■ When using the second parameter list format, the current record pointer is
moved forward record by record until the count is exhausted or until the
current record pointer points to the last record of the AWS.
■ When using the third parameter list format, the current record pointer is
moved backward record by record until the count is exhausted or the AWS
is positioned at the first record in the AWS.
Examples
1. Point to record 30 if it exists:
AWSPM: 0 30
AWSPN: 0 30
2. Point to the first record whose sequence number is at least 30:
AWSPM: 0 30
AWSPN: 0 0
3. Point forward five lines:
AWSPM: 4 5
4. Point backward five lines:
AWSPM: 8 5
Position in AWS
At record pointed to.

4.3.11 PUT Function

PUT places a record into the AWS.
Parameter
addr address of the record to be placed in the AWS.
Notes
■ The expected format of the record depends on how the XRF= parameter is
specified with the AWSI macro.
If XRF=NO is specified, the format of the record is expected to be:
1 81 82 84
┌──────────────────┬───┬─────────┐
│ │ │ │
│ data (length 8) │ │ seq.no. │
└──────────────────┴───┴─────────┘
■ If XRF=YES is specified, the format of the record is expected to be:

1 2 7 9 263
┌────────────┬──────────────┬────┬───────────────────┐
│ │ │ │ │
│ hex length │ hex seq. no. │ │ EBCDIC data (255) │
└────────────┴──────────────┴────┴───────────────────┘
■ When 255-character records are to be inserted, the length field must

contain the length of the data plus eight bytes. AWSI deletes any trailing
blanks, up to the first significant character.
■ The operation of PUT depends on whether insert mode is in effect
(whether a SETI function was specified prior to the PUT).
– If SETI is not specified, the record is placed in the AWS, positioned
according to its sequence number, and overlays any previously existing
record having the same sequence number.
– If SETI is specified, the record is inserted after the current record. Its
sequence number must be greater than that of the current record.
Position in AWS
At record INPUT.

4.3.12 RENUMBER Function

RENUMBER assigns sequence numbers to the records of an AWS.
Parameters
AWSPM specify the new starting sequence number.
AWSPN specify the increment value.
AWSPM: 0 starting sequence number

AWSPN: 0 increment
Notes
■ The first record in the AWS is assigned a sequence number equal to the
contents of AWSPM. Each subsequent record is assigned a sequence
number equal to that of the previous record, plus increment.
Example: Renumber the AWS from 10 by 10:
AWSPM: 0 10
AWSPN: 0 10
Position in AWS
At last record of AWS.
4.3.13 RESETI Function (Terminate Insert Mode)

RESETI terminates insert mode (previously established by SETI) and
renumbers the AWS as needed to maintain ascending sequence numbers.
Parameters
None
Position in AWS
At last record inserted.

4.3.14 SETI Function (Set Insert Mode)

SETI positions the AWS pointer and initiates insert mode.
Parameters
The same as for POINT. Refer to the description of POINT.
Notes
■ When insert mode is in effect, subsequent PUT functions cause new
records to be inserted after the current record. Inserted records must have
ascending sequence numbers. While in insert mode, the only valid
functions are: CKPTIO, INFO, PUT and RESETI. Any other function causes
insert mode to be terminated. (No error or exception condition is
returned.) Use the RESETI function to terminate insert mode. RESETI also
causes records following those inserted to be renumbered until there is no
sequence number conflict.
■ When insert mode is not in effect, inserted records overlay any existing
records.
Example: Prepare to insert new records after record 30:
AWSPM: 0 30
AWSPN: 0 0
Position in AWS:
At insert point.
4.3.15 STATUS Function

STATUS returns the status of the AWS. This information includes the current
number of lines and the highest sequence number in the AWS.
Parameters
addr pointer to an AWS Status Block (AWSSB). The block is eight
bytes long, and is mapped by the Advantage CA-Roscoe macro
AWSSB. The caller must set the first two bytes to X'0C08' before
issuing the STATUS request.
Notes
■ On return from AWSI, the second halfword of AWSSB will contain a value
equal to the number of records in the AWS and the second word will
contain the highest sequence number.

0 AWSIBKSD AWSSBKLN AWSSCRLN

BLOCK ID BLOCK LENGTH CURRENT NUMBER
= X'0C' = AL1(8) OF LINES IN AWS
4 AWSSMXSQ MAXIMUM SEQUENCE NUMBER IN AWS
Position in AWS
Not Applicable.
4.3.16 TERM Function

TERM disconnects the AWSI Interface and releases resources obtained by INIT.
Parameters
None
Notes:
■ INIT must be invoked after all other functions. It does not free AWSs
obtained by ACTIVATE requests; the caller must explicitly free any AWSs
activated.
Position in AWS
Not Applicable.

4.4 AWS Request Block (AWSRB)

The AWSRB (AWS Request Block) is used for all requests to the AWSMGR.
The Advantage CA-Roscoe macro AWSRB can be used to generate a DSECT
mapping the AWSRB.
The fields comprising the AWSRB include:

AWSRSTAT is a one-byte field which contains two flags of interest to the
AWSI called:
AWSRSDMG
If on, there are lines in the AWS with invalid
sequence numbers. This only occurs when
RESETI renumbers the AWS and finds that a
renumbered line exceeds the maximum
allowable sequence number. The caller should
invoke the RENUMBER function to renumber
the AWS.
AWSDFRW This flag may be set by the caller to cause the
AWSMGR to delay actual I/O as long as
possible.
AWSRNMBR is the current number of records in the AWS. This value is
maintained separately for each AWS and is refreshed on
CKPTIO, COPY, DELETE, POINT and PUT.
AWSRHSEQ is the highest sequence number in the AWS. This value is
maintained separately in each AWS and is refreshed on
CKPTIO, COPY, DELETE, POINT and PUT.
AWSRNBPT is a field that identifies the current AWS. By saving and
restoring the contents of this field, different AWSs can be
accessed. FREE frees the AWS pointed to by AWSRNBPT.
AWSRXRC is a field containing the code which describes exception
conditions.
AWSRPARM is a field that AWSI uses to store caller's parameter before
calling the AWSMGR.
Notes
■ On return from the AWSMGR, the following functions return information
in the AWSRPARM field:
Function Returns
FREE parameter from ACTIVATE for 8 bytes starting with
AWSRPARM and continuing through AWSRWORK.
POINT sequence number of record pointed to.

GET address of line.

DELETE number of lines deleted.
SETI sequence number of insert point.
RESETI sequence number of last record.
■ The following functions do not return information:
ACTIVATE
CKPTIO
COPY
INFO
INIT
MOVE
PUT
RENUMBER
STATUS
TERM

4.5 Exception Conditions

The AWSI Interface checks all requests before passing them to the AWSMGR.
When an error in a request is detected, the exception code is generated by
AWSI itself. All such codes have the high-order bit set (that is, all such codes
are greater than 128). All other codes are set by the AWSMGR and are lower
than 128; these codes are symbolically defined in the AWSRB macro.
The codes generated by AWSI are:

Code Meaning
X'81' No work area was provided or a function other than INIT was
invoked before the INIT function was invoked.
X'82' GETMAIN failed. AWSI is unable to obtain the work areas needed
to build the AWSMGR control blocks.
X'85' An invalid entry code was found.
X'86' No ROT and/or ATT1 address was provided.
X'87' An attempt was made to free the AWS maintained by the main
task.
The following symbols (defined in the AWSRB macro) are used to describe
exception conditions returned by the AWSMGR. (Each symbol is defined in the
AWSRB macro and is a one-byte value mutually exclusive with all other
values, rather than a mask.)
Code Value Meaning

AWSXGMF 1 A GETMAIN failure has occurred.
AWSXIOEX 2 An I/O error has occurred.
AWSXOP1I 3 Operand 1 (AWSPM) is invalid.
AWSXOP2I 4 Operand 2 (AWSPN) is invalid.
AWSXOP3I 5 Operand 3 (AWSPO) is invalid.
AWSXLNEX 6 An attempt was made to exceed the
record capacity of the AWS. The record
causing the overflow was not inserted.
Also occurs if Advantage CA-Roscoe
cannot GETMAIN space to build a needed
work area (for example, as used for
INCL/EXCL).
AWSXEOF 7 The end of the AWS was reached by GET
function processing.

Code Value Meaning

AWSXDBOV 8 A data block was needed in one of the
data sets constituting the AWS but was
unavailable. Use of the Interface must be
terminated.
AWSXIBOV 9 A low-level index block was needed in
one of the data sets constituting the AWS
but was unavailable. Use of the Interface
must be terminated.
AWSXINVB 10 An invalid bit number on a bit put. This
is an internal AWSI error. (International
sites should report this to their local
representative.)
AWSXBDBRB 11 The AWSRB is improperly formatted.
Field AWSRNBPT (the pointer) contains
zero, but the function requested was not
ACTIVATE.
AWSBDTA 12 Bad data record encoding. This is an
internal AWSI error.
AWSXRBSY 13 An additional AWS was needed to
complete the requested function but was
unavailable and did not become available
within a reasonable period of time. (See
the Advantage CA-Roscoe Interactive
Environment System Reference Guide for a
description of how to increase the number
of AWSs available in the system.)
AWSXEMPT 14 The AWS was empty and the requested
function cannot be performed on an
empty AWS.
AWSXSEQX 15 The maximum allowable AWS sequence
number was exceeded. If the flag
AWSRSDMG is on, the AWS contains at
least one record with an invalid sequence
number; otherwise, the requested function
was prematurely terminated or
suppressed.
AWSNOLN 16 No records were found in the specified
range. The current position is undefined.

Code Value Meaning

AWSXRSQE 17 A RENUMBER operation with the
specified parameters would cause a
sequence number greater than 999999 to
be assigned. The RENUMBER is not
performed.
AWSXINSE 18 An attempt to PUT a record in insert
mode failed because the sequence number
of the new record did not exceed that of
its predecessor.
AWSBADP 19 The first byte of AWSPM was not X'00' or
X'04' or X'08' when a COPY, DELETE,
MOVE, POINT or SETI function was
invoked; or the first byte OF AWSPO was
not X'00', X'04' or X'08' when a COPY or
MOVE function was invoked.
AWSXSTKO 20 The internal stack used for subroutine
calls has overflowed because subroutine
nesting is too deep. This represents an
internal logic error in the AWSMGR. Use
of the Interface must be terminated.
AWSXDIS 21 Disable posted. This is an internal AWSI
error. Report it to the Advantage
CA-Roscoe Support Staff. (International
sites should contact their local
representative.)
AWSXPLF 22 Page load failed. This is an internal AWSI
error. Report it to the Advantage
CA-Roscoe Support Staff. (International
sites should contact their local
representative.)
AWSXDBIC 23 Maximum number of AWS data blocks
have been used by the user. Reformat the
AWS, increasing the block size of the data
files.
AWSXIBIC 24 Maximum number of AWS index blocks
have been used by the user. Reformat the
AWS, increasing the block size of the data
files.

Chapter 5. User Library Interface (LIBI)
LIBI is the interface to the Advantage CA-Roscoe user library subsystem

(LIBIO).
LIBIO, which runs as AMODE 31, is resident during Advantage CA-Roscoe

execution. It acts as the library manager and controls all access to the user
library. It contains the facilities to find, create, delete, rename and alter library
members.
The LIBI Interface can be used by individuals writing Monitor routines and
other special-purpose routines that perform online library operations. It
provides functions that use many of the facilities contained in LIBIO. LIBI
consists of:
■ The LIBI macro (distributed on CAI.CRO60MLD), and
■ The LIBI routine (distributed on ROSCOE.ROSLIB).
Individuals using the Interface need only concern themselves with the LIBI
macro.
Caution
When using LIBI, the library read and write protection remains in effect.
Review the section describing the User Profile System security groups in
the Advantage CA-Roscoe Interactive Environment System Reference Guide.
Chapter 5. User Library Interface (LIBI) 5-1

5.1 Using the LIBI Interface

The LIBI macro calls the LIBI routine. The routine validates the LIBI macro
before passing control to LIBIO. (LIBI obtains the address of LIBIO from the
ROT, along with addresses of other control areas needed by LIBI.) The routine
also uses WAIT and STIMER to synchronize with LIBIO. Therefore, it must
never be used at the Advantage CA-Roscoe main task level.
A separate LIBI macro call to the LIBI routine must be made for each function
(for example, ADD, PUT) to be performed by LIBIO. The macro provides
functions that can be used to:
■ Add a new or replace an existing library member on the library.
■ Obtain and place records in a library member.
■ Locate a member's index entry.
■ Alter attributes in a library index entry.
■ Delete a member from the library.
■ Obtain information about the library.
Data Areas:
The LIBI macro uses three data areas, two of which must be defined in the
calling program or in dynamically obtained storage. The two areas which must
be defined are:
1. A 32-byte communication area. This area is the LBRB (Library Request
Block) and is required for all functions specified in the LIBI macros. It
must be obtained before the first call on the LIBI routine and must remain
intact until the final call. A DSECT to map the LBRB is generated by the
macro LBRB.
2. An area for the parameter list which can be mapped by the LBPMDEF
DSECT generated by the macro LBPMDEF.
The third area is the LBDB (Library Definition Block) which can be mapped by
the LBDB macro. LBDB is created and maintained by LIBIO. It contains
information about the most recently activated library resource. Any request on
LIBIO is performed upon the library resource identified by LBDB. The address
of the current LBDB is placed in the field LBRBDBPT of the LBRB by LIBI. The
LBDB is only of interest when working with multiple library resources.
Note: The LBDB is allocated above the 16MB line at MVS/XA sites.
All code generated by the Interface is reentrant. If reentrancy is to be observed

in the calling Monitor routine, the data areas and parameter lists provided by
the calling program must be placed in dynamically obtained storage.

Working with Multiple Users: Monitor routines may be written to use the
data from library member(s) belonging to one Advantage CA-Roscoe user to
produce new member(s) for the same user or another user.
When working with multiple users, you must:

■ Ensure there are a sufficient number of library resources available to
accommodate each user.
A library resource is an extra library buffer that is used as a temporary
work area by Advantage CA-Roscoe. Library buffers are defined using the
LIBXLIB= initialization parameter (as described in the Advantage CA-Roscoe
Interactive Environment Programs and Utilities Guide). If multiple users may
execute a Monitor routine (or application under under ETSO) that uses
library resources, the value specified with the LIBXLIB= parameter may
need to be increased.
■ Save the LBDB address (placed in the LBRBDBPT field of the LBRB by
LIBI). Since LIBI requests on LIBIO are performed upon the library
resource identified by the LBDB, the address of the LBDB for a particular
library resource must be placed in the LBRBDBPT field of the LBRB before
the LIBIO request is made.
Linkage Conventions
■ Register 13 must point to an 18-fullword save area. The LIBI routine saves
and restores the contents of registers 2 through 13.
■ On return, register 15 contains a return code of:
0 No error or exception condition.
4 Error or exception condition. The field LBRBXRC in the LBRB
contains a one-byte extended return code permitting an exact
determination of the nature of the exception. It is the
responsibility of the caller to take appropriate action after an
exception occurs.

5.2 Coding the LIBI Macro

The syntax of the LIBI macro is:
LIBI Macro
──┬─────┬──LIBI──FUNC=─┬──────────┬───,PARM=─┬─(,label)─┬─────
└─tag─┘ ├─ACTIVATE─┤ └─(reg)─────┘
├─ADD──────┤
├─ALTER────┤
├─DEL──────┤
├─FIND─────┤
├─FREE─────┤
├─GET──────┤
├─GETKEY───┤
├─GETPFX───┤
├─INFO─────┤
├─INIT─────┤
├─INITX────┤
├─LIB──────┤
├─NOTE─────┤
├─POINT────┤
├─PUT──────┤
├─RENAME───┤
├─SPACE────┤
├─STATUS───┤
└─TERM─────┘
──,LBRB=─┬─label─────┬───┬────────────────────┬────────────────
├─(,label)─┤ └─,ERROR=─┬─+4───┬──┘
└─(reg)─────┘ └─label─┘

FUNC=function is the LIBIO function to be performed by LIBI. (The functions
are described in the next section.)
PARM=label is the address of a function-dependent parameter list that
begins on a fullword boundary. If omitted, the value of zero
is placed in register 0.
LBRB=label is the address of the LBRB. The LBRB must begin on a
fullword boundary. It must be cleared to zeros for the INIT
call only; thereafter, it is maintained by LIBI.
ERROR=label is the label of an instruction to which control is to be
transferred on an exception condition. If omitted, the return
from the LIBI routine after an error or exception (such as
end-of-file on a GET) is to the next instruction, and the
calling routine must test register 15 for non-zero return
codes.

Notes
where the value of x is generated by the macro. If (reg) is coded and it is
equal to the register generated by LIBI, no instruction is generated.
■ The macro generates the code to do the following:
– Load the address of PARM into register 0.
– Load the address of LBRB into register 1.
– Move an entry code into the LBRB.
– Load the address of the LIBI routine into register 15.
– Call the LIBI routine using a BALR 14,15.
■ The macro expansion includes a LOAD macro for the LIBI CSECT. The
CSECT address is saved in the user's LBRB.

5.3 Description of LIBI Functions

The following list introduces the LIBIO functions that can be specified by the
LIBI macro to the LIBI routine. The functions are described on the following
pages.
Function Purpose
ACTIVATE allocates library resource(s) for use by the calling program.
ADD adds a new or replaces an existing entry on the library.
ALTER alters attributes in a member index entry.
DEL deletes a member from the library.
FIND locates the desired index entry and places it in
FREE releases a library resource previously allocated by ACTIVATE.
GET obtains the next logical record.
GETKEY obtains the sign-on key and security group for a given prefix.
GETPFX obtains the prefix and security group for a given sign-on key.
INFO retrieves information about the current library configuration.
INIT initializes the interface. INIT or INITX must be specified in the
first call on LIBI.
INITX initializes the batch interface. INITX or INIT must be specified in
the first call on LIBI.
LIB retrieves an index entry and places it in the area pointed to by a
parameter. (The parameter list.)
NOTE saves the current status of the library.
POINT defines the position within the library member at which the next
read operation (GET, POINT, NOTE) is to be performed.
PUT places the next logical record in the library.
RENAME changes name and specified attributes of a library member.
SPACE computes the number of available blocks.
STATUS retrieves current status of library.
TERM terminates the interface; must be specified in the last call on LIBI.

5.3.1 ACTIVATE Function

ACTIVATE allocates a library resource for use by the calling program and
associates a user's prefix and protect code with the resource.
Parameters
LBPMPFIX specify a three-byte terminal user's prefix. This value is
obtained from the ATTLBPFX field of the user's SCB.
LBPMCODE specify a two-byte user's protect code. This value is obtained
from the ACCNUMX field of the user's SCB.
Notes
■ The value of the user's prefix and protect code must be obtained from the
SCB before the ACTIVATE is issued.
■ The number of library resources available to the user can be determined by
adding the number of concurrent Advantage CA-Roscoe subsessions
defined for the TERMSO= initialization parameter to the number of extra
libraries defined for the LIBXLIB= initialization parameter. (See the
Advantage CA-Roscoe Interactive Environment Programs and Utilities Guide for
details on these parameters.)
■ Any references in this manual to a library resource that has been activated
assumes that a user's prefix and protect code are associated with it.
5.3.2 ADD Function

ADD adds a new or replaces an existing entry on the library.
Parameters
LBPMFLAG is a one-byte reserved flag and must be X'00'.
LBPMRNAM specify an 11-byte field name of the library member to be
added or replaced. The name must consist of a
three-character prefix (or two characters and a blank) and a
name not exceeding eight characters in length. Names less
than eight characters must be padded with spaces.
LBPMUNUS is a one-byte reserved for future expansion of the name field.
LBPMAFL1 is a one-byte flag indicating which attribute should be set.
Specify:
X'01' add/replace member as 'PPR' (Post-Processor).
X'02' reserved.
X'04' add/replace member as RESTRICTED.
X'08' add member as SHARED or reset RESTRICTED to
SHARED.

X'10' reset EXECONLY to SHARED.

X'20' add/replace member as EXECONLY.
X'40' add/replace member as NOSEQ.
X'80' add/replace member as SEQ.
LBPMAFL2 is a one-byte flag indicating which attributes should be set.
Specify:
X'20' add/replace member with 'call to rosdata'
attribute.
X'40' add/replace member with 'SUBTASK' attribute.
X'80' add/replace member with 'ROSDATA' addtrobite.
LBPMAFL3 is a one-byte flag indicating which additional attribute fields
should be set. Specify:
X'20' add/replace starting column of member's
sequence number field.
X'40' add/replace length of member's sequence number
field.
X'80' add/replace member's description.
LBPMCLNT specify a one-byte starting column of the sequence number.
LBPMSQLN specify a one-byte length of the sequence number.
LBPMDESC specify a 30-byte description of the member.
Notes
■ The fields LBPMCLNT, LBPMSQLN and LBPMDESC are optional if
LBPMAFL3 is not set
5.3.3 ALTER Function

ALTER changes attributes in a member index entry. The attribute(s) which will
be changed depends on the setting of the flag butes.
Parameters
LBPMFLAG is a one-byte reserved flag and must be '00'.
LBMPRNAM specify an 11-byte name of the library member whose
attributes are to be changed. The member name must consist
of a three-character (or two characters and a blank) and a
name not exceeding eight characters in length. Names less
than eight characters must be padded with spaces.
LBPMUNUS is a one-byte flag reserved for future expansion of the name
field.

LBPMAFL1 is a one-byte flag indicating which attributes should be

changed. Specify:
X'02' reserved.
X'04' change member's attribute to RESTRICTED.
X'08' reset member's attribute from RESTRICTED to
SHARED.
X'10' reset member's attribute from EXECONLY to
SHARED.
X'20' change member's attribute to EXECONLY.
X'40' change member's attribute to NOSEQ.
X'80' change member's attribute to SEQ.
LBPMAFL2 is a one-byte reserved flag and must be X'00'.
LBPMAFL3 is a one-byte flag indicating which attribute field should be
changed. Specify:
X'20' change starting column of member's ssequence
number field.
X'40' change length of member's sequence number field.
X'80' change member's description.
LBPMCLNT specify a one-byte starting column of the sequence number.
LBPMSQLN specify a one-byte length of the sequence number.
LBPMDESC specify a 30-byte description of the member.
Notes
LBPMAFL3 is not set.
5.3.4 DEL Function

DEL deletes a member from the library.
Parameters
LBPMFLAG is a one-byte reserved flag and must be '00'.
LBPMRNAM specify the 11-byte name of the member to be deleted. The
name must consist of a three-character prefix (or two
characters and a blank) and a name not exceeding eight
characters in length. Names less than eight characters must
be padded with spaces.
LBPMUNUS is a one byte reserved for future expansion.

5.3.5 FIND Function

FIND locates an index entry and places it in the parameter list starting at
LBPMLIBE.
Parameters
LBPMFLBF is a one-byte reserved flag and must be '00'.
LBPMLIBE specify the 11-byte name of the member to be located. The
member name must consist of a three-character prefix (or
two characters and a blank) and a name not exceeding eight
characters in length. Names less than eight characters must
be padded with spaces.
LBPMFUNS is a one-byte flag reserved for future expansion.
LBPMREST is 58 bytes reserved for the remainder of the index entry.
Notes
■ Use the Advantage CA-Roscoe macro LBINDEX to map the format of the
index entry.
5.3.6 FREE Function

FREE releases a library resource.
Parameters: None
Notes
■ All library resources activated by the calling program must be released.
5.3.7 GET Function

GET obtains the next logical record from a library member.
Parameters
LBPMLNLN is a two-byte maximum length of the record. The maximum
record length will not exceed 263 bytes (255 bytes for the line
plus eight control bytes). Trailing blanks are not included in
the length.
LBPMLNSQ is a four-byte sequence number.
LBPMRESV is two bytes reserved for future expansion.
LBPMLINE is a record not exceeding 255 bytes in length. Trailing blanks
are dropped.

5.3.8 GETKEY Function

GETKEY obtains the sign-on key and security group for a given prefix.
Parameters
LBACCB is the address of the Library Account Block (LBACCB). The
LBACCB contains three fields:
LBACCPFX is a three-byte field that must be set to the
appropriate user prefix before invoking this
function.
LBACCGRP
is an eight-byte field that will contain the name
of the user's security group.
LBACCKEY
is a 22-byte field that will contain the user's
sign-on key.
LBACCFKY
formal key or binary zeros. (The field contains
zeros if the user has has not signed on since the
current execution of Advantage CA-Roscoe
started.)
Notes:
■ Before the GETKEY function is invoked, the field LBACCPFX must be set
to the appropriate prefix.
After the function is executed, the remaining fields will contain the user's
sign-on key and security group.
■ Use the Advantage CA-Roscoe macro LBACCB to map the Library
Account Block (LBACCB).
5.3.9 GETPFX Function

GETPFX obtains the prefix and security group name for a given sign-on key.
Parameters
LBACCB is the address of the Library Account Block (LBACCB). The
LBACCB contains three fields:
LBACCKEY
is a 22-byte field that must be set to the
appropriate user sign-on key before invoking
this function.

LBACCPFX is a three-byte field that will contain the user's

prefix.
LBACCGRP
is an eight-byte field that will contain the name
of the user's security group.
LBACCFKY
formal key or binary zeros. (The field contains
zeros if the user has not signed on since the
current execution of Advantage CA-Roscoe
started.)
Notes
■ Before the GETPFX function is invoked, the field LBACCKEY must be set
to the appropriate sign-on key.
After the function is executed, the remaining fields will contain the user's
prefix and security group.
■ Use the Advantage CA-Roscoe macro LBACCB to map the Library
Account Block (LBACCB).
5.3.10 INFO Function

INFO retrieves information about the current library configuration.
Parameter
LBPMINF address of the Library Information Block (LBIB). The block is 12
bytes long and is mapped by the Advantage CA-Roscoe macro
LBIB.
5.3.11 INIT Function

INIT initializes the online LIBI interface. It must be specified in the first call on
LIBI.
Parameters
LBPMAROT is a fullword containing the address of the ROT. This must
be passed to the LIBI routine from the main level.
LBPMATT1 is a fullword containing the address of the terminal user's
ATT1.
Notes
■ The INIT and INITX functions are mutually exclusive.

5.3.12 INITX Function

INITX initializes the batch LIBI interface. It must be specified in the first call
on LIBI.
Parameter: No parameter is passed.
Notes
■ The INITX and INIT functions are mutually exclusive.
5.3.13 LIB Function

LIB retrieves an index entry and places it in the field LBPMLIBE.
Parameters
LBPMFLBF is a one-byte flag which determines what search will be
performed. Specify:
X'A0' Search against protect code to start at the
beginning of the range.
X'20' Search against protect code to resume.
X'C0' Search against prefix to start at the beginning of
the range.
X'40' Search against prefix to resume.
LBPMLIBE is a 70-byte area for the index entry.
Notes
■ The macro LBINDEX can be used to map the index entry area.
■ On the initial call or on any call where retrieval is to start from the
beginning of the prefix or protect code range of the index file, LBPMFLBF
must be either X'A0' or X'C0'. For all subsequent calls, LBPMFLBF must be
set to either X'20' or X'40'.
5.3.14 NOTE Function

NOTE saves the current status of the library buffers.
Parameters
LBPMRES1 is a 30-byte area that can be used for POINT operation
(X'0C') as long as flag byte LBPMRES1 is changed to X'0C'.
Notes
■ The combination of NOTE with POINT(X'0C') will restart library operation
at the NOTEd location.

5.3.15 POINT Function

POINT defines the position within a library member at which the next
operation will be performed. It positions to a specific sequence number,
relative forward from the current position, relative backward from the current
position or to the NOTEd area.
Parameters: POINT will accept four types of parameter lists.

1. To position to a specific sequence number:
LBPMPNFL X'00'
LBPMPNSQ is a three-byte sequence number.
LBPMPNED is a three-byte field specifying the ending sequence
number of the point range. If a search of the entire
member is required, this field should be set to
X'00FFFFFF'.
2. To position relative forward:
LBPMPNFL X'04'
LBPMPNSQ is a three-byte relative position.
LBPMPNED is a four-byte count of records to be gotten in a
subsequent GET operation. If the count is exceeded, EOF
will be indicated.
3. To position relative backward:
LBPMPNFL X'08'
LBPMPNSQ is a three-byte relative position.
LBPMPNED is a four-byte count of records to be gotten in a
subsequent GET operation. If the count is exceeded, a
pseudo-EOF is indicated. (This is useful when the
number of records to be gotten does not include the last
record in the member.)
4. To position to the NOTEd area:
LBPMRES1 X'0C'
LBPMRES2 is 29 bytes of NOTEd area+1.
Notes
■ The FIND and GET functions are used to locate a library member and
obtain the first logical record in that member.

■ POINT is used to position within the member before the next operation is
performed. It can also be used to establish a range or count of records.
■ To position to the end of a library member, set
LBPMPNFL to X'00'
LBPMPNSQ to X'FFFFFF'
LBPMPNED to X'00FFFFFF'
5.3.16 PUT Function

PUT places the next logical line into the library.
Parameters
LBPMLNLN is a two-byte field for the maximum length of the record.
The minimum length is none. The maximum record length
cannot exceed 263 (255 bytes for the line plus eight control
bytes). Trailing blanks are not included in the length.
LBPMLNSQ is a four-byte sequence number.
LBPMRESV is two bytes reserved for future expansion.
LBPMLINE is a record not exceeding 255 bytes in length. Trailing blanks
are dropped.
Notes
■ To write a blank line to a member, LBPMLNLN should contain nine (for
eight control bytes and and a one-byte record) and LBPMLINE should
contain one blank character.
5.3.17 RENAME Function

RENAME changes the name and specified attributes of the desired library
member.
Parameters
LBPMRFLG is a one-byte flag reserved for future expansion and must be
X'00'.
LBPMNAME is an 11-byte name of the member to be renamed. The name
must consist of a three-character prefix (or two characters
and a blank) and a name not exceeding eight characters in
length. Names less than eight characters must be padded
with spaces.
LBPMFLAG is a one-byte flag reserved for future expansion and must be
X'00'.

LBPMRNAM is an 11-byte new name for the library member. The name
must consist of a three-character prefix (or two characters
and a blank) and a name not exceeding eight characters in
length. Names less than eight characters must be padded
with spaces.
LBPMUNUS is a one-byte flag reserved for future expansion and must be
X'00'.
LBPMAFL1 is a one-byte flag indicating which attributes should be
changed. Specify:
X'02' Reserved.
X'04' Change member's attribute to RESTRICTED.
X'08' Change member's attribute from RESTRICTED to
SHARED.
X'10' Reset member's attribute from EXECONLY to
SHARED.
X'20' Change member's attribute to EXECONLY.
X'40' Change member's attribute to NOSEQ.
X'80' Change member's attribute to SEQ.
LBPMAFL2 is a one-byte reserved flag and must be X'00'.
LBPMAFL3 is a one-byte flag indicating which additional attribute fields
should be changed. Specify:
X'20' Change starting column of member's sequence
number field.
X'40' Change length of member's sequence number
field.
X'80' Change member's description.
LBPMCLNT is a one byte starting column of the sequence number.
LBPMSQLN is the one byte length of the sequence number.
LBPMDESC is a 30-byte description of the member.
Notes
LBPMAFL3 is not set.

5.3.18 SPACE Function

SPACE computes the number of available blocks and places the result in the
parameter area.
Parameter
LBPMSPA is the address of a fullword where result will be stored.
5.3.19 STATUS Function

STATUS retrieves the current status of library resources.
Parameter
LBPMSTA is the address of the Library Status Block (LBSB). The block is 12
bytes long and can be mapped by the Advantage CA-Roscoe
macro LBSB.
5.3.20 TERM Function

TERM terminates the LIBI interface. It must be specified in the last call on
LIBI.
Parameter
No parameter is passed.
Notes:
■ TERM does not release a library resource allocated by an ACTIVATE. Use
FREE to release a library resource.

5.4 Library Parameter Definition Macro (LBPMDEF)
5.4 Library Parameter Definition Macro (LBPMDEF)

The LBPMDEF macro generates the parameter list for the standard LIBI
functions.
LBPMDEF Macro
──┬─────┬──LBPMDEF──FUNC=func─────────────────────────────────
└─tag─┘
tag is a name that is at least four characters in length. Only the

first four characters are used in the generation of label
statements. If omitted, the default is LBPM. is LBPM.
FUNC=func
is the first three characters of a LIBI function. The default is ALL
which generates a DSECT with all possible parameters.
Example
LBPM LBPMDEF FUNC=ADD
will generate:
------------------------------------------------------------------
PARAMETERS FOR ROUTINES UPDATE,SAVE,ALTER,DELETE STARTS HERE
NOTE: ALSO REMAINDER OF PARAMETER FOR RENAME
------------------------------------------------------------------
LBPMFLAG DS XL1 RESERVED FOR FUTURE/PARAMETER FOR ADD

LBPMRNAM DS CL11 NEW NAME OF SECOND ENTRY OR ADD NAME
LBPMUNUS DS XL1 UNUSED
LBPMAFL1 DS XL1 FLAG BYTE 1
LBPMCLNT DS XL1 STARTING COLUMN OF A SEQUENCE NUMBER
LBPMSQLN DS XL1 LENGTH OF A SEQUENCE NUMBER
LBPMDESC DS CL3 DESCRIPTION

5.5 Library Request Block (LBRB)
5.5 Library Request Block (LBRB)

The LBRB (Library Request Block) is used for all requests to the LIBIO. It is
formatted by the LIBI interface as follows:
LBRBKID LBRBSTAT LBRBLNTP LBRBXRC

BLOCK ID STATUS FLAGS LINE TYPE EXTENDED RETURN
= X'A4' CODE
4 4 LBRBDBPT
POINTER TO LBDB
8 8 LBRBECDE LBRBDECB
ENTRY CODE DECB ADDRESS
C 12 LBRBXLST
ADDRESS OF EXIT LIST
1 16 LBRBPARM
ENTRY CODE DEPENDENT VALUE
14 2 LBRBAULB
ADDRESS OF LIMIT BLOCK
18 24 LBRBLBEP
ENTRY POINT OF LIBIO
1C 28 LBRBLCTA
ADDRESS OF LBCT
2 32
The following fields in the LBRB deserve special attention:

LBRBSTAT is a one-byte field contain one flag of interest to the LIBI
caller:
LBRBSEOF if on, a pseudo-EOF was encountered on a GET
operation. (A pseudo-EOF is forced when the
end of the member was preset by one of the
point functions (by count or ending sequence
number of field LBPMPNED of POINT
parameter list.
LBRBXRC is a field containing the code that descrives exception
conditions.
LBRBDBPT is a field pointing to the LBDB (Library Definition Block).
The LBDB describes the library resource and its status. By
changing different LBDB pointers into this field, different
library resources can be accessed. (FREE will free library
resources represented by the LBDB pointed to by
LBDRDBPT.)
LBRBECDE is a byte containing the request code set by the LIBI macro.
LBRBPARM is a fullword containing the address of the parameter list or
zero. (Zero for functions TERM and FREE.)


The LIBI routine validates requests before passing control to LIBIO. When an
error in a request is detected, LIBI generates an exception code. All such codes
have the high-order bit set (greater than 128).
The codes generated by LIBI are:

Code Meaning
X'81' Invalid request. INIT function not performed before this request or
invalid request.
X'82' GETMAIN for LIBI's work area failed.
X'85' An invalid entry code was found.
X'86' ROT and/or ATT1 address was not provided.
The following symbols defined in LBRB are set by other than LIBI and
describe additional exception conditions. (Each symbol is a one-byte value
mutually exclusive with all other values, rather than a mask.)
Code Value Meaning

LBRBXBRB 1 Field LBRBDBPT contains zero.
ACTIVATE function was not performed
or overlay of LBRB occurred.
LBRBXBFN 2 Requested function not allowed for
current library state. Most likely a PUT
was not performed before an ADD
function.
LBRBXSTO 3 The internal stack used by subroutine calls
has overflowed because subroutine
nesting is too deep. This represents an
internal logic error in LIBIO. Use of the
Interface must be terminated.
LBRBXNFD 4 Requested member was not found in
library.
LBRBXPRT 5 Function requested was intercepted by a
protection exception. The member is
protected or an illegal request was
encountered.
LBRBXERR 6 An I/O error has occurred.
LBRBXSPC 7 Additional blocks were needed in
ROSLIB0n but the file was full. Use of the
Interface must be terminated.

Code Value Meaning

LBRBXPOS 8 No records were found in range by
POINT logic.
LBRBXEOF 9 End of range or library member was
detected for GET or LIB request. The
LBRBEOF field may be examined for a
pseudo-EOF (end of range set by the
POINT function).
LBRBXIVK 10 Invalid key specified in FUNC=GETPFX
request.
LBRBXBSY 11 Request for additional resource failed. The
library resource did not become available
within a reasonable period of time.
LBRBXNWF 12 RENAME failed because the new member
name already exists.
LBRBXSOF 13 Start of member was detected while
pointing backwards.
LBRBXBAP 14 Missing or invalid parameter list.
LBRBXMSD 15 Missing DD statement - invalid JCL
LBRBXBIX 16 Invalid ROSLIB00 file or invalid
specification.
LBRBXNCR 17 Not enough storage to execute LIBI
interface.
LBRBXISP 18 Not enough space for additional index
entries on ROSLIB00.
LBRBXLIM 19 User exceeded his record save limit.
LBRBXIVP 20 Invalid prefix specified in
FUNC=GETKEY request.
LBRBXDIS 21 Request for immediate termination
encountered. Use of the interface must be
terminated.

Chapter 6. Exit Facilities
This segment of the manual describes the exit facilities that are provided with
Advantage CA-Roscoe. These exit facilities can be used for site security,
accountability and user convenience. The information about these exits is
divided into the following areas:
■ General information that is applicable to all site-written exit routines.
■ Detailed information about each available exit.
All of the exits are optional. If Advantage CA-Roscoe finds that an exit has
been enabled, the exit routine is called; otherwise, no action is taken. (An exit
is enabled when a module with a predefined name exists in the Advantage
CA-Roscoe load library.) Some of the exits are called at critical times during
the online execution (for example, when a user signs on, enters a command,
submits a job, and so forth.). Others are taken during the execution of a
specific function (for example, when a scheduled PRINT request is being
printed.
The remainder of this chapter contains a general overview of the types of exits
provided and the order in which they are called during a Advantage
CA-Roscoe session.
WARNING
Advantage CA-Roscoe internally invokes the member UPSEXIT to initialize
and maintain library protection. THIS IS NOT A STANDARD EXIT
FACILITY. Do not alter this member in any way; it must not be renamed,
modified, or deleted.
Chapter 6. Exit Facilities 6-1

6.1 Exit Types and Call Order

This section categorizes and summarizes the various types of exits provided
with Advantage CA-Roscoe and then describes the order in which they are
called.
6.1.1 Exit Categories

The exits can be divided into the general categories: 1) accounting exits, 2)
command or command-related exits, 3) security exits, and 4) session-oriented
exits. The following list identifies the exits by name and indicates the
command and/or action that causes the exit call.
6.1.1.1 Accounting Exits
A variety of accounting or accounting-related exits are provided with

Advantage CA-Roscoe. The exits include:
SMFEXIT can be used to supplement or replace the standard Advantage
CA-Roscoe accounting records. A site-written SMFEXIT routine is
called at system initialization and shutdown. It is also called for
every: 1) user sign-on, 2) user sign-off, and 3) execution of a
Monitor command that writes an accounting record.
SIGEXIT is called during sign-on. It can be used to add additional
information to each user's sign-on accounting record.
The contents of the user accounting field (SRUAF) of the accounting records
can be supplied by the exit provided with the ACCTDUMP program.
The ROSMAILS program includes an exit that sites can use to add charges
rates and/or comments to the ROSMAILS report.
The exit provided with the functionally stabilized ACCTREPT program allows
sites to: 1) add print lines to the report, 2) write their own reports, and 3) add
accounting information to other site accounting reports.
6.1.1.2 Command and Command-Related Exits
The exits in this category include:

ALLEXIT ALL is the Monitor routine exit.
AMSEXIT AMS is the Monitor routine exit.
AUTEXIT is the automatic terminal processing facilities exit.
BANEXIT is a banner page control exit.
| CLLEXIT is an ETSO exit. (Called by the CALL command, TSO command,
| or when an application executing under ETSO is invoked or
| terminated.)

CMDEXIT is a general command exit. (CMDEXIT is called during the

interpretation of every Advantage CA-Roscoe and RPF command.
CMDEXIT2 is a general command exit. (CMDEXIT2 is called after Advantage
CA-Roscoe has determined that a command is invalid.)
CONEXIT is the CONSOLE Monitor routine exit.
DISEXIT is the DISPLAY Monitor routine exit.
DSFEXIT is the Data Set Facility exit.
EXPEXIT is the EXPORT Monitor routine exit.
IMPEXIT is the IMPORT Monitor routine exit.
JOBEXIT is the PURGE Monitor routine exit.
LIBEXIT is the Library Facility exit.
MONEXIT is a general Monitor routine exit. (Called before each execution of
a Monitor command.)
OUTEXIT is a job output exit. (Called by the commands ATTACH JOB,
ALTER JOB, STATUS JOB and DETACH JOB.)
RPVEXIT is the PRINT command exit.
RTFEXIT is the RTF Monitor command exit.
SCREXIT is the SCREEN command exit. (Called when the user's terminal is
not defined as queriable and does not support the create-partition
structured field.)
SETEXIT is the SET commands exit.
SUBEXIT is the SUBMIT command exit.
ZAPEXIT is the ZAP Monitor routine exit.
6.1.1.3 Security Exits and Considerations
While all of the exits provided with Advantage CA-Roscoe can be used for site
security, three of the exits are explicitly security oriented. They are:
ACFEXIT is an online access facility exit which can be used to control the
site security environment.
DSAEXIT is an online data set access exit which can be used to control a
user's access to a requested data set.
BEXEXIT is a batch access authorization exit which can be used to control
the execution of the batch programs LIBSERVE, ROSCOPY and
ROSDATA.
Note: Advantage CA-Roscoe invokes package-specific processing based on
the site's security package as identified by the EXTSEC= initialization
parameter. If this parameter is omitted, Advantage CA-Roscoe assumes
that no security package is used by the site. (See the Advantage

CA-Roscoe Interactive Environment Programs and Utilities Guide for

additional information.)
RACF Considerations: If IBM's program product RACF (Resource Access

Control Facility) is the site's security system, the Advantage CA-Roscoe
initialization parameter EXTSEC=RACF should be specified.
■ Identifying Users
Before implementing any of the Advantage CA-Roscoe-supplied security
exits, sites must determine how their users are to identify themselves to
Advantage CA-Roscoe and to their security system.
The Advantage CA-Roscoe sign-on key is used to identify a user to
Advantage CA-Roscoe. It is recommended, therefore, that the Advantage
CA-Roscoe sign-on key and RACF userid be the same. If this method is
chosen, the sign-on key is limited by RACF restrictions. (The sign-on key
may be a maximum of seven characters in length and must be comprised
of all alphabetic and numeric characters.)
Sites not wanting to change existing sign-on keys (or be limited to
seven-character keys) can assign each user a unique group code. While a
group code has no meaning to Advantage CA-Roscoe, the code is made
available to the ACFEXIT exit routine which can treat the code as a RACF
userid. (Sites can also use a group code to provide additional user
identification.)
Caution
Use of group codes in place of sign-on keys as RACF identifiers
prohibits the use of BEXEXIT (the batch exit). The programs LIBSERVE,
ROSCOPY and ROSDATA require that the user sign-on key be
specified in the PARM field of the EXEC statement. When a BEXEXIT
routine is used, the user sign-on key must also be specified with the
USER= parameter on the JOB statement. If the user sign-on key is not
the RACF ID, RACF will reject the job.
■ Identifying Advantage CA-Roscoe

If an external security system is not used, the job ROSCOE must be
authorized to access any RACF-protected data set that a terminal user is
authorized to access. If an external security system is used, data set access
can be given to terminal users through the use of external security exits.
Modify the JOB statement for Advantage CA-Roscoe to include the
following parameters:
USER= Required. Specify a valid RACF userid.
PASSWORD= Required. Specify a RACF password that is associated
with the RACF userid.
GROUP= Optional. Specify a RACF group ID.
■ Exit Routine Considerations

When the Advantage CA-Roscoe initialization parameter EXTSEC=RACF is

specified and there is an ACFEXIT, sites must ensure that the field
SCBSENV contains the address of the RACF ACEE control block. (The
Advantage CA-Roscoe-supplied ACFEXIT exit routine does this.) If the
site modifies the Advantage CA-Roscoe-supplied routine or writes their
own, they must ensure that this field is properly set by the ACFEXIT
routine at the initialize call. The Advantage CA-Roscoe- supplied exit
routine also sets the field SCBACFB to the address of the RACF ACEE.
This is not required. Sites may use this field to address security-related
control blocks as long as their code in the DSAEXIT is written to take this
into consideration.
■ Sample Exit Routines
Sample ACFEXIT, DSAEXIT and SUBEXIT routines are provided by
Advantage CA-Roscoe for sites using RACF. The routines are distributed
on CAI.RO60OPT as the members ACFEXIT, DSAEXIT and SUBEXIT,
respectively.
6.1.1.4 Session-Oriented Exits
A session-oriented exit is called as appropriate during the execution of

Advantage CA-Roscoe. These exits include:
RCSEXIT is the ROSCOE Communication Services exit called each time
a session is established.
RDSEXIT is the ROSCOE Communications Services exit enabled by
RCSEXIT and called during Advantage CA-Roscoe data
stream formatting.
ROS3@ATH is an extended version of the DB2 Connection Management
authorization exit.
RPSEXIT is the ROSCOE Printing Services exit called whenever a
scheduled print requests is to be printed.
SMFEXIT is the accounting exit called during initialization and
thereafter whenever Advantage CA-Roscoe writes an
accounting record.
6.1.2 Exit Call Order

This section illustrates the order in which exit routines are called. The
illustrations assume that an exit routine is present for every exit (the
Advantage CA-Roscoe load library contains the modules with their predefined
exit routine names).
Two fields from UXDSECT are shown with each macro call:
UXIDCODE identifies the exit that is calling the routine.
UXCODE identifies the type of call to the routine.

To simplify the illustrations, the exit calls are grouped to show those occur
during:
1. Sign-on processing.
2. General command processing.
3. Individual command processing.
4. Monitor command processing.
6.1.2.1 Sign-on Processing
The ACFEXIT, SIGEXIT and SMFEXIT exits are called when an individual
signs on to Advantage CA-Roscoe (after the sign-on key and, if appropriate,
password are typed and the ENTER key is pressed.) The exit call order is:
1. ACFEXIT (Access Control Facility Exit). The exit routine is entered with:
UXIDCODE set to 1
UXCODE set to (verify call).
2. SIGEXIT (Sign-on Exit). The exit routine is entered with:
UXIDCODE set to 1
UXCODE set to (verify call) or 4 (restart call).
3. ACFEXIT (Access Control Facility Exit). This exit routine is entered with:
UXIDCODE set to 1
UXCODE set to 4 (initialize call).
4. SMFEXIT (Accounting Exit) The exit routine is entered with:
UXIDCODE set to 16
UXCODE set to (sign-on record call).
6.1.2.2 General Command Processing
After the user successfully signs on, he may begin entering commands. If
present, the Command Exit (CMDEXIT) verifies each command before
Advantage CA-Roscoe passes it against the Command Interpreter.
CMDEXIT (Command Exit). The exit routine is entered with:
UXIDCODE set to 3
UXCODE set to (verify command call).
The Command Interpreter validates commands and determines whether the

user entered a:
■ Advantage CA-Roscoe command. The appropriate command exit is called.
■ Monitor command. The appropriate command exit is called.
■ RPF program name. The program is executed.
If it is determined that the user entered an invalid command, the second

Command Exit (CMDEXIT2) is called.

CMDEXIT2 (Command Exit) The exit routine is entered with:

UXIDCODE set to 3
UXCODE set to 4 (invalid command call).
If CMDEXIT2 modifies the command, control returns to the Command

Interpreter. If CMDEXIT2 does not modify the command, a message is
displayed.
6.1.2.3 Individual Command Processing
If the Command Interpreter determines that the user entered a valid

Advantage CA-Roscoe command, the command is examined to see if an
individual command exit routine should be called.
Table 6-1 (Page 1 of 2). Individual Command Processing
Command Exit Routine Entered with:

ATTACH DSN DSFEXIT UXIDCODE set to 27
UXCODE set to 0 (initial call)
ALTER JOB OUTEXIT UXIDCODE set to 8
UXCODE set to 8
ATTACH JOB OUTEXIT UXIDCODE set to 8
UXCODE set to 0, 4, 8, 16 or 20
ATTACH LIB LIBEXIT UXIDCODE set to 29
UXCODE set to 0
CALL DSAEXIT UXIDCODE set to 4
(See Note 1) UXCODE set to 1-6, 12-26
CLLEXIT UXIDCODE set to 15
UXCODE set to 0, 4, 8
DETACH JOB OUTEXIT UXIDCODE set to 8
UXCODE set to 8
DSN DSFEXIT UXIDCODE set to 27
UXCODE set to 0
LIBRARY LIBEXIT UXIDCODE set to 20
UXCODE set to 0
OFF/OFFON ACFEXIT UXIDCODE set to 1
UXCODE set to 8 (terminate call)
SMFEXIT UXIDCODE set to 16
UXCODE set to 4 (sign-off record
call)
PASSWORD ACFEXIT UXIDCODE set to 1
UXCODE set to 12 (password call)

Table 6-1 (Page 2 of 2). Individual Command Processing

PRINT RPVEXIT n/a
n/a
SCREEN SCREXIT UXIDCODE set to 25
UXCODE set to 0
SET AUTOFF AUTEXIT UXIDCODE set to 26
UXCODE set to 8
SET STMTCNT AUTEXIT UXIDCODE set to 26
UXCODE set to 0
SET TLOCK AUTEXIT UXIDCODE set to 26
UXCODE set to 4
SUBMIT DSAEXIT UXIDCODE set to 4
SUBEXIT UXIDCODE set to 11
UXCODE set to 0, 4, 8, 12, 16, 20,
24
Notes
1. When a CALL command is executed, DSAEXIT is called only if the
application opens data set(s) or allocates an internal reader.
2. When a SUBMIT command is executed, DSAEXIT is called only if the job
opens data set(s). If there is no DSAEXIT, the UXCODE 12 call to a
SUBEXIT routine occurs.
6.1.2.4 Monitor Command Processing
If the Command Interpreter determines that the user entered a valid Monitor
command name, two global exit calls are issued before the individual Monitor
command exit routine is called.
The call order for these global exits is:

1. MONEXIT (Monitor Command Exit). The exit routine is entered with:
UXIDCODE set to 17
UXCODE not applicable.
2. SMFEXIT (Accounting Exit). The exit routine is entered with:
UXIDCODE set to 16
UXCODE set to 12.
The execution of the following Monitor commands causes a call to be issued to

the appropriate site-established exit routine:

Table 6-2. Monitor Command Processing

ALL ALLEXIT UXIDCODE set to 24
UXCODE set to 0
AMS AMSEXIT UXIDCODE set to 2
UXCODE set to 0, 4, 8 or 12
CONSOLE CONEXIT UXIDCODE set to 20
UXCODE set to 0, 8 or 16
DISPLAY DISEXIT UXIDCODE set to 5
UXCODE is not applicable
RTF RTFEXIT UXIDCODE set to 9
UXCODE set to 0 or 4
VTOC VTOEXIT UXIDCODE set to 13
If EXPORT, IMPORT, or ZAP is to perform a function that requires a data set

to be opened, a call to the Data Set Access Exit (DSAEXIT) is issued. For any
other functions, the appropriate exit routine is called.

EXPORT DSAEXIT UXIDCODE set to 4 (See Note 1.)
EXPEXIT UXIDCODE set to 6
UXCODE set to 0, 4, 8, 12, 16, 20, 24 or
28
IMPORT DSAEXIT UXIDCODE set to 4
EXPEXIT UXIDCODE set to 7
UXCODE set to 0, 4, 8, 12, 16, 20, 24 or
28
ZAP DSAEXIT UXIDCODE set to 4
ZAPEXIT UXIDCODE set to 14

Notes
1. The UXCODE 8 call to an EXPEXIT routine occurs only if there is no
DSAEXIT routine.
2. The UXCODE 12 call to an IMPEXIT routine occurs only if there is no
DSAEXIT routine.
3. The UXCODE 4 call to a ZAPEXIT routine occurs only if there is no
DSAEXIT routine.

Chapter 7. Information Common to all Exit Routines
This chapter describes the following information and conventions that are
common to all exits.
■ Common coding conventions.
■ Common register conventions.
■ Common data areas.
■ A macro that can be used to test site-written routines.
■ Macros that can be used to establish reentrancy.
■ JCL that can be used to assemble and link-edit an exit routine.
Chapter 7. Information Common to all Exit Routines 7-1

7.1 Common Coding Conventions
7.1 Common Coding Conventions

Unless noted otherwise, the following conventions apply to all exit routines:
■ Exit routines are LOADed during Advantage CA-Roscoe initialization, and
CALLed when necessary. Therefore, all exit routines must be reusable and
reentrant. (The macros UXENTER and UXEXIT can be used to establish
reentrancy.)
■ Since the exit routines become part of the online task at the main task
level:
– An error in an exit routine can cause a Advantage CA-Roscoe abend.
– System throughput and response are directly affected by their length
and complexity.
■ Advantage CA-Roscoe communicates with the exit routines by means of a
parameter list pointed to by register 1.
■ The exit routines communicate with Advantage CA-Roscoe by means of
codes returned in register 15. (If an exit routine uses extended return
codes, these codes are returned in register 0.)

7.2 Common Register Conventions
7.2 Common Register Conventions

Unless noted otherwise, the following register conventions apply upon
entrance to any exit routine:
Register 13 contains the address of the save area that is to be used to save
and restore the calling program's (Advantage CA-Roscoe's)
registers.
Register 14 contains the return address of the calling program (Advantage
CA-Roscoe).
Register 15 contains the entry point address of the called program.
Register 1 contains the address of a fullword. This fullword contains the
address of UXDSECT.

7.3 Common Data Areas

The DSECT UXDSECT contains the common and exit-dependent data areas
that are provided for use by any site-written exit routine.
7.3.1 Using the UXDSECT Macro

To make the data areas in UXDSECT available to the exit routine, the routine
must include the following macro:
UXDSECT Macro
──UXDSECT──┬───────────────────┬──────────────────────────────
│ ┌─,──────┐ │
┬──────┬┴──┘
└─EXIT=──
└─name─┘
name specify as either:

xxx is the first three characters of the exit routine name. If
multiple names are specified, they must be separated by
commas.
$ALL causes the resulting DSECT to map all data areas
available to all exits.
If only UXDSECT is specified or if a name is not specified with EXIT=, it is

treated as though $ALL is specified.
If UXDSECT is specified with a name, as in:

UXDSECT EXIT=(SUB)
all of the common and exit-dependent data areas are made available to the exit
routine. In this case, SUB are the first three characters of SUBEXIT (the
required name for a SUBMIT exit routine).
7.3.2 UXDSECT Data Area Descriptions

The common fullwords of UXDSECT contain addresses of data areas that are
available to all exit routines. The areas are:
UXIDCODE contains the address of a fullword containing a code that
identifies what exit is calling the routine. The code is in the
low-order byte of the fullword.
UXCODE contains the address of a fullword containing a code that
identifies what action the exit is handling. The code is in the
low-order byte of the fullword.
UXROTADR contains the address of the ROT.

UXSCBADR contains the address of the SCB.

UXPCBADR contains the address of the PCB.
UXRETFLG contains the address of a 1-byte field. This field is set by the
exit routine to designate the type of message to be sent to the
terminal user.
If a X'80' is set (ORed) into the field, a site-written message is
sent to the terminal user. (The message must be placed in the
area pointed to by the address in UXMSGADR.)
If a X'80' is not set into the 1-byte field, a Advantage
CA-Roscoe-supplied message is sent to the user.
The field pointed to by UXRETFLG is examined only when
the return code in register 15 is a value other than 0.
UXCALCTL contains the address of a bit map that is used by DSFEXIT
and LIBEXIT. (See the appropriate exit descriptions for
additional information.)
UXMSGADR contains the address of an area that is to contain a
site-written message that is to be written to the terminal. The
format of the message that the exit routine places in this area
is: a halfword containing the length of the message, a
halfword containing binary zeros and the message text,
which must not exceed 80 bytes in length.
X'length' X'0000' C'msg'
For example:
MSGLEN DC X'5'
DC X''
MSGTEXT DC C'HELLO'
UXWRKAREA
contains the first of four contiguous fullwords that are available
for the use of the exit routine.
In most cases, Advantage CA-Roscoe does not modify the
contents of the work area pointed to by UXWKAREA until
sign-off. The exception occurs with the exit routines called by
ATTACH JOB or the Data Set Facility. In these cases, their
operation can be suspended while other commands (that may
themselves have exits) are executed. In such cases, the contents of
UXWKAREA may be changed. To avoid this problem, UXDSECT
contains the two special work areas described next.
UXDSFWRK
contains the first of four contiguous fullwords provided for the
Data Set Facility.

UXOUTWRK
contains the first of four contiguous fullwords provided for
ATTACH JOB.
Notes
■ Referencing the Data Areas:
The documented labels used to reference the common and exit-dependent
data areas will not be changed. The location of these data areas within the
DSECT, however, may change in future releases. Therefore, all exit
routines should reference these data areas symbolically, rather than by
their offset.
■ Obtaining Additional Information:
An exit routine can use the addresses provided in the common data areas
to get additional information. For example, UXSCBADR points to the SCB.
The SCB data areas ATTLBPFX and ACCNUM can be used to obtain the
terminal user's prefix and sign-on key, respectively.
■ Split-Screen Sessions:
The data areas in UXDSECT uniquely identify a user's session. If a user
should split the screen, creating two Advantage CA-Roscoe sessions, each
session is covered by a separate UXDSECT. Information local to a session
may be saved in UXWKAREA. Information that could be used by either
or both sessions may be saved in the fields SCBUSER1 through SCBUSER4
in the SCB.
■ The following illustrates the common data areas that are provided by
UXDSECT. For details, see the UXDSECT DSECT.


7.4 Common Reentrancy Macros

The UXENTER and UXEXIT macros are provided to assist sites in writing
reentrant exit routines.
7.4.1 Using the UXENTER Macro

The UXENTER macro generates the: 1) code to handle addressability; 2)
register equates; and 3) routine identification information. (This routine
identification information includes the name of the routine and the date and
time the routine was assembled.)
UXENTER Macro
┌─,─────┐
┬─────┬┴─)──┬───────────────────┬────────
──UXENTER──REG=(reg──
└─reg─┘ │ ┌─YES─┐ │
└─,GENREG=─┴─NO──┴──┘
REG= identifies the base register(s). For example:

UXENTER REG=(12)
designates register 12 as the base register.
GENREG= specify whether register equates should be generated. If
omitted, the default is YES.
7.4.2 Using the UXEXIT Macro

The UXEXIT macro generates the code to handle returning control to the
calling routine.
UXEXIT Macro
──UXEXIT──RC=rc──┬──────────┬──┬───────────────────┬──────────
└─,XRC=xrc─┘ │ ┌─NO──┐ │
└─,XALINK=─┴─YES─┴──┘
RC= specify either:

■ the return code to be passed back to the calling routine.
The code can be any digit except 15 (for example, RC=8),
or
■ (15) or (R15) which causes the contents of register 15 to
be used. The exit routine must have loaded a return code
in register 15.

XRC= specify either:

■ the extended return code to be passed back to the calling
program. The code can be any digit except 0 (for
example, XRC=4), or
■ (0) or (R0) which causes the contents of register 0 to be
used. The exit routine must have loaded an extended
return code in register 0.
XALINK= designate whether macro expansion is to return to
Advantage CA-Roscoe using BSAM instruction. If omitted,
the default is NO. Specify either:
NO do not use BSAM instruction
YES use BSAM instruction.
Note: XALINK=YES should only be used by MVS/XA and
MVS/ESA sites and only when the individual exit
description states that it is required.

7.5 Testing a Site-written Exit Routine

To verify that a site-written exit routine is performing as expected, use the
macro SHOW to display specific information on entry to and exit from the
routine.
The macro causes a message to be written to the operator console and JES log
every time the exit routine is called. On entry to the exit routine, the messages
are in the following format:
time JOB number exit addr1 NAME csect offset CODE code
where:
exit is the name of the called exit routine.
addr1 is the absolute address to which the exit routine returns.
csect is the CSECT name of the calling routine.
offset is the offset into the CSECT to which the exit routine returns.
code is the UXCODE passed to the exit routine.
When returning from the exit routine, the messages are in the form:
time JOB number exit EXIT RETURN: R15 rc
where rc is a return code. (If the exit routine returns an extended return code,
it is included with the message.)
In addition to these messages, the SHOW macro also saves the contents of
registers 2 through 12 on entry to the exit routine. On exit, the 'saved'
registers are compared to those being returned by the exit routine. If they do
not compare, the 'saved' registers are returned and the following message is
written to the operator console:
time JOB number exit REGISTERS INVALID AFTER EXIT CALL
7.5.1 Installing the SHOW Macro

The procedure to install the SHOW macro documented below assumes that
you have already installed the user exit to be tested with the appropriate
product USERMOD through SMP/E.
Product USERMOD MRO604B is provided in the installation sample JCL to

implement the SHOW macro. Execute an SMP/E RECEIVE and APPLY on
MRO604B after making the following changes:
1. Change 'xxxEXIT' to the name of the exit you wish to test in each place
that it appears in MRO604B.
2. Edit member SHOWMON on the RO60OPT library, again changing
'xxxEXIT' to the name of the exit you wish to test.

The application of MRO604B will cause the SHOW macro to be assembled

with the name of the exit you wish to test. It will also cause the exit to be
re-linked with the assembled SHOW macro into the RO60LIB. The next time
the exit is executed, the SHOW messages will be received as documented
above.
When testing is concluded with the SHOW macro:

1. Execute an SMP/E RESTORE on MRO604B and the product USERMOD
which installed the user exit originally.
2. Execute an SMP/E RECEIVE and APPLY of the product USERMOD which
installed the user exit originally. At this point the user exit will be
assembled and re-linked to RO60LIB without the SHOW macro.

7.6 To Assemble and Link-Edit Exit Routines

Advantage CA-Roscoe exit routines are assembled and linked to your RO60LIB
by the SMP/E RECEIVE and APPLY of product USERMODs. The product
USERMODs follow the naming convention MRO60xx, and are found in the
installation sample JCL library. The table below defines which product
USERMOD should be used for each exit.
Sample source for each exit is placed in the RO60OPT data set by the SMP/E
apply of the base Advantage CA-Roscoe function SYSMOD CRO6000. A copy
of this sample source as shipped will be placed in the distribution library by
the SMP/E ACCEPT of the base Advantage CA-Roscoe function SYSMOD
CRO6000. The copy in the distribution library will be used for future SMP/E
restores or for your reference after making site changes to the original.
The process to install each product USERMOD has the following basic steps:
■ Modify the appropriate source member in RO60OPT.
■ 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 the desired exit into target library RO60LIB.
| ■ Exits should be linked in 24-bit mode.
| Note: Advantage CA-Roscoe distributed or site-written exits have the ability
| to address 31-bit mode; however, they must be linked into RO60LIB in
| 24-bit mode.
Table 7-1 (Page 1 of 2). Advantage CA-Roscoe Exit USERMODs
SAMPJCL SOURCE FUNCTION

MEMBER NAME NAME IN
RO60OPT
MRO6070 ACFEXIT Customize exit
MRO6072 AMSEXIT Customize exit
MRO6073 AUTEXIT Customize exit
MRO6074 BANEXIT Customize exit
MRO6075 BEXEXIT Customize exit
MRO6076 CLLEXIT Customize exit
MRO6077 CMDEXIT Customize exit
MRO6078 CONEXIT Customize exit
MRO6079 DISEXIT Customize exit
MRO607A DSAEXIT Customize exit
MRO607B DSFEXIT Customize exit

Table 7-1 (Page 2 of 2). Advantage CA-Roscoe Exit USERMODs
SAMPJCL SOURCE FUNCTION

MEMBER NAME NAME IN
RO60OPT
MRO607C EXPEXIT Customize exit
MRO607D IMPEXIT Customize exit
MRO607E JOBEXIT Customize exit
MRO607F LIBEXIT Customize exit
MRO6080 MONEXIT Customize exit
MRO6081 OUTEXIT Customize exit
MRO6082 RCSEXIT Customize exit
MRO6083 RDSEXIT Customize exit
MRO6084 RPSEXIT Customize exit
MRO6085 RPVEXIT Customize exit
MRO6086 SCREXIT Customize exit
MRO6087 SETEXIT Customize exit
MRO6088 SIGEXIT Customize exit
MRO6089 SMFEXIT Customize exit
MRO608A SUBEXIT Customize exit
MRO608D ZAPEXIT Customize exit
MRO608E RTFEXIT Customize exit

Chapter 8. Exit Descriptions
This chapter contains detailed information about each of the exits provided
with Advantage CA-Roscoe.
The descriptions are presented in alphabetical order and contain the following
information:
■ General description of the exit.
■ Coding conventions.
■ Entrance Parameters. This includes:
– The types of calls to the exit routine.
– The exit-dependent data areas available to the routine via UXDSECT.
(This is in addition to the common data areas available to the majority
of exit routines.)
■ Return codes and messages.
Chapter 8. Exit Descriptions 8-1

8.1 ACCTDUMP Program Exit
8.1 ACCTDUMP Program Exit

The ACCTDUMP program exit allows sites to complete the user accounting
field (SRUAF) in every accounting record.
Coding Conventions: The coding conventions are:

■ The exit routine must be present on the Advantage CA-Roscoe load library
named in the STEPLIB or JOBLIB DD statement for ACCTDUMP. While it
may be reentrant, but it is treated as a reusable resource.
■ The exit routine may have any name that is unique.
■ Standard OS linkage conventions are used.
Entrance Parameters: Upon entrance to the routine, register 1 contains

either:
1. The address of a fullword (where the fullword contains the address of the
accounting record), or
2. 0, indicating end-of-file.
The exit routine may add or modify the contents of the user accounting field
SRUAF. The information in this field is included in the accounting reports
when the SELECT (UAF) control statement is specified in the SYSIN file of the
ACCTREPT program. (The format of the accounting record is mapped by the
SRECORD macro which generates a DSECT containing the full record format.)
Return Codes: Before returning control, the exit routine must load one of the
following return codes into register 15.
Code Meaning
0 Normal return. Continue processing.
4 Do not call again. The exit routine is disabled.

8.2 ACFEXIT: Access Control Facility Exit

ACFEXIT is a generalized access control facility exit that can be used to control
the Advantage CA-Roscoe security environment. Five types of calls can be
made to ACFEXIT during a user's terminal session.
1. At sign-on, the verify call enables the access facility to check whether the
user may sign on. At this call, the exit routine should take no permanent
action because Advantage CA-Roscoe sign-on processing has not yet
completed.
2. After Advantage CA-Roscoe sign-on processing completes, the initialize
call may be used to create and initialize any control block(s) that the access
control facility requires for the user. The field SCBACFB in the SCB control
block may be used at the discretion of of the ACFEXIT routine to store
information related to the access control facility (for example, the address
of a user identification block). In addition, if the Advantage CA-Roscoe
initialization parameter EXTSEC=RACF is specified, the address of the
user's ACEE control block must be placed in the field SCBSENV of the SCB
control block.
3. When a password is altered (by the PASSWORD command), the password
change call enables the access control facility to validate the change and
update profile information it maintains.
4. At sign-off, the terminate call enables the access facility to return any
memory obtained during the initialize call, and to take any other
appropriate action to sign the user off.
5. When the Terminal Lock screen is displayed and the user has entered a
password, the unlock call enables the access control facility to validate the
password entered by the user.

■ The exit routine must be reentrant and present as a load module in either
the Advantage CA-Roscoe load library or a library concatenated to it.
■ The name of the exit routine must be ACFEXIT.
■ The routine must include the UXDSECT macro in the form:
UXDSECT EXIT=(ACF)
| ■ The member ACFEXIT on CAI.RO60OPT contains a sample exit routine.

Entrance Parameters: Upon entrance to the routine, register 1 contains the

address of a fullword. The fullword contains the address of UXDSECT.
For this exit:

UDIXCODE contains the exit identifier code 1.
UXCODE contains one of the following codes (in the low-order byte)
that identifies the type of call being made to the exit routine.
Code Meaning
0 Verify call (EQU UXAC@VER). This call occurs
when a terminal user signs on to Advantage
CA-Roscoe.
4 Initialize call (EQU UXAC@INT). This call occurs
when a terminal user signs on to Advantage
CA-Roscoe.
8 Terminate call (EQU UXAC@TRM). This call
occurs when a terminal user signs off of
12 Password change call (EQU UXAC@PSW). This
call occurs when a terminal user enters the
PASSWORD command.
16 Terminal unlock call (EQU UXAC@UNL). This
call occurs when the user's terminal is locked and
the user enters a password to unlock it.
In addition to 7.3, “Common Data Areas” on page 7-4, the following

exit-dependent data areas are available to the exit routine:
UXACFPSW is the address of the area containing the user's password,
padded to ten characters. This field will be passed to the
security system on a RACINIT type call as the PASSWORD=
parameter. (If no password is entered, the area contains four
bytes of hexadecimal zeros. If a password is entered, it is
present when the entrance code is 0, 4, 12 or 16.)
UXACFNPS is the address of the area containing the new password,
padded to ten characters. This field will be passed to the
security system on a RACINIT type call as the NEWPASS=
parameter. (If no new password is entered, the area contains
four bytes of hexadecimal zeros. If a new password is
entered, it is present when the entrance code is 0, 4 or 12.)

UXACFGRP is the address of the area containing the user's group code,
padded to eight characters. This field will be passed to the
security system on a RACINIT type call as the GROUP=
parameter. (If the user enters a group code, it is present
when the entrance code is 0 or 4.)
UXACFTRM is the address of the area containing the terminal ID padded
to eight characters. See the description of the area
SCBTRMNM located in Chapter 1, topic 1.2.2, for an
explanation of the ID format. This field will be passed to the
security system on a RACINIT type call as the TERMID=
parameter. (The ID is present for all calls.)
UXACFINF is the address of a storage area, provided by the exit routine,
that contains messages which are to be directed to the
terminal user. (This field is available when the entrance code
is 0 or 4.)
UXACFACD is the address of the area containing the user's ID that is to
be passed to the security system. This field is extracted from
the Advantage CA-Roscoe sign-on key. If the sign-on key is
eight or less characters and does not contain a period (.), then
this field is set to the Advantage CA-Roscoe sign-on key. If
the sign-on key is greater than eight characters, the first eight
characters are used. If a period is found within the first eight
characters of the sign-on key, this field is set to the string up
to the period (.). This field will be passed to the security
system on a RACINIT type call as the USERID= parameter.
(This field is available when the entrance code is 0 or 4.)
UXACFPGM is the address of the area containing the name of the user,
padded to 20 characters. This field is extracted from the
Advantage CA-Roscoe formal key. This field will be passed
to the security system on a RACINIT type call as the
PGMNAME= parameter. (This field is available when the
entrance code is 0 or 4.)
Return Codes: Before returning control to Advantage CA-Roscoe, the exit

routine must load a return code in register 15. The extended return code
should be loaded into register 0. The meaning of the return code depends on
the entrance code pointed to by UXCODE on entry to the routine.

ENTR. RETURN EXT. INT/EXT MEANING SINGLE MULTI

CODE CODE RETURN SECURITY MESSAGE MESSAGE
0 0 n/a Internal Normal return. no yes
n/a External Continue with sign-on. no yes
4 X'00' Internal Successful verification. Advantage yes yes
CA-Roscoe is to validate password.
X'04' Internal User unknown to access facility, or yes no
excessive number of incorrect passwords.
X'08' Internal Unauthorized password. yes no
X'0C' Internal Expired password. yes no
X'10' Internal Invalid new password. yes no
X'14' Internal User not defined to group. yes no
X'18' Internal reserved n/a n/a
X'1C' Internal User's access has been revoked. yes no
4 X'20' Internal Access control facility not currently active. yes no
(cont.)
X'24' Internal User's group access has been revoked. yes no
X'2C' Internal reserved n/a n/a
X'30' Internal User unauthorized to use this terminal. yes no
X'34' Internal User not authorized to use this application. yes no
X'3C' Internal reserved n/a n/a
X'40' Internal Successful verification. Advantage no yes
CA-Roscoe is not to validate the password.
n/a External Reject sign-on attempt. yes no
4 X'00' External Advantage CA-Roscoe is to validate yes no
(cont.) password.
4 0 n/a Internal Normal return. no yes
n/a External Continue with sign-on. no yes
4 X'00' Internal Successful initialization. yes yes
X'04' Internal Initialization failed. User signed off. yes no
n/a External User signed off. yes no
8 0 n/a n/a Normal return. no no
4 n/a n/a Exit controlled termination.
4 X'00' Internal Password successfully updated. yes no
X'04' Internal Password not updated. yes no
n/a External Reject password change. yes no
4 n/a n/a Password rejected./Terminal unlock yes no
denied.

Single or multiple messages may be sent to the user's terminal when the
Message field contains 'YES'. If both types of messages are sent, the multiple
messages are sent to the terminal after the single message.
■ Sending A Single Message
If the Message field labeled One contains 'YES', an ACFEXIT or site-written
message is sent to the user's terminal.
1. Set (OR) a X'80' into the 1-byte field pointed to by UXRETFLG of
UXDSECT. (If the field pointed to by UXRETFLG is not set to X'80', the
appropriate ACFEXIT message is sent to the terminal.)
2. Place the message length and text in the area whose address is in
UXMSGADR of UXDSECT.
The format of the message area pointed to by the address in UXMSGADR
must be: a halfword length field, a halfword containing binary zeros and
the message text which may not exceed 80 bytes in length.
■ Sending Multiple Site-Written Messages
If the Message field labeled Multi in the preceding chart contains 'YES',
multiple informational messages may be sent to a user who is going to be
signed on. To do this, the exit routine must GETMAIN an 88-byte area of
storage in subpool 0, AMODE 24 storage for each message to be issued to
the user.
– The first word of each area must contain either the address of the next
message area or zero if there are no more messages.
– The second word must contain the length of the message, which
cannot exceed 80 bytes in length.
– The message text must begin in the third word.
The exit routine then places the address of the first GETMAINed area in
the field UXACFINF and loads a return code of 4 into register 15.
When this procedure is followed, Advantage CA-Roscoe issues the
messages to the terminal user after the HELLO message and then
FREEMAINs the storage area(s). The exit routine must not attempt to use
this area for any other purpose or free the acquired storage area;
Advantage CA-Roscoe issues the appropriate FREEMAIN.
Notes
■ While messages may be issued as a result of both the 0 and 4 calls, the set
of messages returned by the last call prior to a successful sign-on are the
only ones the user receives. Thus, if messages are returned for both 0 and
4 calls, only the messages associated with the 4 call are issued to the user.
■ When the entrance code is 4, the return code is 4 and the extended return
code is X'00', a single-line message must be specified if a multi-line
message is to be transmitted. (A multi-line message is not required if only
a single-line message is to be transmitted.)

■ If desired, a GETMAIN (for example, for a control block) may be issued in

the initialize call, with the related FREEMAIN call in the terminate code.
■ The terminate call may be invoked by Advantage CA-Roscoe even if no
initialize call was invoked (the termination code should not depend on the
successful completion of an initialize call).
■ The verify call may be executed a number of times in succession by
Advantage CA-Roscoe even after a successful verification code (X'00' or
X'40') is returned. Consequently, any GETMAIN in the verify call must
have the related FREEMAIN in the same call.
■ The user parameters (key, password, and so forth) for an initialize call are
identical to the parameters for the last executed verify call.

8.3 AMSEXIT: AMS Routine Exit

The AMS exit can be used to filter the input to or output from AMS.
As an input filter, the exit routine may direct AMS to do one of the following:
■ Pass the input record, unmodified, to IDCAMS.
■ Terminate IDCAMS and issue zero or more messages.
■ Substitute one or more records for a single user input record.
As an output filter, the exit routine may direct AMS to suppress the output
record or to return it to Advantage CA-Roscoe. The record may be modified
by the exit routine before being returned.

■ The name of the exit routine must be AMSEXIT.
UXDSECT EXIT=(AMS)
Entrance Parameters:
Upon entrance to the routine, register 1 contains the address of a fullword. The
fullword contains the address of UXDSECT.
For this exit:

UXIDCODE contains the exit identifier code of 2.
UXCODE contains one of the following codes (in the low-order byte).
The code identifies the type of call being made to the exit
routine.
Code Meaning
0 Initial call (EQU UXAM@1ST).
4 Input call (EQU UXAM@INP).
8 Output call (EQU UXAM@OUT).
12 Last call (EQU UXAM@LST).


UXAMSREC
address of the record to be input or output. (The address is
supplied by Advantage CA-Roscoe when the entrance code is 4.
The address must be supplied by the exit routine when the
entrance code is 8.)
The record consists of a 1-byte buffer length field followed by the
buffer containing the data. The buffer length field contains either
80 (for input records or 120 (for output records). The length of the
buffer containing data data is 0 to 72 (for input records) or 0 to
120 (for output records).
UXAMSSUB
Address of the address list of records to be substituted. (The
address must be supplied by the exit routine when the entrance
code is 8.)

routine must load a return code in register 15. The meaning of the return code
depends on the entrance code pointed to by UXCODE on entry to the routine.
ENTRANCE RETURN MEANING MESSAGE

CODE CODE
0 0 This is the only valid no
return code from an initial
call.
4 0 Pass record to IDCAMS. no
4 Terminate user. yes
8 Substitute input stream. n/a
The address of the address
list of substitute records
must be placed in
UXAMSSUB. Indicate the
last address in the list with
a X'80' in the high-order
byte.
The first byte of each
substitution record must
contain the length of the
record; the data to be
output must begin in the
second byte. The data may
not exceed 80 characters in
length.


CODE CODE
8 0 Return record to no
The exit routine must load
the address of the record
into AMSREC. The exit
routine can modify or
expand the record to a
maximum of 120
characters.
4 Suppress record. yes
12 0 Only valid return code. no
When the Message field contains 'YES', a AMSEXIT or site-written message is

sent to the terminal. To send a site-written message to the terminal:
UXDSECT. (If the field pointed to by UXRETFLG is not set to a X'80', the
appropriate AMSEXIT message is sent to the terminal.)

must be: a halfword length field, a halfword containing binary zeros and the
message text which may not exceed 80 bytes in length.

8.4 AUTEXIT: Automatic Exit

AUTEXIT can be used to control Advantage CA-Roscoe's automatic terminal
processing facilities. AUTEXIT is called when:
1. The terminal is about to be forced off because:
■ The sign-on screen has been displayed the number of minutes specified
with the AUTOFF initialization parameter and there has been no
activity (no one has attempted to sign on), or
■ A session is in progress and there has been no activity for the number
of minutes specified with the AUTOFVAL parameter and/or the SET
AUTOFF command. ('No activity' means that Advantage CA-Roscoe is
waiting for the user to enter a command or respond to terminal
output.)
2. The Terminal Lock screen is about to be displayed because:
■ A session is in progress and there has been no activity for the number
of minutes specified with the AUTTLVAL and or the SET TLOCK
command.
■ The user has entered the SET TLOCK NOW command.
■ The user has entered the RCS escape command to lock the terminal.
Coding Conventions: The coding conventions are as follows:

■ The name of the exit routine must be AUTEXIT.
UXDSECT EXIT=(AUT)
| ■ The member AUTEXIT on CAI.RO60OPT contains a sample exit routine.

For this exit, the area pointed to by the address in UXIDCODE contains the
exit identifier 18.

The address in UXCODE points to a fullword that contains one of the

following codes (in the low-order byte). The codes identify the type of call
being made to the exit routine.
Code Meaning
0 Reserved.
4 Sign-off call (EQU UXAU@OFF). This call occurs prior to a terminal
being automatically signed off
The UXDSECT field UXSCBADR can be used to determine the type
of sign-off. If it contains:
zeros The Advantage CA-Roscoe sign-on screen is currently
displayed and no one has attempted to sign on within
the specified time period.
SCB addr Advantage CA-Roscoe is in terminal input mode
(waiting for the user to enter a command).
The UXDSECT field UXPCBADR is set to zeros.
8 Terminal Lock processing (EQU UXAU@LAU). This call occurs
prior to the Terminal Lock screen being displayed because of
inactivity.
The UXDSECT field UXSCBADR contains the address of the SCB;
the field UXPCBADR contains zeros.
12 RCS escape command (EQU UXAU@LRC). This call occurs when
the user has entered the RCS escape sequence requesting the
Terminal Lock screen be displayed.
The UXDSECT field UXSCBADR contains the address of the SCB;
the field UXPCBADR contains the address of the PCB.
16 SET TLOCK NOW (EQU UXAU@LST). This call occurs when the
user has enters the SET TLOCK NOW command.
The UXDSECT field UXSCBADR contains the address of the SCB.
The field UXPCBADR contains the address of the PCB.

UXAUTTRM Address of the area containing the terminal id, padded to 8
characters. See the description of the area SCBTRMNM in
Chapter 1, topic 1.2.2, for an explanation of the ID format.
(The ID is present for all calls.)



CODE CODE
0 Reserved.
4 0 Normal return. no
4 Sign-off rejected. (The no
terminal remains signed
on.)
8 0 Normal return. Allow lock. no
4 Reject lock. Continue no
session.
8 Reject lock. Sign user off. no
4 Reject lock. Continue no
session.
4 Reject lock. Continue yes
session.
When the Message field contains 'YES', a AUTEXIT or site-written message is

appropriate AUTEXIT message is sent to the terminal.)


8.5 BANEXIT: Banner Page Exit

The BANEXIT is called when a user opens a file that has been allocated to
SYSOUT. (It is not called when the allocation is for a SYSOUT file for an
internal reader.) This exit permits sites to provide their own SYSOUT
separator pages, rather than using the ones provided with Advantage
CA-Roscoe.

■ The name of the exit routine must be BANEXIT.
UXDSECT EXIT=(BAN)
■ For MVS/XA sites, the routine must be link-edited with an attribute of
AMODE=31, RMODE=24.
■ In an MVS/XA environment, the routine should expect to be called in
31-bit Addressing Mode using a BASSM instruction; return to Advantage
CA-Roscoe should be made via a BSM instruction. This can be
accomplished by using the XALINK=YES parameter on the UXEXIT macro.

exit identifier 28.

Code Meaning
0 ETSO SYSOUT call (EQU UXBA@DTA).
4 RPS (PRINT) SYSOUT call (EQU UXBA@RPS).


UXBANDTA Address of a 133-byte area into which the exit routine may
return either:
1. One line of data that is to be written to the allocated
SYSOUT file. (The line is initialized to blanks before
being passed to the exit routine.)
2. One- to eight-characters which are written in 12-line
block letter format.
UXBANPGM Address of an area containing either:
1. The name of the program beginning called (for ETSO)
calls), or
2. 'RPS' (for RPS calls).
UXBANTIM Address of a five-character area containing the current time
in the format: hh:mm.
UXBANDAT Address of an eight-character area containing the current
date in the format: mm/dd/yy.
The following data areas are available for RPS SYSOUT calls (when the
entrance code is 4).
UXBANPRT Address of the printer ID. The address points to an area
containing a two-byte length followed by the name of the
printer.
UXBANDST Address of the RPS-defined destination name.
UXBANREQ Address of the six-byte request number.
UXBANKEY Address of the 22-byte user sign-on key.
UXBANPFX Address of the three-byte user prefix.
UXBANCLS Address of one-byte SYSOUT class.
UXBANTAB Address of eight-byte request tag or blanks if the user did
not supply a tag.

routine must load one of the following return codes in register 15.
Code Meaning
0 Calling program is to write the contents of the area whose
address is in UXBANDTA and to call again.
4 Calling program is to write the first eight characters in the
area whose address is in UXBANDTA in 12-line block letter
format and to call again.

Code Meaning
8 Calling program is not to call again. (No separator page is
written.)
Notes
■ The exit routine is passed the address of an area in which the routine may
return one-by-one each line that is to be written to the SYSOUT file.
The exit routine may return one to eight characters of data which are to be
written to the SYSOUT file in a 12-line block format.
■ The program that calls the routine takes care of opening and closing the
SYSOUT file and writing the records returned by the routine.
■ The UXWKAREA fields are cleared before the banner page exit is called
the first time. Use of these work area fields is recommended for storing
status information between calls to BANEXIT when writing a set of
separator pages.

8.6 BEXEXIT: Batch Access Authorization Exit

BEXEXIT may be used for site verification of batch access authorization. The
same exit is used by the offline utilities ROSDATA, ROSCOPY, LIBSERVE and
LIBUTIL. If an exit routine is present, it is called before any data sets are
opened.
A BEXEXIT routine can be used to check whether batch execution may

proceed.

■ The routine must be linked as part of LIBSERVE, ROSCOPY and
ROSDATA.
■ The name of the exit routine must be BEXEXIT.

address of the following parameter list:
BEXCALLR Address of a fullword containing a code that identifies how
the routine is being called. The codes are:
1 ROSDATA
2 ROSCOPY
3 LIBSERVE
4 LIBUTIL
BEXSUBCD Address of a fullword containing a code that indicates the
type of call:
1 Initialize call (before any data sets are opened).
2 Initialize complete call (after all Advantage
CA-Roscoe data sets are opened but before any
user data sets are opened).
3 Finalize call.
BEXKEY Address of the sign-on key from the PARM field.
BEXACCRD Address of the UPSREAD entry point. (UPSREAD, 9.5,
“UPSREAD Routine” on page 9-7, is a routine that may be
used by the exit to read user profile records from the
Advantage CA-Roscoe libraries.)

Return Codes: On return, the exit routine must load one of the following
return codes in register 15.
Code Meaning
0 Access authorized; run may continue.
4 Access unauthorized; run is terminated.
Notes
| ■ The sample BEXEXIT routine distributed with Advantage CA-Roscoe
| assumes the use of SAF compliant calls. If running eTrust CA-Top Secret
| or eTrust CA-ACF2, please use their supplied BEXEXIT with our listed
| routines. Except in the case of the LIBUTIL routine and eTrust CA-Top
| Secret; then the Advantage CA-Roscoe supplied BEXEXIT must be used.
| ■ When the Advantage CA-Roscoe-supplied BEXEXIT exit routine is used,
| the userid of an authorized user must be specified with the USER=
| parameter on the JOB statement. The user's sign-on key must be specified
| as a parameter on the EXEC statement for ROSDATA, ROSCOPY, and
| LIBSERVE. (Sites must modify the distributed routine to include the
| sign-on keys of all users who are to be allowed access.)
■ The batch exit should take whatever action is necessary at initialization to
enable the Advantage CA-Roscoe data sets to be opened, since the job is
running under the user-id of the submitter. In addition, during the
initialize complete call, the exit must change the job environment to allow
the submitter's data sets to be opened (the environment must be returned
to its original state).
■ The initialize call should be used to establish whether processing may
continue. If processing is to continue, the routine should make whatever
changes are necessary to the operating environment to enable the
Advantage CA-Roscoe data sets to be opened.
■ The initialize complete call should restore the operating environment to the
state which enables the user data sets to be opened.
| ■ When the BEXEXIT is called by LIBUTIL (BEXCALLR=4), the BEXKEY
| field will contain binary zeros. LIBUTIL does NOT pass the user's sign-on
| key on the PARM field.
| ■ LIBUTL, due to it's multifunctionality, does not call the BEXEXIT initialize
| or complete calls prior opening any files.

8.6.1 Implementing BEXEXIT

For BEXEXIT to be invoked, ROSDATA, ROSCOPY, LIBSERVE, and LIBUTIL
must be relinked with an include for BEXEXIT. BEXEXIT is assembled and
| linked with ROSDATA, ROSCOPY and LIBSERVE to your RO60LIB by the
| SMP/E RECEIVE and APPLY of USERMOD MRO6075.
Sample source for BEXEXIT is placed in the RO60OPT data set by the SMP/E
APPLY of the base Advantage CA-Roscoe function SYSMOD CRO6000. A copy
of this sample source as shipped will be placed in the distribution library by
the SMP/E ACCEPT of the base Advantage CA-Roscoe function SYSMOD
CRO6000. The copy in the distribution library will be used for future SMP/E
RESTOREs or for your reference after making site changes to the original.

8.7 CLLEXIT: ETSO Exit

| The CLLEXIT exit is called whenever an ETSO application is invoked (using
| the CALL or TSO command) or terminated.

■ The name of the exit routine must be CLLEXIT.
UXDSECT EXIT=(CLL)

exit identifier 15.

Code Meaning
0 Program execution has been invoked by the CALL command. This
call can be used to determine whether the terminal user may
execute the CALLed program.
4 Program execution has terminated. This call can be used to monitor
the number of ETSO applications that are executing concurrently.
(A site might use this information, for example, to limit the number
of users executing an application at the same time.)
8 Occurs after program execution has been invoked (after an entrance
code of 0) but before the program begins executing.

UXCLLPRG Address of the program name specified in the CALL
command. (This address is valid when the entrance code is 0
or 4.)
UXCLLPRL Address of a halfword field containing the length of the
parameter list. (This address is valid when the entrance code
is 0.)

UXCLLPRM Address of the parameter list. (This address is valid when the
UXCLPRFX Address of the user's three-character prefix. (This address is
valid when the entrance code is 0 or 4.)
UXCLCPPL Address of the CPPL (Command Processor Parameter List).
The exit can change any of the fields in the CPPL or any of
the control blocks chained off of the CPPL. For example, an
exit routine could permit certain individuals TSO OPER
authority by setting the appropriate bit in the PSCB. (This
address is valid when the entrance code is 8.)
UXCLMAXT Address of a halfword containing the maximum number of
time slices the program is allowed to use. (This address is
valid when the entrance code is 0.)
UXCLMTGM Address of a fullword containing the maximum amount of
storage that the program can GETMAIN. (This address is
UXCLMVGM Address of a fullword containing the maximum variable
GETMAIN requests allowed at one time. (This address is
UXCLMODE Address of a 1-byte field containing a 'Y' if modeset is
allowed by the user program or an 'N' if it is not. (This
UXCLDUMP Address of a 1-byte field containing a 'D' or 'Y' if a dump is
to be taken if the program abnormally terminates. (This
UXCL#USD Address of a halfword containing the number of time slices
used by the program. (This address is valid when when the
UXCLTOTL Address of a fullword containing the total amount of storage
the program used. (This address is valid when the entrance
code is 4.)
UXCLHIGH Address of a fullword containing the largest amount of
storage that the program required during execution. (This
UXCLREAS Address of a one-byte field containing a code that indicates
when a program terminated abnormally. (This address is
The codes are:
0 Normal termination (EQU UXCLNORM).
1 Program not found (EQU UXCLNFND).
2 Time limit exceeded (EQU UXCLNTIM).

3 Data set access contravention (EQU UXCLASCCS).

4 Illegal SVC issued (EQU UXCLSVC).
5 Bad DCB from application (EQU UXCLBDCB).
6 AWS allocation error (EQU UXCLAWER).
7 Unallocated file (EQU UXCLUNAL).
8 Internal error (EQU UXCLINTE).
9 Maximum GETMAIN exceeded (EQU
UXCLMGTM).
10 Program cancelled (EQU UXCLCAN).
11 Full screen I/O illegal (EQU UXCLBFSC).
12 Buffer overflow (EQU UXCLOVFL).
13 DYNALLOC Error - unsupported (EQU
UXCLDYN1).
14 AWS or library member is full (EQU UXCLFULL).


CODE CODE
0 0 Execution is authorized. no
4 Execution is not yes
authorized.
return code.
return code.
When the Message field contains 'YES', a CLLEXIT or site-written message is

appropriate CLLEXIT message is sent to the terminal.)


Notes
■ If a DSAEXIT routine is present, it is called whenever a program executing
under ETSO attempts to allocate a new or existing data set or opens an
internal reader.
| ■ If ETSOXIT=YES was specified in your ROSCOE startup, then the
| CLLEXIT will also be called for commands invoked using the TSO
| command.

8.8 CMDEXIT and CMDEXIT2: Command Exits

CMDEXIT is called during the interpretation of every Advantage CA-Roscoe
and RPF command. CMDEXIT2 is called after it has been determined that the
command is invalid. When a command is entered at the terminal or by an RPF
program, the following hierarchical evaluation is performed:
1. The CMDEXIT exit routine is called before the command is validated.
This is the only time the exit routine is called. (The area pointed to by
UXCODE on entry contains 0.) The exit routine may perform whatever
processing is appropriate, including modifying the command.
2. The command interpreter table is searched to determine if the user entered
a valid Advantage CA-Roscoe command, command abbreviation or RPF
program name.
■ If the user entered a valid command, it is executed.
■ If the user did not enter a valid Advantage CA-Roscoe command,
command abbreviation or RPF program name, the 'word' is compared
against the names of Monitor commands installed at the site.
– If the first three character of the 'word' match the first three
characters of a Monitor command name, it is executed as a
Monitor command.
– If the command is not a valid Monitor command, it is compared
against the names of the members in:
— The user's library, if no prefix is specified.
— The optional RPF execution library, if no prefix is specified.
— The library of the owner of the prefix, if a prefix is specified.
If the command matches a library member name, the member is
assumed to contain an RPF program, and it is executed.
3. If the command is not the name of an RPF program, the CMDEXIT2 exit
routine is called. The exit routine is called only once. (The area pointed to
by UXCODE contains 4.)
■ If the CMDEXIT2 exit routine modifies the command, the preceding
search procedure is repeated.
■ If the command is not modified by the CMDEXIT2 exit routine, a
message is displayed.


■ The name of the exit routines must be CMDEXIT and CMDEXIT2.
■ Each routine must include the UXDSECT macro in the form:
UXDSECT EXIT=(CMD)
■ CMDEXIT should be used when the exit routine's processing is to include
every command. For example, a CMDEXIT exit routine would be needed if
a site wants to record the number of times the EXEC and IMPORT
commands are executed.
Note: CMDEXIT should be used with care. This exit routine goes through
exit initialization and execution for every command processed by
CMDEXIT2 should be used when the exit routine is to handle commands
that would otherwise be invalid to Advantage CA-Roscoe. For example, a
CMDEXIT2 exit routine would be needed if a site wants to translate:
CHANGE A TO B
to
EDIT /A/B/
If a site wants to evaluate every command and modify certain invalid
commands, two exit routines should be written.
■ The routines should not load other programs from a library and should
perform no I/O. The command interpreter, which calls the exit routine, is
one of the most heavily used routines in Advantage CA-Roscoe. It is part
of the main task level and must process every command that Advantage
CA-Roscoe is to execute. It is, therefore, to be handled as a critical path.
■ The member CMDEXIT on ROSCOE.SOURCE contains a sample exit
routine.
Entrance Parameters: Upon entrance to either routine, register 1 contains the

For these exits, the area pointed to by the address in UXIDCODE contains the
exit identifier 3.


Code Meaning
0 CMDEXIT call (EQU UXCM@1ST). The command interpreter has
not yet determined whether the input can be recognized as a valid
command. The input presented to the CMDEXIT exit routine is the
raw input and its address is in UXCMDINP. Every input string to
be processed by the command interpreter is passed to CMDEXIT.
Unless very elaborate analysis routines are used, few meaningful
results can be achieved by processing the raw string.
4 CMDEXIT2 call (EQU UXCM@2ND). It has been determined that
the input cannot be recognized as a valid command. The exit
routine may convert the input string into a form acceptable to
If the output of the CMDEXIT2 exit routine is itself as unrecognized
command, there is no further entrance to the exit for this input.

UXCMDINP Address of the input record. (This address is valid for both
calls.)
The record is a copy of the user's input. The area is 255
bytes long and is blank-filled to the right of the last input
character. The command is presented to the exit routine
exactly as entered from the terminal or RPF program (no
lowercase to uppercase translation has been performed). Do
not modify the data in this area. Use UXCMDOUT if a work
area is needed.
UXCMDOUT Address of the area to be used to build a replacement
command. (This address is valid for both calls.)
The data in this area replaces the input record only if register
15 contains 4 on return from CMDEXIT and/or CMDEXIT2.
The format of the area pointed to by UXCMDOUT must be a
halfword length field followed by the replacement command
which may not exceed 255 characters in length.

routine must load one of the following return codes in register 15:

CODE CODE
0 0 Command is to be no
processed as entered by the
user.
and


CODE CODE
4 4 Command is to be replaced. no
The replacement command
must be placed in the area
pointed to by UXCMDOUT.
8 Command is to be rejected. yes
When the Message field contains 'YES', a command exit or site-written

message is sent to the terminal. To send a site-written message to the terminal:
appropriate command exit message is sent to the terminal.)
The format of the message area pointed to by the address in USMSGADR must
be: a halfword length field, a halfword containing binary zeros and the
Notes
■ A message written to the terminal can be TRAPped in an RPF program. If
the message is site-written, it receives the same trap code as the standard
exit message. (The RPF system variable LASTERR always contains the text
of the standard message, even if a site-written message was sent.)
■ If Advantage CA-Roscoe detects any errors on the part of either of the exit
routines (such as invalid return code), that exit routine is cancelled for the
remainder of the Advantage CA-Roscoe execution, and the console
operator is informed with message ROS350E.

8.9 CONEXIT: CONSOLE Routine Exit

The CONSOLE exit can be used to monitor terminal user requests. The exit
routine can permit the request to be executed, modify the request or terminate
CONSOLE execution.

■ The name of the exit routine must be CONEXIT.
UXDSECT EXIT=(CON)
| ■ The member CONEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 20.

Code Meaning
0 Initial call (EQU UXCO@INT).
4 Reserved.
8 Next subcommand (EQU UXCO@NXT).
12 Reserved.
16 Termination call (EQU UXCO@LST).

UXCONCMD Address of a 1-byte code identifying the subcommand. (This
address is valid for entrance codes of 8 and 16.)
These codes can be:
Code Subcommand
4 * Subcommand (EQU UXCO@AIN)
8 AWS Subcommand (EQU UXCO@AWS)

12 END Subcommand (EQU UXCO@END)

16 UCB Subcommand (EQU UXCO@UCB)
20 Operator Command (EQU UXCO@OPE)
24 NOAWS Subcommand (EQU UXCO@NAW)
28 STATUS Subcommand (EQU UXCO@STS)
32 HELP Subcommand (EQU UXCO@HLP)
36 TERMIN Subcommand (EQU UXCO@TRM)
40 MTT Subcommand (UXCO@MTT)
If the CONSOLE command is entered with no subcommand,
UXCONCMD contains 16.
UXCONUCB Address of the console ucb. (This address is valid when
UXCONCMD contains 16. When the CMD subcommand is
entered, the address is valid when the console buffer is
displayed, following the execution of the operator command.)
UXCONOPE Address of the buffer containing the operator command. The
format of the buffer is: a two-byte length field, two bytes of
binary zeros, the operator command and two bytes of blanks.
(The length includes the two bytes of blanks that follow the
command.) (This address is valid when UXCONCMD
contains 20.)

routine must load one of the following return codes in register 15. The
meaning of the return code depends on the contents of the area pointed to by
UXCODE on entrance to the routine.

CODE CODE
0 0 Allow command. no
4 Deny command. yes
8 0 Allow the subcommand. no
4 Deny the subcommand. yes
return code.
When a return code of 4 is loaded into register 15, a CONEXIT or site-written

message is sent to the terminal.
When the Message field contains 'YES', a CONEXIT or site-written message is



appropriate CONEXIT message is sent to the terminal.)


8.10 DISEXIT: DISPLAY Routine Exit

A DISPLAY exit routine may be used to restrict terminal users from executing
DISPLAY subcommands.

■ The name of the exit routine must be DISEXIT.
UXDSECT EXIT=(DIS)
| ■ The member DISEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 5.
There is only one call to the exit routine. It occurs after the user has finished
DISPLAY subcommand input and all operands of the subcommand have been
syntax checked. (If DISPLAY is entered with no subcommand, it is treated as
though the JOB subcommand was entered.)
In addition to section 7.3, “Common Data Areas” on page 7-4, the following
UXDISCMD Address of a 2-byte code describing the input subcommand.
(This address is always valid.)
The first byte is set to indicate the subcommand. The second
byte is set only if the subcommand is qualified. The codes
are:
Byte 1 Byte 2 Subcommand,Qualifier

X'80' X'80' ACTIVE,ALL
X'80' X'40' ACTIVE,remote
X'80' X'02' ACTIVE,STC
X'80' X'01' ACTIVE,TSO
X'80' X'00' ACTIVE
X'40' n/a DEVICES

Byte 1 Byte 2 Subcommand,Qualifier

X'20' n/a INIT
X'11' n/a MASK
X'10' n/a JOB
X'08' X'08' NAME,class
X'08' X'04' NAME,remote
X'04' X'20' QUEUE,class
X'04' X'10' QUEUE,remote
For example, the subcommand NAME,RM15 sets the code

bytes to to X'0804'.
UXDISCNM Address of an eight-byte alphanumeric subcommand
qualifier. (This address is valid only when the JOB, MASK,
NAME, and QUEUE subcommand has been entered.)
The qualifier is left-justified and blank-filled. The qualifiers
are:
Qualifier Meaning
jobname JOB=jobname
jobname MASK=jobname
class NAME,class
remote NAME,remote
class QUEUE,class
remote QUEUE,remote
UXDISQL Address of a numeric subcommand qualifier. (This address is
valid only when the ACTIVE, NAME, or QUEUE
subcommand has been entered.
The qualifier is presented as a fixed-point integer. The
qualifiers are:
Qualifier Meaning
xx ACTIVE,remote
xx NAME,remote
xx QUEUE,remote

routine must load one of the following return codes into register 15.


CODE CODE
n/a 0 Execute the no
subcommand.
4 Do not execute the yes
subcommand.
When the Message field contains YES, a DISEXIT or site-written message is

appropriate DISEXIT message is sent to the terminal.)


8.11 DSAEXIT: Data Set Access Exit

DSAEXIT exit is called:
■ by the Data Set Facility before any data set-related function is performed.
■ from any Monitor routine that accesses data sets. (Of the Advantage
CA-Roscoe-supplied Monitor routines, this exit is called by EXPORT,
IMPORT, and ZAP.)
■ by the SUBMIT command.
■ during execution of an application under ETSO that uses data sets and/or
dynamically allocates the internal reader.

■ The name of the exit routine must be DSAEXIT.
UXDSECT EXIT=(DSA)
| ■ The member DSAEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 4.

Code Meaning
1 Allocate new data set (EQU UXDS@ALL)
2 Open input data set (EQU UXDS@INP)
3 Open output data set (EQU UXDS@OUT)
4 Open update data set (EQU UXDS@UPD)
5 Scratch data set (EQU UXDS@SCR)
6 Rename data set (EQU UXDS@REN)
7 Reserved
8 Reserved

9 Reserved
10 Reserved
11 Reserved
12 Open input member (EQU UXDS@INM)
13 Open output member (EQU UXDS@OUM)
14 Open update member (EQU UXDS@UPM)
15 Scratch member (EQU UXDS@SCM)
16 Rename member (EQU UXDS@RNM)
17 Find from UTILITY FIND command (EQU UXDS@FND)
18 Listvtoc from UTILITY LISTVTOC command (EQU UXDS@LDS)
19 Catalog (EQU UXDS@CTL)
20 Uncatalog (EQU UXDS@UCT)
21 Build index from UTILITY BLDNDX command (EQU UXDS@BLX)
22 Delete index from UTILITY DLTNDX command (EQU UXDS@DLX)
23 Connect from UTILITY CONNECT command (EQU UXDS@CON)
24 Release from UTILITY DISCONNECT command (EQU UXDS@REL)
25 Define GDG (EQU UXDS@DFG)
26 Reserved
27 Allocate existing data set (EQU UXDS@AEX)
28 Define data set alias (EQU UXDS@DDA)
29 Define PDS member alias (EQU UXDS@DMA)
30 Open internal reader (EQU UXDS@INT)
UXDSADSN Address of the data set name, padded to 44 characters. If the
field contains 44 bytes of binary zeros or hexadecimal 04s, a
VTOC is being accessed. (This address is valid when the
entrance code is 1, 2, 3, 4, 5, 6, 12, 13, 14, 15, 16, 17, 18, 19, 20,
25, 27, or 29.)
UXDSANDS Address of the new data set name, padded to 44 characters.
(This address is valid when the entrance code is 6.)
UXDSAVL# Address of a two-byte field containing the volume count. (If
the user enters a volume serial number, this address is valid
when the entrance code is 1, 2, 3, 4, 5, 6, 12, 13, 14, 15, 16, 18,
19, 27, or 29.)

UXDSAVOL Address of the list of volumes identified by UXDSAVL#. (If

the user enters a volume serial number, this address is valid
when the entrance code is 1, 2, 3, 4, 5, 6, 12, 13, 14, 15, 16, 18,
19, 27, or 29.)
UXDSAMEM Address of the member name, padded to eight characters. (If
the user enters a fully-qualified data set name, this address is
valid when the entrance code is 1, 12, 13, 14, 15, 16, or 27.)
UXDSANME Address of the new member name, padded to eight
characters. (This address is valid when the entrance code is
16.)
UXDSAUNT Address of the eight-character unit name. (If the user enters a
unit designation, this address is valid when the entrance
code is 1, 2, 3, 4, 5, 6, 12, 13, 14, 15, 16, 18, 19, 27, or 29.)
UXDSAJFC Address of the JFCB. This should be treated as read-only the
system does not know about changes made to the contents of
this field. (This address is valid when the entrance code is 1,
27, or 29.)
UXDSADSC Address of the format-1 DSCB if the volume on which the
data set resides is currently mounted. (The address begins at
the DS1FMTID field.) If it is not, the area contains binary
zeros. (This address is valid when the entrance code is 2, 3, 4,
12, 13, 14, or 29.)
UXDSAINX Address of the index name. (This address is valid when the
entrance code is 21, 22, 23, or 24.)
UXDSACIA Address of a catalog information area mapped by the UXCIA
DSECT (contained within UXDSECT). (This address is valid
for all entrance codes except 30.)
The address contains zeros if: 1) the volume list pointed to
by UXDSAVOL does not match the volumes in the data set's
catalog entry (existing data set), 2) the data set pointed to by
UXDSADSN is not cataloged (existing data set), or 3) the
catalog containing the data set's catalog entry is not available.
The fields in UXCIA include:
UXCIACNM Address of the 44-byte data set name of the
catalog associated with the data set pointed to
by UXDSADSN.
UXCIAVOL Address of the six-byte serial number of the
volume on which the catalog resides.
UXCIATYP One-byte flag indicating the type of catalog.
UXCIAETP One-byte flag indicating the catalog entry
type for for the data set pointed to by
UXDSADSN.

UXDSARDS Address of the related (true) data set name. (This address is
UXDSAADS Address of the alias data set name. (This address is valid
when the entrance code is 28.)
UXDSARMN Address of the related (true) member name. (This address is
UXDSAAME Address of the alias member name. (This address is valid
UXDSAPGM Address of the application name, padded to eight characters.


CODE CODE
Applies to Calls 0 Access is authorized. no
1-29 4 Access is not authorized. yes
30 0 Allow open for internal no
reader.
4 Internal reader not opened no
but program allowed to
continue.
8 Program to be cancelled yes
When the Message field contains 'YES', a DSAEXIT or site-written message is

appropriate DSAEXIT message is sent to the terminal.)
2. Place the message in the area whose address is in UXMSGADR of
UXDSECT.

message text. With one exception, the message text should not exceed 80 bytes
in length. The exception is that messages rejecting a UTILITY subcommand
request may not exceed 59 characters in length.
Notes
■ IMPORTANT!

If a DSAEXIT routine is present, it is called whenever the EXPORT,

IMPORT, SUBMIT, or ZAP routine accesses a data set that must be
opened. The call that would otherwise have been made to EXPEXIT,
IMPEXIT, SUBEXIT, or ZAPEXIT when the data set is opened is bypassed.
Note: When ZAP processes a data set, UXDSADSN contains the address
of a 44-byte area containing the name of the SYSLIB data set to be
zapped. If the data set is a volume table of contents, the area
contains either zeros or X'04's.
■ DSAEXIT and ETSO:
Allocation calls occur when a data set is to be allocated by either the
ALLOCATE command or by a user-program that issues an SVC99. (No
allocation call occurs for Advantage CA-Roscoe-managed files.) The call is:
1 Allocating a new data set. Prior to this call, a catalog call (19) is
made if the user has requested that the data set be cataloged.
27 Allocating an existing data set.
When the entrance code is 30, the application executing under ETSO
opened a file allocated to SYSOUT with an internal reader specified. The
exit routine may either accept or reject the open request for the internal
reader.
■ Deleting Data Sets:
When the terminal user attempts to delete a:
– Non-VSAM data set. The DSAEXIT routine is called with an entrance
code of 5 (scratch data set). If the data set is cataloged, the data area
UXCIA is present and a second call occurs to uncatalog the data set
(entrance code 20.)
– VSAM data set. The DSAEXIT routine is called with an entrance code
of 5. (UXCIA is present.)
■ Renaming Data Sets:
When the terminal user attempts to rename a:
– Non-VSAM data set. DSAEXIT is called with an entrance code of 6
(rename data set). If the data set is cataloged, the data area UXCIA is
present and the routine is called two more times, first to uncatalog the
| old data set (entrance code 20) and then to catalog the new data set
| (entrance code 19).
– VSAM data set. The DSAEXIT routine is called with an entrance code
of 6. (UXCIA is present.)
■ DSAEXIT, ACFEXIT and RACF:
In a RACF environment, there is a close relationship between the ACFEXIT
and the DSAEXIT. It is the responsibility of the ACFEXIT routine to save
all information about the user so that the DSAEXIT routine can perform its
check effectively.

If the ACFEXIT routine sets up a control block to enable the DSAEXIT to

determine access authorization for a user, the address of the control block
should be placed in the fullword ACEE pointed to by the address in the
SCB field SCBACFB.
In addition, if the initialization parameter EXTSEC=RACF is in effect, the
ACFEXIT routine must store the address of the user's RACF ACEE in the
field SCBSENV.
■ Site-written Monitor routines can call a DSAEXIT routine by including the
following code:
ROCALL ROUTINE=DSAEXIT
Addressability to the ROT is required. Also, site routines must format a
valid UXDSECT.
■ UXCIA provides catalog information required by certain security systems
to check a user's authority to perform a request. The UXCIA area can be
addressed using the following instructions once addressability to
UXDSECT is established:
L Rn,UXDSACIA LOAD UXCIA ADDRESS
USING UXCIA,Rn ESTABLISH ADDRESSABILITY
UXCIA may not be present. See the description of the UXDSACIA for
additional information.

8.12 DSFEXIT: Data Set Facility Exit

DSFEXIT exit allows a site to exercise a degree of control over certain aspects
of processing performed by Advantage CA-Roscoe's Data Set Facility.
Caution
This is not a security exit. Use DSAEXIT to protect data sets.
The following five types of calls can be made to DSFEXIT:

1. An initial call. This call is made when the Data Set Facility is activated by
the user. This occurs when any of the Advantage CA-Roscoe primary
commands (ATTACH DSN or DSN) that invoke the facility are entered.
(This call is always made from the Advantage CA-Roscoe main task.)
No call is made if:
■ The command fails syntax analysis.
■ The Data Set Facility is active and a primary command is entered that
causes a transition to a new Library Facility process (for example, a
Selection List is displayed and the user enters the command SELECT
MENU or DSN).
■ The Data Set Facility is suspended and a primary command is entered
that causes activation of the facility (for example, when the message D
PENDING is displayed, the Library Facility is suspended. Entering a
command like ATTACH DSN * activates the facility).
2. A termination call. This call is made when the Data Set Facility terminates
a primary command request or a full-screen process. This occurs when a
primary command that does not invoke full-screen processing ends (for
example, RENAME DSN) or when the DETACH DSN command is issued.
(This call is always made from the Advantage CA-Roscoe main task.)
Initial and termination calls are always paired; the termination call is an
appropriate time to clean up anything that may have been created during
any prior calls.
3. A GETMAIN call. This call is made when the Data Set Facility is about to
acquire virtual storage to satisfy a user's request. Because the Data Set
Facility can require large and highly variable amounts of storage, a site
may want to exercise some control over the amount of storage that may be
acquired for any request. This call is made only for those types of
GETMAINs that are of a discretionary nature; storage for areas required
for basic processing is acquired without interaction with DSFEXIT. (This
call is made from the Advantage CA-Roscoe main task and from the Data
Set Facility subtask.)

4. A function validation call. This call is made to allow site control of the
individual functions performed by users. (This call is made either from the
Advantage CA-Roscoe main task or from the Data Set Facility subtask,
based on the setting of the UXCALCTL bit vector.)
DSFEXIT is not intended to support implementation of data set security
facilities; DSAEXIT should be used for that function.
5. List entry exclusion calls. Two types of calls are made to allow sites to
exclude entries from a Selection List that is being built by the Data Set
Facility. One call is provided to exclude data sets from Catalog and VTOC
Selection Lists. The other call permits exclusion of modules and members
from AllFusion CA-Librarian and PDS Selection Lists. (This call is made
either from the Advantage CA-Roscoe main task or from the Data Set
Facility subtask, based on the setting of the UXCALCTL bit vector.)

■ For MVS/XA sites, the routine must be link edited with an attribute of
AMODE=31, RMODE=24.
■ The name of the exit routine must be DSFEXIT.
UXDSECT EXIT=(DSF)
CA-Roscoe should be made by a BSM instruction. This can be
■ When the exit routine is called from the Advantage CA-Roscoe main task,
it should be careful not to incur a system WAIT as this seriously degrades
Advantage CA-Roscoe performance. Several of the call types permit the
exit routine to specify invocation from the Data Set Facility subtask. While
this incurs some additional calling overhead, it should be used when the
exit routine needs to perform processing that may incur a WAIT. Such
processing includes operations like LOAD, RACHECK, and READ.
| ■ The member DSFEXIT on CAI.RO60OPT contains a sample exit routine.


value defined by UXIDCDSF (27).

Code Meaning
0 Initial call (EQU UXDF@STM).
4 Termination call (EQU UXDF@TRM).
8 GETMAIN call (EQU UXDF@GTM).
12 Function validation call (EQU UXDF@FVL).
16 List entry exclusion call for data sets (EQU UXDF@LED).
20 List entry exclusion call for members (EQU UXDF@LEM).
24 List entry exclusion call for units (EQU UXFL@LEU).
UXCALCTL Address of a one-byte bit map used to control future
DSFEXIT calls by the Data Set Facility. These bits should be
set by the exit routine at the initial call to tell Advantage
CA-Roscoe what other types of calls are desired. They may,
however, be altered at any other entry to DSFEXIT to
respecify what types of calls the exit routine is to receive.
At the initial call, the bits are all off. This means that the only
other call made to the exit routine is the termination call.
To activate call types, the following labels define the bits that
should be turned on in the byte pointed to by UXCALCTL:
UXDF$GTM Controls GETMAIN calls. UXDF$GTM is
called from both the main task and subtask
levels. It cannot be controlled by the exit
routine.

Main Task Level:
UXDF$FVL Controls function validation calls.

UXDF$LED Controls list entry exclusion calls for data
sets.
UXDF$LEM Controls list entry exclusion calls for
members.
Subtask Level:
UXDF$FVS Controls function validation calls.

(UXDF$FVL must also be set.)
UXDF$LDS Controls list entry calls for data set.
(UXDF$LED must also be set.)
UXDF$LMS Controls list entry exclusion for members.
(UXDF$LEM must also be set.)
UXDF$LEU Controls list entry exclusion for units.
(Always at the subtask level.)
The following data area is available for an initialization call (when the entrance
code is 0).
UXDS0CTL Address of a one-byte bit map that may be set to indicate how
the Data Set Facility is to handle certain types of processing.
The following fields may be set in this one-byte field:
UXDS0FCD Confirm Delete processing is to be forced for
data set operations (the DSN portion of the
CONFIRM DELETE field on the Data Set
Facility menu is always set to YES).
UXDS0FCM Confirm Delete processing is to be forced for
PDS and AllFusion CA-Librarian master file
operations (the MEM portion of the CONFIRM
DELETE field on the Data Set Facility menu is
always set to YES).
The following data areas are available for GETMAIN calls (when the entrance
code is 8).
UXDS1S24 A fullword containing the current amount of storage allocated
to the Data Set Facility process that is below the 16MB line.
UXDS1S31 A fullword containing: 1) the current amount of storage
allocated to the Data Set Facility process that is above the 16MB
line, or 2) zero, if the operating system is not MVS/XA.

UXDS1R24 A fullword containing the amount of storage about to be

allocated to the Data Set Facility process that is to be below the
16MB line.
UXDS1R31 A fullword containing the amount of storage about to be
allocated to the Data Set Facility that is to be above the 16MB
line.
The following data areas are available for function validation calls (when the
UXDS2FCT Address of a one-byte area containing a code for the function
that the user is about to perform. Values for this code are
defined in the UXDSECT expansion.
UXDS2DSN Address of an area containing the name of the data set or the
search string specified by the user. This area consists of a
one-byte length field followed by a one- to 44-character name.
When no name is specified. (when attaching a VTOC, this field
contains blanks.
UXDS2MEM Address of an area containing the name of the member
specified by the user. If no name is specified, this field contains
blanks.
UXDS2VOL Address of an area containing a list of volumes specified by the
user. The area consists of a one-byte count filed followed by
zero to six 6-character volume names.
UXDS2UNT Address of an area containing a list of units associated with the
volumes in UXDS2VOL. The area consists of a one-byte count
field followed by zero to six 8-character unit names.
UXDS2FPL Address of a function-dependent parameter list for ALLOCATE
and DEFINE GDG. (For all other functions, this field contains
zeros.) The parameter list contains information specified by the
user when the function was requested. This information may be
modified by the exit routine to suit site requirements.
The parameter list for the ALLOCATE function may be
mapped by the UXALC DSECT. It contains:
UXALCDSN Address of the data set name area, consisting of
a one-byte length field followed by a 44-byte
data set name right-padded with blanks.
UXALCVOL Address of the volume area, consisting of a
one-byte count filed followed by zero to six
serial numbers.
UXALCUNT Address of the unit name area, consisting of a
one-byte count field followed by zero to six unit
names.

UXALCSPC One-byte space request type. (Equates are

provided to obtain the specific request type.)
UXALCPRM Three-byte primary allocation quantity, in
binary.
UXALCSEC Three-byte secondary allocation quantity, in
binary.
UXALCPDB Three-byte PDS directory allocation quantity, in
binary.
UXALCDSG Two-byte data set organization. (Equates are
provided to obtain specific information.)
UXALCRFM One-byte record format. (Equates are provide to
obtain specific information.)
UXALCEXP Three-byte expiration date in the form 'yydddd'
(binary), where 'yy' is offset from the year 1900
and 'dddd' is the day of the year.
UXALCLRC Two-byte logical record length, in binary.
UXALCBLK Three-byte block size, in binary.
UXALCKYL One-byte key length, in binary.
UXALCCTO One-byte catalog option. (Equates are provided
to obtain specific information.)
UXALCDCL Eight-byte SMS data class, padded to the right
with blanks.
UXALCMCL Eight-byte SMS management class, padded to
the right with blanks.
UXALCSCL Eight-byte SMS storage class, padded to the
right with blanks.
UXALCSSP One-byte space request type. (Equates are
provided to obtain the specific request type;
used in conjunction with UXALCSPC.)
UXALCRCO One-byte VSAM data record organization.
(Equates are provided to obtain the specific
organization.)
UXALCKYO Two-byte VSAM key-sequenced data set key
offset.
UXALCSCM Address of the security profile name area,
consisting of a one-byte length field followed by
a 44-byte security profile name that is padded
to the right with blanks.
UXALCFL1 One-byte flag byte:

UXALCSCG Address of a generic security

profile name.
The parameter list for the DEFINE GDG function may be
mapped by the UXDFG DSECT. It contains:
UXDFGDSN Address of the GDG name area, consisting of a
one-byte length field followed by a 35-byte
GDG name right-padded with blanks.
UXDFGGDL One-byte GDG limit value, in binary.
UXDFGDGF
One-byte GDG option flags. (Equates are
provided to obtain the settings of these flags.)
UXDFGGDT Four-byte GDG retention date in the form
'yydddfcc', where 'yydddf' is the year and day
in packed decimal format and 'cc' is a one-byte
binary century indicator (00 is 20th century, 01
is 21st century, 02 is 22nd century).
UXDFGGDO Eight-byte GDG owner.
The following data areas are available for the list exclusion calls (when the
entrance code is 16 or 20).
UXDS3LTP Address of a three-byte area containing a code for the type of
list that is being built. Values for this code are defined in the
UXDSECT expansion.
UXDS3LNM Address of an area containing either:
■ The search string specified by the user (when building a
Catalog or VTOC Selection List), or
■ The data set specified by the user (when building a PDS or
AllFusion CA-Librarian Selection List).
In either of the preceding cases, the area consists of a one-byte
length field followed by a one- to 44-character name.
■ Zeros (when building a Volume Selection List).
UXDS3LVL Address of an area containing either:
■ A list of volumes when a VTOC, PDS or AllFusion
CA-Librarian Selection List is being built. The area consists
of a one-byte count field followed by one to six 6-character
volume names, or
■ The wildcard volume search argument when a Volume
Selection List is being built. The area consists of a one-byte
count field (containing 1 in this case) followed by the
search argument or blanks. (Blanks appear if no wildcard
search argument was specified.)

UXDS3LUN Address of an area containing a list of units associated with the

volumes in UXDS3LVL. The area consists of a one-byte count
field followed by one to six 8-character unit names.
UXDS3ENM Address of an area containing either:
■ The name of the data set or member to be added to the list.
If a list of data sets is being built, this points to a one- to
44-character name; if a directory list is being built, this
points to an eight-character member name, or
■ A three-byte unit name (for example, 574 or 57A) when
building a Volume Selection List.
UXDS3ENT Address of an area containing either:
■ The PDS directory entry or the FAIRMOD or FAIRLOC
result area, or
■ Four-byte storage address of the UCB (when building a
Volume Selection List).
UXDS3VLS Address of a one- to six-byte volume serial number associated
with the UCB address given in UXDS3ENT. (This area contains
zeros for all other Lists.)


CODE CODE
0 0 Allow the request. no
8 Reject the request. yes
return code from a
termination call.
8 Do not attempt to obtain yes
the storage. If the process:
- can continue, it will. no
- cannot continue, it yes
terminates with a message.
12 0 Allow request as entered. no
4 Allow request as modified no
by exit routine.
8 Reject request. yes


CODE CODE
16 0 Include the entry. no
8 Reject the entry. yes
8 Exclude the entry. yes
8 Exclude the entry. yes
When the Message field contains 'YES', a DSFEXIT or site-written message is

appropriate message is sent to the terminal.)

Notes
■ Data Set Facility functions can be performed in both the Execution Area
(using the menu, a function-related panel or a Selection List) and in the
Command Area (using a primary command). Each area invokes its own
call to a site-written DSFEXIT exit routine. Advantage CA-Roscoe ensures
that the contents of UXCALCTL and UXDSFWRK are saved and restored
for each caller.
■ UXDS2FPL provides the address of a parameter list when the user requests
an ALLOCATE or DEFINE GDG function. The parameter lists can be
mapped by the UXALC and UXDFG DSECTs, respectively. The following
code illustrates how to establish addressability to UXALC.

L R15,UXDS2FCT load function code address

CLI (R15),UXDS2ALC allocate request?
BE ALOC y, branch to allocate code
CLI (R15),UXDS2ALC define GDG request?
BE GDG y, branck to GDG code
B EXIT n, return with rc=
ALOC DS H
L R2,UXDS2FPL load parameter list address
USING UXALC,R2 establish addressability
...
... modify parameter list as required
...
B EXIT4 return with rc=4
...

8.13 EXPEXIT: EXPORT Routine Exit

An EXPORT exit routine can be used to:
1. Accept user requests, reject user requests or terminate EXPORT execution.
2. Control each input record passed to AllFusion CA-Librarian Immediate
Online Update (IOU).
3. Provide control over the output report generated by the IOU during
updates to a AllFusion CA-Librarian master file.
4. Format PDS directory information.

■ The name of the exit routine must be EXPEXIT.
UXDSECT EXIT=(EXP)
■ If necessary a GETMAIN may be issued to obtain working storage and its
address stored in UXWKAREA of UXDSECT.
| ■ The member EXPEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 6.

Code Meaning
0 Initial call (EQU UXEX@INT). The user finished EXPORT operand
input and all operands have been syntax checked.
4 (MVS.) Dynamic allocation request (EQU UXEX@DYN).

8 Protected data set (EQU UXEX@PRO). This call occurs only if no

DSAEXIT routine is present. If a DSAEXIT routine is present, this
call is bypassed.
12 Last call (EQU UXEX@LST). This call always occurs. It is the
responsibility of the exit routine to free all previously acquired
system resources before returning from the final call.
16 EXPORT/IOU next call (EQU UXEX@NXT). This call occurs during
the update phase of an EXPORT to a AllFusion CA-Librarian
master file. The exit routine can examine each input record passed
to the Immediate Online Update (IOU) of AllFusion CA-Librarian.
The routine may alter or delete existing records and/or insert new
records. Programming specifications are identical to those of the
batch AllFusion CA-Librarian.
20 All but the last call for EXPORT/ROSCOE/IOU (EQU UXEX@IRN).
This call occurs during the update processing of a AllFusion
CA-Librarian master file. The exit routine is called whenever the
IOU outputs a REPORT record to the library member identified by
the RSSCEXPU macro. The exit routine can be used to permit
spooling of EXPORT/ROSCOE/IOU output, suppress
EXPORT/ROSCOE/IOU output and direct the output to an
alternate destination.
24 Last call for EXPORT/ROSCOE/IOU (EQU UXEX@IRL). This is a
housekeeping call. On the last call to the exit routine, the area
pointed to by UXCODE contains 12.
28 STOW call (EQU UXEX@DIR). This call occurs before a member is
STOWed in a partitioned data set.
UXEXPDSN Address of a 44-byte area containing the data set name.
(This address is valid when the entrance code is 0, 4, 8, 16,
20, or 28.)
If the entrance code is 0, the data set name may be changed
by the exit routine. The data set name passed when the
entrance code is 0 may be different from the data set name
passed when the entrance code is 4 if the data set was
specified by the terminal user with an alias for the high-level
index.
UXEXPMEM Address of an eight-byte area containing the member name
(PDS) or module name (AllFusion CA-Librarian). (This
address is valid when the entrance code is 0, 4, 8, 16, 20, or
28.)
If no name was specified, the area contains blanks.

UXEXPVOL Address of a six-byte area containing the volume serial

number of the data set. (This address is valid when the
entrance code is 0, 4, 8, 16, 20, or 28.)
If the entrance code is 0 and no volume serial number was
specified, the area contains binary zeros.
UXEXPIPR Address of an 80-byte area containing the record to be input
to AllFusion CA-Librarian IOU. (This address is valid when
the entrance code is 16.)
UXEXPOPR Address of the 80-character output record from the IOU.
If the last three bytes of this word contain zeros, the
end-of-file is indicated. End-of-file is normally followed (not
accompanied) by entrance code 24.
UXEXPDIR Address of the 75-byte directory record that is used by the
STOW macro to update the directory entry. (This address is
The format of the area is:
Byte 1-8 Member name
Byte 9-11 TTR field
Byte 12 Length of user data (in halfwords)
Byte 13-75 User data
The member name and TTR field should not be changed at
this time. No record is kept of the changed name. If the exit
routine changes (shortens) the user data, the routine must
supply the new length of the user data in halfwords.
UXEXPDR2 Address of the 75-byte area containing the old directory
record. (This address is valid when the entrance code is 28.)
If the member being EXPORTed is new, this area contains
binary zeros. If an existing member is being EXPORTed, the
format of this area is the same as that described with
UXEXPDIR.
UXEXPREC Address of a halfword that contains the number of records
written to the PDS. (This address is valid when the entrance
code is 28.)

UXEXPRCF Address of a halfword return code field. (This address is

Each time the exit routine is called by the IOU to process an
input record, the IOU sets the halfword pointed to by
UXEXPRCF to binary zero.
When returning control to the IOU, the exit routine must
place one of the following return codes into this field. (An
invalid return code is treated as a 4.)
Code Meaning
0 Termination: Same as a return code of 4 but the
exit routine is not called again for this update. The
final housekeeping call is also suppressed. It is the
responsibility of the exit routine to free all system
resources acquired prior to termination since the
exit routine is not called after this condition
occurs. (Use of this return code terminates only
the exit routine and update itself.)
4 Normal Return: The record pointed to by the
address in UXEXPIPR is passed on for processing.
Any desired modifications may be made to the
original record passed to the exit routine.
8 Insertion: The record pointed to by the address in
UXEXPIPR is passed to the update program for
processing. After that record has been processed,
control returns to the exit routine (at its normal
entry point) with the address in UXEXPIPR
pointing to an 80-byte area into which the routine
places the next record to be processed. Any
number of records may be inserted by means of
successive return codes of 8. When the routine has
moved the final record to be inserted into the
specified area, insert series is terminated by using
a return code of 4. A return of 12 (which
terminates the insert series without passing a final
record to the update program) may also be used.
12 Deletion: The record pointed to by the address in
UXEXPIPR is dropped.
16 Skip Module: All operations for the module are
bypassed. The area addressed by the first
parameter is printed on the update report.
Processing continues with the next -ADD, -SEL,
-DLM, or -END statement, if any are present.

20 Flush Input Stream: All operations for the current

module are bypassed. The area addressed by the
first parameter is printed on the update record.
The AllFusion CA-Librarian flushes the remainder
of the input stream.
The exit routine is called one last time to do any final
housekeeping. On this final call, the IOU sets the halfword to
a value other than binary zero. Any code returned by the exit
routine is irrelevant and is ignored.

routine must load one of the following return codes into register 15. The
meaning of the code depends on the contents of the area pointed to by

CODE CODE
0 0 EXPORT is to continue. no
4 User's request is yes
rejected. EXPORT
terminates.
4 Dynamic allocation is yes
rejected. EXPORT
terminates.
4 Request is rejected. yes
EXPORT terminates.
See also 'Notes'
12 0 Normal termination. no
4 Forced termination. yes
(Note: The export
operation has completed
prior to this call.)
return code. (See the
programming
specifications for the
batch AllFusion
CA-Librarian exit.)


CODE CODE
4 Suppress output. yes
EXPORT terminates
4 Suppress output. yes
EXPORT terminates
4 Forced termination. yes
When the Message field contains 'YES', a EXPEXIT or site-written message is


Notes
■ When an external data set is to be opened, Advantage CA-Roscoe checks
to see if a DSAEXIT routine is present.
If a DSAEXIT routine is found, it is called to validate whether the user can
access the designated data set. (The call that would have been made to the
EXPEXIT routine is bypassed.)
If no DSAEXIT routine is found, the EXPEXIT routine is called.
■ If no DSAEXIT routine is present, the EXPEXIT routine is called when a
RACF-protected or OS password-protected data set is to be opened. If the
routine passes a return code of 0 back to Advantage CA-Roscoe,
Advantage CA-Roscoe attempts to open the data set. It is the site's
responsibility to ensure that Advantage CA-Roscoe has been authorized to
access the data set. If Advantage CA-Roscoe is not authorized to access the
data set, EXPEXIT terminates with a 913 abend.

8.14 IMPEXIT: IMPORT Routine Exit

An IMPORT exit routine can be used to:
1. Monitor user requests. After review, the exit routine can permit the request
to be executed, modify the request, or terminate IMPORT execution.
2. Change the format of a PDS directory listing.

■ The name of the exit routine must be IMPEXIT.
UXDSECT EXIT=(IMP)
| ■ The member IMPEXIT on CAI.RO60OPT contains a sample exit routine.
Entrance Parameters: Upon entrance to the routine, register 1 contain the

For this exit, the area pointed to by the address in UXIDCODE contain the exit
identifier 7.

Code Meaning
0 Initial call (EQU UXIM@INT).
4 Extended initial call (EQU UXIM@EIN). The user has finished
IMPORT operand input and all operands have been syntax checked.
8 (MVS.) Dynamic allocation call. The requested data set requires
dynamic allocation (EQU UXIM@DYN).
12 Next input record is presented (EQU UXIM@NXT). This call occurs
before the record is written to the AWS.

16 Protected data set (EQU UXIM@PRO). This call occurs only if no

call is bypassed.
20 Last call (EQU UXIM@LST).
24 Format PDS call (EQU UXIM@DIC). This call occurs before the line
is written to the AWS.
28 PROD2 module call (EQU UXIM@PD2). The setting of the first byte
in the area pointed to by UXIMPLIB identifies whether access is
requested for an index listing or a module retrieval.
UXIMPDSN Address of a 44-byte area containing the data set name.
(This address is valid for all calls except 20.)
The data set name passed with an entrance code of 0 may be
different from the data set name passed when an entrance
code of 4 or above if the data set was specified by the
terminal user with an alias for the high-level index. If the
entrance code is 0, the data set name may be changed by the
exit routine.
UXIMPMEM Address of an eight-byte area containing the member name
(PDS) or module name (AllFusion CA-Librarian). (This
address is valid for all calls except 20.)
If no name was specified, the field is blank. If a PDS
directory listing was specified, the name is an asterisk (*). If
the entrance code is 0, this field may be modified by the exit
routine.
UXIMPVOL Address of a six-byte area containing the volume serial
number of the data set. (If the user enters a volume serial
number, the address is valid for all calls except 20.)
UXIMPLIB Address of a fullword containing the AllFusion CA-Librarian
option. (If the user enters a AllFusion CA-Librarian option,
the address is valid for all calls except 20.)
The format of the field is:
Byte 1 - xxxx xxx1 LIBRARIAN

xxxx xx1x INDEX
xxxx x1xx HIST
Byte 2 - C'C'
Byte 3 - Reserved
Byte 4 - Reserved

UXIMPREC Address of a logical record read from the input field. (This
address is valid when the entrance code is 12 or 24.)
When the entrance code is 12, the area pointed to by
UXIMPREC is a halfword length field followed by the data.
The length of the data is the value of the halfword field; this
value may not be modified.
When the entrance code is 24, UXIMPREC contains the
address of the data.
The data is raw input (IMPORT has not begun any
processing on it). The data may be modified provided that it
remains the same length (shorter records must be padded to
the designated length).
UXIMPRNG Address of the first of two 10-byte fields containing the
name(s) specified with the RANGE= operand. (If the user
enters the RANGE= operand, this address is valid for all calls
except 20.)
The first halfword in each field contains the length of the
name, in execute form (length-1), followed by the name. If no
RANGE= operand was specified, the first byte of the
halfword contains X'FF'. If only one name was specified with
RANGE=, the second field is identical to the first.
This operand is used to limit the retrieval to a PDS directory
or AllFusion CA-Librarian index to within a specified range.
UXIMPOPA Address of a 256-byte output area for use when formatting a
PDS directory listing. (The exit routine must place the
directory entry in the area pointed to by UXIMPOPA.)
The area must contain the following:
■ The length of the formatted directory entry in the first
byte. The maximum length is 255. If the length field
contains 0, the directory entry is ignored.
■ The directory entry formatted for writing to the AWS. It
must not contain any non-printable or non-displayable
fields. (Such fields are replaced by spaces before the
record is passed back to Advantage CA-Roscoe.)
UXIMPHEX Address of a hexadecimal table. The use and contents of this
table are reserved and must not be modified.


routine must load one of the following return codes into register 15. The

CODE CODE
return code.
4 0 IMPORT is to continue. no
4 User's request is yes
rejected; IMPORT
terminates.
8 0 no
4 IMPORT is to continue. yes
Dynamic allocation is
rejected; IMPORT
terminates.
12 0 IMPORT is to return this no
record to the terminal
user if it meets the input
criteria specifications.
(The record presented
may be modified as
required.)
4 IMPORT is to bypass no
this input record and
read the next record.
16 0 IMPORT is to continue. no
4 Request rejected; yes
IMPORT terminates
See also 'Notes'.
return code.


CODE CODE
24 0 Write the PDS directory no
entry. The 81-byte
output area pointed to
by UXIMPOPA must
contain the
site-formatted record to
be written to the AWS.
4 reserved n/a
8 Write the PDS directory no
entry. The entry is to be
formatted by Advantage
CA-Roscoe.
28 0 Access to module is no
granted; IMPORT is to
continue.
4 Access to the module is yes
denied. If the action
being executed is a
AllFusion CA-Librarian
index listing, the entry
for the PROD2 module
is omitted from the
formatted listing. If
action is the retrieval of
a module or its history
records, IMPORT
terminates.
When the Message field contains YES, a IMPEXIT or site-written message is

appropriate IMPEXIT message is sent to the terminal.)


Notes:
If a DSAEXIT routine is found, it is called to validate whether the user ca
IMPEXIT routine is bypassed.)
If no DSAEXIT routine is found, the IMPEXIT routine is called.
■ If no DSAEXIT routine is present, the IMPEXIT routine is called when a
data set, IMPEXIT terminates with a 913 abend.

8.15 JOBEXIT: PURGE Routine Exit
8.15 JOBEXIT: PURGE Routine Exit

JOBEXIT can be used to restrict the use of the PURGE Monitor command.
This exit is provided as part of the user-contributed PURGE Monitor routine. It

does not use the facilities provided by the UXDSECT macro.

| ■ The name of the exit must be JOBEXIT.
| ■ Standard OS linkage conventions are used.
| ■ Use Customization USERMOD MRO607E on SAMPJCL, as a guide for
| assembling and link editing JOBEXIT with the PURGE monitor.

address of a parameter list.
The parameter list consists of five fullwords, each of which contains the
address of a data area. The parameter list is:
Word 1 Address of jobname. The jobname is padded on the right to eight
characters.
Word 2 Address of user prefix.
Word 3 Address of user signon key. The key is padded on the right to 22
characters.
Word 4 Address of the SCB.
Word 5 Address of ROT.

Code Meaning
1 Allow user to cancel job.
4 Prohibit user from cancelling
job.
Notes: Since JOBEXIT is single-threaded with the main Advantage CA-Roscoe

task, it should not perform any operation that might cause a WAIT state (for
example, I/O). If the exit routine goes into a WAIT state, it is highly probably
that all other Advantage CA-Roscoe activities will come to a halt until the exit
routine resumes processing.

8.16 LIBEXIT: Library Facility Exit

LIBEXIT exit allows a site to control certain aspects of the processing
performed by the Advantage CA-Roscoe Library Facility.
The following five types of calls can be made to LIBEXIT:

1. An initial call. This call is made when the Library Facility is activated by
the user. This occurs when any of the Advantage CA-Roscoe primary
commands (ATTACH LIB or LIB) that invoke the facility are entered.
This call does not occur if:
■ The command fails syntax analysis.
■ The Library Facility is active and a primary command is entered that
causes a transition to a new Library Facility process (for example, a
Selection List is displayed and the user enters the command SELECT
MENU or LIBRARY).
■ The Library Facility is suspended and a primary command is entered
that causes activation of the facility (for example, when the message L
PENDING is displayed, the Library Facility is suspended. Entering a
command like ATTACH LIB * activates the facility).
2. A termination call. This call is made when the Library Facility terminates.
Note: Initial and termination calls are always paired; the termination call
is an appropriate time to clean up anything that may have been
created during any prior calls.
3. A GETMAIN call. This call is made when the Library Facility is about to
acquire virtual storage to satisfy a user's request.
Because the Library Facility can require large and highly variable amounts
of storage, a site may want to exercise some control over the amount of
storage that may be acquired for any request. This call is made only for
those types of GETMAINS that are of a discretionary nature; storage for
areas required for basic processing is acquired without interaction with
LIBEXIT.
4. A function validation call. This call is made to allow site control of the
individual functions performed by users.
Note: LIBEXIT should not be used to replace or alter the member security
provided by the User Profile System (UPS). (UPS is described in the
Advantage CA-Roscoe Interactive Environment System Reference Guide.)
5. List entry exclusion call. This allows sites to exclude members from a
Selection List that is being built by the Library Facility. (The number of
excluded members is included on the resulting Selection List.)


■ The name of the exit routine must be LIBEXIT.
UXDSECT EXIT=(LIB)
AMODE=31, RMODE=24.
CA-Roscoe should be made using a BSM instruction. This can be
■ The exit routine should be careful not to incur a system WAIT as this will
seriously degrade Advantage CA-Roscoe performance.
| ■ The member LIBEXIT on CAI.RO60OPT contains a sample exit routine.

value defined by UXIDCLIB (29).

Code Meaning
0 Initial call (EQU UXLS@STM).
4 Termination call (EQU UXLS@TRM).
8 GETMAIN call (EQU UXLS@GTM).
12 Function validation call (EQU UXLS@FVL).
16 List entry exclusion call for members (EQU UXLS@LEM).
UXCALCTL Address of a bit map (currently one-byte in length) that is
used to control future LIBEXIT calls by the Library Facility.
These bits should be set by the exit routine at the initial call
to tell Advantage CA-Roscoe what other types of calls are
desired. They may, however, be altered at any other entry to

LIBEXIT to respecify what type of calls the exit routine is to

receive.
At the initial call, the bits are all off. This means that the only
other call made to the exit routine is the termination call.
To activate call types, the following labels define the bits that
should be turned on in the byte pointed to by UXCALCTL:
UXLS$GTM Controls GETMAIN calls.
UXLS$FVL Controls function validation calls.
UXLS$LEM Controls list entry exclusion calls for
members.
The following data area is available for the initialization call (when the
UXLS0CTL Address of a one-byte bit map that can be set to indicate how
the Library Facility is to handle certain types of processing.
The following field may be set in this one-byte field:
UXLS$CFD Confirm Delete is in effect for this user. The
user cannot alter this setting (the CONFIRM
DELETE field on the Library Facility menu is
always reset to NO).
The following data areas are available for GETMAIN calls (when the entrance
code is 8).
UXLS1S24 A fullword containing the current amount of storage
allocated to the Library Facility process that is below the
16MB line.
UXLS1S31 A fullword containing: 1) the current amount of storage
allocated to the Library Facility process that is above the
16MB line, or 2) zeros if the operating system is not
MVS/XA.
UXLS1R24 A fullword containing the amount of storage about to be
allocated to the Library Facility process that is to be below
the 16MB line.
UXLS1R31 A fullword containing the amount of storage about to be
allocated to the Library Facility process that is to be above
the 16MB line.
The following data areas are available for function validation calls (when the
UXLS2FCT Address of a one-byte area containing a code for the function
that the user is about to perform. Value for this code are
defined in the UXDSECT expansion.

UXLS2LPF Address of a three-byte area containing the prefix specified

by the user. If a two-character prefix is specified, it is
left-justified.
UXLS2KEY Address of a 22-byte field containing the sign-on key that
corresponds to the prefix pointed to by UXLS2PFX.
UXLS2FKY Address of a 22-byte field containing the formal sign-on key
that corresponds to the prefix pointed to by UXLS2PFX.
UXLX2MEM Address of an eight-byte area containing the name of the
member specified by the user. If no name was specified, this
field contains blanks.
UXLS2GRP Address of an eight-byte area containing the name of the
security group that corresponds to the prefixed pointed to by
UXLS2PFX. If the name is less than eight bytes, it is
left-justified.
The following data areas are available for the list exclusion calls (when the
UXLS3PFX Address of a three-byte area containing the prefix specified by the
user. If a two-character prefix is specified, it is left-justified.
UXLS3KEY Address of a 22-byte field containing the sign-on key that
UXLS3FKY Address of a 22-byte field containing the formal sign-on key that
UXLS3LNM
Address of an eight-byte area containing name of the member to
be added to the list. If the name is less than eight bytes, it is
left-justified.
UXLS3ENT Address of an area containing the directory entry mapped by the
LBINDEX DSECT.
UXLS3GRP Address of an eight-byte area containing the name of the security
group that corresponds to prefix pointed to by UXLS3PFX.



CODE CODE
8 Reject the request. yes
return code.
8 Do not attempt to obtain yes
the storage. If the process:
- can continue, it will. no
- cannot continue, it yes
terminates with a message.
12 0 Allow request as entered. no
8 Reject request. yes
8 Reject the entry. no
When the Message field contains 'YES', a LIBEXIT or site-written message is


Notes
■ Library Facility functions can be performed in both the Execution Area
(using the menu, a function-related panel or a Selection List) and in the
Command Area (using a primary command). Each area invokes its own
call to a site-written LIBEXIT exit routine. Advantage CA-Roscoe ensures
that the contents of UXWKAREA is saved and restored for each call.
■ Currently, the following commands do not invoke the Library Facility and,
therefore, do not invoke a call to LIBEXIT:
ALTER mem
COPY mem
DELETE mem

PRINT mem
RENAME mem

8.17 MONEXIT: Monitor Invocation Exit

A MONEXIT exit routine is called before each execution of a Monitor
command.

■ The name of the exit routine must be MONEXIT.
UXDSECT EXIT=(MON)
| ■ The member MONEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 17.
There is only one call to the MONEXIT exit routine. It occurs after the user has
finished operand input and all operands of the Monitor command have been
syntax checked. (The contents of UXCODE are not applicable.)
UXMONNAM Address of a five-byte field containing the five characters
'monxt', extracted from the RUN monx-t or equivalent
command, where 'mon' are the first three characters of the
Monitor command name, 'x' is the fourth character of the
command name or blank if no fourth character was specified,
and 't' is the suffix character or blank if no suffix character
was specified.
If SET MODE XTENDED is in effect when the terminal user
enters the Monitor command name, the first four characters
are translated to uppercase; the fifth character is not
translated.

UXMONLNM Address of the 10-character library member name specified

with the RUN command (or 0 if no name was specified or if
the string RUN was not used.) The library member name is
always translated to uppercase.
UXMONSTR Address of a 201-byte area containing a one-byte count and a
200-byte string (blank-filled to the right).
If SET MODE XTENDED is in effect, the string is not
translated to uppercase.

routine must load one of the following return codes into register 15:

CODE CODE
n/a 0 Execute the command as no
entered.
4 Modify the parameters no
before executing the
command.
8 Suppress execution of the yes
command.
When the Message field contains 'YES', a MONEXIT or site-written message is

sent to the terminal. TO send a site-written message to the terminal:
1. Set (OR) a X'80' into the 1-byte field pointed to by UXRETFLG or
appropriate MONEXIT message is sent to the terminal.)
The format of the message area pointed to by the address in USMSGADR must
be: a halfword length field, a halfword containing binary zeros and the
Notes
■ When modifying the original parameters of a command, please observe the
following points:
– The sign-on key may not be modified.
– Only the fourth and suffix characters of the contents of the area
pointed to by UXMONNAM may be modified. To delete either
character, set it to binary zero.
– To delete the library member name, return blanks in its place. This
forces all reads to the AWS.

– If the member name (in the area pointed to by UXMONLNM) is

changed, the starting and ending line numbers specified by the user
are unchanged.
– Modified parameters have the same format as on entry. The
modifications may be done in place, overlaying the original
parameters.
– UXMONSTR always points to a 65-byte area. If no string was present
in the RUN command or if no operand was present in the Monitor
command, the count in the first byte of the area is zero. To delete the
string, set the count to zero.
■ The contents of UXMONNAM and UXMONSTR are not affected by the
setting of the RUN initialization parameter.

8.18 OUTEXIT: Job Output Exit

OUTEXIT can be used to monitor terminal user requests when viewing job
output. (It issues a call when the user enters the commands ATTACH JOB,
ALTER JOB, STATUS JOB, and DETACH JOB.) The exit routine can permit the
request to be executed, modify the request or terminate execution.

■ The name of the exit routine must be OUTEXIT.
UXDSECT EXIT=(OUT)
■ Since the exit is single threaded with the main Advantage CA-Roscoe task,
the exit routine should perform no operations that can cause a wait state
(for example, I/O). If such operations are performed, there is the risk of
halting all Advantage CA-Roscoe activities until done.
| ■ The member OUTEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 8.

Code Meaning
0 Initial call (EQU UXOU@INT).
4 Check job (JCT). (EQU UXOU@IN2).
8 DETACH JOB or ALTER command (EQU UXOU@NXT).
12 Reserved.

16 Termination call (EQU UXOU@LST).

20 Pass PDDB/OSE information. (EQU UXOU@USC).
UXOUTJNM Address of the jobname, padded to eight characters. (If the
job is attached by its name, this address is valid for all calls.
If the job is attached by its number, it is not valid when the
UXOUTJB# Address of the job number. (This address is valid when the
entrance code is 4, 8, 12 or 16. If the user enters a job
number, the address is also valid when the entrance code is
0.)
UXOUTJCT Address of the JCT. (This address is valid when the entrance
code is 4.)
For JES3 sites, the JCT address starts 28 bytes (decimal) after
the address in UXOUTJCT.
UXOUTSTA Address of a code identifying the current status of the job.
The address is not available with JES3. (This address is valid
when the entrance code is 4.) The code can be:
X'00 Awaiting execution (EQU UXOU@AE).
X'04' Executing (EQU UXOU@XEC).
X'08' Awaiting print - held (EQU UXOU@APH).
X'0C' Awaiting print - not held (EQU UXOU@AP).
UXOUTCMD Address of a code identifying the command. (This address is
valid when the entrance code is 8.) The code can be
X'0C' DETACH JOB command (EQU UXOU@END)
X'10' PRINT set by ALTER command/STATUS JOB
display/RL function in Job List Facility (if
ROSGBL parms set to FILEDSP=PRINT,
PRINTAL=yes) (EQU UXOU@PRT).
X'14' NOPRINT set by ALTER command/STATUS JOB
display/RL function in Job List Facility (if
ROSGBL parms set to FILEDSP=PRINT,
PRINTAL=yes) (EQU UXOU@PRT).

UXOUTRC Address of the UXOUTDS DSECT. (This address is valid

If UXOUTCMD indicates:
■ DETACH JOB -- the area UXOUTACT in the UXOUTDS
DSECT contains either blanks (if no operand was
specified) or the operand HOLD or NOACT. A change
made to the contents of UXOUTACT is verified to ensure
that it contains NOACT, HOLD or spaces. (Use spaces to
eliminate the operand.) If the command is changed, the
modified version is executed. (No message can be sent
to the terminal user that the command is modified. If it is
necessary to inform the user, use the CMDEXIT exit
routine to trap and modify the command.)
■ ALTER or STATUS JOB examine the following areas in
UXOUTDS:
UXOUTRDT Eight-byte area containing either blanks
or the remote ID name specified by the
user.
UXOUTCL One-byte area containing either a blank or
the user-specified SYSOUT class.
UXOUTCPY One-byte area containing either a 0 or the
user-specified number of copies.
UXOUTFRM Eight-byte area containing either blanks
or the user-specified form number.
Any changes made to these areas are not verified; they
are made available to Advantage CA-Roscoe for
processing.
UXOUTOSE Address of the PDDB (for JES2) or OSE (for JES3). (This
UXOUTWRK First of four contiguous fullwords that are available for the use
of the exit routine. If a work area is needed, these fullwords
should be used in place of UXWKAREA. (If the user places the
attached job in a pending status and executes other commands,
it is possible that the contents of UXWRKAREA may be
changed; the contents of UXOUTWRK is not changed.)



CODE CODE
0 0 Allow access to the job. no
4 Deny access to the job. yes
4 0 Allow access to the job. no
4 Deny access to the job. yes
8 0 Allow the command. no
4 If command is:
ALTER - Deny the yes
command.
DETACH JOB - Force no
NOACT.
return code.
20 0 Add file to file table. no
4 Request rejected; OUTPUT yes
terminated.
8 Do not add file to file no
table. OUTPUT execution
continues.
When the Message field contains 'YES', an OUTEXIT or site-written message is

appropriate OUTEXIT message is sent to the terminal.)


8.19 RCSEXIT: Roscoe Communication Services

The Roscoe Communication Services exit (RCSEXIT) is called each time a
session is established. For each session, it can:
■ Replace the output translation table address for the duration of the session
being established by modifying the RCSECA.
■ Enable all subsequent per-output calls to this exit and/or to the RDS Data
Formatting Exit (RDSEXIT) by modifying the RCSECA.
The RCSECA, Roscoe Exit Communication Area, contains information that
can be examined and modified by the exit routine to affect the RCS
function being performed.
If subsequent, per-output calls to RCSEXIT have been enabled, then for
each output operation, prior to the translation of data for transmission, the
exit can:
– Examine and, optionally, alter the data in the transmission buffer. (No
RCSECA modification is required for this operation.)
– Suppress the translation of the current output data by modifying the
RCSECA. (The exit must then take on the responsibility of translation.)
– Supply the address in the RCSECA of an alternate translate table
which is to be used by RCS for the current output operation. The
original session table address is restored after the translation of the
current output is done.

■ The name of the exit routine must be RCSEXIT.
UXDSECT EXIT=(RCS)
| ■ The member RCSEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 21.
The address in UXCODE points to a fullword that contains a value represented

by the equate 'UXRCSXT'.

exit-dependent data areas are available to the exit routine. (The addresses of
the ROT, SCB and PCB are not available through the UXDSECT.)
UXRCSECA Address of the RCS Exit Communication Area. This area

contains information that can be examined by the exit routine
and modified to affect the RCS function that is being
performed.
UXRCSATT Address of a read-only copy of the RCS Attribute Area that
contains device dependent information.


CODE CODE
0 0 No modification made by no
exit routine to RCSECA.
4 Modification made by exit no
routine to RCSECA.
The Message field is always ignored.
Notes
■ RCSEXIT is currently available only for BTAM TTY devices.
■ If the translate table is replaced (either for the session or on a per output
basis), the replacement table must be for the translation of ECBDIC to
ASCII line code.

8.20 RDSEXIT: ROSCOE Communication Services

When enabled by RCSEXIT, this exit is called during Advantage CA-Roscoe
data stream formatting immediately prior to any transformation of the
ROSCOE Data Stream (RDS) into a device-dependent EBCDIC data stream.
This exit can be used, on a per-output basis, to:

■ Modify the output data in any way which fits within the existing buffer for
the existing buffer length. Modification to the RCSECA is required only if
RDS transformation is to be suppressed.
■ Suppress the RDS transformation of TTY data by modifying the RCSECA.
RDS transformation includes both the addition of carriage controls (CR, LF,
and idles) and the folding of one long line into two output lines.

■ The name of the exit routine must be RDSEXIT.
■ The rouitne must include the UXDSECT macro in the form:
UXDSECT EXIT=(RDS)
| ■ The member RDSEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 22.
The address in UXCODE points to a fullword that contains a value represented

by the equate 'UXRDSOD'.
exit-dependent data areas are available to the exit routine. (Note that the
address of the ROT, SCB and PCB are not available through UXDSECT.
UXRCSECA Address of the RCS Exit Communication Area. This area
contains information that can be examined by the exit routine
and modified to affect the RDS function that is being
performed.
UXRCSATT Address of a read-only copy of the RCS Attribute Area that
contains device dependent information.



CODE CODE
0 No modification made by no
exit routine to RCSECA.
4 Modification made by exit no
routine to RCSECA.
The Message field is always ignored.
Notes
■ RDSEXIT is currently only available for BTAM TTY devices.
■ A ROSCOE Data Stream contains no device-dependent characters.
■ The EBCDIC to ASCII translation is not performed during RDS
transformation. This translation process can be affected by using RCSEXIT.

8.21 ROSMAILS Program Exit
8.21 ROSMAILS Program Exit

The ROSMAILS program exit allows sites to: 1) delete library members, 2) add
commentary to the ROSMAILS report about the members, and 3) supply a
charge rate for the members.

■ The exit routine must be present on the Advantage CA-Roscoe load library
named in the STEPLIB or JOBLIB DD statement for REPORT. It may be
reentrant, but is treated as a reusable resource.
■ The exit routine may have any name that is unique.
Entrance Parameters:
Upon entrance to the routine, register 1 contains either:

1. The address of a record that contains a complete description of a single
user library member, accompanied by the user's identification. The format
of the record is mapped by the macro MAILREC. See this macro for the
user fields that can be used to: 1) add a comment record, 2) add a charge
value (as calculated by the exit routine), and/or 3) mark a member for
deletion.
2. End-of-file indicator. At this entrance, any open DCBs must be closed and
any storage acquired using a GETMAIN must be released.
Return Codes: Before returning control, the exit routine must load one of the
following return codes into register 15.
Code Meaning
0 Normal return processing continues.
4 Do not call again. The exit routine is disabled.

8.22 ROS3@ATH: DB2 Authorization Exit

The standard DB2 authorization logic does not correctly identify a Advantage
CA-Roscoe terminal user during DB2 connection processing. Thus, the
standard DB2 Connection Manager authorization exit (DSN3@ATH) must be
extended to sense a connection attempt from a Advantage CA-Roscoe user.
Note: DSN3@ATH resides in DB2; it is not a standard Advantage CA-Roscoe
exit. DB2 calling conventions and execution requirements are observed
by this exit. The extension to DSN3@ATH follows the guidelines for
DB2 exit replacement defined in Chapter 5, Providing Security, of the
IBM manual IBM DB2 System Planning and Administration Guide
(SC26-4085).
Description: ROS3@ATH, the Advantage CA-Roscoe extension to the DB2

exit DSN3@ATH, provides the logic necessary to sense the connection attempt
of a Advantage CA-Roscoe/ETSO/DB2 session.
ROS3@ATH supports RACF, eTrust CA-Top Secret, eTrust CA-ACF2 and

Advantage CA-Roscoe-defined userids. Sites must identify their external
security programs through the Advantage CA-Roscoe initialization parameter
EXTSEC=.
| ROS3@ATH is provided as a load module in the Advantage CA-Roscoe

| installation load library. It is written in Assembler language and processed
| using the IBM High Level Assembler. Its attributes are:
Module Type Connection Manager Execution Exit.
Dependencies DB2 environment and Advantage CA-Roscoe V5.6 or
greater.
Attributes Reentrant, Reusable.
Authorization Supervisor State Key 7 (on entry).
Supervisor State Key 0 (in ROS3@ATH and ROS3@UEX).
Serialization No MVS Locks held, enabled for interrupts.
AMODE/RMODE 31/ANY.
Resides In CSA/ECSA.
Operates In Non-cross memory mode under TCB of ETSO session
requesting DB2 connection.
ROS3@ATH accesses the following MVS, DB2 and Advantage CA-Roscoe data
areas during the course of execution:
PSA MVS Prefix Save Area.
TCB MVS Task Control Block of the calling application.

CVT MVS Communications Vector Table.

RCVT MVS RACF Communications Vector Table.
EXPL DB2 Exit Point Parameter List.
RIB ROSCOE Information Block.
SCB Advantage CA-Roscoe Session Control Block.
ACEE RACF Accessor Environment Element.
SECREC eTrust CA-Top Secret Security Record.
RXGPPL eTrust CA-Top Secret Extract Work Area.
IWA eTrust CA-ACF2 Interface Work Area.
ACMCB eTrust CA-ACF2 User Block.
To properly identify the Advantage CA-Roscoe user to DB2, ROS3@ATH

performs the following:
1. Determines if the DB2 connect process is being requested for a Advantage
CA-Roscoe user. If it is not a Advantage CA-Roscoe connect, ROS3@ATH
exits to the standard site version of DSN3@ATH. (If it is a Advantage
CA-Roscoe connect, DSN3@ATH processing is not invoked; control returns
to DB2).
2. Determines the DB2 version. (ROS3@ATH processes both DB2 V1 and DB2
V2 connect requests.)
3. If the DB2 connect process is being requested for a Advantage CA-Roscoe
user, the value specified with the EXTSEC= initialization parameter in the
Advantage CA-Roscoe JCL is used to determine the external security
program-specific userid processing.
■ For EXTSEC=RACF:
Obtains the RACF userid associated with the Advantage CA-Roscoe
user from the ACEE. The ACEE address is saved in SCBSENV by the
RACF version of the ACFEXIT.
For a DB2 V2 connect, the RACF Connect Group List is copied to the
DB2 Authorization Identifier List, if RACF List of Groups Checking is
active.
■ For EXTSEC=TSS:
Obtains the eTrust CA-Top Secret userid for the Advantage CA-Roscoe
user from the SECREC. The SECREC address is saved in SCBSENV by
the eTrust CA-Top Secret version of the ACFEXIT.
For a DB2 V2 connect, the eTrust CA-Top Secret IBMGROUP list is
copied to the DB2 Authorization Identifier List, if available.
■ For EXTSEC=ACF2:

Obtains the eTrust CA-ACF2 LOGIN userid for the Advantage

CA-Roscoe user from the ACMCB. The ACMCB address is acquired
from the IWA. The IWA address is saved in SCBACFB by the eTrust
CA-ACF2 version of the ACFEXIT.
For a DB2 V2 connect, the eTrust CA-ACF2 Source Groups list is
acquired using the eTrust CA-ACF2 ACF00SSL Utility program.
4. If the EXTSEC= value does not match any of the supported external
security programs, ROS3@ATH checks for the existence of a site supplied
exit extension (ROS3@UEX). If it is found, ROS3@UEX is called to provide
the userid and authorization list.
5. If ROS3@UEX is not available, ROS3@ATH extracts up to eight bytes of the
userid from the SCB field ACCNUM. (The data from ACCNUM is
processed to the first blank or period found in the user's sign-on key.)
6. In all cases for a DB2 V2 connect, the current SQL identifier is set equal to
the Connect Authid.
ROS3@UEX Site Extension: If a site does not use one of the external security
packages supported by ROS3@ATH, a site-written exit routine may be added
to ROS3@ATH. This exit routine is responsible for providing the eight-byte
primary userid to ROS3@ATH for DB2 V1 and, optionally, the Authorization
Identifier List for DB2 V2.
It is not necessary to write this exit routine if the first eight bytes of the
Advantage CA-Roscoe user sign-on ID (stored in the SCB field of ACCNUM)
are sufficient to uniquely identify the user to DB2.
If a site-written exit routine is needed, it must:

■ Be written in assembler,
■ Have the CSECT name ROS3@UEX, and
■ Be capable of operating AMODE(31) and RMODE(ANY) if the operating
system is MVS/XA. Since the exit routine is loaded as part of DSN3@ATH
into E/CSA, this requirement must be met. Failure to adhere to 31-bit
addressing standards may result in Advantage CA-Roscoe/DB2 connection
abends.
ROS3@ATH branches to the exit routine with the following register contents at
entry:
R0 Undefined.
R1 Address of the following parameter list.
0 Address of a 228-byte work area.
4 Address of the PCB.
8 Address of the SCB.
12 Address of the ROT.

16 Address of an 8-byte authid result.

The following two parameters are used in DB2 V2 systems. For DB2
V1, both fields will be zero.
20 Number of entries in Auth List.
24 Address of DB2 V2 Auth List.
R2-R12 Undefined.
R13 Address of register save area.
R14 ROS3@ATH return address.
R15 Exit entry-point.
The exit routine must save and restore the calling registers using standard OS
register save and restore logic. Processing in the exit routine should be limited
to the minimum logic needed to determine the AUTHIDs necessary to satisfy
the DB2 connection requirements. Care should be taken since a failure or
abend in this exit routine terminates the DB2 connection attempt. Since
ROS3@UEX is called in Supervisor State Key 0, appropriate measures should
be taken to ensure that MVS integrity is not compromised by the actions of
this extension. Also exercise care if the routine performs I/O or any function
that may incur an operating system WAIT. (The entire DB2 connection process
for all address spaces is suspended until the WAIT is completed.)
Upon return from the exit routine, the AUTHID result field must contain an
8-byte left-justified, right-blank-padded AUTHID or a value of all blanks.
Specification of an AUTHID of all blanks causes DB2 to use the default
identification specified at DB2 installation time. ROS3@ATH makes no checks
on the 8-byte value returned by the exit routine.
For DB2 V2, the Authorization List should contain a series of eight-byte
left-justified, right-blank-padded secondary identifiers if the site extension
supports this function. If not supported, the list should not be modified by the
site extension. ROS3@ATH makes no checks on the authorization list returned
by the exit routine.
ROS3@ATH Installation: ROS3@ATH must be link-edited with the default (or

site-modified) DSN3@ATH module to create a load module that is also named
DSN3@ATH. If there is a site-written ROS3@UEX exit routine, it must also be
available at link-edit time.
After the link-edit has successfully completed, restart the DB2 system with the
new version of DSN3@ATH in the load library used by DB2 during startup
processing. The new DSN3@ATH must appear before any other version in the
startup libraries. After DB2 is restarted, Advantage CA-Roscoe users are
properly identified when Advantage CA-Roscoe/ETSO/DB2 sessions are
created.

The target load library must be authorized and must be in the DB2 startup JCL
since DSN3@ATH is loaded at DB2 initialization.
//ROS3LINK EXEC PGM=IEWL,PARM='LIST,MAP,RENT,LET,XREF'

//DB2LIB DD DSN=prefix.DSNLOAD,DISP=SHR 1
//ACFLIB DD DSN=prefix.acfload,DISP=SHR 2
//SYSLIB DD DSN=CAI.RO6LIB,DISP=SHR 3
//SYSLMOD DD DSN=user.auth.db2.loadlib,DISP=SHR 4
//SYSUT1 DD UNIT=VIO,SPACE=(CYL,5) 5
//SYSPRINT DD SYSOUT=
//SYSLIN DD
INCLUDE SYSLIB(ROS3@ATH) CA-ROSCOE/DB2 exit extension
INCLUDE ACFLIB(ACFSSL) ACF2 source utility 6
INCLUDE DB2LIB(DSN3@ATH) site or default DSN3@ATH
MODE AMODE(31),RMODE(ANY) MVS/XA requirement 7
ENTRY ROS3@ATH CA-ROSCOE exit as entry 8
NAME DSN3@ATH(R) load module name 9
/
Notes
1 DB2LIB must point to the load library that contains the site's current
version of DSN3@ATH.
2 The ACFLIB DD statement is only required by eTrust CA-ACF2
installations. It must point to the load library that contains the site's
current version of ACF2 module ACF00SSL. Note that the following
ACF2 maintenance is required to use this facility.
ACF2 V500 -- APAR TK87103
ACF2 V510 -- APAR TP87103
3 SYSLIB must point to the load library that contains the module
ROS3@ATH. ROS3@ATH is placed into the RO60LIB by the SMP/E
APPLY of the base Advantage CA-Roscoe SYSMOD CRO6000.
4 SYSLMOD must point to the authorized load library that is used by DB2
during startup to access the new DSN3@ATH module.
5 Use the site standard definition for the link-edit work file.
6 This INCLUDE statement is only required by eTrust CA-ACF2
installations.
7 The MODE statement is required for MVS/XA environments.
8 ROS3@ATH must be identified as the load module entry point.
9 The result load module must be named DSN3@ATH.

Additional Notes
■ The sample JCL illustrates how to create a new DSN3@ATH module that
include ROS3@TH and, optionally, ROS3@UEX.
Ensure that the existing site DSN3@ATH load module in not overlaid by
the link-edit job by either:
– Renaming the old DSN3@ATH, or
– Providing a new authorized library to contain the new DSN3@ATH
load module created by the job.
■ The placement of the modules in the job stream causes ROS3@ATH to be
placed at the beginning of the resulting load module. The ENTRY
statement must identify ROS3@ATH as the execution entry point.
■ ROS3@ATH contains a weak external reference to ROS3@UEX (the
required name of the optional site-written exit routine). If ROS3@UEX is
included, it must be in the same load library as ROS3@ATH when the
link-edit job is executed.
Do not provide a dummy ROS3@UEX module; it may cause exit failure
and incorrect results to be returned to DB2.

8.23 RPSEXIT: Roscoe Printing Services Exit

The ROSCOE Printing Services Exit (RPSEXIT) is called whenever a scheduled
print request is to be printed. (A print request is classified as 'scheduled'
between the time it is placed on the RPS ready queue, after the execution of
the PRINT command, and the time it is actually printed.)

■ The name of the exit routine must be RPSEXIT.
AMODE=31, RMODE=24.
31-bit Addressing Mode by a BASSM instruction; return to Advantage
Entrance Parameters: On entry to the routine, register 1 contains the

address of a fullword parameter list. The parameter list consists of a fullword
with a X'80' in the high-order byte and the address of RPXDSECT in the
low-order bytes.
RPXDSECT contains data areas that are available to the exit routine. To make
these areas available, the routine must include the following macro:
RPXDSECT EXIT=RPS
Two fields from RPXDSECT are valid with each call:

RPXIDCDE Address of a fullword identifying the exit that is calling this
routine. The code is in the low-order byte of the fullword. For
this exit, RPXIDCDE contains the exit identifier 26.
RPXCODE Fullword containing a code (in the low-order byte) that
identifies the type of call to the exit routine.
Code Meaning
0 Initial call (RPXR@INT). A PRINT request has been
selected to be printed and a printer has been
acquired.
The exit routine may add records. They are inserted
before the header and/or first spooled record. If
records are to be inserted, RPXRC1 must equal 12.

4 Final call (RPXR@FIN). The PRINT request has

completed. The exit routine should FREEMAIN all
areas and do all cleanup. The exit routine cannot
add new records.
8 A spooled or separator record is about to be
formatted (RPXR@NXT). The exit routine can do one
or more of the following:
■ Examine the record to be printed,
■ Alter or delete the record,
■ Add new records to the print request,
■ Indicate whether the new records are to print
before or after the input record.
12 End-of-File call (RPXR@EOF). The last record from
the spool has printed. The exit routine can add new
records. Trailer separators have not yet been
printed.
16 Top-of-Page call (RPXR@TOP). The record to be
printed is to be at the top of the page or the first
line after the top margin. Any records added by this
call precede any top margin. This call is not made
for non-Advantage CA-Roscoe requests (CA-ETC,
CA-eMAIL).
20 Last line in page call (RPXR@LLP). The last spool
line on the page has been printed. Either the logical
bottom of the page has been reached, the bottom
margin has been reached, or an EJECT is to be
performed. If any records added by this call cross a
page boundary, the next top-of-page call is not
recognized. This call is not made for non-Advantage
CA-Roscoe requests.
24 Hold call (RPXR@HLD). The print request has been
placed on the HOLD queue. The exit routine gets a
final call unless return codes specify otherwise.
28 Cancel call (RPXR@CAN). The print request has
been cancelled. The exit routine gets a final call
unless return codes specify otherwise.
32 End-of-Request call (RPXR@EOR). The print request
has completed. The exit routine can add new
records before the final call. If records are to be
inserted, RPXRC1 must equal 12.
The data areas of RPXDSECT that are available to the exit routine upon entry
are:

RPXPRTID Printer ID, passed to eight characters.

With VTAM, the ID is the VTAM identification.
With BTAM remote 3270-type terminals, the ID is the label
specified on the RCSDVICE macro in the RCSGEN.
With BTAM local 3270-type printer, the ID is the DD name
specified on the statement included in the Advantage CA-Roscoe
JCL.
RPXUKEY Address of the user's three-character prefix followed by the
22-character sign-on key.
RPXPCH Address of a one-byte control area with the printer characteristics,
where:
Bit Hex Meaning If Bit Is On

1... .... 8 Immediate release in effect.
.1.. .... 4 Separator pages are suppressed; otherwise,
bit 4 controls separators.
..1. .... 2 Carriage return without line feed.
...1 .... 1 Separators under request control; else,
separators under system control.
.... 1... 8 Shift RPS output one position right.
.... .1.. 4 Printer allows form feed character.
.... ..1. 2 Printer is shared with local copy.
RPXCMD Address of the RPSEXCB control area with the print request
options. See 'Notes' for a description of this control block.
RPXINPUT Address of the next input record to be printed. (This address is
valid when the area pointed to by RPXCODE contains an 8. For
all other calls, this address is set to zero.) The format of the input
area containing the record is:

Offset Length Meaning
2 Length of the record including this

2 length.
2 2 Two-byte code indicating record type,

where:
- header separator record

4 - trailer separator record
8 - record from spooled print request
4 1 Data formatting type, where:
X'8' -
Default
X'4' -
ANSI
X'2' -
MCC
X'1' -
Preformatted buffer (CA-ETC or
CA-eMAIL)
| X'8' - Record contains an 8 byte long
| 1 record header.
5 1 Reserved.
6 - Data and/or controls to be transmitted.

If this request is TYPE ANS, the first
column is examined for an ANS control
character. If it is not valid, a blank
is inserted by RPS.
RPXTOTLS Address of four halfword totals. The format of area is:
2 Number of lines currently on the page.

(This field contains zero for non-
CA-Roscoe generated requests.)
2 2 Total number of lines already in the

request (the request is printed)
including all text lines and all
blank or separator lines. (This field
contains zero for non-CA-Roscoe
generated requests.)
4 2 Total records in the spool member for

this request. (Matches value from
PRINT STATUS.)
6 2 Total remaining records in the spool to

be printed.
RPXWKAR Three-word work area for use by the exit routine.
The data areas of RPXDSECT that are available to the exit routine upon exit
are:

RPXRC1 Halfword that contains the return code defining the logical order
of the records pointed to by RPXOUTPT, if any, and RPXINPUT,
where:
0 Print input record only.
4 Print inserted records, then input record.
8 Print input record, then inserted records.
12 Do not print input record, print inserted records if
any.
RPXRC2 Two-byte field that contains either a bit setting (designating calls
to be skipped) or zero (if all calls are to be made).
The bits are meaningful only if the return code in register 15 is
zero. Each bit represents a different call to the exit. If the bit for
an exit call is on, no call is made when that condition occurs.
The bit settings are:
Bit Hex Mask Meaning
1... .... .... .... X'8' RPX$SPL Spool records.
.1.. .... .... .... X'4' RPX$HDR Header records.
..1. .... .... .... X'2' RPX$TRL Trailer records.
...1 .... .... .... X'1' RPX$TOP Top-of-page.
.... 1... .... .... X'8' RPX$LLP Last line of page.
.... .1.. .... .... X'4' RPX$EOF End-of-file.
.... ..1. .... .... X'2' RPX$HLD Hold request.
.... ...1 .... .... X'1' RPX$CAN Cancel request.
.... .... 1... .... X'8' RPX$EOR End of request.
RPXRC3 One-byte field that contains miscellaneous information the exit
passes back to RPS. The bit settings are:
Bit Hex Mask Meaning
1... .... X'8' RC3NOTRN Do not translate;
input record.
RPXOUTPT
Address of the address list that contains the records to be
inserted in the print request, or zero if no records are to be
inserted.
The last address in the list must contain a X'80' in the high-order
byte. If the number of addresses in the list causes a page
boundary to be crossed, calls for the top of page and last line on
page are skipped while processing records returned by the exit.
The format of the record is:

2 Length of the record including this length.
2 2 Record format, where:
- Standard RPS data line. Add one to line

count.
4 - Record contains printer controls to be

transmitted without translation. The next
halfword contains the number to be added
to the current line count.
4 2 Number of lines this record causes the printer

to advance. This value is used only if the
previous value (Offset 2) is 4. It if is
greater than one and a page boundary is
crossed, calls for top-of-page and last-
line-on-page are skipped with processing
records returned by the exit. (This field
is ignored for non-CA-Roscoe generated
requests.)
6 - Data and/or controls are to be transmitted.

These records are not processed by the RPS
line formatting routines (ANS, DEF,
MCC).

Code Meaning
0 Continue calls for this print request.
4 Do not call again for this print request.
Cleanup must have been done by the exit.
Notes: The RPSEXCB control block contains information about a print

request. The control block address is passed to the exit routine by RPXCMD.
The RPSEXCB DSECT can be used to obtain the following information:
Binary request number
Page number last transmitted
Number of copies to be printed
Request page length and width
Top and bottom margin values
User-assigned tag
DLOGMODE name
Device characteristics
Request class code
Request option(s) in use
Separator page suppression

Right shift suppression

Force physical page alignment
Single or double spacing
Description of printer

8.24 RPVEXIT: PRINT Command Exit

The Roscoe Printing Services Validation Exit (RPVEXIT) is called to validate
and control print requests. The calls are made during Advantage CA-Roscoe
maintask print processing.

■ The name of the exit routine must be RPVEXIT.
AMODE=31, RMODE=24.
Entrance Parameters: On entry to the routine, register 1 contains the

address of a fullword parameter list. The parameter list consists of a full-word
with a X'80' in the high-order byte and the address of RPVDSECT in the
low-order bytes.
RPVDSECT contains data areas that are available to the exit routine. To make
these area available, the routine must include the following macro:
RPVDSECT
The following field from RPVDSECT is valid for each call:

UX@CODE Address of a fullword that contains one of the following codes
(in the low-order byte). The code identifies the type of call to
the exit routine.
Code Meaning
0 Initial call (UXRP@INT). A PRINT command has
been issued. No parsing has been done at this
point; the only information available to the exit
routine is the user's terminal ID, key and prefix.
UXRPSTAT indicates the availability of RPS.

4 Authorization call (UXRP@AUT). RPS has attempted

to bind the terminal from which the command was
entered to a destination or destination list (as
defined in the site's RPS definition).
The exit routine should examine the status flag
(UXRPSTAT) to determine whether the terminal is
authorized to use RPS; then:
1. Authorize the terminal with the destination used
with the PRINT command or the RPS definition
default. (The exit routine may supply another
destination name in UXRPAREA to which RPS
should bind the terminal.)
2. The exit routine may designate that the terminal
is not authorized to use RPS.
8 Alternate Control Account call (UXRP@ACA). A
command restricted to owners of the RO or AI
prefix or an individual designated as an ACA was
issued.
This call is made only if the validation check
involved a prefix other than RO or AI. The status
flag (UXRPSTAT) indicates whether the user has a
valid ACA-defined prefix. The exit routine can
force RPS to allow or prohibit command processing.
12 Operand rejection call (UXRP@REJ). The exit routine
is called when RPS encounters an invalid PRINT
command operand or a predefined limit (as defined
in the site's RPS definition) has been reached.
Invalid operands include DEST. Exceeded limit calls
are made for copy, record and spool limits.
The exit routine must examine the UXRPSTAT area
for the rejection reason. Once determined, the exit
routine can accept, modify or reject the operand.
16 Modification call (UXRP@MOD). The exit routine is
called before validation checks are done for each of
the operands tag, DEST, COPY, CLASS and
NOTIFY. The routine must examine the UXRPSTAT
area for the operand currently being examined.
With DEST, COPY or CLASS, the exit routine can
modify the value by placing a new value in
UXRPAREA.
With NOTIFY, the original status of notification is in
the UXRPMISC flag. The exit routine should return
to RPS with a 4 in register 15 to reverse the
notification status.

Note: The exit is not called if notification is

restricted by the system.
20 Final call (UXRP@FIN). This is the final call made to
the exit routine. This call is made to give the exit
routine a chance to cleanup (free any areas it
GETMAINed).
Other exit-dependent data area of RPVDSECT that are available to the exit
routine are:
UX@ROTAD Address of the Roscoe Online Table (ROT) control block.
(Valid for all calls except 0.)
UX@SCBAD Address of the Session Control Block (SCB). (Valid for all calls
except 0.)
UX@PCBAD Address of the Presentation Area Control Block (PCB). (Valid
for all calls except 0.)
UX@WAREA Four fullwords to be used as a work area by the exit. (Valid
for all calls.)
UXRPTRM Address of the eight-byte terminal ID from which the PRINT
command is issued. (Valid for all calls.)
UXRPLCB Address of the eight-byte destination name to which the
current print request is being directed. (Valid for calls: 8, 12, 16
and 20.)
UXRPKEY Address of an area containing the sign-on key (padded to 22
characters) of the user issuing the PRINT command. (Valid for
all calls.)
UXRPPFX Address of area containing the prefix (padded to three
characters) of the user issuing the PRINT command. (Valid for
all calls.)
UXRPEXTP One-byte external indicator identifying the source of the PRINT
command, where:
Code Bit Hex Meaning
.... .... CA-Roscoe command line

4 .... .1.. 4 Data Set Facility
8 .... 1... 8 Library Facility
12 .... 11.. C Job output
16 ...1 .... 1
(RCS ESC sequence)
2 ...1 .1.. 14
(EMAIL/ETC)
24 ...1 1... 18 ETSO
28 ...1 11.. 1C ALLOCATE for SYSOUT (ETSO)
32 ..1. .... 2 Dynamic ALLOCATE for SYSOUT via ETSO
UXRPCLAS One-byte field containing the request class.

UXRPCOPY One-byte field containing the number of copies to be printed.

UXRPTYPE One-byte PRINT command type indicator, where:
.... .... Normal PRINT command

4 .... .1.. 4 PRINT CANCEL
8 .... 1... 8 PRINT HOLD
12 .... 11.. C PRINT RELEASE
16 ...1 .... 1 PRINT ROUTE
2 ...1 .1.. 14 PRINT STATUS
24 ...1 1... 18 PRINT LOCATION
28 ...1 11.. 1C PRINT DEVICE
32 ..1. .... 2 PRINT RESTART
36 ..1. .1.. 24 PRINT STOP
4 ..1. 1... 28 PRINT START
44 ..1. 11.. 2C PRINT MOD
UXRPMISC One-byte field containing miscellaneous flags, where:
.... .... 8 Notify user upon completion of print.

UXRPSTAT Address of one-byte area containing call-dependent
information, where:
1... .... 8 RPS is currently available

4 1... .... 8 Terminal authorized by RPS
.1.. .... 4 Bound on previous print cmd
8 1... .... 8 Prefix belongs to valid ACA
12 .... .... Invalid destination call
.... .1.. 4 Copy limit exceeded
.... 1... 8 Record limit exceeded
.... 11.. C Spool limit exceeded
16 .... .... Modify destination
.... .1.. 4 Modify number of copies
.... 1... 8 Modify request tag
.... 11.. C Modify notification status
...1 .... 1 Modify request class
The following areas are supplied by RPVEXIT to be passed back to RPS:

UXRPAREA Address of area supplied by the exit routine containing
information to be passed back to RPS.
Length of this area is assumed to be eight bytes for destination
names and tag names, a half-word for copy value and one-byte
for the class value.
UXRPAREA should contain an exit-supplied value when the
following return codes are passed back to RPS:

UXCODE R15
4 4
12 8
16 4
UX@MSGAD Address of 84-byte message area.
UX@RETFL One-byte message indicator. (X'80' = user-msg supplied).
UXRPCALL Address of a two-byte field containing bit map of calls to be
skipped. Each bit represents a different call to the exit. If the
bit for an exit call is on, no call is made when that condition
occurs. The bit settings are:
Bit Hex Meaning (Skip If)
1... .... .... .... 8 Dest rejection call

.1.. .... .... .... 4 Copy limit call
..1. .... .... .... 2 Record limit call
...1 .... .... .... 1 Spool limit call
.... 1... .... .... 8 Authorization call
.... .1.. .... .... 4 ACA call
.... ..1. .... .... 2 Destination modify
.... ...1 .... .... 1 Copy number modify
.... .... 1... .... 8 Tag modify call
.... .... .1.. .... 4 Class modify call
.... .... ..1. .... 2 Notify modify call
.... .... ...1 .... 1 Final call

routine must load register 15 with a return code. Examine the following chart
for the appropriate return code.
Code UXRPSTAT Return RPVRAREA Description Msg

0 X'80' 0 Print command issued no
4 Stop all calls for request yes
12 Stop all calls for request no
4 X'80' 0 Authorize terminal no
4 destname Authorize terminal no
8 Unauthorize terminal yes
8 X'80' 0 Allow command to process no
4 Stop command processing yes
12 Stop all calls for request yes

Code UXRPSTAT Return RPVRAREA Description Msg

12 X'00' 0 Bypass dest rejection no
4 Reject destination name yes
8 destname Print to supplied name no
X'04' 0 Bypass copy limit no
4 Reject copy operand yes
12 X'08' 0 Bypass record limit no
(cont.)
4 Reject request yes
X'0C' 0 Bypass spool limit no
4 Reject request yes
16 X'00' 0 No modification to dest no
4 destname Modify print destination no
X'04' 0 No copy modification no
4 copies Modify number of copies no
16 X'08' 0 No modification to tag no
(cont.)
4 tagname Modify tagname no
X'0C' 0 No notify modification no
4 Reverse notify status no
X'10' 0 No class modification no
4 class Modify request class no
20 n/a n/a Exit should free all areas no
Notes
■ A return code of 12 after any call from the exit routine terminates all calls
to the exit for the duration of the print request. It is the responsibility of
the exit routine to cleanup any unfreed storage before returning to RPS.
■ It is the exit routine's responsibility to insert data for the proper length into
the area pointed to by UXRPAREA. (Destination and tag names should be
eight-bytes in length padded to the right with blanks, the copy value is a
half-word and the class value is one byte).

8.25 RTFEXIT: RTF Routine Exit

The RTF exit permits sites to authorize individuals to use RTF. If an exit
routine is not present, only the owners of the RO and AI prefixes are
authorized to use RTF.

■ The routine must be reentrant and present in the object library.
■ The name of the exit routine must be RTFEXIT.
UXDSECT EXIT=(RTF)

exit identifier 9.
The area pointed to by the address in UXCODE contains the following code:
Code Meaning
0 User has finished RTF operand input and all operands have been
syntax checked (EQU UXRT@INT).
4 Last call (EQU UXRT@LST).
See section 7.3, “Common Data Areas” on page 7-4, for information about data
areas provided by UXDSECT. Note that UXDSECT contains no RTF
exit-dependent data areas.


CODE CODE
n/a 0 User may execute RTF. no
4 User may not execute RTF. yes
When the Message field contains 'YES', a RTFEXIT or site-written message is

appropriate RTFEXIT message is sent to the terminal.)


Notes:
■ The RTFEXIT is linked with RSSCRTF0 by executing an SMP/E RECEIVE
and APPLY of product USERMOD MRO608E.

8.26 SCREXIT: SCREEN Command Exit

SCREXIT can be used to control altering alternate screen sizes. SCREXIT is
called when a terminal user enters the SCREEN command and the user's
terminal is not defined as queriable and does not support the create-partition
structured field. This exit not be used for non-IBM terminals.

■ The name of the exit routine must be SCREXIT.
UXDSECT EXIT=(SCR)
| ■ The member SCREXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 25.

Code Meaning
0 SCREEN verify call (EQU UXSC@SET). This call occurs when a user
enters the SCREEN command to alter the screen size to other than
the alternate or primary size set by the terminal hardware or while
in setup mode.
exit-dependent data area is available to the exit routine:
UXSCRTRM Address of the area containing the terminal ID, padded to eight
characters. See the description of the area SCBTRMNM under
topic 1.2.2 for an explanation of the ID format. (The ID is
present for all calls.)



CODE CODE
0 0 Command accepted. No
4 Command rejected. Yes
When the Message field contains 'YES', a SCREXIT or site-written message is

appropriate SCREXIT message is sent to the terminal.)


8.27 SETEXIT: SET Commands Exit

The SET commands exit is called whenever a user issues the SET AUTOFF,
SET STMTCNT or SET TLOCK command. It can be used to control
individual's ability to change settings.

■ The name of the exit routine must be SETEXIT.
UXDSECT EXIT=(SET)
| ■ The member SETEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 26.

Code Meaning
0 SET STMTCNT validation (EQU UXST@STM).
4 SET TLOCK validation (EQU UXST@LOK).
8 SET AUTOFF validation (EQU UXST@AUF).
| C SET PRIVilege validation (EQU UXST@PRV)
| 10 SET DUPCR validation (EQU UXST@DUP)

UXSETVAL Address of a value or area. Each SET command has its own
definition of this area, where for:
SET AUTOFF UXSETVAL contains the address of the
following two-word area:
Word 1 Four-byte integer value which will be:
SET AUTOFF n (where
Word 2 contains the
value of n).
4 Reserved.
8 Reserved.
12 SET AUTOFF OFF disabled
for this terminal.
16 SET AUTOFF ON enabled
for this terminal.
Word 2 Four-byte integer value when Word 1
contains 0. (This value may be
modified.)
SET STMTCNT
UXSETVAL contains the address of a fullword
value FFFFFFFF if the user entered SET
STMTCNT RESET. With any other form of the
command, UXSETVAL contains the value
specified with the command. (This value may
be modified.)
SET TLOCK UXSETVAL contains the address of the
following two-word area:
Word 1 Four-byte integer value which will be:
SET TLOCK n (where Word
2 contains the value of n).
4 SET TLOCK LOGOFF.
8 SET TLOCK NOLOGOFF.
12 SET TLOCK ON/OFF (Use
site default for this terminal.)
16 SET TLOCK ON/OFF (Use
opposite of site default.)
Word 2 Four-byte integer value when Word 1
contains 0. (This value may be
modified.)


routine must load one of the following return codes in register 15. If a value
other than one defined below is found, Advantage CA-Roscoe abends with a
user completion code of 998.

CODE CODE
0 0 Accept or modify no
command.
4 Reject command. yes
command.
command.
| C 0 Accept or modify no
| command.
| 4 Reject command. yes
| 10 0 Accept or modify no
| command.
| 4 Reject command. yes
When the Message field contains 'YES', a SETEXIT or site-written message is

appropriate SETEXIT message is sent to the terminal.)

must be: a halfword length field, a halfword containing binary zeros, and the

8.28 SIGEXIT: Sign-on Exit

The sign-on exit is called during sign-on. The exit routine can converse with
the terminal user to gather information, refuse the sign-on and write user
records to the Advantage CA-Roscoe SESSION file. Other processing may be
performed as necessary.

■ The name of the exit routine must be SIGEXIT.
UXDSECT EXIT=(SIG)
| ■ The member SIGEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 10.

Code Meaning
0 0 Initial call (EQU UXSI@1ST).
4 Start from beginning again (EQU UXSI@AGN).
UXSIGTIM Address of a fullword containing the sign-on time in binary
form (as received from TIME SVC with BIN operand). (This
address is valid for both entrance codes.)

UXSIGRPY Address of a buffer containing a reply from the terminal. (This

address is valid for both entrance codes.)
The buffer contains X'FF000000' if an I/O error occurs when
reading the terminal response or writing a terminal message.
An ATTN from the terminal or null reply is indicated by a
value of X'FE000000' in the buffer.
The text buffer pointed to by this word is 132 bytes long and is
cleared to EBCDIC spaces before the terminal reply is moved
into it. It is a transient area and the address and its contents are
valid only until return from SIGEXIT.
UXSIGREC Address of a fullword-aligned buffer which may be used by the
exit routine to build an accounting record. (This address is
valid for both entrance codes.)
This buffer may not be used to store information between
successive calls. It is not cleared before SIGEXIT is called.
The format of the buffer is:
header 124-byte header. The first two bytes contain the
length of the record. The length includes this
124-byte header plus the length of the user segment
of the record (The length is preset to 224.)
user 100-byte area containing zeros. This area may be
used to pass accounting information to the
accounting files. If less than 100 bytes are needed,
the length in the header may be changed provided it
is not set to less than 124.
UXSIGDAT Address of a six-byte area containing the current date in
display format (mmddyy). (This address is valid for both
entrance codes.)
This date may be inserted by the user exit routine into the field
SDATE of any accounting record to be written.
The state of the SCB is not defined during sign-on; the exit routine should not
refer to any fields in the SCB except for PREFIX (containing the user's prefix)
and ACCNUM (containing the user's sign-on key).

routine must load one of the following return codes in register 15. If a value
other than one defined below is found, unpredictable results may occur.


CODE CODE
0 0 The user is permitted to no
sign on.
4 The user is not yes
permitted to sign on.
8 A site-written message yes
requesting a reply is to
be written to the
terminal.
See also Notes.
12 A user record is to be no
written to the
accounting data sets.
The address of the area
containing the record
must be placed in
UXSIGREC.
See also Notes.
4 0 The user is permitted to no
sign on.
4 The user is not yes
permitted to sign on.
8 A site-written message yes
requesting a reply is to
be written to the
terminal.
See also Notes.
When the Message field contains 'YES', a SIGEXIT or site-written message is

appropriate SIGEXIT message is sent to the terminal.)


Notes
■ If an ACFEXIT routine is being used, SIGEXIT is called between the
ACFEXIT calls of 0 (verify) and 4 (initialize).
■ When creating an accounting record, the field SRTYPE must be set to
appropriate record type code (X'40' through X'4F').
These records are added to the accounting files but are not included in the
accounting reports produced by Advantage CA-Roscoe.
These records can be included in other reports and accounting systems.
This is done by the ACCTREPT program exit. (That is, when the
ACCTREPT program is executed, the exit routine identified by the
ACTEXIT SYSIN control statement processes these records.)
■ The records can be a maximum of 224 bytes in length where the first 124
bytes comprise the standard Advantage CA-Roscoe header segment. (It can
be mapped through the SRECORD DSECT which is generated by the
SRECORD macro.) The variable segment of the record may contain any
data the site wishes as long as it does not exceed 100 bytes in length.
■ If, with either an entrance code of 0 or 4, the exit routine sets the return
code to 8, the routine is called again with an entrance code of 4. On return
to the exit routine, UXSIGRPY contains the address of the area containing
the user's response.
If, when the entrance code is 0, the exit routine sets the return code to 12,
the record is written to the accounting data sets and the routine is called
again with an entrance code of 4.

8.29 SMFEXIT: Accounting Exit

SMFEXIT can be used to supplement or replace the standard Advantage
CA-Roscoe accounting routine when additional online accounting is required.
It is called once at system initialization and thereafter whenever Advantage
CA-Roscoe writes an accounting record.

■ The name of the exit routine must be SMFEXIT.
UXDSECT EXIT=(SMF)
Entrance Parameters: Upon entrance to the routine, register 1 contains either

0 or the address of a fullword. If register 1 contains 0, the exit is being called
during Advantage CA-Roscoe initialization. If register 1 contains the address of
a fullword, the fullword contains the address of UXDSECT.
exit identifier 16.

Code Meaning
0 Sign-on record call (EQU UXSM@SON).
4 Sign-off record call (EQU UXSM@OFF).
8 User record call (EQU UXSM@USR).
12 Monitor record call (EQU UXSM@MON).
16 Shutdown record call; last call (EQU UXSM@SHU).
20 Abend in write last call (EQU UXSM@ABN). An I/O error occurred
while writing an accounting record.
24 Other (EQU UXSM@XXX). See the field SRTYPE in SRECORD.

UXSMFSES Address of the variable length record to be written to the
accounting files. (This address is valid when the entrance code
is 0, 4, 8, 12, or 16.)
This record is mapped by the DSECT SRECORD, generated by
the Advantage CA-Roscoe macro SRECORD.

meaning of the code depends on:
1. The contents of register 1 when the exit routine was called. (If register 1
contained 0, the exit routine was called during Advantage CA-Roscoe
initialization. A 0 return code must be loaded into register 15.)
2. The area pointed to by UXCODE on entrance to the routine.

CODE CODE
0 0 Continue processing. no
4 Omit writing to no
accounting files and
continue.
continue.
continue.
continue.
continue.
return code.


CODE CODE
continue.
Notes
■ SMFEXIT is called during Advantage CA-Roscoe initialization. Register 1
contains 0 for this call. (It contains the address of a fullword that points to
UXDSECT for all subsequent calls.) The SMFEXIT exit routine may
perform such processing as required. Most of the ROT fields are
unformatted at this point in initialization; the contents of LASTATT are
unpredictable.
■ The type of record to be written is determined both from the code
contained in the area pointed to by the address in UXCODE and by the
value in the field SRTYPE. SRTYPE is a one-byte field in SRECORD.
■ If Advantage CA-Roscoe accounting should terminate abnormally, the exit
routine is called one last time; the area pointed to by UXCODE contain 20.
The exit routine should perform whatever termination housekeeping is
required. The accounting calls, including subsequent calls on SMFEXIT, are
disabled.
■ If standard Advantage CA-Roscoe accounting records are to be used, the
only field in the accounting records passed to SMFEXIT that may be
modified is SRUAF.
SRUAF is a 20-byte field that is set to zero and is not modified by the
standard Advantage CA-Roscoe accounting facilities. It is intended to be
used to convey information to site-written ACCTREPT program exit
routines.

8.30 SUBEXIT: Submit Exit

The SUBMIT exit executes under the SUBMIT subtask. It is called by SUBMIT
processing before each record is passed to the output stream for submission to
the operating system. A SUBMIT exit routine may permit a record to be
written to the output stream as is, delete it from the stream, replace it with one
or more other records or abort the submission. In addition, the exit routine
may maintain accounting information on submitted jobs.

■ The name of the exit routine must be SUBEXIT.
UXDSECT EXIT=(SUB)
■ The routine may perform any processing needed, including I/O
processing, but it may not issue any I/O requests to terminals.
| ■ The member SUBEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 11.

Code Meaning
0 Initial call (EQU UXSU@1ST).
4 First or next record in the job stream (EQU UXSU@NXT).
8 Error encountered job aborted (EQU UXSU@ERR).
12 Open AllFusion CA-Librarian master file (EQU UXSU@OPN). This
call occurs only if no DSAEXIT routine is present. If a DSAEXIT
routine is present, this call is bypassed.
16 End of input (EQU UXSU@EOF).
20 Final call (EQU UXSU@LST). Any resources acquired by the exit
routine should be released at this time.

24 Subtask has abended (EQU UXSU@ABT). This call is for

housekeeping purposes only. When it occurs, it becomes the final
call to the exit routine (a 20 call does not occur).
UXSUBJNM Address of an eight-byte jobname. (This address is valid when
the entrance code is 4, 8, 12, 16, 20, or 24.)
If multiple jobs are submitted, the area contains the name of
the first job.
UXSUBJB# Address of the eight-byte job number. (This address is valid
If multiple jobs are submitted, the area contains the number of
the last job.
UXSUBPWS Address of the 10-byte user password as determined at sign-on
or using the PASSWORD command. (This address is valid with
every call.)
UXSUBREC Address of an 80-byte input record. (This address is valid when
the entrance code is 4.)
UXSUBRCO Address of a fullword that is to contain the address of the
address list containing the replacement records. The last
address in the list must contain a X'80' in the high-order byte.
The replacement records must all be 80 bytes in length. (This
address must be supplied by the exit routine.)
UXSUBDSN Address of the 44-byte AllFusion CA-Librarian master file
named in a SET MASTER command. (This address is valid
UXSUBVOL Address of the six-byte volume serial number of the AllFusion
CA-Librarian master file named in the SET MASTER command.
UXSUBMEM Address of the eight-byte module name specified on the -INC
statement. (This address is valid when the entrance code is 12.)


CODE CODE
return code.


CODE CODE
4 0 Use the current record no
and continue.
4 Ignore the current no
record and continue.
8 Replace the current no
record and continue. The
address of the address
list containing the
replacement record(s)
must be placed in the
area pointed to by
UXSUBRCO.
12 Delete the submission. yes
return code.
12 0 Open master file and no
continue.
4 Reject open. yes
See also 'Notes'.
16 0 Continue. no
4 Continue. no
8 Add the current no
record(s) to the end of
the file.
12 Delete the submission. yes
return code.
return code.
When the Message field contains 'YES', a SUBEXIT or site-written message is

appropriate SUBEXIT message is sent to the terminal.)


Notes
■ When a AllFusion CA-Librarian master file is to be opened, Advantage
CA-Roscoe checks to see if a DSAEXIT routine is present. If a DSAEXIT
routine is present, the call to SUBEXIT is bypassed. If no DSAEXIT routine
is present, the call to SUBEXIT is made and the exit routine must
determine if the file is to be opened. Note: No facility is provided with
SUBEXIT to open protected (PROD2) AllFusion CA-Librarian master files.
■ If a site is using RACF (EXTSEC=RACF) and an ACFEXIT exit routine,
their SUBEXIT routine does not need to add USER= or PASSWORD= to
the JOB statement.
■ When deleting a job stream, all JOB statement processing must be
complete (all continued lines have been processed). Unpredictable results
occur if JOB statement processing is not complete.
■ If the job stream contains +INC statements or -INC AllFusion CA-Librarian
control statements, the exit routine is passed the expanded data; not the
+INC or -INC statements themselves.
■ If the exit routine rejects the job stream and a SUBMIT termination
message is written to the terminal, a trap code is set. If the exit routine
returns its own message, no trap code is set.
■ The distributed exit routine illustrates how the NOTIFY parameter can be
handled. This parameter allows JES2/JES3 status messages to be written to
the Response Line of a user's terminal when that user's jobs complete
execution. (See the Advantage CA-Roscoe Interactive Environment System
Reference Guide for additional information.)

8.31 UPSMEXIT: 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.
Caution
If this facility is used while the UPSMNTnn panel is active, the program in
UPSMEXIT must not perform any action that causes a panel to be
deactivated.
The following table identifies the maximum number of arguments that may be
passed to UPSMEXIT.
Table 8-1. UPSMEXIT Arguments
TYPE OF CALL A1 A2 A3 A4
Before Add A1 " Data being
added
After add A2 " Data added code
Before Update U1 Data before update Data after
After Update U2 Data before update Data after code
Before Delete D1 Data to be deleted "
After Delete D2 Deleted data " code
■ When a call occurs before an action is performed, UPSMEXIT may inspect

the data passed to it and may alter processing.
■ When a call occurs after the data has been processed, UPSMEXIT may
audit the action. The code in A4 will contain a zero if the operation
performed successfully or a nonzero value if a problem occurred.
■ A2 contains the string of data as it appears before processing.

■ A3 contains the data as it will appear after processing. The following table
shows the format of this data.
COLUMN CONTENTS
1-3 User's prefix.
4-25 User's sign-on key.
26-47 User's formal key.
48 Password required indicator.
49 Password change indicator.
50-57 User's library line limit.
58-65 Current number of lines user has saved in library.
66-77 Name of user's sign-on procedure.
78 Sign-on procedure change indicator.
79 Restricted user indicator.
80-87 Name of user's security group.
88 Operator command privileges indicator.
89 RPS command privileges indicator.
90 Accounting command privileges indicator.
91 ETSO command privileges indicator.
| 92 UPS Administrator privileges indicator.
| 93 Library Administrator privileges indicator.
UPSMEXIT may pass one to three values back to UPSMNTnn or UPSBLKnn

when returning from the calls shown in the table below.
CALL ACTION TO OCCUR RETURN

VALUES
A1 Perform operation. 0
And U1 Data altered. (Person doing 1 msg
maintenance is prompted to
verify new data.)
Cancel operation. v msg
D1 Perform Operation. 0
Cancel Operation. v msg

USPMEXIT Return Values
'v', shown above, may be any value other than 0 or 1.
Messages (msg) are optional. If a message is returned, it may be a maximum

of 78 characters and length. It is displayed on the UPSMNTnn panel or the
terminal screen (for UPSBLKnn executions).
When altering data, the format of the new data must conform to the string
format described above.
For information about writing RPF programs, see the Advantage CA-Roscoe
Interactive Environment RPF Language Guide.

8.32 ZAPEXIT: ZAP Routine Exit

Sites may want to implement the ZAP exit to verify the authorization of the
terminal user to access or update a data set. The exit routine is given control
after all ZAP command statements have been read but before the SYSLIB data
set is opened.

■ The name of the exit routine must be ZAPEXIT.
UXDSECT EXIT=(ZAP)
| ■ The member ZAPEXIT on CAI.RO60OPT contains a sample exit routine.

exit identifier 14.

Code Meaning
0 Verify call (EQU UXZA@NXT).
4 Protected data set (EQU UXZA@PRO). This call occurs only if no
call is bypassed.
8 Last call (EQU UXZA@LST).
UXZAPDSN
Address of a 44-byte area containing the name of the SYSLIB data
set to be zapped. (This address is valid when the entrance code is
0, or 4.)
If the data set is a volume table of contents, the area contains the
true data set name of the volume table of contents rather than
FORMAT4.DSCB.

UXZAPCOD
Address of a one-byte field whose low-order bit contains either:
Code Meaning
0 No REP or SETSSI subcommand was included in the
subcommands entered by the user.
1 At least one REP or SETSSI subcommand was
included in the subcommands entered by the user.
(The address of this field is valid when the entrance code is 0 or
4.)

meaning of the code depends on the contents of the area pointed to by

CODE CODE
0 0 ZAP execution no
continues.
4 Processing is yes
suppressed; ZAP
terminates.
4 0 ZAP execution no
continues.
4 ZAP terminates. yes
See also Notes.
return code.
When the Message field contains YES, a ZAPEXIT or site-written message is

appropriate ZAPEXIT message is sent to the terminal.)


Notes
If a DSAEXIT routine is found, it is called to validate whether the user can
ZAPEXIT routine is bypassed.)
If no DSAEXIT routine is found, the ZAPEXIT routine is called.
■ If no DSAEXIT routine is present, the ZAPEXIT routine is called when a
data set, ZAPEXIT terminates with a 913 abend.

| Chapter 9. Service Routines and Load Modules
This chapter describes how to use the:

■ IAJTODAY module can be used to obtain the current date and time.
■ LIBSIEVE module can be used to verify that a name conforms to
Advantage CA-Roscoe member naming conventions.
■ ROSXINIT load module can be used to execute a specific module during
Advantage CA-Roscoe initialization.
■ ROSXTERM load module can be used to execute a specific module during
Advantage CA-Roscoe termination.
■ UPSREAD service routine which can be used to look up user sign-on keys
in the User Profile System (UPS).
Chapter 9. Service Routines and Load Modules 9-1

9.1 IAJTODAY Routine
9.1 IAJTODAY Routine

The IAJTODAY module can be called as appropriate to obtain the current date
and time.
Entrance Parameters: Upon entrance, IAJTODAY should be passed the

following variable-length parameter list:
Contents Meaning
date Required. Address of the eight-byte area that is to contain the
current date in the form mm/dd/yy.
time Optional. Address of the eight-byte area that is to contain the
current time in the form hh.mm.ss.
Example
CALL IAJTODAY,(DATE,TIME),VL
...
DATE DC CL8' '
TIME DC CL8' '

9.2 LIBSIEVE Module
9.2 LIBSIEVE Module

The reentrant module LIBSIEVE is loaded and called as needed by every
Advantage CA-Roscoe program that accesses the Advantage CA-Roscoe library
to evaluate the correctness of a member name.
Coding Conventions: Standard OS linkage conventions should be used

when calling LIBSIEVE.
Entrance Parameters: Upon entrance to LIBSIEVE, register 1 must contain:

A(MEM) Eight-character area containing the Advantage CA-Roscoe member
name, right-filled as needed with blanks.
Return Codes: On return from LIBSIEVE, register 15 contains one of the

following:
Code Meaning
0 The name is formed correctly according to Advantage
CA-Roscoe naming conventions.
4 The name is not formed correctly according to Advantage
CA-Roscoe naming conventions.

9.3 ROSXINIT Module
9.3 ROSXINIT Module

ROSXINIT is a load module consisting of a list of modules that are to be
executed during Advantage CA-Roscoe initialization, in addition to the
standard Advantage CA-Roscoe code. Such modules may process initialization
for either Monitor routines or for user exits. ROSXINIT is loaded by the last
phase of Advantage CA-Roscoe initialization. Each module named in the list
is LINKed to in the order of its appearance in the list. The LINKs may be
made conditional.
ROSXINIT source code is included on the Advantage CA-Roscoe source

library. If changes to the source code are made, be sure that the module
names already present are not removed.
To add entries to the list, code the ROSX macro (carried in the source as a user
macro) as follows:
ROSXINIT Module
──┬─────┬──ROSX──name──┬────────┬─────────────────────────────
└─tag─┘ └─(,MON)─┘

Name of a load module which is to be LINKed to.
If the load module performs initialization for a Monitor routine, the
first three letters of the load module name should correspond to the
base name of the Monitor routine. (For example, if the Monitor
routine is named RSSCABC0, the load module name might be
ABCINIT.) This naming conventions permits conditional execution
of the module if the MON operand is coded.
MON causes execution of the named module during initialization to be
conditional upon the inclusion of a Monitor routine whose name
has base characters identical to the first three characters of 'name'. If
omitted, ROSXINIT always attempts to execute the named module.
Coding Conventions: Coding conventions for the modules named in

ROSXINIT are:
■ They need not be reusable since they are used only once.
■ Standard OS linkage conventions are used. Registers 1 and 15 are used to
pass information between Advantage CA-Roscoe and each module.

9.3 ROSXINIT Module
Entrance Parameters: On entrance, register 1 will contain the address of the

ROT. The ROT is completely formatted at this time, except for such fields as
are completed by extended initialization. All DCBs are open, and in BTAM
systems, a READ TI (initial) is outstanding to every terminal.
Notes: Sites that want:

■ specific load modules executed during Advantage CA-Roscoe initialization
should use ROSXINIT to identify those modules.
■ to pre-load specific load modules but do not want them executed during
initialization can use the PRELOAD= initialization parameter. (See the
Advantage CA-Roscoe Interactive Environment Programs and Utilities Guide for
additional information about this and all other Advantage CA-Roscoe
initialization parameters.)

9.4 ROSXTERM Module
9.4 ROSXTERM Module

ROSXTERM is a load module consisting of a list of modules that are to be
executed during Advantage CA-Roscoe termination, in addition to the
standard Advantage CA-Roscoe code. Such modules may process termination
for either Monitor routines or for user exits. ROSXTERM is loaded by the last
phase of Advantage CA-Roscoe termination. Each module named in the list is
LINKed to in the order of its appearance in the list. The LINKs may be made
conditional.
ROSXTERM source code is included on the Advantage CA-Roscoe source

library. If changes are made to the source code, be sure that the module
names already present are not removed.
To add entries to the list, code the ROSX macro (carried in the source as a user
macro) as follows:
ROSXTERM Module
──┬─────┬──ROSX──name──┬────────┬─────────────────────────────
└─tag─┘ └─(,MON)─┘

name is the name of a load module that is to be LINKed to.
If the load module performs termination for a Monitor routine, the
first three letters of the load module name should correspond to the
base name of the Monitor routine. (For example, if the Monitor
routine is named RSSCABC0, the load module name might be
ABCTERM.) This naming convention permits conditional execution
of the module if the MON operand is coded.
MON causes execution of the named module during termination to be
conditional upon the inclusion of a Monitor routine whose name
has base characters identical to the first three characters of 'name' If
omitted, ROSXTERM always attempts to execute the named
module.
Coding Conventions: Coding conventions for the modules named in

ROSXTERM are:
■ They need not be reusable since they are used only once.
■ Standard OS linkage conventions are used. Registers 1 and 15 are used to
pass information between Advantage CA-Roscoe and each module.
Entrance Parameters: On entrance, register 1 contains the address of the

ROT.

9.5 UPSREAD Routine
9.5 UPSREAD Routine

The UPSREAD service routine allows site-written programs to look up user
sign-on keys in the User Profile System (UPS) for accounting or verification
purposes. (Use the service routine GETUPS to sequentially read user profiles.)
UPSREAD may be link-edited with the calling program and called, or loaded
and called. It is not reentrant. It contains a DCB that is opened when the
routine is first called and left open for use on subsequent calls until it is closed
on request of the calling program.
When a program that invokes UPSREAD is executed, the JCL must include a
DD statement for each file comprising the Advantage CA-Roscoe library, as in:
//ROSLIBnn DD DSN=ROSCOE.ROSLIBnn,DISP=SHR
Coding Conventions: Standard OS linkage conventions should be used

when calling UPSREAD.
The routine using UPSREAD must be established as a subtask as UPSREAD

uses the LIBI Interface.
Entrance Parameters: Upon entrance to UPSREAD, register 1 must contain

the address of the following 2-word parameter list:
Contents Meaning
FUNC Fullword containing a function code identifying the type of call to
UPSREAD. The calls are:
1 Initialize call.
2 Get user key call.
3 Terminate call.
A(REC) Address of an area into which the user's UPS profile record is to be
placed. (This area may be mapped by the ACCMEM macro.) When
UPSREAD is called with a function code 2, it expects the user
sign-on key to be in the ACMKEY field of ACCMEM.
Return Codes: On return to the site-written program from UPSREAD,

register 15 contains one of the following return codes:
Code Meaning
0 Call completed without error (the sign-on key was found and
the UPS record has been placed in the area pointed to by
A(REC)).
4 Either the sign-on key was not found or an I/O error occurred.

9.5 UPSREAD Routine
Code Meaning
8 Advantage CA-Roscoe libraries are not defined.
12 Parameter list conflict. Either an invalid call code was specified
or the site-written program attempted to get a user sign-on key
before making an initial call to UPSREAD.

Appendix A. Monitor Linkage Conventions
Caution
The Monitor macros, described in Chapter 3 should be used in place of the
linkage conventions described in this appendix.
The Monitor macros can be used to handle:

■ Communications between the Monitor routine and Advantage
CA-Roscoe.
■ Subtasking.
■ Reentrance.
Standard OS linkage conventions are used.
Appendix A. Monitor Linkage Conventions A-1

A.1 Entrance Parameters

Registers 0 and 1 are used to pass information between Advantage CA-Roscoe
and the Monitor routine.
The entrance codes contained in register 0 on each entry to the Monitor routine
are divided into three types: initial entrance, normal continuation and
exception continuation.
1. Initial Entrance
Register 0 contains the following:
Location Contents
Byte 1 X'00'.
Byte 2 First character of the command identifier (Z for ZAP).
Byte 3 Fourth character of the command identifier. If it was not
specified with the command, a binary zero is present.
Byte 4 Optional appendage to the identifier (B in ZAP-B). Where
there is no appendage, the byte is set to X'00'.
Register 1 contains the address of the string, if a string was specified with
the invoking command. The format is a 1-byte length field followed by n
characters, where n does not exceed 200.
On the initial entrance to the routine, register 6 points to a 120-byte buffer
which may be used as a work area only during initialization. The area is
reused by Advantage CA-Roscoe immediately upon return from the initial
call, so no data may be stored in it between calls.
Use of the X Attribute
If the terminal user enters a command and the X attribute has been specified in
the RUN initialization parameter for that Monitor, bytes 2 and 3 are translated
to uppercase. Byte 4 and the string in register 1 are not translated to
uppercase.
If X is not specified, bytes 2, 3 and 4 and the string are translated to uppercase.
Note: For more information on passing information to monitors, see the RUN
command in the Advantage CA-Roscoe Interactive Environment Command
Reference Guide.
A-2 Extended Facilities for System Programmers Guide

2. Normal Continuation
Register 0 contains binary zero. Register 1 contains one of the following:
Contents Meaning
0 No data is being passed from Advantage CA-Roscoe to
the Monitor routine.
address of reply Pointer to:
a. A 200-byte area containing the reply from the
terminal. The length of the data in the area can be
determined by scanning backwards for a nonblank
character. All terminal control characters have been
deleted.
b. The next line of the AWS or library member being
read.
With 255-character records, an eight-byte header
precedes the data. The header consists of a length
field (containing the length of the data plus eight
bytes), the sequence number (as a binary fullword)
and a halfword of binary zeros. The format of the
record is:
1 3 7 9 263
┌─────────┬───────────┬─────┬──────────────┐
└─────────┴───────────┴─────┴──────────────┘
With 80-character records, the format is 74 characters of data followed by

the six-digit sequence number (as a binary fullword). A Monitor routine
may direct Advantage CA-Roscoe to pass data from the AWS or a library
member without overlaying the contents of columns 75 through 80 with
the sequence number by ORing a X'40' into SWITCH06 in the SCB. This
switch setting is reset before the initial entrance to the Monitor routine, but
is not reset by Advantage CA-Roscoe during the execution of the routine.
address of get data
Pointer to an area containing the data requeste from the
Advantage CA-Roscoe Program Variable Pool, formatted
as a one-byte length field, followed by n characters.

3. Exception Continuation
Register 0 contains the following:
Location Contents
Byte 1 X'FF'
Byte 2 X'00'
Byte 3 X'00'
Byte 4 An indicator identifying the nature of the exception condition.
It may have one of the following values:
X'00' Forced termination due to an I/O error or sign-off. The
Monitor routine must terminate. After a Monitor
routine is entered with the must-stop condition
(register 0 = X'FF000000'), it is permitted to request a
real wait before taking the final exit. If such a real wait
is requested, the next entry to the routine does not
occur until after complete of the awaited event: this is
to permit an orderly disposal of subtasks and the like.
It is the responsibility of the Monitor routine to ensure
against a processing loop in this state.
C'N' End-of-file on input from the AWS or a library
member. This condition does not require termination of
the Monitor routine which ends when the appropriate
code is returned in register 15.
C'S' An ATTN was received from the terminal during I/O.
(For example, the user pressed the CLEAR key in
response to a terminal prompt.) Normally, an ATTN
causes the current routine to terminate and the stop
switch to be set to place an RPF program in pause
mode. However, the Monitor routine may ignore this
condition and continue processing. In this case, the
pending stop condition is purged. If, however, the
Monitor routine returns immediately after this entrance
code with a return code of 8, the stop condition is
reinstated.
'C'O' The AWS has overflowed on the last PUTAWS exit.
The Monitor routine need not terminate.

C'V' The variable request could not be completed due to an

error. This condition does not require termination of
the Monitor routine. Register 1 points to a descriptive
message that can be used for debugging. Execution of
the Monitor routine can be terminated by returning the
appropriate code in register 15.
C'T' A message could not be sent to the terminal because of
the terminal user's use of SET MONLEVEL or SET
MONTRAP. The message has been placed in the RPF
session variable S.LASTERR.
Register 1 contains no information except as stated above for indicator
C'V'.

A.2 Return Codes
A.2 Return Codes

Before returning control, the Monitor routine must:
1. Load one of codes shown below in register 15.
2. Set register 1 to either a data pointer or 0. The presence of a data pointer
(described below) is independent of the return code, unless register 15
contains 04, 16, 20, 24, 28 or 36. When register 1 does not contain a data
pointer, it must be set to 0.
Note: The $ROSCOE macro provides functions that simplify reading and
writing data. The appropriate $ROSCOE function is shown with
each return code.
Code Meaning
00 Call again with next 80-byte line from the AWS or library. (See
$ROSCOE FUNC=GETAWS.)
04 The combination of registers 15 and 1 designate the function.
Register 15 must contain 4. If register 1 contains:
■ A data pointer: Call again with no input. (See $ROSCOE
FUNC=PUTTERM.)
The address in register 1 must point to an address list, as
follows:
REG1 DC A(MSG1)
DC A(MSG2)
...
DC X'8',AL3(LASTMSG)
such that,
MSG1 DC AL1(L'MSG1A)
MSG1A DC C'ANY ALPHANUMERIC DATA'
...
LASTMSG DC AL1(L'LASTMSGA)
LASTMSGA DC C'LAST LINE WRITTEN ...'
To activate the terminal alarm: OR X'80' into SWITCH07 in the
SCB.
To cause the user's response to be masked: OR X'01' into
SWITCH07 in the SCB.
■ 0 and the SCB field SWITCH02 is X'02': Real Wait. (See A-10.)
■ 0 and the SCB field SWITCH02 is X'80': Time-out Request. (See
A-10.)
■ 0 and the SCB field SWITCH02 is not X'02' or X'80': Pause State
(See A-10.)
■ 0 and register 0 contains the SPIE address: SPIE (See A-12.)

A.2 Return Codes
08 Final return; program is terminated. (See $ROSCOE FUNC=FINAL.)

Register 1 must contain 0.
The value returned in the low-order two bytes of register 0 is taken
as a return code. This return code may be accessed by RPF
programs as the session variable S.RC.
If a Monitor routine is made unavailable because of an 0Cx
exception or an invalid parameter returned to Advantage
CA-Roscoe, the return code is set to 998.
12 Call again with a terminal reply. (See $ROSCOE
FUNC=GETTERM.)
Register 1 must contain 0.
16 Write an 80-byte line into the AWS and call again. (See $ROSCOE
FUNC=PUTAWS.)
Register 1 must contain the address of an address list, as described
with return code 4.
20 Write a user accounting record and call again. (See $ROSCOE
FUNC=SESSION.)
24 Put or get data from the Advantage CA-Roscoe Program Variable
Pool and call again. (See $ROSCOE FUNC=PVR.)
To place data in the Program Variable Pool, register 1 must contain
the address of an address list. This address list contains the address
of the request to place (PUT) the data, the variable which contains
the data, and the data itself.
To obtain data from the Program Variable Pool, the address list
pointed to by register 1 must contain the address of the request to
obtain (GET). On return, register 1 contains the address of the data,
formatted as a one-byte length field immediately followed by the
data.
The address list in register 1 is formatted as:
DC A(request)
DC A(variable)
DC X'8',AL3(data)
The request must be specified to either place or obtain the data. It is
formatted as:
#GET DC F'1'
#PUT DC F'2'
The variable must be specified by valid variable names. All
variables may be specified. The format is:

A.2 Return Codes
LOC1 DC AL1(L'LOCAL1)
LOCAL1 DC C'L1'
NM DC AL1(L'NAME)
NAME DC C'ANYNAME<5>'
The preceding example illustrates how a user-defined indexed
variable can be referenced.
The data is formatted as:
DATA DC AL1(L'DTASTR)
DTASTR DC C'ANY DATA STRING'
28 Write a 255-byte line into the AWS and call again. (See $ROSCOE
FUNC=PUTAWSX.)
Register 1 must contain the address of an address list. The first byte
of the address list must contain X'80' an dthe address must point to
the record to be written. The format of the record is:
1 3 7 9 263
┌─────────┬───────────┬─────┬──────────────┐
└─────────┴───────────┴─────┴──────────────┘
32 Call again with the next 255-byte line from the AWS or library. (See
$ROSCOE FUNC=GETAWSX.)
36 Write message not exceeding 255 bytes and call again. (See
$ROSCOE FUNC=PUTMSG.)
Register 1 must contain the address of a $MONMSG message.
Register 0 must contain the address of a sublist or binary zeros (if
no sublist is present). The sublist contains the addresses of one to
four variable text segments that are to be substituted into the
message generated by the $MONMSG macro. (The last segment
must have a X'80' ORed in the high-order byte.)
Notes
■ No line of data to be sent to the terminal may exceed 255 characters in
length, nor may it contain any control characters or other characters that
cannot be printed or displayed on a terminal.
■ With a return code of 16, the length of a line to be written into the AWS
may not exceed 80 characters. With a return code of 28, the line length
may not exceed 255 characters. Lines are assigned sequence numbers
beginning with one and incremented by one. When a Monitor routine
makes its first request to write to the AWS, the previous contents of the
AWS is lost.
■ On every call to the Monitor routine, register 7 contains the address of the
ATT1 and register 5 contains the address of the SCB. The four fullwords in

A.2 Return Codes
the SCB with the tags SCBUSER1 through SCBUSER4 are reserved for use
by the Monitor routine. The integrity of these four words is guaranteed by
Advantage CA-Roscoe between the initial call to the routine and final
return from it, but not between discrete executions of the routine.

A.3 Pause State
A.3 Pause State

The Monitor pause state is defined as a return from the Monitor routine to
Advantage CA-Roscoe with register 15 containing 4 and register 1 containing
0. After such a return, the Monitor routine is reentered (dispatched) again
when all pending work for the other terminals has come to a break point. (The
purpose of the pause state is to allow other users to dispatch in this fashion.)
Pending work is represented to Advantage CA-Roscoe by an ECB that is
posted to indicate completion of some request (I/O). A break point means that
the user last dispatched has reentered a wait state (pending completion of an
I/O request). If a Monitor routine returns in a pause state when there is no
pending work for any other user of the system, the Monitor routine is
immediately reentered.
Additional facilities are provided for delaying the reentrance to the Monitor
routine. These facilities, described below, are mutually exclusive (for a single
return from the Monitor routine) and are designed for different purposes. Each
facility is enabled by setting a request flag in the SCB. The real wait request
facility also uses fields in the Advantage CA-Roscoe data areas ATT1 and ROT
(covered by register 13 on entrance to the Monitor routine). Each facility can be
used only when the Monitor returns in a pause state.
■ Time-out Request
SWITCH02 in the SCB is ORed with X'80'. Advantage CA-Roscoe does not
dispatch the Monitor routine again until one-tenth of a second has elapsed.
(The reentrance may be somewhat delayed if there are many users with
work pending on the dispatching list. It may also occur earlier if a timer
request is already pending for another user.)
■ Real Wait Request
SWITCH02 in the SCB is ORed with X'02'. This facility is designed for
subtask communications between the Monitor routine and its subroutines.
If the Monitor routine attaches a subtask and then has nothing to do until
completion of the subtask (or of a request by the subtask for input, and so
forth), it should pass to the subtask the address of field ECB in the ATT1.
The subtask should then post the ECB when appropriate. The Monitor
routine is meanwhile in a wait state which ends only when the ECB is
posted.
Once the ECB is posted, Advantage CA-Roscoe:
1. Copies the contents of the ECB into the field LASTECB in the ROT.
2. Clears the ECB.
3. Dispatches the Monitor routine.

A.3 Pause State
If the Monitor routine does not ensure that the ECB is eventually posted,
the terminal is locked out until Advantage CA-Roscoe is shut down. For
some subtasks, particularly those that perform no input or output
operations, the ECB may be specified as the operand of the ECB=keyword
of ATTACH. Normally, though, the ECB is needed to control ongoing
communications between the Monitor routine and the subtask; it is then
necessary to specify an exit routine address (via the ETXR= keyword of
ATTACH) and arrange for the specified exit routine to notify the Monitor
routine when the subtask has completed.
After a Monitor routine is entered with the must-stop condition (R0 =
X'FF000000'), it is permitted to request a real wait before making its final
return. This is to permit the orderly disposal of subtasks and the like. It is
the responsibility of the Monitor routine to ensure against a processing
loop in this state.
After some number of consecutive pause-state returns from the Monitor

routine, the terminal user is permitted to terminate execution of the Monitor
routine when the following message is issued:
PAUSE ... ENTER "STOP" TO TERMINATE
The value of the pause limit is preset to 120. It may be changed in two ways:
■ With the Advantage CA-Roscoe initialization parameter PAUSE, as defined
in the Advantage CA-Roscoe Interactive Environment Programs and Utilities
Guide.
■ By the privileged command ROZAP, as described in the Advantage
CA-Roscoe Interactive Environment System Commands Guide.

A.4 Monitor SPIE/ESPIE Handling
A.4 Monitor SPIE/ESPIE Handling

Advantage CA-Roscoe intercepts all program exception interrupts (except
significance) with its own SPIE/ESPIE exit. The Monitor routine may not issue
a SPIE, ESPIE, STAT or ESTAE SVC at the main task level. Instead, if it can
handle or expects such an interrupt, it may return the address of a
pseudo-SPIE exit routine on its first return to Advantage CA-Roscoe. This
address must be returned in register 0. (The contents of register 0 are ignored
unless the S subparameter has been coded in the RUN initialization
parameter.) A pseudo-SPIE exit routine is simply a SPIE exit routine written
according to all conventions defined by OS, and to which Advantage
CA-Roscoe passes control after having intercepted the program exception
interrupt. The contents of the registers and return conventions are precisely as
though the pseudo-SPIE exit had received control directly from the operating
system.
The Monitor routine is run with all program exception interruptions enabled
except significance. The Roscoe CA-SPIE/ESPIE exit intercepts all such
interruptions occurring under the first PRB of the Advantage CA-Roscoe main
task. Interruptions occurring in subtasks or under SVRBs are not so
intercepted.
If a Monitor routine, lacking its own pseudo-SPIE exit, is interrupted by a

program exception, it is disabled for the remainder of the current Advantage
CA-Roscoe execution, and the following message is displayed:
CMD7 COMMAND TERMINATED DUE TO PROGRAM EXCEPTION
Subsequent attempts to use the same command fail with the message:
CMD24 REQUESTED MONITOR COMMAND NO LONGER AVAILABLE TODAY
The Monitor routine can be reactivated via the ROZAP UNLOCK command.
Note: If there is no pseudo-SPIE exit, the MONABXIT routine is invoked
when a program exception occurs. MONABXIT writes: 1) a snap dump
to the SYSOUT file defined by the MONSNAP DD statement, and 2) a
diagnostic message to the console.

Index
ACFEXIT Exit (continued)

Special Characters Common Reentrancy Macros 7-8, 7-9
$CALL Macro (Monitor) 3-3 Data Areas
$GBL Macro (Monitor) 3-5—3-6 Common 7-4, 7-5, 7-6, 7-7
$GBLEND Macro (Monitor) 3-5—3-6 Exit-Dependent 8-4
$MONMSG Macro (Monitor) 3-8—3-9 Description 8-3
$PRM Macro (Monitor) 3-10 Entrance Parameters
$PRMEND Macro (Monitor) 3-10 Exit-Dependent 8-4
$PROC Macro (Monitor) 3-11—3-14 Register Conventions 7-3
$PROCEND macro (Monitor) 3-15 Return Codes 8-5, 8-7
$RETURN macro 3-16 Sample JCL 7-12
$ROSCOE Macro (Monitor) 3-17—3-33 Testing 7-10, 7-11
$WRK Macro (Monitor) 3-34 ACTIVATE function
$WRKEND Macro (Monitor) 3-34 AWSI 4-7
LIBI 5-7
A Activate new AWS (AWSI) 4-7
Active Terminal Table 1 (ATT1) 1-4
Access Control Facility
Add entry to library
See ACFEXIT Exit
LIBI 5-7, 5-8
ACCMEM Macro 9-7
ADD function
ACCNUM in SCB 1-4
LIBI 5-7, 5-8
Accounting
Advantage CA-Roscoe 1-1
Exits
Allocate
ACCTDUMP 8-2
Library resources (LIBI) 5-7
Descriptions 6-2
ALTER function
ROSMAILS 8-81
LIBI 5-8, 5-9
SIGEXIT 8-108
ALTER JOB Command
SMFEXIT 8-112
Exit 8-73
Write to file from Monitor routine 3-29
Altering
ACCSONT in SCB 1-4
Library Member Attributes
ACCTDUMP Program Exit
LIBI 5-8, 5-9
Coding Conventions 8-2
AMS Command
Description 8-2
Exit 8-9
Entrance Parameters 8-2
AMSEXIT Exit
Return Codes 8-2
Coding Conventions
ACEE in SCB 1-4
Common 7-2
ACFEXIT Exit 8-3
Exit-Dependent 8-9
ACEE in SCBACFB 1-4
Common Reentrancy Macros 7-8, 7-9
Coding Conventions
Data Areas
Common 7-2
Common 7-4, 7-5, 7-6, 7-7
Exit-Dependent 8-3
Index X-1
AMSEXIT Exit (continued) AWSI Interface (continued)
Data Areas (continued) Current AWS (AWSRNBPT) 4-22
Exit-Dependent 8-10 Data areas 4-2
Description 8-9 Delete AWS records 4-10, 4-11
Entrance Parameters Description of 4-1, 4-2, 4-3
Exit-Dependent 8-9 Error conditions 4-24
Register Conventions 7-3 Exception code (AWSRXRC) 4-22
Return Codes 8-10, 8-11 Functions, list of 4-6
Sample JCL 7-12 Get AWS configuration 4-13
Testing 7-10, 7-11 Get AWS status 4-20
Arithmetic symbols (syntax diagrams) xvi Highest sequence number in AWS
ATT1 (Active Terminal Table 1) 1-4 (AWSRHSEQ) 4-22
ATTACH DSN Command Initialize Interface 4-14
Exit 8-41 Insert
ATTACH JOB Command Initiate 4-20
Exit 8-73 Reset/Terminate 4-19
ATTACH LIBRARY Command Linkage conventions 4-3
Exit 8-64 Macro, description of 4-5
AUTEXIT Exit Move records 4-14, 4-16
Coding Conventions Number of records in AWS (AWSRNMBR) 4-22
Common 7-2 Position pointer
Exit-Dependent 8-12 Direct 4-16, 4-17
Common Reentrancy Macros 7-8, 7-9 When inserting 4-20
Data Areas Read AWS record 4-12, 4-13
Common 7-4, 7-5, 7-6, 7-7 Record format 4-2
Exit-Dependent 8-13 Release AWS 4-11
Description 8-12 Renumber AWS 4-19
Entrance Parameters Terminate 4-21
Exit-Dependent 8-12, 8-13 With multiple users 4-3
Register Conventions 7-3 Write record to AWS 4-18
Return Codes 8-14 AWSI Macro
Sample JCL 7-12 See also AWSI Interface
Testing 7-10, 7-11 Description of 4-1, 4-2, 4-3
AWS Syntax 4-4, 4-5
Information Block (AWSIB) 4-13 AWSIB (AWS Information Block) 4-13
Parameter Block (AWSPB) 4-2 AWSIB Macro 4-13
Request Block (AWSRB) 4-2 AWSMGR Subsystem 4-1, 4-2, 4-3
Status Block (AWSSB) 4-20 AWSPB (AWS Parameter Block)
Working with 4-4 Macro 4-2
AWSI and LIBI Interfaces plus individual exit AWSRB (AWS Request Block)
descriptions Fields comprising 4-22, 4-23
See Data areas Load address 4-4
AWSI Interface 4-1 Macro 4-2
Activate new AWS 4-7 AWSRHSEQ in AWSRB 4-22
AWS Information Block (AWSIB) 4-13 AWSRNBPT in AWSRB
AWS Parameter Block (AWSPB) 4-2 Description 4-22
AWS Request Block (AWSRB) 4-2 With multiple AWSs 4-3
AWS Status Block (AWSSB) 4-20 AWSRNMBR in AWSRB 4-22
Checkpoint 4-7 AWSRPARM in AWSRB 4-22, 4-23
Coding macro 4-4, 4-5 AWSRSTAT in AWSRB 4-22
Copy AWS records 4-8, 4-9
X-2 Extended Facilities for System Programmers Guide

AWSRXRC in AWSRB CKPTIO function (AWSI) 4-7
Description 4-22 CLLEXIT Exit
Return codes 4-3 Coding Conventions
AWSSB (AWS Status Block) 4-20 Common 7-2
Exit-Dependent 8-21
B Data Areas
BANEXIT Exit Common 7-4, 7-5, 7-6, 7-7
Coding Conventions Exit-Dependent 8-21, 8-22, 8-23
Common 7-2 Description 8-21
Exit-Dependent 8-15 Entrance Parameters
Common Reentrancy Macros 7-8, 7-9 Exit-Dependent 8-21
Data Areas Register Conventions 7-3
Common 7-4, 7-5, 7-6, 7-7 Return Codes 8-23
Exit-Dependent 8-16 Sample JCL 7-12
Description 8-15 Testing 7-10, 7-11
Entrance Parameters CMDEXIT and CMDEXIT2 8-25
Exit-Dependent 8-15 CMDEXIT Exit
Register Conventions 7-3 Coding Conventions
Return Codes 8-16, 8-17 Common 7-2
Sample JCL 7-12 Exit-Dependent 8-26
Testing 7-10, 7-11 Common Reentrancy Macros 7-8, 7-9
Banner Page, Controlling Data Areas
See BANEXIT Exit Common 7-4, 7-5, 7-6, 7-7
Batch Access Authorization Exit Exit-Dependent 8-27
See BEXEXIT Description 8-25
BEXACCRD in BEXEXIT 8-18 Entrance Parameters
BEXCALLR in BEXEXIT 8-18 Exit-Dependent 8-26, 8-27
BEXEXIT 8-18 Register Conventions 7-3
BEXEXIT Exit Return Codes 8-27, 8-28
Coding Conventions 8-18 Sample JCL 7-12
Description 8-18 Testing 7-10, 7-11
Entrance Parameters 8-18 CMDEXIT2 Exit
Return Codes 8-19 Coding Conventions
BEXKEY in BEXEXIT 8-18 Common 7-2
BEXSUBCD in BEXEXIT 8-18 Exit-Dependent 8-26
C Data Areas
Common 7-4, 7-5, 7-6
CALL Command
Exit-Dependent 8-27
Exit 8-21
Description 8-25
Calling Monitor routine ($CALL macro) 3-3, 3-4
Entrance Parameters
CHAIN02 in ATT1 1-4
Exit-Dependent 8-26, 8-27
CHAINTO1 in SCB 1-4
Register Conventions 7-3
Change
Return Codes 8-27, 8-28
Library member name
Sample JCL 7-12
LIBI 5-15, 5-16
Testing 7-10, 7-11
Member attributes
Comma
LIBI 5-8, 5-9
repeat symbol, use in xix
Checkpoint AWS data modified by Monitor routine
Command Exits
(AWSI) 4-7
See CMDEXIT and CMDEXIT2
Index X-3
CONEXIT Exit DISEXIT Exit (continued)
Coding Conventions Common Reentrancy Macros 7-8, 7-9
Common 7-2 Data Areas
Exit-Dependent 8-29 Common 7-4, 7-5, 7-6, 7-7
Common Reentrancy Macros 7-8, 7-9 Exit-Dependent 8-32, 8-33
Data Areas Description 8-32
Common 7-4, 7-5, 7-6, 7-7 Entrance Parameters
Exit-Dependent 8-29 Exit-Dependent 8-32
Description 8-29 Register Conventions 7-3
Entrance Parameters Return Codes 8-33, 8-34
Exit-Dependent 8-29 Sample JCL 7-12
Register Conventions 7-3 Testing 7-10, 7-11
Return Codes 8-30 DISPLAY Command
Sample JCL 7-12 Exit 8-32
Testing 7-10, 7-11 DSAEXIT 8-35
CONSOLE Command DSAEXIT Exit
Exit 8-29 ACEE in SCBACFB 1-4
Copy AWS records (AWSI) 4-8, 4-9 Coding Conventions
COPY function (AWSI) 4-8, 4-9 Common 7-2
Exit-Dependent 8-35
D Data Areas
Data areas 1-1 Common 7-4, 7-5, 7-6, 7-7
See also Advantage CA-Roscoe Exit-Dependent 8-36—8-38
ATT1 1-4 Description 8-35
Caution 1-1 Entrance Parameters
ROT 1-2 Exit-Dependent 8-35, 8-36
SCB 1-4 Register Conventions 7-3
Data Set Access Exit Return Codes 8-38
See DSAEXIT Sample JCL 7-12
Data Set Facility Testing 7-10, 7-11
Exit (See DSFEXIT) 8-41 DSFEXIT Exit
DB2 Authorization Exit Coding Conventions
See ROS3@ATH Exit Common 7-2
Default values (syntax diagrams) xx Exit-Dependent 8-42
DEL function Common Reentrancy Macros 7-8, 7-9
LIBI 5-9 Data Areas
DELETE function (AWSI) 4-10, 4-11 Common 7-4, 7-5, 7-6, 7-7
Deleting Exit-Dependent 8-48
AWS records (AWSI) 4-10, 4-11 Description 8-41, 8-42
Member from library Entrance Parameters
LIBI 5-9 Exit-Dependent 8-43
Delimiters Register Conventions 7-3
syntax diagrams, use in xvii Return Codes 8-48, 8-49
DETACH DSN Command Sample JCL 7-12
Exit 8-41 Testing 7-10, 7-11
DETACH JOB Command DSN Command
Exit 8-73 Exit 8-41
DISEXIT Exit DSN3@ATH Exit
Coding Conventions See ROS3@ATH Exit
Common 7-2
Exit-Dependent 8-32

E F
ECBLIST in ROT 1-2 FINAL function ($ROSCOE) 3-19
ECBLISTX in ROT 1-2 FIND function
Entry point, establishing Monitor ($PROC) 3-11, LIBI 5-10
3-12, 3-13, 3-14 Find library member entry
Error conditions LIBI 5-10
AWSI 4-24 Formatting
LIBI 5-20 Library member entry (LIBI) 5-10
Monitor macros 3-32 Free
ETSO AWS (AWSI) 4-11
Exit Library resource
Banner 8-15 LIBI 5-10
CALL Command 8-21 FREE function
Exit AWSI 4-11
See ROSMAILS Program Exit LIBI 5-10
Exit Facilities
See also individual exit descriptions
Call Order 6-5—6-10 G
Common Coding Conventions 7-2 GET Function
Common Data Areas 7-4, 7-5, 7-6, 7-7 AWSI 4-12, 4-13
Common Reentrancy Macros 7-8, 7-9 LIBI 5-10
Common Register Conventions 7-3 GETAWS Function ($ROSCOE) 3-19
Testing 7-10, 7-11 GETAWSX Function ($ROSCOE) 3-20
Types of GETKEY Function
Accounting 6-2 LIBI 5-11
Command 6-2, 6-3 GETPFX Function
Security 6-3, 6-4, 6-5 LIBI 5-11
Session 6-5 GETTERM Function ($ROSCOE) 3-21
UPS 8-119, 8-120 GETUPS Service Routine 9-2
EXPEXIT Exit Global Monitor work areas, establish 3-5
Coding Conventions
Common 7-2
Exit-Dependent 8-51
I
IAJTODAY Routine 9-2
IMPEXIT Exit
Data Areas
Coding Conventions
Common 7-4, 7-5, 7-6, 7-7
Common 7-2
Exit-Dependent 8-52, 8-53, 8-55
Exit-Dependent 8-57
Description 8-51
Entrance Parameters
Data Areas
Common 7-4, 7-5, 7-6, 7-7
Description 8-57
Sample JCL 7-12
Entrance Parameters
Testing 7-10, 7-11
EXPORT Command
Exit 8-51
Extended
Sample JCL 7-12
Initialization (ROSXINIT) 9-4
Testing 7-10, 7-11
Termination (ROSXINIT) 9-6
Index X-5
IMPORT Command LBRBDBPT in LBRB
Exit 8-57 Description 5-19
INFO function LBDB address 5-3
AWSI macro 4-13 LBRBECDE in LBRB 5-19
LIBI 5-12 LBRBPARM in LBRB 5-19
INIT function LBRBSTAT in LBRB 5-19
AWSI macro 4-14 LBRBXRC in LBRB
LIBI 5-12 Description 5-19
Initialize Error code 5-3
AWSI Interface 4-14 LBSB (Library Status Block) macro 5-17
Batch LIBI Interface 5-13 LIB function
Online LIBI Interface 5-12 LIBI 5-13
INITX function LIBEXIT Exit
LIBI 5-13 Coding Conventions
Insert into AWS Common 7-2
Initiate (AWSI) 4-20 Exit-Dependent 8-65
Terminate (AWSI) 4-19 Common Reentrancy Macros 7-8, 7-9
Data Areas
Common 7-4, 7-5, 7-6, 7-7
J Exit-Dependent 8-65—8-67
JCL, Sample Description 8-64
Assemble/link Monitor routines 2-3 Entrance Parameters
Exits Exit-Dependent 8-65
Assemble/Link 7-12 Register Conventions 7-3
Include SHOW macro 7-11 Return Codes 8-67, 8-68
Monitor routines, Assemble/Link 2-2 Sample JCL 7-12
JOBEXIT Exit Testing 7-10, 7-11
Coding Conventions 8-63 LIBI Interface 5-1
Description 8-63 Add entry to library 5-7, 5-8
Entrance Parameters 8-63 Allocate library resources 5-7
Return Codes 8-63 Alter member attributes 5-8, 5-9
Change member name 5-15, 5-16
K Coding macro 5-4, 5-5
Data Areas 5-2
Keywords (syntax diagrams) xvi
Delete member from library 5-9
Description 5-1
L Error Exceptions 5-20
LASTATT in ROT 1-2 Fine member entry 5-10
LASTECB in ROT 1-2 Format member entry 5-10
LBAAC macro (Library Account Block) 5-11 Functions, list of 5-6
LBDB (Library Definition Block) 5-2 Get
LBIB (Library Information Block) macro 5-12 Index entry 5-13
LBINDEX Macro 5-10, 5-13, 8-67 Key and security group 5-11
LBPMDEF (Library Parameter Definition) macro Library configuration 5-12
Description 5-2 Number of available library blocks 5-17
Syntax 5-18 Prefix and security group 5-11
LBRB (Library Request Block) macro Status of library resources 5-17
Description 5-2 Initialize
Format 5-19 Batch Interface 5-13
Online Interface 5-12
Library Account Block (LBAAC) 5-11

LIBI Interface (continued) Local Monitor work areas, establish 3-34
Library Information Block (LBIB) 5-12 Locate library member entry
Library Parameter Definition (LBPMDEF) LIBI 5-10
Description 5-2
Syntax 5-18
Library Request Block (LBRB) M
Description 5-2 Macros
Format 5-19 $CALL (Monitor) 3-3, 3-4
Library Status Block (LBSB) 5-17 $GBL 3-5, 3-6
Linkage conventions 5-3 $GBLEND 3-5, 3-6
Locate member entry 5-10 $MONMSG 3-8, 3-9
Macro, description of 5-4, 5-5 $PRM 3-10
Position within member 5-14, 5-15 $PRMEND 3-10
Read next logical member record 5-10 $PROC 3-11, 3-12—3-14
Release library resource 5-10 $PROCEND 3-15
Replace entry in library 5-7, 5-8 $RETURN 3-16
Save status of library buffers 5-13 $ROSCOE 3-17—3-33
Terminate LIBI 5-17 $WRK 3-34
With multiple users 5-3 $WRKEND 3-34
Write next logical line to library 5-15 ACCMEM 9-7
LIBI macro 5-4 AWSI
See also LIBI Interface Description 4-1, 4-2, 4-3
Description 5-1 Syntax 4-4, 4-5
Syntax 5-5 AWSIB 4-13
LIBIO Subsystem 5-1 AWSPB 4-2
Libraries, user AWSRB 4-2
Monitor routines, site-written LBAAC 5-11
Account Block 5-11 LBDB 5-2
Get index entry 5-13 LBIB 5-12
Number of available blocks 5-17 LBINDEX 5-10, 5-13, 8-67
Request block (LBRB) 5-19 LBPMDEF
Working with Description 5-2
See LIBI Interface Syntax 5-18
LIBRARY Command LBRB
Exit 8-64 Description 5-2
Library member Format 5-19
Monitor routine, site-written LBSB 5-17
Add to library 5-7, 5-8 LIBI
Alter attributes 5-8, 5-9 Description 5-1
Change member name 5-15, 5-16 Syntax 5-4, 5-5
Delete from library 5-9 MAILREC 8-81
Find entry 5-10 MONM 3-7
Format entry 5-10 ROSX
Position within 5-14, 5-15 With ROSXINIT 9-4
Read next logical record 5-10 With ROSXTERM 9-6
Replace in library 5-7, 5-8 RPVDSECT 8-95
Validate Name Using LIBSIEVE 9-3 RPXDSECT 8-88
LIBSERVE Program RSSCEXPU 8-52
Exit 8-18 SHOW 7-10, 7-11
LIBSIEVE Module 9-3 SRECORD
With SIGEXIT 8-111
With SMFEXIT 8-113, 8-114
Index X-7
Macros (continued) Monitor macros (continued)
UXALC 8-45, 8-47 MONM 3-7
UXDFG 8-47 Monitor Routines
UXDSECT Defining to Advantage CA-Roscoe 2-3
Data Areas 7-4 Definition of 2-2
Description 7-4 Monitor writing
UXENTER 7-8 description of facilities 2-1
UXEXIT 7-8, 7-9 Passing parameters to 2-4
UXOUTDS 8-75 Monitor writing
MAILREC macro 8-81 Advantage CA-Roscoe communications
Message from Monitor routine Activate WAIT state 3-31
To terminal ($MONMSG) 3-8, 3-9 Examples 3-33
To terminal/AWS (MONM) 3-7 Exceptions Conditions 3-32
Messages Program variable pool 3-27, 3-28
To terminal or AWS Read 255-character AWS/member line 3-20
$MONMSG macro 3-8, 3-9 Read 80-character AWS/member line 3-19
MONM macro 3-7 Read terminal line 3-21
MONEXIT Exit Set pause state 3-22
Coding Conventions SPIE handling 3-30, 3-31
Common 7-2 Subtask communications 3-28
Exit-Dependent 8-70 Terminate 3-19
Common Reentrancy Macros 7-8, 7-9 Write 255-character line to AWS 3-23
Data Areas Write 80-character line to AWS 3-23
Common 7-4, 7-5, 7-6, 7-7 Write accounting record 3-29
Exit-Dependent 8-70, 8-71 Write message to terminal 3-24, 3-25
Description 8-70 Write to terminal 3-26
Entrance Parameters AWSI Interface, using 4-1, 4-2, 4-3
Exit-Dependent 8-70 AWSI macro, coding 4-4, 4-5
Register Conventions 7-3 Call a routine 3-3, 3-4
Return Codes 8-71 Defining to Advantage CA-Roscoe 2-3
Sample JCL 7-12 Definition of terms 2-2
Testing 7-10, 7-11 Description of facilities 2-1
Monitor Commands Establish
Definition of 2-2 Advantage CA-Roscoe communications 3-17,
Exit 8-70 3-18
Monitor macros Entry point 3-11, 3-12, 3-13, 3-14
$CALL 3-3, 3-4 Global work areas 3-5, 3-6
$GBL 3-5, 3-6 Local work areas 3-34
$GLBEND 3-5, 3-6 Parameter list 3-10
$MONMSG 3-8, 3-9 Storage requirements 3-11, 3-12, 3-13, 3-14
$PRM 3-10 Subtask 3-11, 3-12, 3-13, 3-14
$PRMEND 3-10 LIBI Interface, using 5-1
$PROC 3-11, 3-12, 3-13, 3-14 LIBI macro, coding 5-4, 5-5
$PROCEND 3-15 Load module requirements 2-2, 2-3
$RETURN 3-16 Message to terminal/AWS
$ROSCOE 3-17—3-33 Static 3-7
$WRK 3-34 Variable 3-8, 3-9
$WRKEND 3-34 Monitor macros, description of 3-1, 3-2
AWSI 4-4, 4-5 Naming conventions 2-2
Description of 3-1, 3-2 Passing parameters to routine 2-4
LIBI 5-4, 5-5 Restrictions 2-5, 2-6

Monitor writing (continued) PREFIX in SCB 1-4
Return to calling routine 3-16 Presentation Area Control Block (PCB) 1-6
MONM macro (Monitor) 3-7 PRINT Command
Move AWS records (AWSI) 4-14, 4-16 Exit 8-95
MOVE function (AWSI) 4-14, 4-16 Program variable pool
MRO608E USERMOD 8-102 $ROSCOE macro 3-27, 3-28
Programs
comma
N repeat symbol, use in xix
NOTE function parentheses
LIBI 5-13 syntax diagrams, use in xvii
punctuation
O syntax diagrams, use in xvi
Pseudo-SPIE exit
OFF Command
Monitor routine 3-30, 3-31
Exit 8-3
Punctuation marks (syntax diagrams) xvi
OFFON Command
PURGE Command
Exit 8-3
Exit 8-63
OUTEXIT Exit
PUT
Coding Conventions
See Writing
Common 7-2
PUT function
Exit-Dependent 8-73
AWSI 4-18
LIBI 5-15
Data Areas
PUTAWS function ($ROSCOE) 3-23
Common 7-4, 7-5, 7-6, 7-7
PUTAWSX function ($ROSCOE) 3-23
PUTMSG function ($ROSCOE) 3-24, 3-25
Description 8-73
PUTTERM function ($ROSCOE) 3-26
Entrance Parameters
PVR function ($ROSCOE) 3-27, 3-28
Return Codes 8-76 R
Sample JCL 7-12 RCS
Testing 7-10, 7-11 Exit
Communications 8-77, 8-79
P RCSECA 8-77, 8-79
RCSEXIT Exit
Parameter list area, establish Monitor 3-10
Coding Conventions
Parentheses
Common 7-2
syntax diagrams, use in xvii
Exit-Dependent 8-77
PASSWORD Command
Exit 8-3
Data Areas
PAUSE function ($ROSCOE) 3-22
Common 7-4, 7-5, 7-6, 7-7
PCB (Presentation Area Control Block) 1-6
Exit-Dependent 8-78
PCBUSERn in PCB 1-6
Description 8-77
POINT function
Entrance Parameters
AWSI 4-16, 4-17
Exit-Dependent 8-77
LIBI 5-14, 5-15
Position
Return Codes 8-78
AWS pointer (AWSI) 4-16, 4-17
Sample JCL 7-12
AWS pointer and insert (AWSI) 4-20
Testing 7-10, 7-11
Within library member
LIBI 5-14, 5-15
Index X-9
RDSEXIT Exit ROSDATA Program
Coding Conventions Exit 8-18
Common 7-2 ROSMAILS Program Exit 8-81
Exit-Dependent 8-79 Coding Conventions 8-81
Common Reentrancy Macros 7-8, 7-9 Description 8-81
Data Areas Entrance Parameters 8-81
Common 7-4, 7-5, 7-6, 7-7 Return Codes 8-81
Exit-Dependent 8-79 ROSX Macro
Description 8-79 With ROSXINIT 9-4
Entrance Parameters With ROSXTERM 9-6
Exit-Dependent 8-79 ROSXINIT Module 9-4
Register Conventions 7-3 ROSXTERM Module 9-6
Return Codes 8-80 ROT (Roscoe Online Table) 1-2, 1-3
Sample JCL 7-12 ROTn in ROT 1-2
Testing 7-10, 7-11 ROTUSERn in ROT 1-3
Reading RPF
255-character AWS/member line Program variable pool access 3-27, 3-28
($ROSCOE) 3-20 RPS
80-character AWS/member line Exit
($ROSCOE) 3-19 Banner 8-15
AWS For Scheduled Print Requests 8-88
Configuration (AWSI) 4-13 RPSEXCB 8-94
Record (AWSI) 4-12, 4-13 RPSEXIT Exit
Status (AWSI) 4-20 Coding Conventions 8-88
Library configuration (LIBI) 5-12 Data Areas 8-88—8-93
Library index entry (LIBI) 5-13 Description 8-88
Next logical member record (LIBI) 5-10 Entrance Parameters 8-88
Terminal line ($ROSCOE) 3-21 Return Codes 8-93
REALWAIT function ($ROSCOE) 3-28 RPVDSECT Macro 8-95
Release RPVEXIT Exit
AWS (AWSI) 4-11 Coding Conventions 8-95
Library resource Data Areas 8-95—8-99
LIBI 5-10 Description 8-95
RENAME function Entrance Parameters 8-95
LIBI 5-15, 5-16 Return Codes 8-99, 8-100
Renaming RPXCMD in RPSEXIT 8-90
Library member (LIBI) 5-15, 5-16 RPXCODE in RPSEXIT 8-88, 8-89
RENUMBER function (AWSI) 4-19 RPXDSECT Macro 8-88
Replace entry in library RPXIDCDE in RPSEXIT 8-88
LIBI 5-7, 5-8 RPXINPUT in RPSEXIT 8-91
RESETI function (AWSI) 4-19 RPXOUTPT in RPSEXIT 8-92, 8-93
Return to calling Monitor routine 3-16 RPXPCH in RPSEXIT 8-90
ROS3@ATH Exit 8-82 RPXPRTID in RPSEXIT 8-90
Description 8-82, 8-84 RPXRC1 in RPSEXIT 8-92
Extension 8-84, 8-85 RPXRC2 in RPSEXIT 8-92
Installation 8-85, 8-86 RPXRC3 in RPSEXIT 8-92
Sample JCL 8-85, 8-86 RPXTOTLS in RPSEXIT 8-91
Roscoe Online Table (ROT) 1-2, 1-3 RPXUKEY in RPSEXIT 8-90
ROSCOPY Program RPXWKAR in RPSEXIT 8-91
Exit 8-18 RSSCEXPU Macro (EXPORT Routine) 8-52

RTF Command SESSION function ($ROSCOE) 3-29
Exit 8-101 Session Level Control Block
RTFEXIT Exit ATT1 1-4
Coding Conventions PCB 1-6
Exit-Dependent 8-101 SCB 1-4
Description 8-101 SET AUTOFF Command
Entrance Parameters Exit 8-12, 8-105
Exit-Dependent 8-101 SET STMTCNT Command
Register Conventions 7-3 Exit 8-105
Return Codes 8-101, 8-102 SET TLOCK Command
RUN Initialization Parameter with Exit 8-12, 8-105
Site-written Monitor routines 2-3 SETEXIT Exit
Coding Conventions
Common 7-2
S Exit-Dependent 8-105
Save status of library buffers Common Reentrancy Macros 7-8, 7-9
LIBI 5-13 Data Areas
SCB (Session Control Block) 1-4 Common 7-4, 7-5, 7-6, 7-7
SCBACFB in SCB 1-4 Exit Dependent 8-106
SCBAMETH in SCB 1-5 Description 8-105
SCBDEVT in SCB 1-5 Entrance Parameters
SCBFKEY in SCB 1-5 Exit-Dependent 8-105
SCBGROUP in SCB 1-5 Register Conventions 7-3
SCBPCB in SCB 1-5 Return Codes 8-107
SCBPCBCU in SCB 1-5 Sample JCL 7-12
SCBSENV in SCB 1-5 Testing 7-10, 7-11
SCBTRMNM in SCB 1-5 SETI function (AWSI) 4-20
SCBUAF in SCB 1-5 SHOW Macro 7-10, 7-11
SCBUNVPW in SCB 1-5 SIGEXIT Exit
SCBUSERX in SCB 1-5 Coding Conventions
SCREEN Command Common 7-2
Exit 8-103 Exit-Dependent 8-108
SCREXIT Exit Common Reentrancy Macros 7-8, 7-9
Coding Conventions Data Areas
Common 7-2 Common 7-4, 7-5, 7-6, 7-7
Exit-Dependent 8-103 Exit-Dependent 8-108, 8-109
Common Reentrancy Macros 7-8, 7-9 Description 8-108
Data Areas Entrance Parameters
Common 7-4, 7-5, 7-6, 7-7 Exit-Dependent 8-108
Exit-Dependent 8-103 Register Conventions 7-3
Descriptions 8-103 Return Codes 8-109, 8-110
Entrance Parameters Sample JCL 7-12
Exit-Dependent 8-103 Testing 7-10, 7-11
Register Conventions 7-3 Sign on
Return Codes 8-104 Exit 8-108
Sample JCL 7-12 SMFEXIT Exit
Testing 7-10, 7-11 Coding Conventions
Security Exits Common 7-2
See ACFEXIT, BEXEXIT, DSAEXIT Exit-Dependent 8-112
Session Control Block (SCB) 1-4 Common Reentrancy Macros 7-8, 7-9
Data Areas
Common 7-4, 7-5, 7-6, 7-7
Index X-11
SMFEXIT Exit (continued) Syntax diagrams
Data Areas (continued) reading (how to) xvi—xxi
Exit-Dependent 8-113
Description 8-112
Entrance Parameters T
Exit-Dependent 8-112 TERM function
Register Conventions 7-3 AWSI 4-21
Return Codes 8-113 LIBI 5-17
Sample JCL 7-12 Terminate
Testing 7-10, 7-11 See Stopping
SPACE function TERMNUM in SCB 1-5
LIBI 5-17 TERMSO in ROT 1-3
Space Requirements TERMTO in ROT 1-3
Number of available library blocks (LIBI) 5-17 TERMTYPE in SCB 1-6
Site-written Monitor routines 3-11, 3-12, 3-13, TIMEOUT function ($ROSCOE) 3-31
3-14, 5-17
SPIE function ($ROSCOE) 3-30, 3-31
SRECORD macro
U
UPS (User Profile System)
With SIGEXIT 8-111
Exit 8-119, 8-120
With SMFEXIT 8-113, 8-114
GETUPS Routine 9-2
STATUS function
UPSREAD Routine 9-7
AWSI 4-20
UPSMEXIT Member 8-119, 8-120
LIBI 5-17
UPSREAD Service Routine 9-7
STATUS JOB Command
USERWDn in SCB 1-6
Exit 8-73
UX@CODE in RPVEXIT 8-95, 8-97
Status of
UX@MSGAD in RPVEXIT 8-99
Current AWS (AWSI) 4-20
UX@PCBAD in RPVEXIT 8-97
Library resources
UX@RETFG in RPVEXIT 8-99
LIBI 5-17
UX@ROTAD in RPVEXIT 8-97
Stopping 4-21
UX@SCBAD in RPVEXIT 8-97
AWSI Interface 4-21
UX@WAREA in RPVEXIT 8-97
LIBI 5-17
UXACFACD in ACFEXIT 8-5
SUBEXIT Exit
UXACFGRP in ACFEXIT 8-5
Coding Conventions
UXACFINF in ACFEXIT 8-5
Common 7-2
UXACFNPS in ACFEXIT 8-5
UXACFPGM in ACFEXIT 8-5
UXACFPSW in ACFEXIT 8-4
Data Areas
UXACFTRM in ACFEXIT 8-5
Common 7-4, 7-5, 7-6, 7-7
UXALC 8-45, 8-47
UXAMSREC in AMSEXIT 8-10
Description 8-115
UXAMSSUB in AMSEXIT 8-10
Entrance Parameters
UXAUTTRM in AUTEXIT 8-13
UXBANCLS in BANEXIT 8-16
UXBANDAT in BANEXIT 8-16
UXBANDST in BANEXIT 8-16
Sample JCL 7-12
UXBANDTA in BANEXIT 8-16
Testing 7-10, 7-11
UXBANKEY in BANEXIT 8-16
SUBMIT Command
UXBANPFX in BANEXIT 8-16
Exit 8-115
UXBANPGM in BANEXIT 8-16
Subtasking Monitor routine ($PROC) 3-11, 3-12,
3-13, 3-14

UXBANPRT in BANEXIT 8-16 UXDS3LUN in DSFEXIT 8-48
UXBANREQ in BANEXIT 8-16 UXDS3LVL in DSFEXIT 8-47
UXBANTAB in BANEXIT 8-16 UXDS3VLS in DSFEXIT 8-48
UXBANTIM in BANEXIT 8-16 UXDSAADS in DSAEXIT 8-38
UXCALCTL UXDSAAME in DSAEXIT 8-38
in DSFEXIT 8-43, 8-44 UXDSACIA in DSAEXIT 8-37
in LIBEXIT 8-66 UXDSADSC is DSAEXIT 8-37
in UXDSECT 7-5 UXDSADSN in DSAEXIT 8-36
UXCIA 8-37 UXDSAINX in DSAEXIT 8-37
UXCL#USD in CLLEXIT 8-22 UXDSAJFC in DSAEXIT 8-37
UXCLCPPL in CLLEXIT 8-22 UXDSAMEM in DSAEXIT 8-37
UXCLDUMP in CLLEXIT 8-22 UXDSANDS in DSAEXIT 8-36
UXCLHIGH in CLLEXIT 8-22 UXDSANME in DSAEXIT 8-37
UXCLLPRG in CLLEXIT 8-21 UXDSAPGM in DSAEXIT 8-38
UXCLLPRL in CLLEXIT 8-21 UXDSARDS in DSAEXIT 8-38
UXCLLPRM in CLLEXIT 8-22 UXDSARME in DSAEXIT 8-38
UXCLMAXT in CLLEXIT 8-22 UXDSAUNT in DSAEXIT 8-37
UXCLMODE in CLLEXIT 8-22 UXDSAVL# in DSAEXIT 8-36
UXCLMTGM in CLLEXIT 8-22 UXDSAVOL in DSAEXIT 8-37
UXCLMVGM in CLLEXIT 8-22 UXDSECT
UXCLPRFX in CLLEXIT 8-22 Data Areas 7-4, 7-5, 7-6, 7-7
UXCLREAS in CLLEXIT 8-22, 8-23 Description 7-4
UXCLTOTL in CLLEXIT 8-22 UXDSFWRK in UXDSECT 7-5
UXCMDINP for CMDEXIT 8-27 UXENTER Macro 7-8
UXCMDINP2 for CMDEXIT 8-27 UXEXIT Macro 7-8, 7-9
UXCMDOUT for CMDEXIT 8-27 UXEXPDIR in EXPEXIT 8-53
UXCMDOUT2 for CMDEXIT 8-27 UXEXPDR2 in EXPEXIT 8-53
UXCODE in UXDSECT 7-4 UXEXPDSN in EXPEXIT 8-52
UXCONCMD in CONEXIT 8-29 UXEXPIPR in EXPEXIT 8-53
UXCONOPE in CONEXIT 8-30 UXEXPMEM in EXPEXIT 8-52
UXCONUCB in CONEXIT 8-30 UXEXPOPR in EXPEXIT 8-53
UXDFG 8-47 UXEXPRCF in EXPEXIT 8-54, 8-55
UXDISCMD in DISEXIT 8-33 UXEXPREC in EXPEXIT 8-53
UXDISCNM in DISEXIT 8-33 UXEXPVOL in EXPEXIT 8-53
UXDISQL in DISEXIT 8-33 UXIDCODE in UXDSECT 7-4
UXDS0CTL in DSFEXIT 8-44 UXIMPDSN in IMPEXIT 8-58
UXDS1R24 in DSFEXIT 8-45 UXIMPHEX in IMPEXIT 8-59
UXDS1R31 in DSFEXIT 8-45 UXIMPLIB in IMPEXIT 8-58
UXDS1S24 in DSFEXIT 8-44 UXIMPMEM in IMPEXIT 8-58
UXDS1S31 in DSFEXIT 8-44 UXIMPOPA in IMPEXIT 8-59
UXDS2DSN in DSFEXIT 8-45 UXIMPREC in IMPEXIT 8-59
UXDS2FCT in DSFEXIT 8-45 UXIMPRNG in IMPEXIT 8-59
UXDS2FPL in DSFEXIT 8-45 UXIMPVOL in IMPEXIT 8-58
UXDS2MEM in DSFEXIT 8-45 UXLS0CTL in LIBEXIT 8-66
UXDS2UNT in DSFEXIT 8-45 UXLS1R24 in LIBEXIT 8-66
UXDS2VOL in DSFEXIT 8-45 UXLS1R31 in LIBEXIT 8-66
UXDS3ENM in DSFEXIT 8-48 UXLS1S24 in LIBEXIT 8-66
UXDS3ENT in DSFEXIT 8-48 UXLS1S31 in LIBEXIT 8-66
UXDS3LNM in DSFEXIT 8-47 UXLS2FCT in LIBEXIT 8-66
UXDS3LTP in DSFEXIT 8-47 UXLS2FKY in LIBEXIT 8-67
Index X-13
UXLS2GRP in LIBEXIT 8-67 UXSIGDAT in SIGEXIT 8-109
UXLS2KEY in LIBEXIT 8-67 UXSIGREC in SIGEXIT 8-109
UXLS2LPF in LIBEXIT 8-67 UXSIGRPY in SIGEXIT 8-109
UXLS2MEM in LIBEXIT 8-67 UXSIGTIM in SIGEXIT 8-108
UXLS3ENT in LIBEXIT 8-67 UXSMFSES in SMFEXIT 8-113
UXLS3FKY in LIBEXIT 8-67 UXSUBDSN in SUBEXIT 8-116
UXLS3GRP in LIBEXIT 8-67 UXSUBJB# in SUBEXIT 8-116
UXLS3KEY in LIBEXIT 8-67 UXSUBJNM in SUBEXIT 8-116
UXLS3LNM in LIBEXIT 8-67 UXSUBMEM in SUBEXIT 8-116
UXLS3PFX in LIBEXIT 8-67 UXSUBPSW in SUBEXIT 8-116
UXMONLNM in MONEXIT 8-71 UXSUBRCO in SUBEXIT 8-116
UXMONNAM in MONEXIT 8-70 UXSUBREC in SUBEXIT 8-116
UXMONSTR in MONEXIT 8-71 UXSUBVOL in SUBEXIT 8-116
UXMSGADR in UXDSECT 7-5 UXWRKAREA in UXDSECT 7-5
UXOUTCMD in OUTEXIT 8-74 UXZAPCOD in ZAPEXIT 8-123
UXOUTDS 8-75 UXZAPDSN in ZAPEXIT 8-122
UXOUTJB# in OUTEXIT 8-74
UXOUTJCT in OUTEXIT 8-74
UXOUTJNM in OUTEXIT 8-74 V
UXOUTOSE in OUTEXIT 8-75 Variables (syntax diagrams) xvi
UXOUTRC in OUTEXIT 8-75
UXOUTSTA in OUTEXIT 8-74
UXOUTWRK in OUTEXIT 8-75
W
Working with
UXOUTWRK in UXDSECT 7-6
See AWSI Interface
UXPCBADR in UXDSECT 7-5
Writing 4-18
UXRCSATT
Line to AWS (AWSI) 4-18
in RCSEXIT 8-78
Monitor routine, site-written
in RDSEXIT 8-79
255-character line to AWS (ROSCOE) 3-23
UXRCSECA
80-character line to AWS ($ROSCOE) 3-23
in RCSEXIT 8-78
Accounting record ($ROSCOE) 3-29
in RDSEXIT 8-79
Line to library 5-15
UXRCSXT in RCSEXIT 8-77
Message to terminal ($ROSCOE) 3-24, 3-25
UXRDSOD in UXRDSEXIT 8-79
Static message to terminal/AWS
UXRETFLG in UXDSECT 7-5
(MONM) 3-7
UXROTADR in UXDSECT 7-4
To terminal ($ROSCOE) 3-26
UXRPAREA in RPVEXIT 8-98
Variable message to terminal
UXRPCALL in RPVEXIT 8-99
($MONMSG) 3-8, 3-9
UXRPCLAS in RPVEXIT 8-97
UXRPCOPY in RPVEXIT 8-98
UXRPEXTP in RPVEXIT 8-97 Z
UXRPKEY in RPVEXIT 8-97 ZAP Command
UXRPLCB in RPVEXIT 8-97 Exit 8-122
UXRPMISC in RPVEXIT 8-98 ZAPEXIT Exit
UXRPPFX in RPVEXIT 8-97 Coding Conventions
UXRPSTAT in RPVEXIT 8-98 Common 7-2
UXRPTRM in RPVEXIT 8-97 Exit-Dependent 8-122
UXRPTYPE in RPVEXIT 8-98 Common Reentrancy Macros 7-8, 7-9
UXSCBADR in UXDSECT 7-5 Data Areas
UXSCRTRM in SCREXIT 8-103 Common 7-4, 7-5, 7-6, 7-7
UXSETVAL in SETEXIT 8-106 Exit-Dependent 8-122, 8-123
Description 8-122

ZAPEXIT Exit (continued)
Entrance Parameters
Sample JCL 7-12
Testing 7-10, 7-11
Index X-15

ROSCOE - B001632e - Extended Facilities For System Programmers 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 - B001632e - Extended Facilities For System Programmers Guide

Uploaded by

Copyright:

Available Formats

Advantage CA-Roscoe

Extended Facilities for

The manufacturer of this Documentation is CA.

Copyright  2005 CA. All rights reserved.

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Chapter 1. Advantage CA-Roscoe Data Areas . . . . . . . . . . . . . . . . 1-1

Chapter 2. Monitor Routine Facilities . . . . . . . . . . . . . . . . . . . . . 2-1

Chapter 3. Monitor Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Chapter 4. AWS Interface (AWSI) . . . . . . . . . . . . . . . . . . . . . . . 4-1

Chapter 5. User Library Interface (LIBI) . . . . . . . . . . . . . . . . . . . . 5-1

iv Extended Facilities for System Programmers Guide

Chapter 6. Exit Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Chapter 7. Information Common to all Exit Routines . . . . . . . . . . . 7-1

Chapter 8. Exit Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

| Chapter 9. Service Routines and Load Modules . . . . . . . . . . . . . . . 9-1

Appendix A. Monitor Linkage Conventions . . . . . . . . . . . . . . . . A-1

vi Extended Facilities for System Programmers Guide

The Advantage CA-Roscoe Interactive Environment Extended Facilities for System

About This Guide vii

viii Extended Facilities for System Programmers Guide

About This Guide ix

x Extended Facilities for System Programmers Guide

Advantage CA-Roscoe Data Areas

Monitor Routine Facilities

About This Guide xi

User Series Contents

xii Extended Facilities for System Programmers Guide

About This Guide xiii

The following manuals relate to Advantage CA-Roscoe and are on

xiv Extended Facilities for System Programmers Guide

Licensing Management Program (LMP)

Advantage CA-Roscoe now interfaces with CAIRIM services to determine

About This Guide xv

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.

Default Keywords and Variables: Appear above a main line.

Double Arrowheads Pointing to the Right: Indicate the beginning of a

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

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

Punctuation Marks or Arithmetic Symbols: If punctuation marks or

, comma > greater than symbol

xvi Extended Facilities for System Programmers Guide

Statement Without Parameters

You must write:

Statement with Required Parameters

You must write:

COMMAND PARM1 PARM2

Delimiters such as parentheses around parameters or clauses must be included.

Delimiters Around Parameters

If the word variable is a valid entry, you must write:

COMMAND (PARM1) PARM2='variable'

Choice of Required Parameters

About This Guide xvii

Default Value for a Required Parameter

COMMAND PARM1=NO PARM2

Choice of Optional Parameters

xviii Extended Facilities for System Programmers Guide

Repeatable Variable Parameter

In the preceding example, the word variable is in lowercase italics, indicating

Separator with Repeatable Variable and Delimiter

// ASSEMBLE SITE-MONITOR ROUTINE