ROSCOE - B001622e - Extended Development Tools Guide

Advantage CA-Roscoe
 
Interactive Environment
Extended Development Tools 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v
Part I. ETSO Application Programming Interface
Chapter 1. Using ROETSAPI . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.2 Coding Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
1.2.1 Specifying ROETSAPI Function Calls . . . . . . . . . . . . . . . . . 1-3
1.2.2 Linking ROETSAPI to Application . . . . . . . . . . . . . . . . . . . 1-4
1.3 Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
1.4 ROETSAPI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
1.4.1 DVRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
1.4.2 GETV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
1.4.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
1.4.3 PANL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
1.4.4 PUTV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
1.4.5 QENV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
1.4.6 QERR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-25
1.4.7 SUSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28
Chapter 2. Other Programming Considerations . . . . . . . . . . . . . . . 2-1
Chapter 3. ROETSAPI Examples . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.1 Assembler Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
3.2 COBOL Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
3.3 PL/I Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
Part II.Sketch
Chapter 4. SKETCH Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Chapter 5. Using SKETCH (for CICS Applications) . . . . . . . . . . . . 5-1

5.1 Establishing Defaults - Option 1 . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.1.1 Macro Definition Defaults . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.1.2 Map Field Definition Defaults . . . . . . . . . . . . . . . . . . . . . 5-6
5.1.3 JCL Specification Defaults . . . . . . . . . . . . . . . . . . . . . . . . 5-8
5.2 Create/Update a Map - Option 2 . . . . . . . . . . . . . . . . . . . . . 5-11
Contents iii
5.2.1 Macro and Field Definitions . . . . . . . . . . . . . . . . . . . . . 5-12
5.2.2 Painting the Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
5.2.2.1 Designing a New Map . . . . . . . . . . . . . . . . . . . . . . 5-12
5.2.2.2 Designing a New Map Using an Existing Map or RPF Panel 5-13
5.2.2.3 Modifying a Map . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
5.2.2.4 Using PF Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
5.2.2.5 Using Line Commands . . . . . . . . . . . . . . . . . . . . . . 5-14
5.2.3 Review Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
5.2.4 Field Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
5.2.4.1 Modifying Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
5.2.4.2 Positioning Panel . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
5.3 Generate Macro - Option 3 . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
5.4 BMS Copybook Generation - Option 4 . . . . . . . . . . . . . . . . . . 5-20
Chapter 6. Using SKETCH (for IMS Applications) . . . . . . . . . . . . . 6-1

6.1.1 Message Format Defaults . . . . . . . . . . . . . . . . . . . . . . . . 6-4
6.2 Create/Update a Map - Option 2 . . . . . . . . . . . . . . . . . . . . . . 6-9
6.2.1 Statement and Field Definitions . . . . . . . . . . . . . . . . . . . 6-10
6.2.2 Painting the Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
6.2.2.1 Designing a New Map . . . . . . . . . . . . . . . . . . . . . . 6-10
6.2.2.2 Designing a New Map Using an Existing Map or RPF Panel 6-11
6.2.2.3 Modifying a Map . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
6.2.2.4 Using PF Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
6.2.2.5 Using Line Commands . . . . . . . . . . . . . . . . . . . . . . 6-12
6.2.3 Review Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13
6.2.4 Field Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13
6.2.4.1 Modifying Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
6.2.4.2 Positioning Panel . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
6.3 Generate Message Statements - Option 3 . . . . . . . . . . . . . . . . 6-16
6.4 MFS Copybook Generation - Option 4 . . . . . . . . . . . . . . . . . . 6-18
Chapter 7. SKETCH Customization Considerations . . . . . . . . . . . . 7-1

7.1 SKETCH-Related Library Members . . . . . . . . . . . . . . . . . . . . . 7-2
7.2 RPF Variables Used by SKETCH . . . . . . . . . . . . . . . . . . . . . . 7-4
7.3 IMS Device Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1
iv Extended Development Tools Guide

About This Guide
This guide for Advantage CA-Roscoe Interactive Environment (Advantage

CA-Roscoe) describes the following:
■ the ETSO Application Programming Interface (ROETSAPI). ROETSAPI
plus information about other programming considerations may be of
assistance to individuals developing applications for use under ETSO.
■ the interactive facilities provided by SKETCH that can be used to generate
and maintain panels used in programs running under CICS or IMS.
About This Guide v

Organization
CHAPTER DESCRIPTION
Part I, ETSO Application Programming Interface
1 Describes ETSO and how to use the Application
Programming Interface.
2 Presents an assortment of programming considerations
applicable to any program that is run under ETSO.
3 Contains examples of Assembler, COBOL and PL/I
programs using the Application Programming Interface.
Part II, SKETCH
4 Introduces SKETCH and the facilities it provides.
5 Describes how to use SKETCH to generate BMS (Basic
Mapping Support) macros that define panels to CICS
applications.
6 Describes how to use SKETCH to generate MFS (Message
Format Services) statements that define panels to IMS
applications.
7 Describes SKETCH customization considerations.
vi Extended Development Tools Guide

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

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

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.
viii Extended Development Tools Guide

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

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

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.
x Extended Development Tools Guide

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

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

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

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

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

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

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

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

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
xii Extended Development Tools Guide

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

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

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

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

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─┘
xiv Extended Development Tools Guide

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

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

reference, as in this example:
Variables Representing Several Parameters

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

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.
xvi Extended Development Tools Guide

Part I. ETSO Application Programming Interface
Chapter 1. Using ROETSAPI . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.2 Coding Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
1.2.1 Specifying ROETSAPI Function Calls . . . . . . . . . . . . . . . . . 1-3
1.2.2 Linking ROETSAPI to Application . . . . . . . . . . . . . . . . . . . 1-4
1.3 Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
1.4 ROETSAPI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
1.4.1 DVRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
1.4.2 GETV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
1.4.3 PANL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
1.4.4 PUTV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
1.4.5 QENV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
1.4.6 QERR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-25
1.4.7 SUSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28
Chapter 2. Other Programming Considerations . . . . . . . . . . . . . . . 2-1
Chapter 3. ROETSAPI Examples . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.1 Assembler Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
3.2 COBOL Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
3.3 PL/I Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
Chapter 1. Using ROETSAPI
This chapter contains:
■ An overview of ROETSAPI
■ The conventions for code ROETSAPI function calls
■ The JCL needed to link edit ROETSAPI to the application
■ The return codes passed from ROETSAPI to the application
■ The specific functions provided with ROETSAPI
Chapter 1. Using ROETSAPI 1-1

1.1 Overview
1.1 Overview
The Extended Time-Sharing Option (ETSO) is an application execution system
that can be used to execute purchased or site-developed applications under
Advantage CA-Roscoe. Whether or not these applications currently execute
interactively, there may be cases where sites may want to modify them to
allow their users to take advantage of Advantage CA-Roscoe facilities.
The ETSO Application Programming Interface (ROETSAPI) enables an

application executing under Advantage CA-Roscoe to take full advantage of all
Advantage CA-Roscoe facilities. For example, applications can use ROETSAPI
to:
■ Display RPF panels to provide and obtain information.
■ Establish and obtain the value of any type of RPF variable.
■ Obtain the result of executing any RPF function.
■ Dynamically change TGET, TPUT, WTO and WTP system macro settings.
■ Suspend application execution, allowing the application to return control
to Advantage CA-Roscoe so that the user (or controlling RPF program) can
process in 'native' Advantage CA-Roscoe. The user (or RPF program) can
then:
– Return to the application
– Terminate the application
– Display information about suspended applications
ROETSAPI can be used with any application written in any language that
handles standard IBM parameter lists (for example, COBOL, PL/I, FORTRAN
and Assembler). For additional information about ETSO, refer to the:
■ Command Reference Guide for detailed descriptions of the ETSO-related
commands that are available to all users.
■ RPF Language Guide for information about using ETSO-related commands
within RPF programs.
■ System Commands Guide for detailed descriptions of those ETSO-related
commands that are meant to be used by the individual assigned the RO or
AI prefix or the console operator.
■ System Reference Guide for information about defining applications that are
to run under ETSO.
■ User Guide for general information about using ETSO.
1-2 Extended Development Tools Guide

1.2 Coding Conventions

ROETSAPI may be used with applications that are:
■ Executed under Advantage CA-Roscoe or in a non-Advantage CA-Roscoe
environment (for example, in batch, under TSO)
■ Written using amode 31 or amode 24
1.2.1 Specifying ROETSAPI Function Calls

While the ROETSAPI functions are presented in this manual according to the
PL/I call format, they may be used with any language that handles standard
IBM parameter lists. In all cases,
■ The function code is four characters in length.
■ The parameters associated with each ROETSAPI function are positional.
They must be coded in the order shown with each function description.
Optional parameters may be omitted.
■ A semi-colon (;) shown within the syntax of a function is required. (A
terminating semi-colon is required only in PL/I.) For example,
CALL ROETSAPI ('DVRT' 'TGET AWS;');
where the first semi-colon (that is, with 'TGET AWS;') is required. The last
semi-colon is required only when terminating a PL/I function call.
Language-Specific Call Formats

■ COBOL
The general format of CALLs to ROETSAPI is:
CALL 'ROETSAPI' USING function parm1 parm2 ...
COBOL does not allow literals within a CALL statement. The function and
parameters may, therefore, be specified as variables, as in:
WORKING-STORAGE SECTION.
1 ETSO-FUNCTION-CODE PIC X(4) VALUE SPACES.
...
MOVE 'QERR' TO ETSO-FUNCTION-CODE
...
CALL 'ROETSAPI USING ETSO-FUNCTION-CODE ...
...
■ PL/I
The general format of CALLs To ROETSAPI is:
CALL ROETSAPI ('function','parm1','parm2',...);

As already noted, the semi-colon (;) is required to terminate a PL/I

function call. Also note that PL/I programs should include the following
DECLARE statement:
DECLARE ROETSAPI ENTRY OPTIONS(ASSEMBLER,INTER,RETCODE);
■ FORTRAN
The general format of calls to ROETSAPI is:
return=ROETS('function', 'parm1','parm2'...)
FORTRAN restricts module names to a maximum of six characters. Thus,
ROETS, an alias for ROETSAPI, must be used by calls from FORTRAN
programs.
'return' may be any valid FORTRAN name identifying an integer variable
into which the return code from the function is to be placed. The
parameters may be passed as FORTRAN variables or literals.
■ Assembler
When writing assembler programs, the standard OS coding conventions
should be used. For example, when setting up a parameter list, the last
parameter must have the high order byte set to X'80'.
Example of call:
MVC FUNCTION,=CL4('GETV')
CALL ROETSAPI,(FUNCTION,REQUEST1,RETURN1),VL
...
FUNCTION DC ...
REQUEST1 DC ...
RETURN1 DC ...
1.2.2 Linking ROETSAPI to Application

To use the facilities provided by ROETSAPI, you must link edit ROETSAPI
into the application. The following sample illustrates the JCL that might be
used to perform this link edit.
//LINK EXEC PGM=IEWL,PARM='LIST,MAP,NCAL,LET'
//SYSLIB DD DSN=ROSCOE.user-application-library,DISP=SHR
//SYSLIB1 DD DSN=ROSCOE.ROSLIB,DISP=SHR
//SYSLMOD DD DSN=ROSCOE.ROSLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(5,5))
//SYSPRINT DD SYSOUT=
//SYSLIN DD
INCLUDE SYSLIB(user-application)
INCLUDE SYSLIB1(ROETSAPI)
ENTRY user-application-entry-point
NAME user-application(R)

1.3 Return Codes
1.3 Return Codes

After issuing a call to ROETSAPI, one of the following return codes will be
passed back to your application:
Code Meaning
0 Successful execution of ROETSAPI request.
4 Warning that truncation occurred on a GETV string hexadecimal request.
8 Errors occurred while processing this function.
12 Termination due to lack of storage.
16 Termination due to application executing in a non-ETSO environment.
20 Abnormal termination intercepted.
24 Illegal API function requested.
The code is returned in register 15.

■ COBOL Programs:
Use the built-in RETURN-CODE variable to examine the return code.
■ PL/I Programs:
Use the PLIRETV built-in function to examine the return code. To use this
function, the following DECLARE statement must be included in the
programs:
DECLARE PLIRETV BUILTIN;
■ FORTRAN Programs:
Examine the return code using an integer variable, such as 'return' in:
return = ROETS(function,parm1,...)

1.4 ROETSAPI Functions

ROETSAPI functions may be included in applications that execute in both an
ETSO environment and a non-ETSO (for example, TSO) environment.
The ROETSAPI functions that may be used with applications running in an

ETSO environment include:
QENV Queries the environment to determine if the application is executing
under ETSO.
If the application is executing under ETSO, QENV may be used to
obtain Advantage CA-Roscoe-specific environmental information.
GETV Obtains the value of one or more RPF variables or functions.
PUTV Establishes the value of one or more RPF variables.
PANL Dynamically activates and transmits an RPF panel.
DVRT Dynamically diverts TPUT, TGET, WTO and WTP operations to a
different location.
QERR Obtains information associated with an error encountered in a
previous call to ROETSAPI.
SUSP Suspends application execution, allowing the user to return to
If an application using ROETSAPI functions is executed in a non-ETSO

environment, ROETSAPI always returns to the calling application with register
15 set to 16.
1.4.1 DVRT
DVRT can be used to change TGET, TPUT, WTO and WTP system macro
settings dynamically while the application is executing.
DVRT TGET Function

┌─TERMINAL─┐
──CALL ROETSAPI──('DVRT'──'TGET──┼─AWS──────┼──;');───────────
└─MEM──mem─┘
DVRT TPUT Function

──CALL ROETSAPI──('DVRT'──'TPUT──┼─AWS──────┼──;');───────────
├─MEM──mem─┤
└─DISCARD──┘

DVRT WTO Function

┌─CONSOLE──┐
──CALL ROETSAPI──('DVRT'──'WTO──┼─TERMINAL─┼──;');────────────
├─AWS──────┤
DVRT WTP Function

──CALL ROETSAPI──('DVRT'──'WTP──┼─CONSOLE──┼──;';─────────────
├─AWS──────┤
TGET causes terminal input to be obtained from an alternate input source.

The default input source is TERMINAL.
TPUT causes terminal output to be directed to an alternate output target
or discarded. The default target is TERMINAL.
WTO causes console output to be directed to an alternate output target or
discarded. The default target is CONSOLE.
WTP causes terminal output to be directed to an alternate output target
or discarded. The default target is TERMINAL.
Note: A WTP is a WTO with route code 11 which causes the
output to be directed to the terminal rather than the
operator console.
Notes
■ Dynamic diversions made by the application remain in effect until:
– Another DVRT function changes the source or target, or
– The user enters the DIVERT command to alter the source or target
■ A diversion request must have both the type of diversion desired (for
example, TGET) and the diversion setting (for example, AWS).
■ The diversion settings mean:
AWS directs input/output to the active AWS.
CONSOLE directs input/output to the operator console.
DISCARD ignores any input/output.
MEM mem directs input/output to the designated library member. The
member is assumed to belong to the individual executing
the application. To divert input/output to the library of a
specific individual, include that person's Advantage
CA-Roscoe prefix with the member name.

When directing output to a library member, the member is

created if it does not already exist. If it does exist, its
contents are overlaid.
TERMINAL direct input/output to the terminal. (TERMINAL may also
be specified as *.)
Example: In the following example, TPUT output is directed to a specific

library member, TGET input is obtained from the active AWS, WTO messages
are directed to the terminal and WTP messages are directed to the operator
console.
. . .
CALL ROETSAPI,(FUNC,TPUTDVRT,TGETDVRT, WTODVRT,WTPDVRT),VL
LTR R15,R15 ERROR IN DVRT CALL?
BNZ QERR Y, EXIT PROGRAM
. . .
FUN DC CL4'DVRT' FUNCTION = 'DVRT'
TPUTDVRT DC C'TPUT MEM XF.TPUTOUT;' TPUT = LIB MEMBER
TGETDVRT DC C'TGET AWS;' TGET = AWS
WTODVRT DC C'WTO TERMINAL;' WTO = TERMINAL
WTPDVRT DC C'WTP CONSOLE;' WTP = CONSOLE
1.4.2 GETV
The GETV function can be used to obtain the value of any RPF variable or
function.
GETV Function
──CALL ROETSAPI──('GETV'──'──┬─var1─────┬──────────────────────
└─rptfunc1─┘
──format1(length1);',return1,───────────────────────────────────
┌─;──────────────────────────────────────────┐
┬──────────────────────────────────────────┬┴──);───────────
───
└─┬─varn─────┬──formatn(lengthn)',returnn,─┘
└─rptfuncn─┘
var is the name of any variable. When appropriate, the variable prefix
must be included. (The valid prefixes are A., D., L., P. and S. plus
the PF/PA key prefixes AWS., DSN., JOB. and LIB).
rpffunc is any valid RPF function or an expression containing RPF
variables. The function name or expression must be enclosed in
parentheses, as in:
(LENGTH('AC')) or (L1+L2)
format is the format in which the data is to be returned and must be
specified as:
BINARY One- to four-byte binary data. (Abbreviate as
BIN.)

CHARACTER Character data. (Abbreviate as CHAR.)

FLOAT Four-byte short form real number.
HEXADECIMAL Hexadecimal representation. (Abbreviate as
HEX.) See the Notes for additional
information about this format.
PACKED Packed data format. (Abbreviate as PACK.)
VARCHAR Two-byte halfword followed by one to 255
bytes of data whose length is specified in the
halfword. (Abbreviate as VCHAR.)
The format must be compatible with the format of the data stored
by Advantage CA-Roscoe. If it is not, an error condition will occur.
length is the length of the data area that is to receive the variable or
function.
With the exception of VCHAR format requests, this length must
correspond to the size of the return field (return). When VCHAR is
specified, the return field length must be equal to or greater than
the length that will be returned. The true data length of VCHAR
data can be found in the first two bytes of the return field.
return is the name of the field into which the value of the specified
variable or function is to be returned.
Notes:
■ A GETV function call must have at least one request specified. (A request
consists of the fields: variable name or function, format and length and a
return field.)
■ There is no limit to the number of requests that can be specified through a
single GETV function. When coding a GETV function, remember that:
– Each request uses 660 (decimal) bytes of storage.
– A GETV function which has multiple variable requests processes faster
than multiple GETV functions for single variables.
■ Hexadecimal Format:
When the format of the data to be returned is specified as hexadecimal, the
user is requesting that the data be returned as a character string which
represents the requested data.
The character string is not the data connected to the character format but is
the hexadecimal representation of the RPF variable. For example, suppose
L1 contains the value 100, stored by Advantage CA-Roscoe as the fullword
X'00000064'. If the application contains the call:
CALL ROETSAPI ('GETV','L1 HEX(8);',return1);
'return1' will contain C'00000064' after the call. This is the character data. If
the call had been:

CALL ROETSAPI (GETV' 'L1 CHAR(8);',return1);

'return1' would contain C' 100'
■ Data Conversion Information:
The format and length specified with a GETV function call must be
compatible with the format and length of the data stored by Advantage
CA-Roscoe. The following chart shows the Advantage CA-Roscoe data
formats and the GETV data formats into which the Advantage CA-Roscoe
data may be converted.
Advantage CA-Roscoe DATA VALID GETV DATA FORMAT

FORMAT REQUESTS
String (1- to 255-byte character string) BIN, CHAR, FLOAT, HEX, PACK or
VCHAR
Integer (4-byte binary number) BIN, CHAR, HEX, PACK or VCHAR
Real (4-byte short-form real number) CHAR, FLOAT HEX or VCHAR
The length of the data area that is to receive the variable or function is
restricted by the specified format, as noted in the following chart.
Data Format LENGTH LENGTH

MINIMUM MAXIMUM
BIN 1 4
CHAR 1 255
FLOAT 4 4
HEX 2 510
PACK 1 15
VCHAR 1 255
(+ halfword length)
The rules regarding the conversion of data from its Advantage CA-Roscoe
format to the specified GETV format are:

Advantage GETV CONVERSION RESULTS

CA-Roscoe FORMAT
FORMAT
String BIN If the converted string is less than the
defined BIN length, it is moved to the
return area, right justified and blank filled.
If the converted string is equal to the
return area.
If the converted string is greater than the
return area and an overflow error occurs.
Note: If the defined BIN length is greater
than four, an error occurs.
String CHAR If the string is less than the defined CHAR
length, it is moved to the return area, right
justified and blank filled.
If the string is equal to the defined CHAR
length, it is moved to the return area.
If the string is greater than the defined
CHAR length, it is moved to the return
area and truncated on the right.
String FLOAT The string is converted to a four-byte
short-form real number and moved to the
return area.
String HEX If the string multiplied by two is less than
the defined HEX length. the converted
data is moved to the return area, left
justified and blank filled.
If the string multiplied by two is equal to
the defined HEX length, the converted data
is moved to the return area.
If the string multiplied by two is greater
than the defined HEX length, the converted
data is moved to the return area and
truncated on the right.


CA-Roscoe FORMAT
FORMAT
String PACK If the converted string is less than the
defined PACK length, it is moved to the
defined PACK length, it is moved to the
return area.
defined PACK length, the return area is
zero-filled and an overflow condition
occurs.
String VCHAR If the string is less than the defined
VCHAR length, the string is moved to the
return area.
If the string is equal to the defined VCHAR
length, the data is moved to the return
area.
If the string is greater than the defined
VCHAR length, the data is moved to the
return area.
Integer BIN If the defined BIN length is large enough
to hold the converted integer value, it is
moved to the return area, right justified
and zero filled.
If the defined BIN length is not large
enough, an overflow error occurs.
Integer CHAR If the converted string is less than the
defined CHAR length, it is moved to the
return area.
defined CHAR length, asterisks are moved
to the return area and an overflow error
occurs.


CA-Roscoe FORMAT
FORMAT
Integer HEX If the converted integer is less than the
defined HEX length, it is moved to the
return area, left justified and blank filled.
If the converted integer is equal to the
return area.
If the converted integer is greater than the
return area and truncated on the right.
Integer PACK If the defined PACK length is large enough
to hold the converted integer value, it is
moved to the return area, right justified
and and zero filled.
If the defined PACK length is not large
enough, an overflow error occurs.
Integer VCHAR If the length of the integer data is less than
the defined VCHAR length, it is moved to
the return area.
If the length of the integer data is equal to
the defined VCHAR length, it is moved to
the return area.
If the length of the integer data is greater
than the defined VCHAR length, an error
occurs.
Real CHAR If the length of the real data is less than the
If the length of the real data is equal to the
return area.
If the length of the real data is greater than
the defined character length, asterisks are
moved to the return area and an overflow
error occurs.
Real FLOAT If the defined FLOAT length is equal to
four, the data is moved to the return area.
If the defined FLOAT length is not equal to
four, an error occurs.


CA-Roscoe FORMAT
FORMAT
Real HEX If the defined HEX length is less than eight,
the converted data is moved to the return
area, truncated on the right.
If the defined HEX length is equal to eight,
the data is converted and returned for the
length of eight.
If the defined HEX length is greater than
eight, the data is converted and returned
for the length of eight. The returned data is
left justified and blank filled.
Real VCHAR If the length of the real data is equal to or
less than the defined VCHAR length, the
data is moved to the return area.
If the length of the real data is greater than
the defined VCHAR, an overflow error
occurs.
1.4.2.1 Examples
1. The following example illustrates how to obtain the current value of the
variables L1, P1, AWS.PF1, P.PANELV and S.VTAMAPPL.
. . .
CALL ROETSAPI,
(FUNC,REQL1,L1,REQP1,P1,REQAPF1,PF1,
REQPVAR,PVAR,REQSVAR,VTAMAPPL),VL
LTR R15,R15 ERROR IN GETV?
BNZ QERR N, EXIT PROGRAM
. . .
FUNC DC CL4'GETV' FUNC = 'GETV'
REQL1 DC C'L1 CHAR(1);' GETV L1
REQP1 DC C'P1 VCHAR(1);' GETV P1
REQAPF1 DC C'AWS.PF1 CHAR(5);' GETV AWS.PF1
REQPVAR DC C'P.PANELV BIN(4);' GETV PANEL VAR
REQSVAR DC C'S.VTAMAPPL CHAR(8);' GETV S.VTAMAPPL
L1 DS CL1 AREA FOR L1
P1VAR DS XL12 AREA FOR P1
P1LEN DC H'1' LENGTH OF P1
P1 DS CL1 CONTENTS OF P1
PF1 DS CL5 AREA FOR AWS.PFK1
PVAR DS F AREA FOR BIN VAR
VTAMAPPL DS CL8 AREA FOR VTAMAPPL

This GETV function might return the following values:

L1 DC CL1'ABCDEFGHIJ' AREA FOR L1
P1 DC CL1'123456789' CONTENTS OF P1
PF1 DC CL5'DIS I' AREA FOR AWS.PFK1
PVAR DC XL4'64' AREA FOR BIN VAR
VTAMAPPL DC CL8'DNEXTROS' AREA FOR VTAMAPPL
2. The next example illustrates how to use GETV to obtain the results of RPF
functions. In this case, assume that the variable L1 contains the value
'ABCDEFGHIJ'. The SUBSTR function extracts the first eight characters.
The CONFORM function then verifies that those characters are alphabetic.
. . .
CALL ROETSAPI, 1 (FUNC,RSUBSTR,SUBSTR,RCONFORM,CONFORM),VL
. . .
RSUBSTR DC C'(SUBSTR(L1 1 8)) CHAR(8);' SUBSTR OF L1
RCONFORM DC C'(CONFORM(L1 ''A'')) BIN(4);' CONFORM ID
SUBSTR DS CL8 AREA FOR SUBSTR
CONFORM DS F AREA FOR CONF. FLAG
The values returned by the GETV function might be:
SUBSTR DC CL8'ABCDEFGH' AREA FOR SUBSTR
CONFORM DC X'1' AREA FOR CONF. FLAG
3. The final example illustrates how the GETV function can be used to
request data type conversions. In this case, assume that the variable L1
contains the value '1234'.
. . .
CALL ROETSAPI,
(FUNC,REQL1C,L1CHAR,REQL1V,L1VCHAR,REQL1H,
L1HEX, REQL1B,L1BIN,REQL1R,L1REAL),VL
LTR R15,R15 ERROR IN GETV CALL?
. . .
REQL1C DC C'L1 CHAR(4);' CHARACTER FORMAT
REQL1V DC C'L1 VCHAR(4);' VARYING CHAR FORMAT
REQL1H DC C'L1 HEX(8);' HEXADECIMAL REPR.
REQL1B DC C'L1 BIN(4);' BINARY
REQL1R DC C'L1 REAL(4);' SHORT FORM FLOAT
L1CHAR DS CL4 L1 IN CHAR FORM
L1V DS XL6
L1VLEN DC H'4' HALFWORD LENGTH
L1VCHAR DS CL4 L1 IN VCHAR FORM
L1VHEX DS CL8 L1 IN HEX FORMAT
L1VBIN DS F L1 IN BINARY FORM
L1VREAL DS F L1 IN REAL FORM

The values returned by GETV would be:

L1CHAR DC CL4'1234' L1 IN CHAR FORM
L1V DC XL6
L1VLEN DC XL2'4' HALFWORD LENGTH
L1VCHAR DC CL4'1234' L1 IN VCHAR FORM
L1VHEX DC CL8'F1F2F3F4' L1 IN HEX FORMAT
L1VBIN DC XL4'4D2' L1 IN BINARY FORM
L1VREAL DS F L1 IN REAL FORM
1.4.3 PANL
The PANL function allows RPF PANEL command facilities to be executed
dynamically from within an application executing under ETSO.
PANL Function
──CALL ROETSAP1──('PANL'───────────────────────────────────────
──┬─(──'ACTIVATE──def──;'──)───────────────────────┬──);───────
├─(──'EXECUTE──def ──ALARM CURSOR P.──var──;'──)─┤
├─(──'SEND ALARM CURSOR P.──var──;'──)───────────┤
├─(──'RESEND ALARM CURSOR P.──var──;'──)─────────┤
├─(──'OUT ALARM CURSOR P.──var──;'──)────────────┤
└─(──'IN ALARM CURSOR P.──var──;'──)─────────────┘
ACTIVATE activates a panel definition without transmitting it to the

terminal.
EXECUTE activates a panel definition, writes it to the terminal and reads it
back.
def location of the panel definition, identified as:
AWS definition is in the active AWS.
AWS (aname) definition is in the specified AWS.
mem definition is in the designated library member.
If the member belongs to another user, that
user's prefix must be specified.
SEND transmits a previously activated panel definition to the terminal
and reads it back.
RESEND transmits a previously activated panel definition to the terminal.
The presentation area is not erased.
OUT transmits a previously activated panel definition to the terminal.
The keyboard is locked; no data entry may occur. The panel
definition is not read back.
IN read the data from panel fields without first writing the panel to
the terminal. (Synonym for RESEND.)

ALARM at 3270-type terminals with an alarm, causes the alarm to sound

when the panel is displayed. ALARM is ignored if the terminal
does not support this facility.
CURSOR causes the cursor to be positioned to a specific field when the
panel is redisplayed. The field must be identified as:
P.var is the name of the panel field at which the cursor is
to be placed.
Notes
■ If both ALARM and CURSOR are specified, ALARM must precede
CURSOR in the request string.
■ Error Handling:
If an error occurs, the application is not interrupted (that is, no messages
are displayed at the terminal). An error code is returned to the application
from ROETSAPI and a subsequent QERR call can retrieve the text of the
error message.
■ Attention Handling:
If an attention interrupt should occur while a panel is active and the
application has previously established its own attention exit through the
STAX macro, that routine gets control.
If the application has not established its own attention exit routine, the
ETSO default attention interrupt exit gets control.
Under no circumstances does the invoking RPF program's ON
ATTENTION exit get control.
Example: The following example illustrates how an application can use this
function to invoke an RPF panel.
. . .
CALL ROETSAPI,(FUNC,PANLREQ),VL
LTR R15,R15 ERROR IN PANL CALL?
. . .
FUNC DC CL4'PANL' FUNCTION = 'PANL'
PANLREQ DC C'EXECUTE AWS ALARM CURSOR P.FIELD;' PANEL CMD
1.4.4 PUTV
The PUTV function can be used to establish the value of an RPF variable.
PUTV Function
──CALL ROETSAPI──('PUTV'──,────────────────────────────────────
┌─,──────────────────────────────────────────┐
─'var1──format1──(──length1──)──;',──data 1─┴──);───────────
───

or
PUTV Function
──CALL ROETSAPI──('PUTV'──,────────────────────────────────────
──'var──format──(──length──)──rdm-format──;',──data──);────────
var is the name of any modifiable RPF variable. When appropriate,

the variable prefix must be included. (The valid prefixes are A.,
D., L., P. and S. plus the PF/PA key prefixes AWS., DSN., JOB
and LIB.)
format is the format of the data being passed for this request, specified
as:
BINARY one- to four-byte binary data. (May be
abbreviated as BIN.)
CHARACTER one- to 255-byte character data. (May be
abbreviated as CHAR.)
FLOAT four-byte short-form real number.
HEXADECIMAL hexadecimal representation. (May be
abbreviated as HEX.) See the Notes for
additional information about this format.
PACKED Packed data. (May be abbreviated as
PACK.)
VARCHAR two-byte halfword followed by one to 255
bytes of data whose length is specified in
the halfword. (May be abbreviated as
VCHAR.)
length is the length of the data that is being passed to update or become
the RPF variable. It must correspond to the size of the data being
passed. The length is restricted by the specified format.
rdm-format is the format to which the data is to be converted after it is
passed by ROETSAPI. If it is omitted, the data is stored in a
format that is compatible with the format of the data being
passed. If specified, it must be one of the following formats:
INTEGER Four-byte binary data. (May be abbreviated as INT.)
REAL Short-form floating point.
STRING Character string. (May be abbreviated as STR.)
If the format of the data being passed is not compatible with the
format into which it is to be converted, an error condition occurs.
data is the name of the field from which PUTV is to obtain the data
that is to be moved to Advantage CA-Roscoe. With the exception
of panel variables, the data may not exceed 255 characters in

length. With panel variables, the data may not exceed the length
of the panel field.
Notes:
■ A PUTV function call must have at least one request specified. (A request
consists of: variable, format and length, optional RDM format plus a data
field.)
■ There is no limit to the number of requests that can be specified through a
single PUTV function. When coding a PUTV request, remember that:
– Each request for a variable uses approximately 400 (decimal) bytes of
storage.
– Multiple requests may be included in a single PUTV call. A PUTV
request which has multiple variable requests processes faster than
multiple PUTV requests for a single variable.
■ Hexadecimal Format:
When the hexadecimal format is specified, the data being passed to the
program is expected to be the character representation of the hexadecimal
data. For example, to store the fullword that is equal to a decimal 100, the
following call might be issued:
CALL ROETSAPI ('PUTV', L1 HEX(8) INT;',PROGL1;
The variable L1 will contain C'00000064'. If the call were coded as:
CALL ROETSAPI ('PUTV', L1 BIN(4) STR;',PROGL1;
The variable L1 will contain C'100'.
■ The following chart shows the data formats, their lengths and the format
to which they may be converted:
Table 1-1 (Page 1 of 2). Converting Data Formats
FROM FORMAT TO FORMAT

TYPE LENGTH LENGTH TYPES DEFAULT
MINIMUM MAXIMUM
BIN 1 4 INT, REAL INT
or STRING
CHAR 1 255 INT, REAL STRING
or STRING
FLOAT 4 4 REAL REAL
HEX 2 510 INT, REAL STRING
or STRING
PACK 1 6 INT INT

Table 1-1 (Page 2 of 2). Converting Data Formats
FROM FORMAT TO FORMAT

VCHAR 1 255 INT, REAL STRING
or STRING
(+ halfword length)
■ Note that a request specifying:

– BIN with no RDM format, may have a length of zero. This causes the
variable to be set to zero.
– CHAR with no RDM format, may have a length of zero. This removes
the variable from the RDM Area.
Examples
1. The following example places values in the variables L1, P1, AWS.PF1,
P.PANELV and S.LASTMEM.
. . .
CALL ROETSAPI,
(FUNC,REQL1,L1,REQP1,P1,REQAPF1,PF1,
REQPVAR,PVAR,REQSVAR,MEMBER),VL
. . .
FUNC DC CL4'PUTV' FUNC = 'PUTV'
REQL1 DC C'L1 CHAR(1);' PUTV L1
REQP1 DC C'P1 VCHAR(4);' PUTV P1
REQAPF1 DC C'AWS.PF1 CHAR(5);' PUTV AWS.PF1
REQPVAR DC C'P.PANELV BIN(4);' PUTV PANEL VAR
REQSVAR DC C'S.LASTMEM CHAR(12);' PUTV S.LASTMEM
L1 DC CL1'ABCDEFGHIJ' AREA FOR L1
PF1 DC CL5'DIS I' AREA FOR AWS.PFK1
PVAR DC F'1' AREA FOR BIN VAR
MEMBER DC CL12'ABC.MYMEMBER' AREA FOR LASTMEM
2. In addition to placing values in the variables L1, L2, L3, P1 and
P.PANELV, the following example illustrates how you can request specific
data type conversions.

. . .
CALL ROETSAPI,
(FUNC,REQL1,L1,REQL2,L2,REQL3,L3,
REQP1,P1,REQPVAR,PVAR),VL
. . .
REQL1 DC C'L1 HEX(1) STR;' PUTV L1
REQL2 DC C'L2 CHAR(5) FLOAT;' PUTV L2
REQL3 DC C'L3 PACK(5) STR;' PUTV L3
REQP1 DC C'P1 VCHAR(4) INT;' PUTV P1
REQPVAR DC C'P.PANELV BIN(4) STR;' PUTV PANEL VAR
L1 DC CL1'C1C2C3C4C5' DATA FOR L1
L2 DC CL5'12.5' DATA FOR L2
L3 DC XL5'123456789C' DATA FOR L3
1.4.5 QENV
The QENV function performs two tasks. First, it can be used to determine the
environment in which the application is executing. Second, it allows an
application executing in an ETSO environment to obtain information about the
Advantage CA-Roscoe environment.
QENV Function
──CALL ROETSAPI──('QENV'──,──'ENV'──;',──retenv────────────────
──┬────────────────┬──┬────────────────┬──┬────────────────┬────
└─,'KEY;',retkey─┘ └─,'PFX;',retpfx─┘ └─,'RPF;',retrpf─┘
──┬────────────────┬──┬────────────────┬──┬────────────────┬────
└─,'PCB;',retpcb─┘ └─,'SCB;',retscb─┘ └─,'ROT;',retrot─┘
──┬────────────────────────┬──┬────────────────────────┬────────
│ ┌─TERMINAL─┐ │ │ ┌─TERMINAL─┐ │
└─,'GET;',─┼──────────┼──┘ └─,'PUT;',─┼──────────┼──┘
└─retget───┘ └─retput───┘
──┬────────────────┬──┬───────────────────────┬─────────────────
└─,'VER;',retver─┘ │ ┌─CONSOLE─┐ │
└─,'WTO;',─┼─────────┼──┘
└─retwto──┘
──┬────────────────────────┬──);───────────────────────────────
│ ┌─TERMINAL─┐ │
└─,'WTP;',─┼──────────┼──┘
└─retwtp───┘
ENV queries the environment to determine if the application is executing

in an ETSO environment. If it is not, register 15 contains 16. If the
application is executing in an ETSO environment, register 15
contains 0.

retenv is the four-byte field into which the literal 'ETSO' is

returned if the application is executing in an ETSO
environment.
KEY causes the current user's Advantage CA-Roscoe sign-on key to be
returned.
retkey is the 22-byte field into which the sign-on key is to be
placed. The key is in a format comparable to that
provided by the S.KEY session variable.
PFX causes the current user's Advantage CA-Roscoe prefix to be
returned.
retpfx is the three-byte field into which the prefix is to be
placed. The prefix is in a format comparable to that
provided by the S.PREFIX session variable.
RPF causes the name of the currently executing RPF program to be
returned. (This is the name of the RPF program responsible for
CALLing the application currently making the ROETSAPI call.)
retrpf is the 12-byte field into which the RPF program name is
to be placed. The name is in a format comparable to that
provided by the S.RPFNAME session variable.
PCB causes the current PCB address to be returned.
retpcb is the four-byte field into which the PCB address is to be
placed.
SCB causes the current SCB address to be returned.
retscb is the four-byte field into which the SCB address is to be
placed.
ROT causes the address of the ROT to be returned.
retrot is the four-byte field into which the ROT address is to be
placed.
GET causes the current TGET diversion setting to be returned.
retget is the 12-byte field into which the diversion setting is to
be placed. If no diversion setting is in effect, TERMINAL
(the default) is returned. If a setting is in effect, the value
will be either:
AWS (active AWS) or
pfx.mem
PUT causes the current TPUT diversion setting to be returned.
retput is the 12-byte field into which the diversion setting si to
will be either:

AWS (active AWS),

pfx.mem or
DISCARD
WTO WTO Causes the current WTO diversion setting to be returned.
retwto is the 12-byte field into which the diversion setting is to
be placed. If no diversion setting is in effect, CONSOLE
will be one of the following:
■ AWS (active AWS),
■ pfx.mem,
■ DISCARD or
■ TERMINAL
WTP causes the current WTP diversion setting to be returned.
retwtp is the 12-byte field into which the diversion setting is to
will be either:
AWS (active AWS),
pfx.mem,
DISCARD or
CONSOLE
VER causes the Advantage CA-Roscoe release number to be returned.
retver is a 4-byte field into which the release number is to be
placed. The release number is in a format comparable to
that provided by the S.VERSION session variable.
Note: The return fields are assumed to be variables or data areas defined in
the application. There is no restriction on the names that may be
assigned to these fields. The size of each field must be large enough to
accommodate maximum size of the information that might be returned.
Examples:
1. The first example illustrates how you can use the QENV function to
determine the execution environment. This example actually performs two
tests. In the first test, if register 15 contains the return code 16, the
application is not executing in an ETSO environment. In the second test, if
the field RETENV does not contain ETSO, the application is not executing
in an ETSO environment.

CALL ROETSAPI, (FUNC,ENV,RETENV),VL

CH R15,=H'16' ETSO?
BE NOTETSO N, NON ETSO RTN
LTR R15,R15 ERROR IN QENV CALL?
BNZ QERR Y, EXIT PGM
CLC RETENV,=CL4'ETSO' IS IT REALLY ETSO?
BNE NOTETSO N, NON ETSO RTN
. . .
FUNC DC CL4'QENV' FUNC = 'QENV'
ENV DC CL4'ENV;' REQ. ENVIRONMENT
RETENV DC CL4' ' RETURN AREA
2. The next example shows how you can get information about the
Advantage CA-Roscoe environment.
CALL ROETSAPI,
(FUNC,ROT,RETROT,RPF,RETRPF,PCB,RETPCB,
SCB,RETSCB),VL
LM R9,R11,RETROT LOAD R9-R11 WITH
PCB,SCB,ROT ADDRS.
FUNC DC CL4'QENV' QENV FUNC
ROT DC CL4'ROT;' REQ. ROT ADDR
RPF DC CL4'RPF;' REQ. RPF NAME
SCB DC CL4'SCB;' REQ. SCB ADDR
PCB DC CL4'PCB;' REQ. PCB ADDR
RETRPF DC CL12 RPF NAME
RETPCB DC F'' PCB ADDR
RETSCB DC F'' SCB ADDR
RETROT DC F'' ROT ADDR
3. The last example illustrates how you can obtain the current diversion
settings.
CALL ROETSAPI,
(FUNC,TGET,RETTGET,TPUT,RETTPUT,
WTO,RETWTO,WTP,RETWTP),VL
CLC RETTGET(3),=CL3'AWS' TGETS GO TO THE AWS?
BE TGETDVRT Y, CHANGE DIVERSION
. . .
FUNC DC CL4'QENV' FUNCT = 'QENV'
TGET DC CL4'GET;' REQ. TGET DIVERT
TPUT DC CL4'PUT;' REQ. TPUT DIVERT
WTO DC CL4'WTO;' REQ. WTO DIVERT
WTP DC CL4'WTP;' REQ. WTP DIVERT
RETTGET DS CL12 TGET DIVERSION
RETTPUT DS CL12 TPUT DIVERSION
RETWTO DS CL12 WTO DIVERSION
RETWTP DS CL12 WTP DIVERSION

1.4.6 QERR
The QERR function can be used to get the information associated with an error
encountered on a previous call to ROETSAPI.
QERR Function
──CALL ROETSAPI──('QERR'──,──retmsg──┬─────────┬──);──────────
└─,retrib─┘
retmsg is the field that is to receive the error message text. The first
halfword of the field must contain the length of the error message
being requested; the remainder of the field must be at least this
length and may not exceed 255 bytes in length.
reterib is the field that can be used following GETV and PUTV function
calls to receive a specially formatted Error Information Block. The
first halfword of the field must contain the size of the Error
Information Block; the remainder of the field must be at least the
length specified in that first halfword.
Notes:
■ If a QERR call is issued and no error was encountered on a previous call
to ROETSAPI, a code of 8 is returned and the field retmsg will contain the
message: NO PREVIOUS ERROR FOR QERR REQUEST.
If an error was encountered, a code of 0 is returned and the field identified
by retmsg will contain the text of the appropriate:
– RPF-related error message, or
– ROETSAPI-related error message.
■ Error Information Block:
An Error Information Block is recognized only if the previous function call
was a PUTV or GETV. It is ignored for all other types of function calls.
An Error Information Block is useful when the previous PUTV or GETV
function contains multiple requests and one or more errors are
encountered. (Note that any request within the PUTV or GETV function
that is not in error is satisfied.)
When an Error Information Block is used, a QERR function call returns:
– An error message. (The message is in the field identified as retmsg.)
– The Error Information Block containing information about each request
specified in the previous PUTV or GETV.
The Error Information Block must be formatted as follows:

1st Halfword is the length of the Error Information Block needed

to accommodate error information about the requests
specified in the previous PUTV or GETV function
call.
2nd Halfword is the area that is to contain the total number of
requests specified through the previous GETV or
PUTV function call. (This value is supplied by
ROETSAPI.)
3rd Halfword is the area that is to contain the number of requests
in error. (This value is supplied by ROETSAPI.)
4th Halfword is the area that is to contain a number identifying
which request in the preceding PUTV/GETV
function call corresponds to the message being
returned in the field identified as retmsg. (This
value is supplied by ROETSAPI.)
n Halfwords is a variable entry. There must be one halfword
entry for each request specified in the previous
GETV or PUTV function call.
If the request was successful performed, ROETSAPI
sets the entry to 0000.
If the request was in error and could not be
performed, ROETSAPI sets the entry to a
hexadecimal value that corresponds to the numeric
portion of the API error messages. For example, if
the message API15 is associated with the request in
error, the entry contains 000F.
Example: The following PUTV function call contains five requests and all of
them are in error.
CALL ROETSAPI,
(FUNC,REQL1,L1,REQL2,L2,REQL3,L3,
REQP1,P1,REQPVAR,PVAR),VL
. . .
REQL1 DC C'L1 HEX(1) STR' PUTV L1
REQL2 DC C'L2 CHAR(5) FLOAT;' PUTV L2
REQL3 DC C'L3 PACK(25) STR;' PUTV L3
REQP1 DC C'P1 XXXXX(4) INT;' PUTV P1
REQPVAR DC C'P.PANELV BIN(4) STR;' PUTV PANEL VAR
L1 DC CL1'C1C2C3C4C5' DATA FOR L1
L2 DC CL5'12.5' DATA FOR L2
L3 DC XL5'123456789C' DATA FOR L3

When the first error is encountered, control transfers to QERR which might
look like:
QERR DS H
CALL ROETSAPI,
(FUNC,ERRMSG,ERRINBLK),VL PROCESS ERR MSG
LH R5,ERRORCNT COUNT ERRORS
LA R5,1(,R5) INCREMENT COUNT
STH R5,ERRORCNT RESTORE COUNT
CH R5,ERRORNUM GOT LAST MSG?
BE EXIT Y, EXIT
MVC ERRMSG+2(1),BLANK INIT MSG AREA
B QERR
FUNC DC CL4'QERR' FUNC = 'QERR'
ERRMSG DC H'1' MSG LENGTH
DS CL1 MSG AREA
ERRINBLK DS XL12 ERROR INFO BLK
ERRORLEN DC H'18' MSG LENGTH
ERRORTOT DS H TOTAL REQUESTS
ERRORNUM DS H NUMBER IN ERROR
ERRORIND DC H ERROR INDEX
ERRORVAR DS 5H INFO AREA
ERRORCNT DS H ERROR COUNTER
As illustrated below, after the first QERR function call, the second halfword
contains the total number of requests, the third halfword contains the number
of errors and the fourth halfword contains the number of the first request in
error. The remaining halfwords identify the numeric portion of the associated
API error message.
QERR DS H
CALL ROETSAPI,(FUNC,ERRMSG,ERRINBLK),VL
. . .
B QERRCALL
FUNC DC CL4'QERR' FUNC = 'QERR'
ERRMSG DC H'1' MSG LENGTH
DS CL1'API52 INVALID DELIMITER ON PUTV
REQUEST ";" EXPECTED'
ERRINBLK DS XL12 ERROR INFO BLK
ERRORLEN DC H'18' MSG LENGTH
ERRORTOT DC X'5' TOTAL REQUESTS
ERROR IN DC X'5' NUMBER IN ERROR
ERRORIND DC X'1' ERROR INDEX
ERRORVAR DS H INFO AREA
DC X'34' MSG API52
DC X'1D' MSG API29
DC X'17' MSG API23
DC X'F' MSG API15
DC X'2' MSG API32
ERRORCNT DC X'1' ERROR COUNTER
With each subsequent QERR function call, the fourth halfword reflects the
number of the 'current' request in error. If the application issues a sixth
function call, a code of 8 is returned indicating that this call failed because
there are no more errors.

1.4.7 SUSP
The SUSP function suspends execution of an application executing under
ETSO.
CALL ROETSAPI ('function'[,retcode] );
SUSP Function
──CALL ROETSAPI──('function'──┬──────────┬──);────────────────
└─,retcode─┘
function is the function to be performed (for example, SUSP).

retcode is the name of the field which contains a halfword binary value that
is to be used to set the S.RC session variable before application
execution is suspended. If omitted, S.RS is set to 0 when the
application is suspended.
Notes:
■ You might want to suspend execution when, for example, the application
has obtained data and directed it to the active AWS and you now want to
allow the terminal user to perform editing functions before resuming
application execution.
■ While the application is suspended, normal Advantage CA-Roscoe
command execution may occur. In addition, the user (or RPF program)
may issue the commands:
RESUME ETSO to continue application execution.
CANCEL ETSO to terminate the application.
QUERY CALL to display information about suspended applications.
Note: The FREE command should not be used to release any of the files
(Advantage CA-Roscoe-managed or OS) that the application has
opened.
■ If the application was invoked through an RPF program, the application
can use the session variables:
S.ETSSTAT To determine the status of the application. For example,
S.ETSSTAT is set to 2 when the application is suspended.
S.ETSPGM To obtain the name of the application.
S.RC To communication with the RPF program. This is especially
useful if the application might be suspended for a variety
of reasons. When the RPF program regains control, it can
test the setting of S.RC to determine why the application
was suspended.

See the Advantage CA-Roscoe RPF Language Guide for information about
addition variables that may be of use.
Example: In the following example, the application is suspended and a

return code of 255 is set.
. . .
CALL ROETSAPI,(FUNC,RETURNCD),VL
LTR R15,R15 ERROR IN DVRT CALL?
. . .
FUNC DC CL4'SUSP' FUNCTION = 'SUSP'
RETURNCD DC H'255' RETURN CODE (S.RC)

Chapter 2. Other Programming Considerations
This chapter contains an assortment of notes that may be of assistance when

you are writing an application for execution under ETSO.
1. In addition to this manual, review the section entitled 'Evaluating
Applications' in the System Reference Guide.
2. Advantage CA-Roscoe-Managed Files:
Advantage CA-Roscoe-managed files (for example, an AWS, terminal and
library) can be accessed using BSAM or QSAM access methods. (If BSAM
or QSAM is used, the application need not know the difference between a
Advantage CA-Roscoe-managed file and an external data set.)
Note: In BSAM, NOTE/POINT to Advantage CA-Roscoe files are invalid
and cause program termination.
3. Dynamic Allocations:
An AWS, library member and SYSOUT files may be dynamically allocated
by the program using SVC 99. To dynamically allocate:
■ An AWS. Use the dsn text unit DALDSNAM to specify the data set
name ROAWS. (With no additional information, the active AWS is
assumed.)
Use the member name text unit DALMEMBR to specify a specific
existing AWS.
■ A library member. Use the dsn text unit DALDSNAM to specify the
data set name ROLIB or ROLIBpfx (where 'pfx' is the prefix of the
individual to whom the member belongs).
Use the member name text unit DALMEMBR to specify the name of a
library member.
■ A SYSOUT file for output to a 328x-type printer. Specify the sysout
text unit as one of the RPS classes defined in the ETSRPS=
initialization parameter. The only other valid text units are for the RPS
printer destination, number of copies and record format.
4. AWS Access:
In addition to allocating the active AWS and then using standard OS I/O
macros, you can also use the AWS Interface (AWSI). This interface includes
the AWSI macro which allows you to specify the action to be taken. While
Chapter 2. Other Programming Considerations 2-1

the AWS Interface is described in detail in the Extended Facilities for System
Programmers Guide, the following list indicate the functions that you can
perform:
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.
TERM Terminates use of the AWSMGR. It must be
specified in the last call on AWSI.
GET Retrieves a record from the AWS.
PUT Places a record into the AWS.
POINT Defines the position within an AWS at which the
next operation will be performed.
SETI and RESTI Establishes (SETI) and terminates (RESTI) an insert
operation. With SETI, subsequent records PUT to the
AWS are inserted after a given record.
DELETE Purges lines from an AWS.
COPY and MOVE Repositions data within an AWS, and acts identically
except that MOVE deletes the repositioned data from
its original location while COPY does not.
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.
5. Library Access:
In addition to allocating a library member and then using standard OS I/O
macros, you can also use the Library Interface (LIBI). This interface
includes the LIBI macro which lets you specify the action to be taken.
While the Library Interface is described in detail in the Extended Facilities
for System Programmers Guide, the following list indicates the functions that
you can perform:
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.

ACTIVATE Allocates library resource(s) for use by the calling program.
FREE Releases a library resource previously allocated by
ACTIVATE.
TERM Terminates interface must be specified in the last call on
LIBI.
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.
PUT Places the next logical record in the library.
LIB Retrieves an index entry and places it in the area pointed to
by a parameter.
FIND Locates the desired index entry and places it in the parameter
list.
ADD Adds a new or replacing an existing entry on the library.
ALTER Alters attributes in a member index entry.
DEL Deletes a member from the library.
NOTE Saves the current status of the library.
POINT Defines the position within the library member at which the
next read operation (for example, GET, POINT NOTE) is to
be performed.
RENAME Changes name and specified attributes of a library member.
INFO Retrieves information about the current library configuration.
SPACE Computes the number of available blocks.
STATUS Retrieves current status of library.
Note:
■ A LIBI INIT function call is recognized from an application
running under ETSO. (Normally, this would be rejected.) When
INIT is used, no allocation need be made for the Advantage
CA-Roscoe libraries by the application. INIT will use the
libraries being used by Advantage CA-Roscoe.
■ If LIBI is called for an INITX function from an application
running under ETSO, Advantage CA-Roscoe will determine
whether the Advantage CA-Roscoe libraries allocated by the
application are the same as those being used by Advantage
CA-Roscoe. If they are, the INITX function is internally changed
into an INIT to significantly reduce overhead and improve
response.

6. Terminal Access:
Terminals can be accessed using:
■ TSO TPUT and TGET macros
■ MVS WTO and WTOR macros
■ Standard I/O to the terminal
■ ROETSAPI function PANL
7. Record Length Considerations:
ETSO checks the validity of the DCB record length and block size at open
time.
■ When the terminal is used as an I/O file, the record length should not
exceed the length of a terminal line and may not be greater than 132
characters in length for input, and 133 characters (including control
characters) for output.
■ When the AWS is used, the record length should not exceed 255
characters in length.
■ When a library member is used, the record length should not exceed
255 characters in length.
If the data record length greater than a valid maximum is specified, the
program is terminated with an error message.
If both LRECL and BLKSIZE are specified with the ALLOCATE command,
BLKSIZE must be related to LRECL as shown in the following chart. If not,
the program terminates with an error message.
SUPPLIED BY RECFM LRECL BLKSIZE

PROGRAM
Nothing (Note 1) FA 81 81
Nothing (Note 2) F 80 80
RECFM only F 80 80
FA/FM 81 80
V 84 81
VA/VM 85 88
U 80 89
80
RECFM and F 1<n<80 n<80
LRECL or BLKSIZE FA/FM 1<n<81 n<81
(Note 3) V 5<n<84 n+4<88
VA/VM 6<n<85 n+4<89
Note:
■ Output file allocated with CTRL= operand of ALLOCATE
command.

■ Input or output file without the CTRL= operand.
■ If LRECL is found, BLKSIZE will be forced as shown in the
rightmost column. If LRECL is 0 but BLKSIZE is valid, the later
will be used to compute LRECL.
8. PL/I uses locate mode for output. Therefore, a dummy blank record may
be needed to force a prompt line to the terminal before soliciting input.
9. SYNAD routines are not employed for Advantage CA-Roscoe file I/O,
since I/O errors in Advantage CA-Roscoe files cause forced termination of
the user program.
| 10. Determining if an application is executing under Advantage CA-Roscoe
| Sites may want an application to perform different functions based on the
| environment it is running in (Advantage CA-Roscoe, IBM TSO, or IBM
| ISPF). Whenever Advantage CA-Roscoe attaches a subtask (ETSO
| applications execute at the subtask level), the TCBCAUF field of the
| TCBXTNT2 for the executing TCB is updated with the address of
| Advantage CA-Roscoe's Information Block (RIB). The presence of the RIB
| indicates that the current TCB is being executed under Advantage
| CA-Roscoe. The RIB is distributed on the Advantage CA-Roscoe macro
| library.
| Macro ROCURRIB, distributed on the Advantage CA-Roscoe macro
| library, can be used to determine the presence of the RIB control block.
Following is the syntax of the ROCURRIB macro.
|
| ROCURRIB Macro
| ──┬─────┬──ROCURRIB──,──REG=──┬────────┬──┬───────┬────────
| └─tag─┘ └─,none=─┘ └─,tcb=─┘
| ──┬────────────────────┬──┬──────────────────┬─────────────
| │ ┌─YES─┐ │ └─,using=─┬─YES─┬──┘
| └─,tcbequs=─┼─────┼──┘ └─NO──┘
| └─NO──┘
| tag Any valid Assembler tag. It is ignored.

| REG= (Required) Specifies the register where the RIB address is
| loaded.
| none= (Optional) Specifies a label to be branched to if there is no
| RIB address present in the TCB extension.
| tcb= (Optional) Specifies the address of the TCB where the RIB
| address is to be loaded. If omitted, the current TCB is
| used.
| tcbequs= (Optional) Specifies whether TCB mapping macro equates
| can be used when generating the instructions to load the
| RIB address.

| TCBEQUS=YES - (default) Equates are used (this requires
| the inclusion of the IBM IKJTCB macro).
| TCBEQUS=NO - Hard coded values are used to reference
| TCB fields.
| using= (Optional) Specifies whether a USING statement is to be
| generated to establish addressability to the RIB control
| block.
| USING=YES - A USING statement is generated (this
| requires the inclusion of the Advantage CA-Roscoe RIB
| macro).
| USING=NO - A USING statement is not generated.

Chapter 3. ROETSAPI Examples
The same programs in this appendix are provided to illustrate a variety of calls
to ROETSAPI from different programming languages.
Chapter 3. ROETSAPI Examples 3-1

3.1 Assembler Example

The following example illustrates how the QERR function may be used to
obtain information about a GETV function which includes erroneous requests.
REGS
----------------------------------------------------------------------
GETV FOLLOWED BY QERR LOOP FOR ERRORS
----------------------------------------------------------------------
CUST1 CSECT
CUST1 AMODE 24
CUST1 RMODE 24
SAVE (14,12) SAVE CALLERS REGISTERS
LR R12,R15 R12 IS BASE REGISTER
USING CUST1,R12
ST R13,SAVE+4 SAVE CALLERS SAVE AREA ADDR.
LA 2,SAVE POINT TO OUR SAVE AREA
ST 2,8(13) PUT OUR SAVE AREA ADDR IN CALLRS
LR 13,2 R13 POINTS TO OUR SAVE AREA
----------------------------------------------------------------------
GETV CALL FOR P1,P2,JOB.PC1,JOB.PC2,P3
NOTE: JOB.PC1 AND JOB.PC2 ARE NOT VALID PF KEY
VARIABLES.
----------------------------------------------------------------------
CALL ROETSAPI,(GETV,GVR1,GVD1,GVR2,GVD2,GVR3,GVD3, X
GVR4,GVD4,GVR5,GVD5),VL
LTR R15,R15 IS THERE AN ERROR IN GETV CALL?
BZ EXIT N, EXIT PROGRAM
----------------------------------------------------------------------
QERR CALL FOR 1ST ERROR MSG AND ERROR INFORMATION BLOCK
----------------------------------------------------------------------
CALL ROETSAPI,(QERR,MSG1,ERIB1),VL
TPUT MSG1+2,8 DISPLAY 1ST ERROR MESSAGE
SLR R5,R5 CLEAR BEFORE INSERT
ICM R5,3,ERIBINER GET THE TOTAL NUMBER OF ERRORS X
FOR THE PREVIOUS GETV CALL.
BCTR R5, DECREMENT FOR 1ST ERROR THAT X
HAS ALREADY BEEN GOTTEN.
LOOP DS H
TGET REPLY,1 ISSUE TGET TO FORCE PREVIOUS X
ERROR MESSAGE TO BE DISPLAYED.
MVI MSG1+2,C' ' GET READY
MVC MSG1+3(79),MSG1+2 TO CLEAR ERR. MSG AREA

----------------------------------------------------------------------
QERR CALL FOR NEXT ERROR MSG AND ERROR INFORMATION
BLOCK
----------------------------------------------------------------------
CALL ROETSAPI,(QERR,MSG1,ERIB1),VL
TPUT MSG1+2,8 DISPLAY ERROR MESSAGE
BCT R5,LOOP DECREMENT ERRORS AND CONTINUE
EXIT DS H
L R13,SAVE+4 R13 POINTS TO CALLERS SAVE AREA
LM 14,12,12(13) RELOAD CALLERS REGISTERS
BR 14 RETURN TO CALLERS PROGRAM
----------------------------------------------------------------------
ERROR MESSAGE RETURN AREA
----------------------------------------------------------------------
MSG1 DS XL82 TOTAL MSG LEN=HW LEN + MSG AREA
DC H'8' LENGTH = 8
DC 8CL1' ' 8 CHAR ERROR MSG RETURN AREA
----------------------------------------------------------------------
ERROR INFORMATION BLOCK
----------------------------------------------------------------------
ERIB1 DS XL5 TOTAL ERIB LEN=HW LEN+ERIB AREA
ERIBLEN DC H'5' LENGTH = 5
ERIBTOT DS H TOT REQUESTS ON PREV. PUTV/GETV
ERIBINER DS H TOT REQUEST IN ERROR
ERIBCURR DS H INDEX OF CURRENTLY RETURNED MSG
DS XL44 ERROR INDEX ARRAY FOR PREV REQ.
GETV DC CL4'GETV' FUNCTION = 'GETV'
QERR DC CL4'QERR' FUCNTION = 'QERR'
GVR1 DC C'P1 CHAR(1);' GETV FOR P1
GVR3 DC C'JOB.PC1 CHAR(1);' GETV FOR JOB.PC1 (ERROR!)
GVR4 DC C'JOB.PC2 CHAR(1);' GETV FOR JOB.PC2 (ERROR!)
GVD1 DS CL1 RETURN AREA FOR P1
GVD3 DS CL1 RETURN AREA FOR JOB.PC1
GVD4 DS CL1 RETURN AREA FOR JOB.PC2
REPLY DS CL1 AREA FOR TGET
SAVE DS 18F SAVE AREA
LTORG
END CUST1

3.2 COBOL Example
3.2 COBOL Example

The sample program shown in this section illustrates all of the calls a COBOL
program may issue to ROETSAPI. The program uses ROETSAPI to display a
panel to obtain and display information. The panel definition, assumed to be
in the member RO.SAMPAPI, looks like:
STARTDEF
TAG $ S
TAG % UMH FUNCTION
TAG ¬ UMH VARIABLE
TAG & UMH INPUT
TAG @ S OUTPUT
TAG S ERROR
$ E T S O
$ A P I
$
$ FUNCTION: %_$
$
$ 1) SUSPEND - SUSPEND EXECUTION OF THIS APPLICATION
$ 2) RESPOND - RESPOND (GETV) A VARIABLE
$ 3) UPDATE - UPDATE (PUTV) A VARIABLE
$ 4) QUERY - DISPLAY STATUS OF DIVERTS
$
$ X) QUIT - END APPLICATION
$
$ VARIABLE: ¬ $ (I.E., S.DATE OR L.AMEMBER......)
$ INPUT: & $
$ OUTPUT: @
$
$
ENDDEF
Note: The field P.OUTPUT must be 70 characters in length and the field
P.ERROR must be 60 characters in length.
IDENTIFICATION DIVISION.
PROGRAM-ID. BLDPANEL.
AUTHOR. DAVID J. HENDERSON
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IBM-37
OBJECT-COMPUTER. IBM-37.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
DATA DIVISION.
FILE SECTION.

3.2 COBOL Example
WORKING-STORAGE SECTION.
1 PROGRAM-WORK-AREA.
5 ETSO PIC X(8) VALUE 'ROETSAPI'.
1 ETSO-FUNCTION-CODE PIC X(4) VALUE SPACES.
1 ETSO-SECOND-PARM.
5 ETSO-VARIABLE-NAME PIC X(3) VALUE SPACES.
5 FILLER PIC X VALUE SPACES.
5 ETSO-VARIABLE-FORMAT PIC X(4) VALUE SPACES.
5 FILLER PIC X VALUE SPACES.
5 ETSO-VARIABLE-LENGTH PIC X(6) VALUE SPACES.
1 ETSO-DATA-PORTIONS PIC X(255) VALUE SPACES.
1 ETSO-ERR-PORTIONS REDEFINES ETSO-DATA-PORTIONS.
5 ETSO-ERR-LENGTH PIC S9(2) COMP.
5 ETSO-ERR-MSG PIC X(253).
1 ETSO-QERR-PORTIONS PIC X(4) VALUE 'MSG.'.
1 GENERAL-WORK-AREAS.
5 SAVE-VARIABLE-NAME PIC X(3) VALUE SPACES.
5 DIVERT-STAT.
1 DIVERT-GET.
15 DIVERT-GET-LIT PIC X(4) VALUE 'GET;'
15 DIVERT-GET-REP PIC X(12) VALUE SPACES.
15 FILLER PIC X VALUE SPACE.
1 DIVERT-PUT.
15 DIVERT-PUT-LIT PIC X(4) VALUE 'PUT;'
15 DIVERT-PUT-REP PIC X(12) VALUE SPACES.
1 DIVERT-WTO.
15 DIVERT-WTO-LIT PIC X(4) VALUE 'WTO;'
15 DIVERT-WTO-REP PIC X(12) VALUE SPACES.
1 DIVERT-WTP.
15 DIVERT-WTP-LIT PIC X(4) VALUE 'WTP;'
15 DIVERT-WTP-REP PIC X(12) VALUE SPACES.
5 QUIT-FLAG PIC X VALUE 'N'.
88 REQUESTED-TO-SUSPEND VALUE '1'.
88 REQUESTED-TO-RESPOND VALUE '2'.
88 REQUESTED-TO-UPDATE VALUE '3'.
88 REQUESTED-TO-QUERY VALUE '4'.
88 REQUESTED-TO-QUIT VALUE 'X'.
88 ERROR-ENCOUNTERED VALUE 'E'.
5 ERR-REPOSITORY.
1 FILLER PIC X(5) VALUE 'FUNC:'.
1 ERR-FUNC PIC X(4).
1 FILLER PIC X(5) VALUE 'PARM:'.
1 ERR-PARM PIC X(3).
5 ERR-MSG.
1 FILLER PIC X(5) VALUE 'MSG:'.
1 ERR-MSG-MSG PIC X(8).

3.2 COBOL Example
PROCEDURE DIVISION.
----------------------------------------------------------------------
MAIN-CONTROL-SECTION.
ISSUE QENV CALL TO DETERMINE ENVIRONMENT. IF 'ETSO',
DISPLAY AND PROCESS PANEL.
----------------------------------------------------------------------
MAIN-CONTROL-SECTION.
MOVE 'QENV' TO ETSO-FUNCTION-CODE.
CALL 'ROETSAPI' USING ETSO-FUNCTION-CODE
IF RETURN-CODE NOT EQUAL ZERO
DISPLAY 'ETSO ENVIRONMENT IS NOT ESTABLISHED'
GO TO GO-BACK.
PERFORM B2-PANL-CALL THRU B2-PANL-CALL-EXIT.
PERFORM D1-ERR-HANDLER THRU D1-ERR-HANDLER-EXIT
GO TO GO-BACK.
PERFORM A1-PROCESS THRU A1-PROCESS-EXIT
UNTIL REQUESTED-TO-QUIT.
GO-BACK.
GOBACK.
A1-PROCESS.
PERFORM B3-GET-REQUEST THRU B3-GET-REQUEST-EXIT.
PERFORM D1-ERR-HANDLER THRU D1-ERR-HANDLER-EXIT.
IF REQUESTED-TO-SUSPEND
PERFORM B4-SUSPEND-REQ THRU B4-SUSPEND-REQ-EXIT.
IF REQUESTED-TO-RESPOND
PERFORM B5-RESPOND-REQ THRU B5-RESPOND-REQ-EXIT.
IF REQUESTED-TO-QUERY
PERFORM B6-QUERY-REQ THRU B6-QUERY-REQ-EXIT.
IF REQUESTED-TO-UPDATE
PERFORM B7-UPDATE-REQ THRU B7-UPDATE-REQ-EXIT.
IF NOT ERROR-ENCOUNTERED
IF NOT REQUESTED-TO-SUSPEND
MOVE 'PUTV' TO ETSO-FUNCTION-CODE
MOVE SPACES TO ETSO-SECOND-PARM
MOVE 'P.ERROR' TO ETSO-VARIABLE-NAME
MOVE 'CHAR' TO ETSO-VARIABLE-FORMAT
MOVE '(1);' TO ETSO-VARIABLE-LENGTH
MOVE ' ' TO ETSO-DATA-PORTIONS
IF NOT REQUESTED-TO-QUIT
IF NOT REQUESTED-TO-SUSPEND
MOVE 'PANL' TO ETSO-FUNCTION-CODE
MOVE 'RESEND ; ' TO ETSO-SECOND-PARM
IF REQUESTED-TO-QUERY
ETSO-SECOND-PARM
ELSE
MOVE 'RESEND CURSOR P.VARIABLE;' TO ETSO-SECOND-PARM
ETSO-SECOND-PARM.
A1-PROCESS-EXIT.

3.2 COBOL Example
----------------------------------------------------------------------
B2-PANL-CALL.
EXECUTE THE PANEL DEFINITION FOUND IN CA-ROSCOE LIBRARY
MEMBER RO.SAMPAPI.
----------------------------------------------------------------------
B2-PANL-CALL.
MOVE 'PANL' TO ETSO-FUNCTION-CODE.
MOVE SPACES TO ETSO-SECOND-PARM.
MOVE 'EXECUTE RO.SAMPAPI ALARM;' TO ETSO-SECOND-PARM.
CALL 'ROETSAPI' USING ETSO-FUNCTION-CODE ETSO-SECOND-PARM.
B2-PANL-CALL-EXIT.
EXIT.
----------------------------------------------------------------------
B3-GET-REQUEST.
ISSUE GETV FUNCTION CALL TO RETRIEVE PANEL VARIABLE
P.FUNCTION.
----------------------------------------------------------------------
B3-GET-REQUEST.
MOVE 'GETV' TO ETSO-FUNCTION-CODE.
MOVE SPACES TO ETSO-SECOND-PARM ETSO-DATA-PORTIONS.
MOVE 'P.FUNCTION ' TO ETSO-VARIABLE-NAME.
PERFORM C1-CALL-ETSO THRU C1-CALL-ETSO-EXIT.
MOVE ETSO-DATA-PORTIONS TO QUIT-FLAG.
B3-GET-REQUEST-EXIT.
EXIT.
----------------------------------------------------------------------

B4-SUSPEND-REQ.
PRIME CMDLINE LINE WITH 'RESUME ETSO'. THEN ISSUE
SUSP CALL TO SUSPEND APPLICATION.

AFTER USER ISSUES 'RESUME ETSO' FROM NATIVE CA-ROSCOE,

1) ISSUE PANL REQUEST TO REACTIVATE PANEL.
2) ISSUE PUTV REQUEST TO SET PANEL VARIABLE P.ERROR TO
INFORM USER THAT APPLICATION HAS RESUMED.
3) FINALLY, ISSUE PANL REQUEST TO SEND PANEL BACK TO
USER.
----------------------------------------------------------------------
B4-SUSPEND-REQ.
MOVE 'PUTV' TO ETSO-FUNCTION-CODE.
MOVE 'S.CMDLINE' TO ETSO-VARIABLE-NAME.
MOVE 'RESUME ETSO' TO ETSO-DATA-PORTIONS.
GO TO B4-SUSPEND-REQ-EXIT.

3.2 COBOL Example
MOVE 'SUSP' TO ETSO-FUNCTION-CODE.

CALL 'ROETSAPI' USING ETSO-FUNCTION-CODE.
MOVE 'PANL' TO ETSO-FUNCTION-CODE.
MOVE 'ACTIVATE RO.SAMPAPI;' TO ETSO-SECOND-PARM.
CALL 'ROETSAPI' USING ETSO-FUNCTION-CODE ETSO-SECOND-PARM.
MOVE 'P.ERROR' TO ETSO-VARIABLE-NAME.
MOVE 'CHAR' TO ETSO-VARIABLE-FORMAT.
MOVE 'APPLICATION EXECUTION HAS BEEN RESUMED'
TO ETSO-DATA-PORTIONS.
MOVE 'PANL' TO ETSO-FUNCTION-CODE
MOVE 'SEND ; ' TO ETSO-SECOND-PARM
ETSO-SECOND-PARM.
B4-SUSPEND-REQ-EXIT.
EXIT.
----------------------------------------------------------------------
B5-RESPOND-EXIT.
GET THE NAME OF THE VARIABLE IDENTIFIED IN P.VARIABLE.
THEN RETRIEVE THE DATA REQUESTED. FINALLY, PLACE THE
DATA IN THE PANEL VARIABLE P.OUTPUT.
----------------------------------------------------------------------
B5-RESPOND-REQ.
MOVE 'P.VARIABLE ' TO ETSO-VARIABLE-NAME.
GO TO B5-RESPOND-REQ-EXIT.

3.2 COBOL Example

MOVE ETSO-DATA-PORTIONS TO ETSO-VARIABLE-NAME
MOVE 'P.OUTPUT' TO ETSO-VARIABLE-NAME
B5-RESPOND-REQ-EXIT.
EXIT.
----------------------------------------------------------------------
B6-QUERY-REQ.
OBTAIN THE CURRENT DIVERSION SETTINGS FOR TGET, TPUT,
WTO AND WTP VIA QENV CALL. THEN PLACE THAT INFORMATION
IN PANEL VARIABLE P.OUTPUT.
----------------------------------------------------------------------
B6-QUERY-REQ.
MOVE 'QENV' TO ETSO-FUNCTION-CODE.
MOVE 'GET;' TO DIVERT-GET-LIT.
MOVE 'PUT;' TO DIVERT-PUT-LIT.
MOVE 'WTO;' TO DIVERT-WTO-LIT.
MOVE 'WTP;' TO DIVERT-WTP-LIT.
DIVERT-GET-LIT DIVERT-GET-REP
DIVERT-PUT-LIT DIVERT-PUT-REP
DIVERT-WTO-LIT DIVERT-WTO-REP
DIVERT-WTP-LIT DIVERT-WTP-REP.
GO TO B6-QUERY-REQ-EXIT.
MOVE 'GET=' TO DIVERT-GET-LIT.
MOVE 'PUT=' TO DIVERT-PUT-LIT.
MOVE 'WTO=' TO DIVERT-WTO-LIT.
MOVE 'WTP=' TO DIVERT-WTP-LIT.
MOVE 'P.OUTPUT' TO ETSO-VARIABLE-NAME
MOVE DIVERT-STAT TO ETSO-DATA-PORTIONS.

3.2 COBOL Example

GO TO B6-QUERY-REQ-EXIT.
B6-QUERY-REQ-EXIT.
EXIT.
----------------------------------------------------------------------
B7-UPDATE-REQ.
GET THE CONTENTS OF P.VARIABLE (VARIABLE TO BE UPDATED)
AND P.INPUT (DATA TO BE USED TO UPDATE VARIABLE). THEN
MAKE REQUEST VIA PUTV TO UPDATE THAT VARIABLE.
----------------------------------------------------------------------
B7-UPDATE-REQ.
MOVE 'P.VARIABLE ' TO ETSO-VARIABLE-NAME.
MOVE 'CHAR' TO ETSO-VARIABLE-FORMAT.
GO TO B7-UPDATE-REQ-EXIT.
MOVE ETSO-DATA-PORTIONS TO SAVE-VARIABLE-NAME.
MOVE 'P.INPUT' TO ETSO-VARIABLE-NAME.
MOVE SAVE-VARIABLE-NAME TO ETSO-VARIABLE-NAME

3.2 COBOL Example

MOVE 'P.INPUT' TO ETSO-VARIABLE-NAME.
B7-UPDATE-REQ-EXIT.
EXIT.
C1-CALL-ETSO.
ETSO-SECOND-PARM
ETSO-DATA-PORTIONS.
C1-CALL-ETSO-EXIT.
EXIT.
----------------------------------------------------------------------
D1-ERR-HANDLER.
USE THE QERR CALL TO OBTAIN THE ERROR MESSAGE.
(RETURNED LENGTH IS 8 BYTES.)
----------------------------------------------------------------------
D1-ERR-HANDLER.
MOVE ETSO-FUNCTION-CODE TO ERR-FUNC.
MOVE ETSO-SECOND-PARM TO ERR-PARM.
MOVE 'QERR' TO ETSO-FUNCTION-CODE.
MOVE 8 TO ETSO-ERR-LENGTH.
ETSO-ERR-PORTIONS.
MOVE 'P.ERROR' TO ETSO-VARIABLE-NAME.
DISPLAY 'RECURSIVE ERROR HANDLING'
DISPLAY ERR-REPOSITORY
MOVE ETSO-DATA-PORTIONS TO ERR-MSG-MSG
DISPLAY ERR-MSG
MOVE 'X' TO QUIT-FLAG
ELSE
MOVE 'E' TO QUIT-FLAG.
MOVE SPACES TO ETSO-FUNCTION-CODE.
D1-ERR-HANDLER-EXIT.
EXIT.

3.3 PL/I Example
3.3 PL/I Example

The following program displays a panel that requests the user to enter a
GETV, PUTV or QENV function plus the information desired. After validating
the input, the program either displays the appropriate information or an error
message. (The panel definition follows this sample program.)
API: PROCEDURE OPTIONS(MAIN);
DCL ROETSAPI ENTRY OPTIONS(ASSEMBLER,INTER,RETCODE);
DCL SYSPRINT FILE STREAM OUTPUT;
DCL (PLIRETV) BUILTIN;
DCL (SUBSTR) BUILTIN;
DCL 1 MSG,
5 MSG_LEN FIXED BINARY(15,),
5 MSG_MSG CHAR(5) INIT((5)' ');
DCL FUNC_REQ CHAR(19) INIT('P.FUNCTION CHAR(4);');
DCL REQ_REQ CHAR(19) INIT('P.REQUEST CHAR(4);');
DCL DATA_REQ CHAR(17) INIT('P.DATA CHAR (45);');
DCL EHEAD_REQ CHAR(16) INIT('P.EHEAD CHAR(5);');
DCL EMSG_REQ CHAR(16) INIT('P.EMSG CHAR(5);');
DCL AID_REQ CHAR(14) INIT('S.AID CHAR(5);');
DCL FUNCTION CHAR(4) INIT(' ');
DCL REQUEST CHAR(4) INIT((4)' ');
DCL DATA CHAR(5) INIT((5)' ');
DCL AID CHAR(5) INIT((5)' ');
DCL RC FIXED BINARY(31,) INIT();
DCL EXIT_SW BIT(1) INIT(''B);
MSG.MSG_LEN = 5;
CALL RSETSAPI('PANL','EXECUTE ABC.APITEST ALARM CURSOR P.FUNCTION ;')
RC=PLIRETV();
IF RC ¬=
THEN DO;
CALL ROETSAPI('QERR',MSG);
PUT SKIP LIST(MSG.MSG_MSG);
END;
ELSE DO;
CALL ROETSAPI('GETV',AID_REQ,AID);
RC = PLIRETV();
IF RC ¬= THEN RETURN;
DO WHILE (SUBSTR(AID,1,4) ¬= 'PF15');
MSG.MSG_MSG = (5)' ';
CALL ROETSAPI('PUTV',EMSG_REQ,MSG.MSG_MSG);
CALL ROETSAPI('PUTV',EHEAD_REQ,' ');

3.3 PL/I Example
/----------------------------- ----------------------------------/
/ GET FUNCTION, IF THERE IS AN ERROR DISPLAY IT ON PANEL /
/----------------------------------------------------------------/
CALL ROETSAPI('GETV',FUNC_REQ,FUNCTION);
RC=PLIRETV();
IF RC ¬=
THEN CALL ERROR_PROCESSOR;
ELSE DO;
REQUEST = (4)' ';
CALL ROETSAPI('GETV',REQ_REQ,REQUEST);
RC=PLIRETV();
IF RC ¬=
ELSE
SELECT (FUNCTION);
WHEN ('GETV') CALL GETV_PROCESSOR;
WHEN ('PUTV') CALL PUTV_PROCESSOR;
WHEN ('QENV') CALL QENV_PROCESSOR;
WHEN ('DVRT') CALL DVRT_PROCESSOR;
OTHERWISE RC = ;
END;
END;
CALL ROETSAPI('PANL','RESEND ALARM CURSOR P.FUNCTION;');
RC=PLIRETV();
IF RC ¬= THEN DO;
EXIT_SW = '1'B;
END;
IF EXIT_SW THEN LEAVE;
CALL ROETSAPI('GETV',AID_REQ,AID);
RC = PLIRETV();
IF RC ¬= THEN DO;
EXIT_SW = '1'B;
END;
IF EXIT_SW THEN LEAVE;
END;
END;
RETURN;

3.3 PL/I Example
ERROR_PROCESSOR : PROCEDURE;
CALL ROETSAPI('PUTV',EHEAD_REQ,'ERROR');
END ERROR_PROCESSOR ;
PUTV_PROCESSOR : PROCEDURE;
CALL ROETSAPI('GETV',DATA_REQ,DATA);
RC = PLIRETV;
IF RC ¬=
ELSE DO;
CALL ROETSAPI(FUNCTION,REQUEST,DATA);
RC=PLIRETV();
IF RC ¬= THEN CALL ERROR_PROCESSOR;
ELSE DO;
DATA = (5)' ';
MSG.MSG_MSG = 'DATA HAS BEEN ADDED TO RDM SUCCESSFULLY';
CALL ROETSAPI('PUTV',DATA_REQ,DATA);
END;
END;
END PUTV_PROCESSOR;
GETV_PROCESSOR : PROCEDURE;
DATA = (5)' ';
RC=PLIRETV();
IF RC > 4
ELSE DO;
IF RC = 4 THEN CALL ERROR_PROCESSOR;
RC=PLIRETV();
END;
END GETV_PROCESSOR;
QENV_PROCESSOR : PROCEDURE;
DATA = (5)' ';
RC=PLIRETV();
IF RC ¬=
ELSE DO;
RC=PLIRETV();
END;

3.3 PL/I Example
END QENV_PROCESSOR;
DVRT_PROCESSOR : PROCEDURE;
DATA = (5)' ';
RC=PLIRETV();
IF RC ¬=
ELSE DO;
RC=PLIRETV();
END;
END DVRT_PROCESSOR;
END API;
The preceding program uses the panel definition saved as the member
APITEST in the library of the individual assigned the prefix ABC. The
following definition illustrates what that panel might look like:
<<APITEST>>

TAG $ S
TAG + UM FUNCTION REQUEST DATA EHEAD EMSG
$||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$||||||||||||||||||||||||||| ETSO API |||||||||||||||||||||||||||||||||
$||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$
$ Function ==> + (GETV, PUTV or QENV)
$
$ Request# ==> + $
$
$ Data ==> + $
$
$||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$+ $ + $
$ PF15 ==> TERMINATE
ENDDEF


3.3 PL/I Example

Part II.Sketch
Chapter 4. SKETCH Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Chapter 5. Using SKETCH (for CICS Applications) . . . . . . . . . . . . 5-1

5.1.1 Macro Definition Defaults . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.2 Create/Update a Map - Option 2 . . . . . . . . . . . . . . . . . . . . . 5-11
5.2.1 Macro and Field Definitions . . . . . . . . . . . . . . . . . . . . . 5-12
5.2.2 Painting the Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
5.2.3 Review Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
5.2.4 Field Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
5.3 Generate Macro - Option 3 . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
5.4 BMS Copybook Generation - Option 4 . . . . . . . . . . . . . . . . . . 5-20
Chapter 6. Using SKETCH (for IMS Applications) . . . . . . . . . . . . . 6-1

6.1.1 Message Format Defaults . . . . . . . . . . . . . . . . . . . . . . . . 6-4
6.2 Create/Update a Map - Option 2 . . . . . . . . . . . . . . . . . . . . . . 6-9
6.2.1 Statement and Field Definitions . . . . . . . . . . . . . . . . . . . 6-10
6.2.2 Painting the Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
6.2.3 Review Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13
6.2.4 Field Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13
6.3 Generate Message Statements - Option 3 . . . . . . . . . . . . . . . . 6-16
6.4 MFS Copybook Generation - Option 4 . . . . . . . . . . . . . . . . . . 6-18
Chapter 7. SKETCH Customization Considerations . . . . . . . . . . . . 7-1

7.1 SKETCH-Related Library Members . . . . . . . . . . . . . . . . . . . . . 7-2
7.2 RPF Variables Used by SKETCH . . . . . . . . . . . . . . . . . . . . . . 7-4
7.3 IMS Device Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Chapter 4. SKETCH Overview
SKETCH is a menu-driven RPF application that simplifies the generation of

panels used by programs running under:
■ CICS. SKETCH generates BMS (Basic Mapping Support) macros that define
panels to CICS applications.
■ IMS. SKETCH generates the MFS (Message Format Services) statements
that define panels to IMS applications.
Using just a few prompt panels, you can use SKETCH to:
■ Design a BMS or MFS map.
The input can be from:
1. your responses to SKETCH prompts,
2. an RPF panel, or
3. an existing map.
Using one map, you can generate MFS statements for model 1, 2, 3, 4 or 5
3270-type terminals.
■ Specify individual fields within a map.
Default values for the fields (for example, attributes and colors) are
automatically supplied by SKETCH.
You have the option of modifying the site-defined default values that are
used in generating the macros/statements defining: 1) all maps and map
fields, or 2) a particular map.
■ Generate the macros/statements used in creating the map(s).
Before generating the macros, you have the option of displaying a
prototype map, thus ensuring that the map you are about to generate is
correct.
■ Generate the JCL to:
1. Assemble and link edit the BMS macros. You can also designate
whether the resulting output is to be used in an Assembler, COBOL or
PL/I application program.
2. Create the online blocks for the MFS statements. You can designate
whether the resulting output is to be placed in the production or test
library.
Chapter 4. SKETCH Overview 4-1

While a familiarity with BMS or IMS is helpful, it is not essential when
defining the panels and then generating them to create maps. SKETCH allows
you to create and maintain panels by using the WYSIWYG ("What You See Is
What You Get") method.

Chapter 5. Using SKETCH (for CICS Applications)
To execute SKETCH, type:

EXEC pfx.SKETCH [n]
where:
pfx is the prefix of the sign-on key assigned to SKETCH. The default
prefix is RSK.
n is the number of an option on the main menu. If specified,
execution begins with the panel associated with the designated
option. If omitted, the main menu (as illustrated by the following
screen) is displayed.
BMS: SKETCH Main Menu
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||TM|
||||||||||||||| ||| || ||| ||| ||| ||| ||| |||||||||||
||||||||||||||| ||| ||| | |||| ||||||||| ||||| ||||||| ||| |||||||||||
||||||||||||||| |||||||| ||||| ||||||||| ||||| ||||||| |||||||||||
||||||||||||||| ||| ||||| ||||||| ||||| ||||||| |||||||||||
|||||||||||||||||||| ||| | |||| ||||||||| ||||| ||||||| ||| |||||||||||
||||||||||||||| ||| ||| || ||| ||||||||| ||||| ||||||| ||| |||||||||||
||||||||||||||| ||| ||| || ||||| ||||| ||| ||| |||||||||||
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| Version 6. |||
SKETCH Main Menu Date: Time:

User:
Select the facility desired and press ENTER: _
SKETCH Services- 1 - Profile to Establish Defaults

2 - Create/Update a Map
3 - Generate a BMS Macro
4 - Generate a Copybook
PF1/13: Exit PF2/14: Help PF3/15: Return

The options on the main menu permit you to:
1. Alter site-defined default values. SKETCH includes the default values in
several of the panels that it presents to you. If you choose to alter these
values, they are saved as a member in your library and reused every time
Chapter 5. Using SKETCH (for CICS Applications) 5-1

you sign on to SKETCH. If you do not choose to alter the values, the
site-defined defaults are used.
2. Display the prompt panels used to create and update a map, modify field
parameters and display a prototype of the created map. (The map is saved
as a member in your library.)
3. Display the prompt panels used to generate BMS macros and save the
resulting map. (The macro is saved as a member in your library.) This
option also allows you to display and modify the generated macro.
4. Generate the JCL necessary to compile and link edit the generated macro.
You can also use this option to display and modify the generated JCL.
The SKETCH prompt panels use the following function key assignments:
PF1/13 Terminate SKETCH. (Changes to the displayed data are ignored.)
PF2/14 Display Help for the current prompt panel. (Changes to the
displayed data are ignored.)
PF3/15 Return one level. (Changes to the displayed data are ignored.)
PF4/16 Hold display. (The displayed data is evaluated and new or changed
data is applied as an update. The current panel is then redisplayed.)
PF5/17 Return to Main Menu. (Changes to the displayed data are ignored.)
Pressing the ENTER key causes the displayed data to be evaluated and new or
changed data to be applied as an update. The next panel is redisplayed.
You can 'jump' from one option to another without having to return to the
main menu. To do this, move the cursor to the 'Select One' field of any option
panel and type: =n where 'n' is the number of an option shown on the main
menu. For example, if you are currently viewing Option 1 and you enter =2 in
the 'Select One' field of that panel, you do directly to Option 2.

5.1 Establishing Defaults - Option 1

Site-defined default values are used in generating maps and fields within
maps. Default values are also provided for several JCL parameters. This option
allows you to establish your own default values.
Note: The use of this option may be restricted by site management.
BMS: Profile Tables
--------------------------- PROFILE TABLES ----------------------------------
Select One: __
1. Macro/Statement Defaults
2. Map Field Definitions
3. JCL Specification
4. Switch Format Only
Select One: _ (BMS Format is currently active)
1. BMS Format
2. MFS Format
PF1/13: Exit PF2/14: HELP PF3/15: Return

You can select one of the following suboptions:
Suboption 1 or 2:
You can change the default values that are used by Option 2 'Create/Update a
Map' for every map that you generate.
Your new values are saved in the library member ZZZZZBMS in your library.
(If you do not modify the default values, the site-defined values are saved in
the member ZZZZZBMS under the key assigned for SKETCH.)
Suboption 3:
You can modify the following:

■ default JOB statement parameters, and
■ default name of the CICS SYSLIB and the data set to contain the generated
DSECTs.
The new values are saved in the member ZZZZZJCL in your library.

Suboption 4:
You can switch from BMS to MFS without having to change defaults. If you
select this option, you must designate the format to which you want to switch.
5.1.1 Macro Definition Defaults

As its name implies, the Macro Definition Defaults panel contains the current
macro definition default values.
BMS: Macros Definition Defaults
----------------------- Macro Definition Defaults --------------------------
Storage: A Auto or name for base

Color: _ Blue, Red, Pink, Green, Yellow,Turquoise
Ctrl: FR_ Alarm, Free keyboard, Reset MDT
Extatt: M Yes, No, Maponly
Hilight: _ Blink, Reverse video, Underscore
Lang: C Cobol, Pl1, Asm
Mode: B Input, Output, Both
Suffix: _ Numeric character
Supply the uppercase character for each option as desired.

Specify A for STORAGE=AUTO; name for BASE=name.
More than one can be selected for Ctrl only. Supply only the R to
specify Reset MDT.
PF1/13: Exit PF2/14: Help PF3/15: Return PF4/16: Hold PF5/17: Main
ENTER: Cont

Note: The screen above shows the default values.
The meaning of the defaults and the value(s) to which they can be set are:
Storage Designate how the program is to acquire storage for the map(s).
Specify:
A The program acquires main storage for the maps.
(Default.)
name Name of a data area. BASE is then assumed.
(BASE=name specifies that different maps are to use the
same named storage area.)
(For language-specific information about obtaining storage, see
IBM's CIC/VS Application Programmer's Reference Manual (Command
Level).)

Color Identify the color to be used by entering the first character of the
color (for example, B for blue). If omitted, the standard terminal
display colors are used.
Note: Color is ignored at those terminals having no color
capabilities.
Ctrl Define one or more 3270-type terminal characteristics. The possible
values are:
A Sound an audible alarm when the map is displayed.
F Free (or unlock) the keyboard when the map is
displayed. If omitted, the user will not be able to enter
data.
R Reset all modified data tags to a 'not modified' condition
before displaying the map.
Extatt Define how extended attributes (for example, color and
highlighting) are to be supported. The possible values are:
Y Use extended attributes that can be modified by the
program through symbolic descriptor maps (DSECTs are
link edited/copied to the program).
N Do not use extended attributes in this map set.
M Use extended attributes that can be modified by the
program. Symbolic descriptor maps are not required to
do this.(Default.)
Highlight Define the highlighting attribute for all fields in the map. If omitted,
no highlighting is used. The possible values are:
B The fields are to 'blink'
R Reverse video (for example, green characters on a black
background become black characters on a green
background).
U All fields are to be underlined.
Note: These values are ignored at those terminals not supporting
such capabilities.
Lang Define the source language of the application program that uses the
map. The possible values are:
C COBOL. (Default.)
P PL/I.
A Assembler.
Mode Ddefine whether the map is to be used for input, output or both.
The possible values are:
I Input

O Output
B Both input and output (Default.)
Suffix Define a one-character suffix for the map set. This suffix is used
when multiple versions of the same named map set are referenced
by an application program.
Note: Multiple versions can exist if variations are generated for
different terminals or languages. For more information on
suffixing, see IBM's CICS/VS Application Programmer's
Reference Manual (Command Level).
5.1.2 Map Field Definition Defaults

A variety of attributes can be assigned to the fields comprising a map. To
simplify defining maps, SKETCH allows a site to establish default attributes.
The panel displayed through suboption 2 allows you to modify the
site-defined default values.
You can associate default values with specific special characters. You will be
using these special characters to mark the beginning of fields when 'painting' a
map. Once you have painted a map, SKETCH assigns the values to the field(s)
denoted by the special characters. (This is similar to the definition and use of
TAG characters in RPF panels.)
BMS: Map Field Definition Defaults
----------------------- MAP FIELD DEFINITION DEFAULTS -----------------------
Char Attr Fill Color Char Attr Fill Color
& UAM________ _ ¬ PMB_______ _

| X__________ _ _ __________ _
_ ___________ _ _ __________ _
_ ___________ _ _ __________ _
Attributes:
U unprotected A alphanumeric R reverse video > justify right

P protected N numeric W underscore < justify left
S skip B bright Y blink Z justify w/zero
X end D dark E must enter justify w/blank
M mdt on F must fill
Colors: B blue; G green; P pink; R red; T turquoise; Y yellow OR D default

or D default
ENTER: Cont

Note: The screen above shows the default special characters and their
attributes.

The panel fields and their meanings are:

Char Designate a special character to be used when 'painting' the screen.
The character is used as a field marker. You may define a
maximum of eight special characters.
Note: SKETCH reserves the tilda and the broken line.
Attr Assign one or more of the following attributes to the special
character:
U Unprotected - data can be entered.
P Protected - data cannot be entered.
S Skip - the cursor is to skip over the field, thus
preventing data from being entered.
X End-of-field marker. Only one character can be specified
as an end-of-field delimiter. Any other attributes
assigned to this character are ignored.
Note: Each special character must be assigned one of the preceding
attributes.
Any valid combination of the following attributes may also be
specified:
M Set modified data tag on when the map is displayed,
thus allowing the contents of a field to be read whether
modified or not.
A Alphanumeric
N Numeric
Note: A and N are valid only when the Numeric Lock feature is
installed. If neither is specified, the field is assumed to
contain alphanumeric data.
B Bright (high-intensity display).
D Dark (non-display).
Note: If neither B nor D are specified, the fields are shown in
normal intensity.
R Reverse video
W Underscore field
Y Blink
The next two attributes are available only at an IBM 8775-type
terminal which supports validation:
E Must enter. Data must be entered into the field but need
not fill it. The cursor cannot be moved from this field
and data cannot be transmitted until something is
entered.

F Must fill. Data must be entered into the field to fill it.
The cursor cannot be moved from this field and data
cannot be transmitted until the field is filled.
If the following attributes are omitted, the defaults for numeric data
are right and zero and for nonnumeric data are left and blank.
< Right (< and > are mutually exclusive.)
> Left
Z Zero (Z and O are mutually exclusive.)
O Blank
Note: Specifying either > (Left) or O (Blank) assumes the other.
Specifying < (Right) or Z (Zero) assumes the other.
Fill Assign any character. This character is used to fill the field when
the map is initially displayed. The default is blanks.
Color set the fields to one of the following colors:
B Blue
G Green
P Pink
R Red
T Turquoise
Y Yellow
5.1.3 JCL Specification Defaults

You can use this suboption to modify the site-defined default values for a
variety of JCL statement parameters.

BMS: Default JCL Information
-------------------------- DEFAULT JCL DEFINITIONS -------------------------
Job Statement Information:
Job Name:
Account Number:
Programmer Name:
Class:
Msgclass:
Priority:
Other:
ASSEMBLER:
DSECT SYSOUT Dsn:
CICS SYSLIB Dsn:
SYSLIB Concatenation:
LINKAGE EDITOR:
SYSLMOD Dsn:
ENTER: Cont

Job Name Enter a one- to eight-character string to be used as the
job name.
Account Number Enter any one- to 16-digit account number valid at
your site. Commas and parentheses may be included
in the account number. SKETCH does not attempt to
validate this number.
Programmer Name Enter a one- to 20-character name.
Class Enter any valid alphanumeric class code.
Msgclass Enter any valid alphanumeric message class code.
Priority Enter any valid one- or two-character alphanumeric
priority code.
In addition, you may provide default names for:
ASSEMBLER Enter the name of the Assembler program that you
will be using.
DSECT SYSOUT Dsn Enter the one- to 44-character name of the output data
set that is to contain the generated DSECT(s).
CICS SYSLIB Dsn Enter the one- to 44-character name of the CICS macro
library that is to be used for generating the BMS
macros.
SYSLIB Concatenation Enter the one- to 44-character name of the macro
library that is to be used in addition to the CICS
macro library. (Optional.)

LINKAGE EDITOR Enter the name of the Linkage-Editor program that

you will be using.
SYSLMOD Dsn Enter the one- to 44-character name of the data set this
is to contain the output from the Linkage-Editor.

5.2 Create/Update a Map - Option 2

This option permits you to:
1. Modify the defaults used in defining maps and map sets. These defaults
may be either the ones defined by your site or by you through Option 1.
2. Modify the defaults used in defining fields within a map. These are the
special characters and attributes that are defined either by your site or by
you through Option 1.
3. 'Paint' the map.
4. Display a prototype of the 'painted' map.
5. Modify individual field attributes.
BMS: Map Creation/Update
------------------------ BMS MAP CREATION/UPDATE ---------------------------
Select One: __
1. Macro Definition
2. Field Definition
3. Paint Map
4. Review Map
5. Field Detail
Map (member) Name: __________ Map (member) Source: __________
Map Information:
Number of Rows: ___ (1 - 43)

Number of Columns: ___ (1 - 16)

In addition to selecting one of the preceding options, you must provide:
Map Name Specify the one- to seven-character name of the Advantage
CA-Roscoe library member that is to contain the map definition
and related information. (This name is also used for the generated
macro.)
Optionally, you can provide:

Map Source Specify the name of the Advantage CA-Roscoe library member
that contains a BMS map or RPF panel. The contents of this
member is then used as the base for creating a new map and
overrides the default base (for example, ZZZZZBMS).

Number of Specify the number of rows and columns to be used. The

maximum is based on the row/columns size of the terminal
being used. The defaults are 24 rows by 80 columns.
5.2.1 Macro and Field Definitions

Suboptions 1 and 2 allow you to display and modify the default values that
are used when generating the map set, map and fields within a map. When
either suboption is selected, the displayed panel is very similar to the one
displayed through Option 1 on the main menu.
The defaults designated through these panels apply only to the map that is
currently being 'painted'. (Option 1 on the main menu should be selected if
you want to permanently change the defaults.)
When you press the ENTER key or PF4/16 (assigned the Hold function), the
displayed default values are saved in the designated map member.
5.2.2 Painting the Map

Suboption 3 is used to create or modify a map.
If the map name that you entered on the 'Create/Update a Map' panel exists,
then that map is displayed for modification. If no map by that name exists, a
blank-filled screen is displayed.
When you complete creating or modifying your map, a field detail list is
automatically generated for that map if it contains at least one field character.
(See page 5-6 for a description of the field detail list.)
5.2.2.1 Designing a New Map
The blank-filled screen is the size specified on the 'Create/ Update a Map'
panel.
Use the special characters you defined in the 'Field Definition' panel to denote
the map fields. These characters are displayed on the last line of this panel,
along with the PF key assignments. If enough space is available on that line,
the PF keys used for Help, Return, Hold and the line commands are also
displayed. (Excluding the scrolling functions, the PF key functions are
available, even though they are not displayed.) You may overtype the data on
this last line to include additional map fields. When the field detail list is
generated, this line is evaluated only if it has been overtyped.

Mark the end of a field with the same special character that marks its
beginning or by another special character. If no other fields are to immediately
follow a field, the end-of-field special character can be used. For example, the
following is a prompt for a name using the default special characters (where
the % attributes are protected and modified data tag on, the ¬ attributes are
unprotected and modified data tag on, and the / attribute is end-of-field.)
%NAME: ¬__________/
This example actually specifies two fields; SKETCH generates macros for each
of them. As shown in the following example, the macro generates for the first
field specifies the starting position as column 1 of row 1. Note that the field
itself begins in column 2 of row 1. A special character, not included in the
field, is required to mark the beginning of the field. The POS operand,
therefore, specifies the location of this special character.
The generated DFHMDF macros will be:

DFHMDF POS=(1,1), x
LEN=7, x
ATTRB=(PROT,FSET), x
INITIAL='NAME: ', x
DFHMDF POS=(1,1), x
LEN=1, x
ATTRB=(UNPROT,FSET), x
INITIAL='__________'
5.2.2.2 Designing a New Map Using an Existing Map or RPF Panel
You can bypass this option when you use an existing map or RPF panel as the
input source (for example, named on the 'Create/Update a Map' panel). The
field detail list is generated automatically from the named input source.
If an RPF panel is used:

■ The library member must contain only the panel definition (for example, it
must begin with a STARTDEF statement and terminate with an ENDDEF
statement).
■ The panel definition must not:
– define more than eight different field characters and must not use the
tilda and broken vertical bar special characters
– include more than 12 TAG statements
■ Names assigned to panel fields through TAG statements are assigned to
the map fields. Panel indexing is ignored.
■ To preserve the panel, you should ensure that the name of the map to be
created is different from the name of the member containing the panel.
■ While it is not required, you should display the RPF panel as a designed
map.

5.2.2.3 Modifying a Map
The special characters and, possibly PF2/14, PF3/15, PF4/16, PF6/18 and
PF9/21, are displayed only if the bottom line of the map does not contain any
map data.
■ To change the contents, simply overtype the displayed map with the
desired modification. The updates are applied to the map when the
ENTER key or PF4/16 is pressed.
■ To change the size of the map, specify the new value(s) on the
'Create/Update a Map' prompt and redisplay the designed map. Size
changes only take affect after displaying the designed map. Modifications
can also be made to the map at this time.
Note: Caution should be used when reducing the size as fields may be
lost.
■ To delete fields without affecting any other fields, overtype the special
character marking the start of the field with a tilda. The entire field
(beginning with the special character and including the end-of-field special
character, if there is one) is translated to blanks. The deleted field will be
removed from the field detail list.
If you have modified an existing map, select Suboption 5 (Field Detail) to

modify the parameters and specify the names for individual fields.
5.2.2.4 Using PF Keys
The following keys can be used whether painting a new map or modifying an
existing one.
ENTER, PF4 or PF16
causes the painted map to be read and stored.
PF1, PF3, PF5 PF13, PF15 or PF17
causes SKETCH to ignore any changes you have made to the map.
PF5, PF6, PF17 or PF18
displays the map prototype. Pressing the ENTER key while viewing
the prototype returns you to the 'Map Painting' panel. Using these
keys, you can 'jump' from the painted map to the prototype and
back again.
5.2.2.5 Using Line Commands
A basic line command facility is provided to assist you in inserting and

rearranging fields.
To use the line commands, press PF9/21. The 'painted' map becomes a
protected display. To the right of each map line is a field containing two
underscores. One line command function may be entered at a time by
overtyping the two underscores. The available line commands are:

Iv Insert v number of lines, where 'v' can be 1 through 9.

Rv Repeat line containing R v number of times, where 'v' can be 1
through 9.
D or DD Delete one line or the block of lines from the line containing the
first DD through the line containing the second DD.
C or CC Copy one line or the block of lines from the line containing the
first CC through the line containing the second CC to the
designated destination.
M or MM Move one line or the block of lines from the line containing the
first MM through the line containing the second MM to the
The destination commands required by C, CC, M and MM are:

A After this line
B Before this line
Note: If more lines are generated by the insert, repeat or copy line command
than fit on the panel, the excess lines are truncated from the bottom.
To return to the unprotected map display, press the ENTER key. Using
PF9/21 and the ENTER key, you can 'jump' between the protected and
unprotected map, using the line commands as needed.
In those cases where you want to use several line commands, enter the first
and press PF4/16. After that line command is executed, you can enter the next.
(This allows you to view the result of the line command before returning to
the unprotected map display.)
5.2.3 Review Map

Suboption 4 is provided to assist you in designing a map. It displays a
prototype of the map. The special characters defining the start and end of
fields are not displayed. Fields designated as D (non-displayable) are not
displayed; field designated as B (high intensity) are highlighted. You may
overtype unprotected fields.
You may not, however, modify the map under this suboption. Use suboption 3
to change the modifiable map definition.

5.2.4 Field Detail

Once the map is designed, the field detail can be displayed if at least one field
character was specified. (Field detail is not available if the map contains no
fields.)
BMS: Map Field Detail
---------------------------- MAP FIELD DETAIL -----------------------------

Map (member) Name: ________
NOS LINE COL LEN NAME ATTR FILL CURSOR COLOR
___ __ ___ ___ ________ __________ _ _ _

__________________________________________ _______________ ________________
___ __ ___ ___ ________ __________ _ _ _

__________________________________________ _______________ ________________
___ __ ___ ___ ________ __________ _ _ _

_____________________________ ___________ _______________ ________________
___ __ ___ ___ ________ ___________ _ _ _

__________________________________________ _______________ __________________
The second line for each field displays the first 4 characters of that field.
The next two fields can be used to specify PICIN and PICOUT, respectively.
For a list of possible attributes, press PF2/14.
PF7/19: Bkwd PF8/2: Fwd PF1/22: Top PF11/23: Bottom ENTER: Cont

The fields specified in a map are displayed in sequential order along with the
attributes representing the parameter values in effect for the fields.
5.2.4.1 Modifying Fields
■ The position, length and initial value of each field is taken from the
designed map. To modify these, you must update the map design itself.
(If the map is modified under suboption 3 'Painting Map', only those fields
whose positions have not changed retain any modifications made through
this suboption.)
■ At this time, you may:
1. Assign a name to each field
2. Modify the attributes associated with each field
3. Change the fill character
■ If a map is to be used by a COBOL or PL/I program, values are provided
for PICIN and PICOUT. These values are modifiable.
■ One of the fields can be selected as the field to which the cursor is
positioned when the map is initially displayed.

The changes that you make on this panel are associated with the fields defined
in the map. Note, however, that if you change the map design, only those
fields whose positions have not changed retain the field data that you have
supplied.
5.2.4.2 Positioning Panel
Depending on the screen size, either four or eight fields are displayed at one
time. To display additional fields, use:
PF7/19 Scrolls the field listing backwards and update.
PF8/20 Scrolls the field listing forwards and update.
PF10/22 Scrolls to the top of the field listing and update.
PF11/23 Scrolls to the bottom of the field listing and update.
Other PF key assignments include:

PF1/13 Exits SKETCH.
PF3/15 Returns to the main menu without applying updates to the current
display.
PF4/16 Updates the currently displayed fields and redisplay.
PF5/17 Returns to the 'Create/Update a Map' panel. No updates are
applied to the current display.
ENTER Updates the currently displayed fields and returns to the
'Create/Update a Map' panel.

5.3 Generate Macro - Option 3

This option is used to:
1. Generate the BMS macro based on the information stored with the
designated map
2. Display an existing macro
BMS: Macro Generation
-------------------------- BMS MACRO GENERATION ---------------------------
Selection One: __
1. Generate Macro
2. Display Macro
3. Generate and Display Macro
Macro (member) Name: ________ (Required)
Map (member) Name: ________ (Required to Generate Macro)
_ Check if map to be included in mapset specified as Macro Name

Suboption 1:
You can:
■ Supply a macro and map name to generate a macro. (The map name is
supplied by SKETCH using the name you specified under Option 2.) The
generated macro is stored in the Advantage CA-Roscoe library under the
name you provide.
Note: The macro name that you supply is assigned to the BMS macro
DFHMSD. The map name is used as the name of the DFHMDI
macro. The field you supplied in the 'Field Detail' panel are used as
the names of the DFHMDF macros.
To generate BMS macros from an RPF panel, execute Option 2
'Create/Update a Map' prior to this option. Option 2 is the only option
that translates an RPF panel into information that can be used to generate
the macros.

■ Type an 'X' in the field provided to generate map sets and specify the
various map (member) names to be included. Maps are added to the
macro one at a time.
If a map set is not being generated, specifying a member name that
already exists causes that member to be updated with a new BMS macro.
Suboption 2:
You can display and, optionally, modify a generated macro. If you modify the
macro, you must update the Advantage CA-Roscoe library member containing
it before returning to Advantage CA-Roscoe. (The SKETCH map member does
not reflect the changes you made directly to the macros.)
While you are viewing the generated macro, you should avoid executing any
other RPF program. The results are unpredictable. Also, the following
Advantage CA-Roscoe commands cannot be executed:
EXEC LET RETURN
EXIT POP STOP
FETCH PUSH WRITE
The following PF key assignments are available to you:

PF1/13 End SKETCH
PF2/15 Help
PF 3/15 Return
PF 5/17 Return to Main Menu
Suboption 3:
You can generate and display a macro as described above.

5.4 BMS Copybook Generation - Option 4

This option can be used to:
■ Produce the JCL required to assemble and link edit the generated macro.
■ Submit the JCL.
■ Display the JCL for review.
BMS: Copybook Generation
------------------------- BMS COPYBOOK GENERATION --------------------------

Select option: __
1. Tailor JCL
2. Submit
3. Display and Submit (delete AWS to bypass submit)
Macro (member) Name: ________ (Required)
Dsect: _ or Map: _ (Required)

Suboption 1:
You can modify the default JCL for an individual macro. (You also use
Suboption 3 to display and modify the JCL prior to submission.)
Suboption 2:
The default JCL is concatenated to the generated macro and submitted for
execution.
Suboption 3:
The default JCL is concatenated to the generated macro and displayed. To

bypass job submission, delete the contents of the active AWS.

The Macro (member) Name:
The Macro (member) Name is the name of the Advantage CA-Roscoe library
member that contains the SKETCH-generated BMS macros. (This is the name
you gave to the macro that was generated under Option 3 'BMS Macro
Generation'.)
Notes:
Because of BMS requirements, you must execute Option 4 twice. BMS requires
that both a symbolic and a physical map be generated. Therefore, select
DSECT for one execution and MAP for the other. (DSECT causes a symbolic
map (or DSECT) to be assembled with the output being stored in your source
library where it is available to your application program. MAP causes a
physical map to be generated which is assembled, link edited and stored in
your CICS program library.)
Note: The generated JCL does not specify alignment. If halfword alignment is
necessary, the JCL must be modified.
If you select Suboption 3, the generated JCL is written to the active AWS
which is then displayed. You can modify the JCL and save it as a Advantage
CA-Roscoe library member. If you do, this must be done before returning to
While you are viewing the generated JCL, you should avoid executing any
EXEC LET RETURN
EXIT POP STOP
FETCH PUSH WRITE

PF1/13 End SKETCH
PF2/14 Help
PF3/15 Return
PF5/17 Return to Main Menu

Chapter 6. Using SKETCH (for IMS Applications)
To execute SKETCH, type:

EXEC pfx.SKETCH [n]
where:
pfx is the prefix of the sign-on key assigned to SKETCH. The default
prefix is RSK.
n is the number of an option on the main menu. If specified,
execution begins with the panel associated with the designated
option. If omitted, the main menu (as illustrated by the following
screen) is displayed.
MFS: SKETCH Main Menu
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||TM|
||||||||||||||| ||| || ||| ||| ||| ||| ||| |||||||||||
||||||||||||||| ||| ||| | |||| ||||||||| ||||| ||||||| ||| |||||||||||
||||||||||||||| |||||||| ||||| ||||||||| ||||| ||||||| |||||||||||
||||||||||||||| ||| ||||| ||||||| ||||| ||||||| |||||||||||
|||||||||||||||||||| ||| | |||| ||||||||| ||||| ||||||| ||| |||||||||||
||||||||||||||| ||| ||| || ||| ||||||||| ||||| ||||||| ||| |||||||||||
||||||||||||||| ||| ||| || ||||| ||||| ||| ||| |||||||||||
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| Version 6. |||
SKETCH Main Menu Date: Time:

User:
Select the facility desired and press ENTER: _
SKETCH Services- 1 - Profile to Establish Defaults

2 - Create/Update a Map
3 - Generate MFS Format
4 - Generate a Copybook

The options on this introductory selection panel (or main menu) permit you to:
1. Alter site-defined default values. SKETCH includes the default values in
several of the panels that it presents to you. If you choose to alter these
values, they are saved as a member in your library and reused every time
Chapter 6. Using SKETCH (for IMS Applications) 6-1

you sign on to SKETCH. If you do not choose to alter the values, the
site-defined defaults are used.
2. Display the prompt panels used to create and update a map, modify field
parameters and display a prototype of the created map. (The map is saved
as a member in your library.)
3. Display the prompt panels used to generate MFS statements and save the
resulting data. (The data is saved as a member in your library.) This
option also allows you to display and modify the generated macro.
4. Generate the JCL necessary to execute the generated data to create online
blocks from MFS statements. You can also use this option to display and
modify the generated JCL.
The SKETCH prompt panels use the following function key assignments:
PF1/13 Terminate SKETCH. (Changes to the displayed data are ignored.)
PF2/14 Display Help for the current prompt panel. (Changes to the
displayed data are ignored.)
PF3/15 Return one level. (Changes to the displayed data are ignored.)
PF4/16 Hold display. (The displayed data is evaluated and new or changed
data is applied as an update. The current panel is then
redisplayed.)
PF5/17 Return to Main Menu. (Changes to the displayed data are ignored.)
Pressing the ENTER key causes the displayed data to be evaluated and
new/changed data to be applied as an update. The 'next' panel is redisplayed.
You can 'jump' from one option to another without having to return to the
main menu. To do this, move the cursor to the 'Select One' field of any option
panel and type:
=n
where 'n' is the number of an option shown on the main menu. For example, if
you are currently viewing Option 1 and you enter =2 in the 'Select One' field
of that panel, you go directly to Option 2.


Site-defined default values are provided for use in generating MFS statements.
Default values are also provided for several JCL parameters. This option
allows you to establish your own default values.
Note: The use of this option may be restricted by site management.
MFS: Profile Tables
------------------------------- PROFILE TABLES -----------------------------
Select One: __
1. Macro/Statement Defaults
2. Map Field Definitions
3. JCL Specification
4. Switch Format Only
Select One: _ (MFS Format is currently active)
1. BMS Format
2. MFS Format
PF1/13: Exit PF2/14: HELP PF3/15: Return

Suboption 1 or 2:
You can change the default values used by Option 2 'Create/Update a Map'
for every map that you generate.
Your new values are saved in the library member ZZZZZMFS in your library.
(If you do not modify the default values, the site-defined values are saved in
the member ZZZZZMFS under the key assigned for SKETCH.)
Suboption 3:
You can modify the:

■ Default JOB statement parameters
■ Region size
If they are modified, the changed data is saved in the member ZZZZZJCL in
your library.

Suboption 4:
You can switch from MSF to BMS without having to change defaults. If you
select this option, you must designate the format to which you want to switch.
6.1.1 Message Format Defaults

As its name implies, the Message Format Defaults panel contains the current
message format default values.
MSF: Message Format Defaults
------------------------ MESSAGE FORMAT DEFAULTS --------------------------

Message Defaults:
Graphic: Y Y to translate input data to uppercase

N for no translation
Edit: ______ Edit exit routine to be executed on input.
Input Opt: 2 1. All fields contain data (fill or data) or

2. Only actual data in fields
Output Opt: 1 1. All fields contain data (fill or data) or
2. Only actual data in fields
Type: B O for output, B for input and output
Alpha:
(enter any characters to be alphabetic; you may omit A-Z and nationals)
ENTER: Cont

Note: The preceding screen shows the default values.
The meaning of the defaults and the value(s) to which they can be set are:
Graphic Designate whether input data is to be translated to uppercase
by specifying:
Y Force translation. (Default.)
N Do not translate.
Exit Designate the edit exit routine interface for the input by
specifying x,y where:
x is the value of the exit routine number.
y is the value to be passed to the routine.
Input Opt Designate how MFS is to format the input data to the program
by specifying:
1 Pad all messages to the specified length with the fill
character.

2 Translate any input fields not containing data to a

single byte. (Default.)
Output Opt Designate how MFS is to format the output data by specifying:
1 Pad all messages to the specified length with the fill
character. (Default.)
2 Translate output fields not containing any data to a
single byte.
Type Designate the type of MFS statements to be generated as:
O Output only
B Input and output (Default.)
Alpha Designate the characters to be recognized as alphabetic. A-Z
and national characters are already included.
6.1.2 Map Field Definition Defaults

A variety of attributes can be assigned to the fields comprising a map. To
simplify defining maps, SKETCH allows a site to establish default attributes.
The panel displayed through suboption 2 allows you to modify these
site-defined default values.
You can associate default values with specific special characters. You will be
using these special characters to mark the beginning of fields when 'painting' a
map. Once you have painted a map, SKETCH assigns the values to the field(s)
denoted by the special characters. (This is similar to the definition and use of
TAG characters in RPF panels.)
MFS: Map Field Definition Defaults
--------------------- MAP FIELD DEFINITION DEFAULTS ------------------------

Char Attr Fill Color Char Attr Fill Color
& UAM________ _ ¬ PMB_______ _

| X__________ _ _ __________ _
_ ___________ _ _ __________ _
_ ___________ _ _ __________ _
Attributes:
U unprotected A alphanumeric R reverse video < justify right

P protected N numeric W underscore > justify left
S skip B bright Y blink
X end D dark E must enter
M mdt on F must fill
Colors: B blue; G green; P pink; R red; T turquoise; Y yellow OR D default
ENTER: Cont


Note: The above screen shows the default special characters and their
attributes.
The panel fields and their meanings are:

Char A special character to be used when 'painting' the screen. The
character is used as a field marker. You may define a maximum of
eight special characters.
Note: SKETCH reserves the tilda and the broken line.
Attr Assign one or more of the following attribute(s) to the special
character:
U Unprotected - data can be entered.
P Protected - data cannot be entered.
S Skip - the cursor is to skip over the field, thus
preventing data from being entered.
X End-of-field marker. Only one character can be specified
as an end-of-field delimiter. Any other attributes
assigned to this character are ignored.
Note: Each special character must be assigned one of the preceding
attributes.
Any valid combination of the following attributes may be specified.
M Modified data tag is set on when the map is displayed,
thus allowing the contents of a field to be read whether
modified or not.
A Alphanumeric
N Numeric
Note: A and N are valid only when the Numeric Lock feature is
installed. If neither is specified, the field is assumed to
contain alphanumeric data.
B Bright (high-intensity display)
D Dark (non-display)
Note: If neither B nor D are specified, the fields are shown in
normal intensity.
R Reverse video
W Underscore field
Y Blink
The next two attributes are available only at an IBM 8775-type
terminal which supports validation:

E Must enter. Data must be entered into the field but need
not fill it. The cursor cannot be moved from this field
and data cannot be transmitted until something is
entered. (Default)
F Must fill. Data must be entered into the field to fill it.
The cursor cannot be moved from this field and data
cannot be transmitted until the field is filled.
If the following attributes are omitted, the defaults for numeric data
are right and zero and for nonnumeric data are left and blank.
< Right. (< and > are mutually exclusive)
> Left
fill Assign any character or NU. The character are used to fill the field
when the map is initially displayed. NU indicates that MFS should
compress partially filled fields. The default is blanks.
Color set the fields to one of the following colors:
B Blue
G Green
P Pink
R Red
T Turquoise
Y Yellow
6.1.3 JCL Specification Defaults

You can use this suboption to modify the site-defined default values for a
variety of JCL statement parameters.
MFS: Default JCL Information
------------------------- DEFAULT JCL INFORMATION --------------------------
JOB Statement Information:
Job Name:
Account Number:
Programmer Name:
Class:
Msgclass:
Priority:
Other:
Region:
ENTER: Cont


Job Name Enter a one- to eight-character string to be used as the

job name.
Account Number Enter any one- to 16-digit account number valid at your
site. Commas and parentheses may be included in the
account number. SKETCH does not attempt to validate
this number.
Programmer Name Enter a one- to 20-character name.
Class Enter any valid alphanumeric class code.
Msgclass Enter any valid alphanumeric message class code.
Priority Enter any valid one- or two-character alphanumeric
priority code.
Region Enter the size of the area needed for execution. If
omitted, the default size is 360K.


This option permits you to:
1. Modify the defaults used in defining maps. These defaults may be either
the ones defined by your site or by you through Option 1.
2. Modify the defaults used in defining fields within a map. These are the
special characters and attributes that are defined either by your site or by
you through Option 1.
3. 'Paint' the map.
4. Display a prototype of the 'painted' map.
5. Modify individual field attributes.
MFS: Map Creation/Update
------------------------ MFS MAP CREATION/UPDATE --------------------------
Select One: __
1. Statement Definition
2. Field Definition
3. Paint Map
4. Review Map
5. Field Detail
Map (member) Name: __________ Map (member) Source: __________
Map Information:
Number of Rows: ___ (1 - 43)

Number of Columns: ___ (1 - 16)

In addition to selecting one of the preceding options, you must provide a:
Map Name
Specify the one- to seven-character name of a Advantage
CA-Roscoe library member that is to contain the map definition and
related information. (This name is also used as the name for the
generated macro.)
Optionally, you can provide a:

Map Source Specify the name of a Advantage CA-Roscoe library member
that contains an MFS map or RPF panel. The contents of this
member is then used as the base for creating a new map and
overrides the default base (for example, ZZZZZMFS).

Number of Specify the number of rows and columns to be used.

Rows/Columns
Size of the terminal being used. The Defaults are 24 rows by
80 columns
6.2.1 Statement and Field Definitions

Suboptions 1 and 2 allow you to display and modify the default values that
are used when generating a map and fields within a map. The panel displayed
when either suboption is selected is very similar to that displayed through
Option 1 on the main menu.
The defaults designated through these panels apply only to the map that is
currently being 'painted'. (Option 1 on the main menu should be selected if
you want to permanently change the defaults.)
When you press the ENTER key or PF4/16 (assigned the Hold function), the
displayed default values are saved in the designated map member.
6.2.2 Painting the Map

Suboption 3 is used to create or modify a map.
If the map name that you entered on the 'Create/Update a Map' panel exists,
then that map is displayed for modification. If no map by that name exists, a
blank-filled screen is displayed.
If the map contains lowercase characters in the literal fields, they are translated
to uppercase to conform to MFS requirements.
When you complete creating or modifying your map, the field detail list is
automatically generated for that map if it contains at least one field character.
(See page 6-13 for a description of the field detail list.)
6.2.2.1 Designing a New Map
The blank-filled screen is the size specified on the 'Create/Update a Map'

panel.
Use the special characters you defined in the 'Field Definition' panel to denote
the map fields. These characters are displayed on the last line of this panel,
along with the PF key assignments. If enough space is available on that line,
the PF keys used for Help, Return, Hold and the line commands are also
displayed. (Excluding the scrolling functions, the PF key functions are
available, even though they are not displayed.) You may overtype the data on
this last line to include additional map fields. When the field detail list is
generated, this line is evaluated only if it has been overtyped.

Mark the end of a field with the same special character that marks its
beginning or by another special character. If no other fields are to immediately
follow a field, the end-of-field special character can be used. For example, the
following is a prompt for a name using the default special characters (where
the % attributes are protected and modified data tag on, the ¬ attributes are
unprotected and modified data tag on, and the / attribute is end-of-field.)
%NAME: ¬__________/
This example actually specifies two fields. Assuming that the unprotected field
is to be named and the protected field is not to be named, the generated
MFLD and DFLD statements will be:
(input) MFLD NME,LTH=12,ATTR=YES,FILL=C'_'
(output) MFLD (NME,'__________'),LTH=1,ATTR=NO
DFLD 'NAME: ',POS=(1,2),LTH=7, X
ATTR=(ALPHA,PORT,NORM), X
EATTR=(HD,CD)
NME DFLD POS=(1,1),LTH=1, X
ATTR=(ALPHA,NOPROT,NORM,MOD), X
EATTR=(HD,CD)
The statements generated for the first field specifies the starting position as
column 2 of row 1. (A field cannot begin in column 1 because a special
character, not included in the field itself, is required to mark the beginning of a
field.)
6.2.2.2 Designing a New Map Using an Existing Map or RPF Panel
You can bypass this suboption when you use an existing map or RPF panel as
the input source (for example, named on the 'Create/Update a Map' panel).
The field detail list is generated automatically from the named input source.
If an RPF panel is used:

■ The library member must contain only the panel definition (for example, it
must begin with a STARTDEF statement and terminate with an ENDDEF
statement).
■ The panel definition must not:
– define more than eight different field characters and must not use the
tilda and broken vertical bar special characters.
– include more than 12 TAG statements.
■ Names assigned to panel fields through TAG statements are assigned to
the map fields. Panel indexing is ignored.
■ To preserve the panel, you should ensure that the name of the map to be
created is different from the name of the member containing the panel.
■ While it is not required, you should display the RPF panel as a designed
map.

6.2.2.3 Modifying a Map
The special characters and, possibly PF2/14, PF3/15, PF4/16, PF6/18 and
PF9/21, are displayed only if the bottom line of the map does not contain any
map data.
■ To change the contents, simply overtype the displayed map with the
desired modification. The updates are applied to the map when the
ENTER key or PF4/16 is pressed.
■ To change the size of the map, specify the new value(s) on the
'Create/Update a Map' prompt and redisplay the designed map. Size
changes only take effect after displaying the designed map. Modifications
can also be made to the map at this time.
Note: Caution should be used when reducing the size as fields may be
lost.
■ To delete fields without affecting any other fields, overtype the special
character marking the start of the field with a tilda. The entire field
(beginning with the special character and including the end-of-field special
character, if there is one) is translated to blanks. The deleted field are
removed from the field detail list.
If you have modified an existing map, select Suboption 5 (Field Detail) to

modify the parameters and specify the names for individual fields.
6.2.2.4 Using PF Keys
The following keys can be used whether painting a new map or modifying an
existing one.
ENTER, PF4 or PF16 Causes the painted map to be read and stored.
PF1, PF3, PF5, PF13, PF15 or PF17
Causes SKETCH to ignore any changes you have made
to the map.
PF6 or PF18 Displays the map prototype. Pressing the ENTER key
while while viewing the prototype returns you to the
'Map Painting' panel. Using these two keys, you can
'jump' from the painted map to the prototype and back
again.
6.2.2.5 Using Line Commands
A basic line command facility is provided to assist you in inserting and

rearranging fields.
To use the line commands, press PF9/21. The 'painted' map becomes a
protected display. To the right of each map line is a field containing two
underscores. One line command function may be entered at a time by
overtyping the two underscores. The available line commands are:

Iv Insert v number of lines, where 'v' can be 1 through 9.

Rv Repeat line containing R v number of times, where 'v' can be 1
through 9.
D or DD Delete one line or the block of lines from the line containing the
first DD through the line containing the second DD.
C or CC Copy one line or the block of lines from the line containing the
first CC through the line containing the second CC to the
M or MM Move one line or the block of lines from the line containing the
first MM through the line containing the second MM to the
The destination commands required by C, CC, M and MM are:

A After this line
B Before this line
Note: If more lines are generated by the insert, repeat or copy line command
than fit on the panel, the excess lines are truncated from the bottom.
To return to the unprotected map display, press the ENTER key. Using
PF9/21 and the ENTER key, you can 'jump' between the protected and
unprotected map, using the line commands as needed.
In those cases where you want to use several line commands, enter the first
and press PF4/16. After that line command is executed, you will be able to
enter the next. (This allows you to view the result of the line commands before
returning to the unprotected map display.)
6.2.3 Review Map

Suboption 4 is provided to assist you in designing a map by displaying a
prototype of the map. When a prototype is displayed: 1) the special characters
defining the start and end of fields are not shown, and 2) color or extended
attributes assigned to fields are recognized and used. You may overtype
unprotected fields.
You may not, however, modify the map under this suboption. Use suboption 3
to change the modifiable map definition.
6.2.4 Field Detail

Once the map is designed, the field detail can be displayed if at least one field
character was specified. (Field detail is not available if the map contains no
fields.)

MFS: Map Field Detail
----------------------------- MAP FIELD DETAIL ----------------------------

Map (member) Name: ________
NOS LINE COL LEN NAME ATTR FILL CURSOR COLOR
___ __ ___ ___ ________ __________ __ _ _

_________________________________________ _______________
___ __ ___ ___ ________ __________ __ _ _
_________________________________________ _______________
___ __ ___ ___ ________ __________ __ _ _
_________________________________________ _______________
___ __ ___ ___ ________ __________ __ _ _
__________________________________________________________
The second line for each field displays the first 4 characters of that field.
The next field can be used to specify the EXIT= value.
For a list of possible attributes, press PF2/14.
PF7/19: Bkwd PF8/2: Fwd PF1/22: Top PF11/23: Bot ENTER: Cont

The fields specified in a map are displayed in sequential order along with the
attributes representing the parameter values in effect for the fields.
6.2.4.1 Modifying Fields
■ The position, length and initial value of each field is taken from the
designed map. To modify these, you must update the map design itself. (If
the map is modified under suboption 3 'Painting Map', only those fields
whose positions have not changed retain any modifications made through
this suboption.)
■ At this time, you may:
1. Assign a name to each field.
2. Modify the attributes associated with each field.
3. Change the fill character.
■ You can use the second field of the second line to provide the value for an
edit exit routine that is to be associated with a field. If specified, it must be
in the form x,y where 'x' is the value of the exit routine and 'y' is the value
to be passed to the routine.
■ One of the fields can be selected as the field to which the cursor is
positioned when the map is initially displayed.
The changes that you make on this panel are associated with the fields defined
in the map. Note, however, that if you change the map design, only those
fields whose positions have not changed retain the field data that you have
supplied.

6.2.4.2 Positioning Panel
Depending on the screen size, either four or eight fields are displayed at one
time. To display additional fields, use:
PF7/19 Scrolls the field listing backwards entries and update.
PF8/20 Scrolls the field listing forwards update.
PF10/22 Scrolls to the top of the field listing and update.
PF11/23 Scrolls to the bottom of the field listing and update.
Other PF key assignments include:

PF1/13 Exits SKETCH.
PF3/15 Returns to the main menu without applying updates to the current
display.
PF4/16 Updates the currently displayed fields and redisplays.
PF5/17 Returns to the 'Create/Update a Map' panel. No updates are
applied to the current display.
ENTER Updates the currently displayed fields and returns to the
'Create/Update a Map' panel.

6.3 Generate Message Statements - Option 3

This option is used to:
■ Generate the message format statements based on the information stored
in the designated map.
■ Display an existing statement.
MFS: Message Statement Generation
---------------------- MESSAGE STATEMENT GENERATION -----------------------
Selection One: __
1. Generate Message Format Statements

2. Display Statements
3. Generate and Display Statements
Format (member) Name: ___________ (Required)
Map (member) Name: ___________ (Required to Generate Format)
Format statements for the following 327 terminal models:
_1 _2 _3 _4 _5

You can select one of the following options:
Suboption 1:
Follow these steps:

1. Supply a format and map name to generate the message format
statements. (The map name is supplied by SKETCH using the name you
specified under Option 2.) The generated statements are stored in the
Advantage CA-Roscoe library under the name you provided as the format
name.
The format name you supply is:
■ Assigned to the FMT statement
■ Modified for use with MSG statements
The modification is that the last two characters are set to one of the
following.
■ IN (for input statements)
■ OU (for output statements)

For example, if you state that the format name is MAP, the following is
generated:
MAPIN MSG TYPE=INPUT,SOR=MAP,1 NXT=MAPOU,...
MAPOU MSG TYPE=OUTPUT,SOR(MAP, IGNORE),NXT=MAPIN,...
MAP FMT
The hierarchy used in generating MFLD and DFLD statements is based on
whether the field is: 1) named and 2) protected or unprotected. A DFLD
statement is generated for every field. If the field is named, an MFLD
statement for MSG TYPE=OUTPUT is created. If the field is unprotected
and named, an MFLD statement for MSG TYPE=INPUT is created. The
initial value of the field is specified on the DFLD statement of unnamed
fields and on the MSG TYPE=OUTPUT MFLD statement of named fields.
To generate message format statements from an RPF panel, execute Option
2 'Create/Update a Map' prior to this option. Option 2 is the only option
that translates an RPF panel into information that can be used to generate
the statements.
2. Designate that the generated message format statements are for any model
1, 2, 3, 4 or 5 3270-type terminals. The only limitation is based on the
specified map size (not 'painted' map). Thus, if you stated that the map
size is to be 24 lines by 80 columns, you may specify any model except 1.
If you set he map size to 43 lines by 80 columns, only a model 4 3270-type
terminal can be selected.
Suboption 2:
You can display and modify the generated message format statements. If you
modify the statements, you must update the Advantage CA-Roscoe library
member containing them before returning to Advantage CA-Roscoe. (The
SKETCH map member does not reflect the changes you made directly to the
statements.)
While you are viewing the generated statements, you should avoid executing
any other RPF program. The results are unpredictable. Also, the following
EXEC LET RETURN

EXIT POP STOP
FETCH PUSH WRITE

PF1/13 End SKETCH
PF2/14 Help
PF3/15 Return
Suboption 3:
You can generate and display statements, as noted previously.

6.4 MFS Copybook Generation - Option 4

This option can be used to:
■ Produce the JCL required to create the online blocks for the MFS
statements.
■ Submit the JCL.
■ Display the JCL for review.
MFS: Copybook Generation
------------------------ MFS COPYBOOK GENERATION --------------------------

Select option: __
1. Tailor JCL
2. Submit
3. Display and Submit (delete AWS to bypass submit)
Format (member) Name: ________ (Required)
Message statements to be formatting in: _ (Required)
1. Production Library
2. Test Library

Suboption 1:
You can modify the default JCL for an individual execution. (You can also use
Suboption 3 to display and modify the JCL prior to submission.)
Suboption 2:
The default JCL is concatenated to the generated statements and submitted for
execution.
Suboption 3:
The default JCL is concatenated to the generated statements and displayed. To

bypass job submission, delete the contents of the active AWS.

Format (member) Name:
The Format (member) Name is the name of the Advantage CA-Roscoe library
member that contains the SKETCH-generated message format statements. (This
is the name you gave to the member that was generated under Option 3
'Message Statement Generation'.)
Message statements to be formatting in:
You must designate whether the generated online blocks are to be placed in
the production libraries of IMSVS.FORMAT or the test libraries of
IMSVS.TFORMAT.
Notes
If you select suboption 3, the generated JCL is written to the active AWS
which is then displayed. You can modify the JCL and save it as a Advantage
CA-Roscoe library member. If you do, this must be done before returning to
While you are viewing the generated JCL, you should avoid executing any
EXEC LET RETURN
EXIT POP STOP
FETCH PUSH WRITE

PF1/13 End SKETCH
PF2/14 Help
PF3/15 Return

Chapter 7. SKETCH Customization Considerations
SKETCH is distributed in LIBUTIL format on ROSCOE.KEYS. By default, the

profile name is ROSCOE.SKETCH and the prefix is RSK.
Chapter 7. SKETCH Customization Considerations 7-1

7.1 SKETCH-Related Library Members

When Advantage CA-Roscoe is initially installed, the SKETCH profile is added
to the User Profile System (UPS) and associated library members are added to
the Advantage CA-Roscoe library.
At CICS sites, the library members include:

ZZZZZBMS Contains the default values for the DFHMSD and DFHMDF
macro parameters. For the user, these defaults are the base
used for the macro values, the special characters and attributes,
the screen size and the blank-filled map.
This member can be modified by executing SKETCH under the
key assigned to SKETCH. Select Option 1 from the main menu
and modify the suboptions as appropriate.
ZZZZZDSE Contains the JCL used to assemble a DSECT for use in
application programs.
Review this member immediately after installation and modify
it as needed to meet your site requirements.
ZZZZZJCL Contains the default JOB statement parameters. It also contains
the names of the CICS SYSLIB and data set to be used to hold
the generated DSECT(s).
ZZZZZMAP Contains the JCL to assemble and link edit the BMS macros to
the CICS load library.
At IMS sites, the library members include:

ZZZZZFMT Contains the JCL needed to generate the MFS online blocks and
place them on the IMSVS.FORMAT library.
ZZZZTFMT Contains the JCL needed to generate the MFS online blocks and
place them on the IMSVS.TFORMAT library.
ZZZZZJCL Contains the default JOB statement parameters. It also contains
the region size.


ZZZZZMFS Contains the default values for the MFS statements (DFLD,
DIV, MFLD, MSG and SEG). For the user, the defaults are used
for the statement values, the special characters and attributes,
the screen size and the blank-filled map.
All sites can use the library member:

ZZZZZPFX This member can be used by site management to restrict certain
users from modifying the default values displayed in Option 1.
As distributed, this member contains a blank (for example, no
user is restricted from modifying the default values.) To restrict
a user, add that individual's prefix to this member. Prefixes
may be added one per line or multiple prefixes may be on a
single line. All prefixes must be immediately followed by a
semicolon (;). For example, to restrict the user assigned the
prefix AAA, the entry in ZZZZZPFX would be: AAA;
Sites using SKETCH with CA-MetaCOBOL+ have the additional library

member:
PFKEYUPD This member contains an RPF program that will define the PF
key assignments for PF3/15 and PF5/17 (for example, PF3/15
returns to the main menu and PF5/17 will return one level.)

7.2 RPF Variables Used by SKETCH
7.2 RPF Variables Used by SKETCH

SKETCH uses the following permanent variables:
P2 Map member name.
P3 Macro/format member name. (For MFS, the name is a maximum of
six characters in length.)
P4 List of the special characters being used for the current map (map
referenced in P2).
P5 List of special characters and attributes to be displayed when
designing the map.
P6 BMS for creating BMS macros or MFS for creating MFS statements.
The names specified for P2 and P3 as well as for each field may be one to
seven characters in length. This length qualification is in keeping with BMS
requirements. Other than that, the name must follow Advantage CA-Roscoe
naming conventions.
When the user presses PF1 or PF13 to terminate the SKETCH session, all
permanent variables are set to null. It should also be noted that SKETCH
terminates with an RPF RETURN command. This means that if SKETCH is
executed as an option of another RPF application, that application receives
control when the user exits SKETCH.

7.3 IMS Device Types

The device type values SKETCH uses for 3270-type terminals when generating
DEV statements are:
Model TYPE Value

1 3270-A5
2 3270-A2
3 3270-A3
4 3270-A4
5 3270-A7
These values are the IBM-recommended standard symbolic names for each
model.
Note: Model 1 refers to terminals with 12 rows by 40 columns.
Sites that either do not use IMS symbolic terminal names or use different
values may need to change the Advantage CA-Roscoe-distributed values so
that they agree with the site's IMS/VS system generation. To do this, sign on
to the SKETCH key and use Option 1.1 to specify the device type values that
are to be generated. (For the SKETCH key only, the Option 1.1 panel includes
the Device Type Values information.)


Index
Color
A Defining
Advantage CA-Roscoe Library Interface 2-2 BMS SKETCH 5-5
Arithmetic symbols (syntax diagrams) xi MFS SKETCH 6-7
Assembler Comma
Coding ROETSAPI 1-4 repeat symbol, use in xiv
Assembler Example Copybook Generation
ROETSAPI 3-2 BMS SKETCH 5-20
Attributes, Extended MFS SKETCH 6-18
Defining
BMS SKETCH 5-5
MFS SKETCH 6-6 D
AWS Interface (AWSI) 2-1 DCB Records 2-4
AWSI Macro 2-1 Default values (syntax diagrams) xv
Delimiters
syntax diagrams, use in xii
B DFHMDF Macro 5-13
BMS (SKETCH) DVRT Function 1-6
Copybook Generation 5-20
Create/Update Map 5-11
Default JCL Definitions 5-8 E
Macro Definition Defaults 5-4 ETSRPS= Initialization Parameter 2-1
Macro Generation 5-18 Examples
Map Field Definition Defaults 5-6 Assembler 3-2
Map Field Detail 5-16 COBOL 3-4
Painting Maps 5-12 PL/I 3-12
Profile Tables 5-3 Extended Attributes
SKETCH Main Menu 5-1 Defining
BMS SKETCH 5-5
MFS SKETCH 6-6
C
CA-MetaCOBOL+
Using with SKETCH 7-3 F
CICS FORTRAN
Executing SKETCH 5-1 Coding ROETSAPI 1-4
COBOL Functions
Coding ROETSAPI 1-3 ROETSAPI 1-6
Example, ROETSAPI 3-4
Coding Conventions
ROETSAPI 1-3
Index X-1
G P
GETV Function 1-8 Painting Maps
BMS SKETCH 5-12
MFS SKETCH 6-10
H PANL Function 1-16
Highlights Parentheses
Defining (BMS SKETCH) 5-5 syntax diagrams, use in xii
PFKEYUPD Library Member 7-3
I PL/I
Coding ROETSAPI 1-3
IMS
Example, ROETSAPI 3-12
Executing SKETCH 6-1
Programs
IMS Device Types 7-5
comma
repeat symbol, use in xiv
J parentheses
JCL syntax diagrams, use in xii
Defining Defaults punctuation
BMS SKETCH 5-8 syntax diagrams, use in xi
MFS SKETCH 6-7 Punctuation marks (syntax diagrams) xi
PUTV Function 1-17
K
Keywords (syntax diagrams) xi Q
QENV Function 1-21
QERR Function 1-25
L
Language, Source
Defining R
BMS SKETCH 5-5 Return Codes
LIBI Macro 2-2 ROETSAPI 1-5
Library Members ROETSAPI
SKETCH-Related 7-2 Coding Conventions 1-3
Linkage Conventions Function Calls 1-3
ROETSAPI 1-4 Functions 1-6
Linkage Conventions 1-4
Overview 1-2
M Return Codes 1-5
MFS (SKETCH)
Copybook Generation 6-18
Create/Update Map 6-9 S
Default JCL Definitions 6-7 SKETCH
Map Field Definition Defaults 6-5 Advantage CA-Roscoe Library Members 7-2
Map Field Detail 6-13 Defaults
Message Format Defaults 6-4 BMS 5-3
Message Statement Generation 6-16 MFS 6-3
Painting Maps 6-10 Main menu
Profile Tables 6-3 BMS 5-1
SKETCH Main Menu 6-1 MFS 6-1
Overview 4-1
RPF Variables 7-4
Signon prefix
CICS 5-1
X-2 Extended Development Tools Guide

SKETCH (continued)
Signon prefix (continued)
IMS 6-1
Under CICS 5-1
Under IMS 6-1
Using with CA-MetaCOBOL+ 7-3
Special Characters
Defining
BMS SKETCH 5-7
MFS SKETCH 6-6
Storage
Defining (BMS SKETCH) 5-4
SUSP Function 1-28
Syntax diagrams
reading (how to) xi—xvi
T
Terminal Characteristics
Defining
BMS SKETCH 5-5
MFS SKETCH 6-10
V
Variables
Used by SKETCH 7-4
Variables (syntax diagrams) xi
Z
ZZZZTFMT Library Member 7-2
ZZZZZBMS Library Member 7-2
ZZZZZDSE Library Member 7-2
ZZZZZFMT Library Member 7-2
ZZZZZJCL Library Member 7-2
ZZZZZMAP Library Member 7-2
ZZZZZMFS Library Member 7-3
ZZZZZPFX Library Member 7-3
Index X-3

ROSCOE - B001622e - Extended Development Tools 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 - B001622e - Extended Development Tools Guide

Uploaded by

Copyright:

Available Formats

Advantage CA-Roscoe

Extended Development Tools Guide

The manufacturer of this Documentation is CA.

Copyright  2005 CA. All rights reserved.

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Part I. ETSO Application Programming Interface

Chapter 1. Using ROETSAPI . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Chapter 2. Other Programming Considerations . . . . . . . . . . . . . . . 2-1

Chapter 3. ROETSAPI Examples . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Chapter 4. SKETCH Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Chapter 5. Using SKETCH (for CICS Applications) . . . . . . . . . . . . 5-1

Chapter 6. Using SKETCH (for IMS Applications) . . . . . . . . . . . . . 6-1

Chapter 7. SKETCH Customization Considerations . . . . . . . . . . . . 7-1

iv Extended Development Tools Guide

This guide for Advantage CA-Roscoe Interactive Environment (Advantage

About This Guide v

vi Extended Development Tools Guide

User Series Contents

About This Guide vii

viii Extended Development Tools Guide

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

About This Guide ix

Licensing Management Program (LMP)

Advantage CA-Roscoe now interfaces with CAIRIM services to determine

x Extended Development Tools Guide

The following terminology, symbols, and concepts are used in syntax

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

Variables: Appear in italicized lowercase letters, for example, variable.

Required Keywords and Variables: Appear on a main line.

Optional Keywords and Variables: Appear below a main line.

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

About This Guide xi

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

xii Extended Development Tools Guide

Default Value for a Required Parameter

COMMAND PARM1=NO PARM2

Choice of Optional Parameters

About This Guide xiii

Repeatable Variable Parameter

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

Separator with Repeatable Variable and Delimiter

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

Optional Repeatable Parameters

xiv Extended Development Tools Guide

Default Value for a Parameter

Because YES is the default in the example preceding, if you write:

you have written the equivalent of:

COMMAND PARM1=YES PARM2

In some syntax diagrams, a set of several parameters is represented by a single