GC20 1807 3_VM370_System_Programmers_Guide_Rel_2_Jan75 3 VM370 System Programmers Guide Rel 2 Jan75
User Manual: GC20-1807-3_VM370_System_Programmers_Guide_Rel_2_Jan75
Open the PDF directly: View PDF 
.
Page Count: 437
| Download | |
| Open PDF In Browser | View PDF |
File No.
S370-37
Order No. GC20-1807-3
IBM Virtual Machine
Facility /370:
System Programmer's Guide
Systems
Release 2 PLC 13
This publication is intended for VM/370 system
programmers. A debugging section describes the procedures, commands, and utilities useful in debugging
and provides guidance in dump reading. A Control
Program (CP) section describes how CP works and
tells how to modify or better utilize CPo A Conversational Monitor System (CMS) section describes
how CMS works, and describes in detail some
special features of CMS. The last two sections describe teleprocessing support for VM/370: one
section describes the IBM 3704 and 3705
Communications Controllers and the other
describes the Remote Spooling Communications
Subsystem (RSCS).
For the titles and abstracts of related publications,
refer to the latest IBM System/360 and System/370
Bibliography, GA22-6822, and its Virtual Storage
Supplement, GC20-0001.
GC20-1807-3 Paqe Modified by TNL GN2U-2662, March 31,
This edition, together with Technical Newsletter GN20-2662 dated March
31, 1975, is a major revision of GC20-1807-2 and makes that edition and
Technical Newsletter GN20-2643 obsolete.
This edition corresponds to
B~l~~~~
l R1~ 11 (Program Level Change) of IBM Virtual Machine
Facility/370 and to all subsequent releases until otherwise indicated in
new editions or technical newsletters.
Changes are periodically made to the specifications herein; before using
this publication in connection with the operation of IBM systems,
consult the latest l~~ ~I~!~~L1§Q ~nQ ~I~!g!L11Q ~iQliQg~~EhI, Order No.
GA22-6822, and its Yi~!Y~l ~!QE~~~ ~~EE1~!~n!, Order No. GC20-0001, for
the editions that are applicable and current.
Technical changes and additions to text and illustrations are indicated
by a vertical bar to the left of the change.
Requests for copies of IBM publications should be made to your
representative or to the IBM branch office serving your locality.
IBM
A form for readers'
comments is
provided at the back of this
publication.
If the form has been removed, comments may be addressed to
IBM Corporation, VM/370 Publications,
24 New England Executive Park,
Burlington, Massachusetts 01803. Comments become the property of IBM.
©
Copyright International
1974, 1975
Business Machines Corporation
1972, 1973,
1975
Preface
This publication describes how to debug
VM/370 and
how to modify,
extend or
implement
Control
Program
(CP)
and
Conversational
Monitor
System
(CMS)
functions.
This information is intended
for system programmers, system analysts,
and program personnel.
This publication consists
and two appendixes.
of five parts
"Part
1:
Debugging
with
VM/370"
discusses the CP and CMS debugging tools
and procedures to follow when debugging.
This part is logically divided into three
topics. The first section "Introduction to
Debugging" tells you how to identify a
problem and lists guidelines to follow to
find
the cause.
The second
section
"Debugging with
cpu
describes
the CP
debugging com.ands and utilities, debugging
CP in a virtual .achine, the internal trace
table
and
restrictions.
A
detailed
description of CP dump reading is also
included.
The third section "Debugging
with CMS" describes
the CMS debugging
commands and utilities, load maps, and
restrictions and tells you what fields to
examine when reading a CMS dump.
"Part 2: Control Program (CP)" contains
an introductory and functional description
of CP as well as guidance in implementing
some CP features.
"Part 3:
\~n~J"
Conversational
contains
dll
Monitor System
introductory
"Appendix A:
System/370 Information"
describes the System/370 extended PSi and
extended control register usage.
"Appendix B: MULTI-LEAVING" provides a
detailed description of MULTI-LEAVING1, a
computer-to-computer
communications
technique developed for use by the HASP
system and used by the RSCS component of
VM/370.
In this publication,
the term 3330
series is used in reference to both the IBM
3330 Disk Storage, Models 1, 2, and 11, and
the IBM 3333 Disk storage and Control,
Models 1 and 11. The term 2305 series is
used in reference to the IBM 2305 Fixed
Head storage, Models 1 and 2.
Also, any
reference to the IBM 2741 Terminal is also
applicable to the IBM 3767 Communications
Terminal unless noted otherwise.
The Glossary has been eliminated from
this publication. An expanded glossary is
available in
the IBM
virtual Machine
Faci!illn70: Gl.Q§sar,!-!nd Masti!: -!J!de!,
Order No. GC20-1813.
Knowledge of Asse.bler
Language and
experience with programming concepts and
techniques are prerequisite to using this
publication.
References to a standalone dump occur in
several places in this publication. One
such program is the BPS Storage Print
program, Program No. 360P-UT-056.
dUU
functional description of CMS including how
CMS handles interrupts
and SVC calls,
structures its nucleus and its storage, and
manages free
storage.
Information
on
saving the CMS system and implementing the
Batch Facility is also included.
"Part
4.
IBM
3704
and
3705
Communications Controllers" describes the
functions and uses of these programmable
units. Information is included on loading,
testing, and updating the control program.
PREREQUISITE PUBLICATIONS
IBM Q..§L.!.§ !J!,g VML37.Q
Guid§, GC33-4021.
IBM
OSLVS, ]OS/VS, and
GC33-4010.
l~gy!g~,
"Part 5. Remote Spooling Communications
Subsystem (RSCS)" describes the functions
and uses of the component of VM/370 that
handles the trans.ission of files between
VM/370 users and remote programmable and
non-program.able stations.
AS2~!!2!~ Pr2gra!!u!:~
!l1L37.Q
!2§~!~ler
Knowledge of the co.mands and system
functions
of CP,
CMS,
and RSCS
is
corequisite.
1 IBM Unregistered Trademark
COREQUISITE PUBLICATIONS
f!~nni~
~~g ~2!~!
Co •• ~n~
1~~gy~g§
Data ~~naqe.ent
Order No. GC26-3793.
Ge]~~!!~]
Order No. GC20-1801
~2§!2'
g~L!~
~yid~
!£!
~~fI~
lB2!!Yfti~n2'
~~id~,
Ge~~!~!
Order No. GC20-1804
QE~~!Q!~2 ~uide,
Terminal
(;C20=1810
Order No. GC20-1806
Y~~2
Order
111~ ~2~I!2 ~uid~,
IBM
3211
Printer,
Train-~artr~gg§,
No.
J~l~
~nd 3811
Printer Control
unit ~2~EQ!l~! Descript!Q!l and gperatQI's
Gui~§, Order No. GA24-3543.
1~~ Q~L!~ Lin!~g§ Idit~£
Order No. GC20-1812
InteI£ha!lg~~~le
~]g 1~~g~!,
Order
Introduction to the IBM 3704 and
CommunIcations-- contro!!er§-,---Order
GA27=3051:----
1105
No. GC26-3813.
£~n!!~!
R!Qgf~~
(£R)
Order No. SY20-0880
Re!Qte
IBM
3704
controllers
"(;127==3055:
~EQQ!~ng £~!~yni£gtiQn2 ~ybsY2!§!
(RS~~)
RIQgf~
1Qqic,
Order
No.
SY20-0883
!~te:
No.
References in text to titles
coreguisite VM/370 publications will
given in abbreviated form.
of
be
If the IBM 3767 Communication Terminal
is used by the system programmer as a
virtual machine console,
the IBM 3767
Q~§!~!£!!§ ~~id§, Order No. GA18-2000~s
also a coreguisite publication.
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Summary of Amendments
for GC20-1807-3
VM/370 Release 2 PLC 13
!~!:
A
Program Feature
new
expa~sion
commmand
(INDICATE)
and
an
Transmission
Control
Unit,
or
a
3704/3705 Communications Controller in
emulation mode. The remote 3270 user
also has the capability of copying an
entire screen display on a 3284, 3286,
or 3288 printer at the remote location.
of the MONITOR command provide
a way to dynamically measure system
performance. The general user can have
displayed, at his
terminal, certain
certain system load conditions and his
virtual
system's
usage
of
system
resources.
The
system analyst
can
sample and record a wide variety of
system load data, I/O activity, resource
utilization,
response
data
and
simulation data.
The followinq changes to
reflect this new support:
A
new
section,
"Performance
Observation and Analysis" has been added
to "Part 2: Control Program (CP)."
•
!~~:
•
•
•
A new operand, PFnn COPY is added to
the CP SET command
in "Part 1:
Debugging with VM/370."
The section on "CP Restrictions" is
updated to include restrictions to
this new support.
"Figure
11.
CP
Control
Block
Relationships" is updated.
"Part
4:
IBM
3704
and
3705
Communications
Controllers"
is
updated
to include
remote
3270
support.
!~!:
requirements
of
the
other.
~n~
following changes to this manual reflect
this support:
•
•
•
A new operand, PAGEX, is added to the
CP SET command in "Part 1: Debugging
with VM/370."
A new section, "VM/VS Handshaking" is
added to "Part 2: Control Program
(CP) ."
A new Diagnose code 0 is added to the
"Diagnose Instruction in a virtual
Machine" section in "Part 2: Control
Program (CP)."
!~!:
Program Feature
A virtual machine user may now initiate
the punching of
an accounting card
containing up to 70 bytes of data, the
content and format of which he can
determine.
The fcllowing changes to
this manual reflect this support:
Program Feature
•
VM/370
now supports
the IBM
3270
Information Display System as a remote
virtual machine console attached via
nonswitched point-to-point lines to a
2701
Data
Adapter
Unit,
2703
Program Feature
Two new operands to the SET command
described in "Part 1: Debugging with
VM/370" allow the virtual machine user
~u ~naD~e and disable
~ne ECMODE and/or
ISAME options, dynamically.
•
!~~:
manual
Program Feature
The VM/VS Handshaking
feature is a
communication path between VM/370 and
OS/VS1 that makes each system control
program aware of certain capabilities
and
this
"Accounting
Records
for
Virtual
Machine Users" in "Part 2: Control
Program (CP) " is updated to describe
the implementaticn of this support.
The section "Diagnose Instruction in
a Virtual
Machine" in
"Part 2:
Control Program
(CP)" is updated to
expand the function of Diagnose code
X'4C' to include this new support.
Summary of Amendments
for GC20-1807 .. 3
VM/370 Release 2 PLC 11
!~!:
Program Feature
The 3340 Direct Access storage Facility
is now
supported by
VM/370.
This
support includes:
•
•
•
3348 Data Module, Models 35 and 70
Rotational position Sensing
Fixed Head Feature
•
Remote stations and remote
type batch systems.
•
Remote stations
virtual machine.
•
!~:
Batch
The Spooling Functions" section in
"Part 2: Control Program (CP)" has
been updated to include the remote
spooling capabilities of RSCS and the
addition of the spool file tag field
to all output spool files.
•
The
"Diagnose Instruction
in
a
virtual Machine" section in "Part 2:
Control
Program (CP)"
has
been
updated to include a new subfunction
code X'OFFF' to Diagnose code 14.
RSCS uses this new option to retrieve
spool file block and tag data for
files that it is to process for
transmission.
•
The "CMS Batch Facility" section in
"Part
3:
Conversational
Monitor
System (CMS) has been updated to
include remote job entry via RSCS.
•
"Part
5:
Remote
Spooling
Communications SubsJste. CRSeS)" bas
been added to provide the system
programmer with pertinent information
on the new component of VM/370.
The
INPUT
AND
OUTPUT
control
statements for the DASD Dump Restore
Program,
described in
"Part
2:
Control Program (CP)," are changed.
Documentation Only
VM/370
support
for the
IBM
3767
Communications Terminal (at 300bps) as
an IBM 2741 Communications Terminal is
reflected in an update to "Figure 12. CP
Device
Classes, Types,
Models
and
Fea tures".
CMS
•
CP Device
Classes,
"Figure 12.
Types,
Models and
Features"
is
updated.
!~:
a
The addition of this new component is
reflected in the following changes and
additions to this publication:
This device support is reflected in the
following changes to this publication:
•
and
HASP/ASP
Program Feature
The
Remote
Spooling
Communications
Subsystem (RSCS) has been included as a
component of the VM/370 system. Together
with the Control Program (CP) of VM/370,
it manages telecommunication I/O devices
and lines used to automatically transfer
files between:
•
VM/370 users and remote stations.
•
Remote stations
stations.
•
VM/370 users and remote HASP/ASP type
batch systems.
and
other
remote
!§!: Program Feature
CMS now supports the reading of DOS
files as well as OS data sets. This
support is described in the "OS Data
Management Simulation" section of "Part
3: Conversational Monitor System (CMS) ".
The "VM/370: Restrictions" section in
"Part 1: Debugging
with VM/370" is
updated
to remove
the
restriction
against reading DOS files.
Be!: Program Feature
£A~~E~g:
Programs such as DOs/Vs, Vs1 and Vs2
that use
block multiplexer
channel
operations can now be run under VM/370
in virtual block multiplexer mode. The
.ode of operation for all channels,
except channel 0 and any channel to
which
a
channel-to-channel
Adapter
(CTCA) is attached, is selectable via a
DIRECTORY option or the DEFINE Command.
This new feature is described under
"Functional Information" in "Part 2:
Control Program (CP)".
Documentation Only
Information on planning considerations
and generation of the 3704/3705 control
program, formerly in "Part 4: IBM 3704
and 3705 Communications Controllers" has
been moved to the !ML37Q: Pl~nni~E and
§~§!~! Ge~~£~tio~ Gu!g~.
The information about generating and
testing the standalone
program that
controls the 2780 formerly in "Part 5:
IBM 2780 Data Transmission Terminal" has
been moved to the !~Ll1Q: PI~~ni~g and
~I§!~~ Gene~!io~ 2~!~~.
]~!~!~~~~£~:
Program and Documentation
Two new ABEND codes, PGT008 and PRG019,
have been added to "Figure 10. CP ABEND
Codes". Many other changes, to numerous
to detail, have also been included in
this publication.
Summary of A.endments
for GC20-1807-2
as updated by TNL GN20-2643
VM/370 Release 2 PLC 4
IBM 3704/3705 COftftUNICATIONS CONTROLLERS
NETWORK
CONTROL
PROGRAM
(NCP)
AND
PARTITIONED EMULATION PROGR1~ ,IDVD\
......... I
•
The considerations for the use of the
ftultiple
Terminal
Access
(MTA)
feature with a PEP control program
are updated
in Step
4 of
the
"Generating and Loading the 3704/3705
Control Program" section.
•
The "Special Considerations for the
stage 1 Assellbly" section of "Step 6.
The stage 1 Generation Procedure" is
updated.
this
•
•
The Preface is updated.
•
A new CP ABEID code, NLDOOi, ~~ added
to "Figure 10. CP ABEND Codes" in
"Part 1: Debugging with Vft/370".
A
new
section,
"Special
Considerations for Loading the EP
3704/3705 Control Program", is added
to step 10 of the "Generating and
Loading
the
3704/3705
Control
Program" section.
•
A new step, "step 11. Logging On
Through the 3704/3705", is added to
the "Generating
and Loading
the
3704/3705 Control Program" section.
•
The "Testing the 3704/3705 Control
Program" section is updated to add
information about using the NETWORK
cOllmand.
VM/370 now supports all three of
3704/3705 control programs:
•
•
•
the
Emulation Program (EP)
Network Control Program (NCP)
Partitioned Emulation program (PEP)
The following
support:
changes
reflect
The following changes to "Part 4: IBM
3704
and
3705
Communications
Controllers" also reflect this support:
•
A new section, "VM/370 Support of the
3704/3705" is added to the "Planning
Considerations" section.
This new
section describes the extent to which
Vft/370 supports the three 3704/3705
control programs.
•
The NAMENCP macro is updated in the
"Planning Considerations" section.
MISCELLANEOUS
•
The required options for the SYSCNTRL
macro are updated in Step 4 of the
"Generating and Loading the 3704/3705
Control Program" section.
£h!ng~~:
Documentation only
A new section "CMS Interface for Display
Terminals", is included in "Part 3:
Conversational Monitor System (CftS)."
The index is corrected.
Summary of Amendments
for GC20-1807-2
VM/370 Release 2 PLC 1
!~~:
program Feature
The following
supported:
IBM
~~!:
devices
are
now
•
IBM 3330 Disk storage, Model 11
•
IBM 3333 Disk
Model 11
•
IBM 3420 Magnetic
4, 6, and 8
•
IBM 3272 Control unit, Model 2 (local
attachment)
Storage and
Program Feature
A new section, "storage Protection," in
"Part
2:
Control
Program
~P),"
describes both store and fetch storage
protection.
Control,
Tape Units, Models
!~!:
•
IBM 3277 Display station,
(local attachment)
Model
•
IBM 3066 System Console, Model 2
2
This device support caused the following
changes to this pUblication:
Program Feature
The virtual machine assist feature is a
combination of a CPU feature and VM/370
programming
which
improves
the
performance of VM/370.
The discussion,
"virtual Machine Assist Feature," in the
"preferred Machines" section of "Part 2:
Control Program (CP)," describes this
feature.
•
CP Device
Classes,
"Figure 11.
Types,
Models and
Features"
is
updated.
Changes for this feature appear in "Part
1:
Debugging with
VM/370" in
the
descriptions
of
the
following
CP
commands:
•
The SET command described in "Part 1:
Debugging
with
VM/370"
contains
support for the 3270 program function
•
•
•
1r,.. ... ~
1\.<:;;1~·
•
The
INPUT
AND • OUTPUT
control
statements for the DASD Dump Restore
program,
described in
"Part
2:
Control Program (CP)," are changed.
•
The "DIAGNOSE Code 58 -- 3270 virtual
Console Interface" section of "Part
2: Control Program (CP)" describes
the DIAGNOSE interface for a 3270.
•
ADSTOP
SET
TRACE
QUERY
The "Program States" section of "Part 2:
Control Program (CP) " is also updated.
!~!:
Program Feature
All virtual machines that issue an SVC
76 to record errors signal VM/370 to do
the recording for them.
SVC 76 support
caused changes to
"Part 2: Control
Program {CP)II in
!~!:
Program Feature
A
new section,
"OS/VS2 Release
2
Uniprocessor under VM/370," in "Part 2:
Control Program (CP)," describes this
support.
•
The "svc Interrupts" section
•
"Figure 20. SVC Interrupt Handling"
New:
considerations,
guidelines
for
generating and loading the 3704/3705
control program, and a description of
the co.mands used for testing the
3704/3705 control prograll.
Program Feature
All terminal input and output (not just
the input and output from the virtual
machine
operating
system)
is
now
spooled.
This spooling
change
is
described in the "Spooling Facilities"
section of "Part 2: Control Program
(CP) ."
Ne~:
Documentation Only
Four
CMS
lIacros,
previously
docullented,
are described
in
pUblication:
not
this
•
DMSABI is described
in the "CMS
ABEIDs" section of "Part 1: Debugging
with VM/370."
•
DMSFREE, DMSFRET, and DMSFRES are
described
in the
"Free
Storage
Managellent" section
of "Part
3:
Conversational
Monitor
System
(CMS) ."
!~!:
Program Feature
This publication is updated to describe
the 3704/3705 control program under the
control of VM/370. The changes are:
•
Two new abnormal teraination codes
(BIBOOl and BIB002)
are described in
"Figure 9. CP ABEID Codes."
•
"Figure 11. CP Device Classes, Types,
Models, and Features" is updated.
•
A new DIAGNOSE code is described in
the "DIAGBOSE Code 50 -- Save the
3704/3705
Control
Program
Image
(Privilege Class A, B, or COnly)"
section of "Part 2: Control Prograll
(CP) • "
Program Feature
CMS now supports the reading of OS data
sets. This change is described in the
"OS Macro Siaulation under CMS" section
of "Part
3: Conversational
Monitor
System (CMS)." The restriction list in
"Part 1: Debugging with VM/370" is also
updated
to remove
the
restriction
against reading OS data sets.
!~!:
•
A new chapter, "Part 4: IBM 3704 and
3705
Communications
Controllers,"
contains an introduction, planning
!~!:
Program and Documentation
Programaing changes have caused control
block changes for both CP and CMS. The
changes to the CP control blocks are
described in:
•
The "Virtual and Real Control Block
Status" section of "Part 1: Debugging
with V~/310."
•
"Figure
10.
Relationships."
•
"Figure 11.
CP Device
Classes,
Types, Models, and Features."
The changes to the
are described in:
Control
CMS control
Block
blocks
•
"Figure 15. CMS Control Blocks."
•
"Figure 36. CMS Storage Map."
For CP, the abnormal termination codes
have changed.
"Figure
9. CP ABEND
Codes" reflects the following changes:
•
Codes CFM001, CNSOOl through CNSOOS,
PTR006, QCN001, QCN002 and VATOOl
have been deleted froll CP.
•
Codes PRG016, PRG017, PRG01S, PTR011,
PTR012, RNB001, and RNB002 have been
added to CP.
For CP, the internal trace table now
traces machine checks, entry to the
scheduler, and the
unstacking of
IOBLOKs and TRQBLOKs.
"Figure S. CP
Trace Table Entries" reflects these
changes.
!~!:
Program and Documentation
Attention handling has been revised.
Not all
terminals have
"attention"
keys.
The
number
of
attention
interrupts required depends on command
settings and the environment of the
virtual
machine.
Consequently,
the
phrase
"signal attention"
is
used
instead of "press the attention key
[onceltwice]."
~hgng~g:
•
The VDUMP command has been
the VMFDUMP command.
•
The description of the PAGING operand
of the QUERY command contains more
detailed information.
~!lg!!g~§
(£~) ":
~h~ng~~:
~!~n~~~:
1Q
iifgrt
~:
£ont~QJ:
renamed
fIQgIg!
•
The description
of the
PRIORITY
operand of the SET command described
in the "Preferred Machines" section
contains more detailed information.
•
The KINIDASD command is no longer
supported. The IBCDASDI Virtual Disk
Initialization
program
replaces
MINIDASD.
•
The Set Page Boundary (SPB)
card is
no longer required for every page
boundary in the loadlist. See the
"CP Loadlist Requirements" section.
•
A new section, "Removing Optional
support from the CP Nucleus," has
been added.
•
~Pigure 37. CMS Command (and Request)
Processing" has
been redrawn
to
include more detail.
•
The "BATEXIT2: Processing the Batch
Facility /JOB Control Card" section
contains additional information.
Program and Documentation
Several CP commands
have additional
operands and features.
The commands
(DCP, DISPLAY, DMCP,
and DUMP)
are
described in "Part 1: Debugging with
VK/370."
Also, "Figure 6. Summary of
VK/370 Debugging Tools" is updated to
reflect the command changes.
Program and Documentation
Documentation Only
Information about the Assembler virtual
storage
requirements
and
overlay
structures has been added to "Part 3:
Conversational Monitor System
(CMS) ."
This information was in the VKL37Q:
~Q!!Ang 19n9yg~ §y~g~ !Q~ §~~~~gl Q~~§
previously.
The information about generating and
testing the standalone
program that
controls the 2780 has been moved from
the
.!~L11Q :
f.!gnni!!9
~n~
~I§!~!
Generation Guide to the "Part 5.
IBM
2780-Dati-TraiiSiission Terminal" section
of this publication.
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Contents
PART 1: DEBUGGING WITH VM/370.
• 11
INTRODUCTION TO DEBUGGING • •
•
How To start Debugging • •
• • • •
Does a Problem Exist?
•
Identifying the Problem~
Analyzing the Problem. •
•
How 10 Use VM/370 Facilities to Debug. •
ABEND. • • • • • • • • • •
•
CP ABEND • • • • • • • • • • •
•
CP Termination without a Dump.
•
CMS ABEND • • • • • • • •
•
Virtual Machine ABEND (Other Than
CM S). • • • • • • • • • • •
•
Unexpected Results • • • • • •
•
Unexpected Results in CP • •
•
Unexpected Results in a Virtual
Machine • • • •
•
Loop • • • • • • • •
•
CP Disabled Loop •
•
Virtual Machine Disabled Loop.
•
Virtual Machine Enabled Loop •
•
WAIT • • • • • • •
• ••• •
CP Disabled Wait • • • •
•
CP Enabled Wait • • • • •
•
Virtual Machine Disabled Wait.
•
virtual Machine Enabled Wait •
•
RSCS Virtual Machine Disabled Wait •
RSCS virtual Machine Enabled Wait. •
Summary of VM/370 Debugging Tools • • • •
Comparison of CP and CMS Facilities for
Debugging • • • • • • • • • •
•
13
13
14
16
22
26
26
26
27
28
31
32
32
32
33
33
34
34
35
35
36
36
37
37
38
39
44
Function Statement • • • • • • • • •
PRINT/TYPE Function Statement • • • •
Debugging CP on a Virtual Machine..
CP Internal Trace Table • • • • • • • • •
CP Restrictions. • • • • • • • • • •
Dynamically Modified Channel Programs. •
Minidisk Restrictions. • • • •
•
Timing Dependencies. . . • • • • • . • • Q"7
:7,
CPU Model-Dependent Functions • •
• • 98
Virtual Machine Characteristics.
• • 98
CMS Restrictions • • • • • •
• • 101
Miscellaneous Restrictions • •
• .102
ABEND Dumps. • • • • • • • • •
• • 103
Using the VMFDUMP Command • •
• • 103
How to Print A CP Abend Dump From
Tape. • • • • • • • • •
• .104
Reading CP ABEND Dumps
• .104
Reason for the ABEND
• .105
Collect Information • • •
• .120
Register Usage • • • •
• • 120
Save Area Conventions. •
• • 121
Virtual and Real Control Block Status. 122
VMBLOK •
• • 122
VCHBLOK.
• • 125
VCUBLOK.
• • 125
VDEVBLOK •
• • 126
RCHBLOK.
• .127
RCUBLOK.
• • 128
RDEVBLOK
• • 128
Identifying a Pageable Module.
• • 133
DEBUGGING WITH CMS • • •
CMS Debugging Commands •
DEBUG. • • • • • • •
SVCTRACE
DEBUGGING WITH CPo • • • • •
•
CP Commands Used To Debug in the Virtual
Machine
••••
• • • • •
ADSTOP •
• • • • •
BEGIN. •
•
DISPLAY.
• ••••
DUMP •
• • • • •
• • • • •
SE T. • •
• • • • •
STORE. •
•
SYSTEM •
• • • •
•
TRACE.
•
CP Commands for System Programmers and
System Analysts •
•
DCP. •
•
DMCP • •
•
LOCA'IE •
•
MONITOR.
•
QUERY • •
•
SAVENCP.
•
SAVESYS.
•
STCP • •
•
DASD Dump Restore Program (Standalone
Version). • • • • • • • • • •
•
DDR Control Statements • • • • •
•
I/O Definition Statements • • •
•
INPUT/OUTPUT Control Statement
•
SYSPRINT Control statement • •
•
45
45
46
48
49
54
57
62
65
67
•
•
•
•
•
•
86
86
86
86
87
• • 134
• • 134
• • 135
•
•
• 160
DASD Dump Restore Service Program and
How To Use It • • • • • • • • • • • • • 164
Invoking DDR under CMS • • • • • • • • 164
Invoking DDR as a Standalone Program • 164
Nucleus Load Map. • • • •
• .165
Load Map. • • • • • • • •
• .165
Reading CM S AEEND Dumps. •
• • 167
Reason for the ABEND.
• .167
Collect Information.
• .171
Register Usage • • • • • • • • • • • • 173
PART 2: CONTROL PROGRAM
72
73
76
79
81
82
83
84
85
88
92
93
93
96
96
96
(CP)
• • 175
VM/370 • • • • • • • • • • •
• .177
Introduction to the VM/370 Control
Program • • • • • • • • • • • • • • • • 177
Virtual Machine Time Management • • • • 178
Virtual Machine Storage Management • • 178
Virtual Machine I/O Management • • • • 180
Spooling Functions
• • • • • • 181
CP Commands. • • • • • •
• • • • 182
PROGRAM STATES
• .183
USING CPU RESOURCES. •
Queue 1 • • •
Queue 2 • • • • • • • •
• • 184
• • 184
• • 184
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
INTERRUPTION HANDLING • • •
Program Interrupt. • • •
Machine Check Interrupt.
SVC Interrupt. • • • • •
External Interrupt • • •
• 186
• 186
.186
• 186
.187
FUNCTIONAL INFORMATION. • • • •
.188
Performance Guidelines •
.200
General Information. • • • • •
.200
Virtual Machine I/O. •
• • • • • 201
Paging Considerations.
.202
Preferred virtual Machines • • • • • .204
The Virtual Block Multiplexer Channel
Option • • • • • • • • • • • • • • • • 210
PERFORMANCE OBSERVATION AND ANALYSIS .210.1
Load Indicators • • • • • • • • • • • • 210.1
The Indicate Command • • • • • • • • 210.1
The Class G INDICATE Command •
.210.2
The Class E INDICATE Command • • • • 210.4
The MONITOR Command. • •
• • • • 210.8
Implemented Classes. •
• 210.12
VM Monitor Response to Unusual
Tape Conditions. • •
• • • 210.14
VM Monitor Considerations.
210.14
VM Monitor Data Volume and
Overhead. • • • • • • • .. •
210.15
Load Environments of VM/370.
210.16
ACCOUNTIN G RECORDS
•••••
Accounting Records for Virtual Machine
Users • • .. • • •
••• • • • • •
Accounting Records for Dedicated
Devices • • • • •
•••••
User Formatted Accounting Records.
Operational Notes. • • •
•••• •
User Accounting Options • • • • • •
.211
GENERATING NAMED SYSTEMS • • • • •
Configuring the NAMESYS Macro (Module
DMK SN T) • • • • • • • • • • • • •
Using the SAVESYS Command . . . . . . . . . ..
Determining When To Save a System • •
Special Considerations for Shared
Segments. • • • •
• • • •
Saving OS. • • • • • •
• •••
.214
VM/VS HANDSHAKING • • • •
Closing CP Spool Files •
Pseudo Page Faults • • • • •
VS 1 Nonpaging Mode • • •
Miscellaneous Enhancements
.211
.211
.212
.212
.213
.214
.215
.216
.216
.216
• .218.1
• .218.2
• • • 218.2
• .218.2
• .218.3
S pooling Consider ations. . • • • • • .225
An Example of VM/370 Running under
VM/370. • • • • • • • • • •
• .225
TIMERS IN A VIRTUAL MACHINE.
Interval Timer • •
CPU Timer • • • • •
TOD Clock. • • • • • • •
Clock Comparator • • • • •
Pseudo Timer • • • • • • •
Pseudo Timer Start I/O
Pseudo Timer DIAGNOSE. •
• .236
• • • • 236
• .236
• .237
• .237
• .237
• .238
• .238
DIAGNOSE INSTRUCTION IN A VIRTUAL
MACHINE. • • • • • • • • • • •
• .239
DIAGNOSE Code 0 -- Store
Extended-Identification Code..
• .239
DIAGNOSE Code 4 -- Examine Real Storage.240
DIAGNOSE Code 8 -- virtual Console
Function • • • • • • • • • • • • • • • • 240
DIAGNOSE Code C -- Pseudo Timer • • • • 240.1
DIAGNOSE Code 10 -- Release Pages • • • 240.1
DIAGNOSE Code 14 -- Input Spool File
Manipulation • • • • • • • • • • • • • 240.2
DIAGNOSE Code 18
Standard DASD I/O • • 241
DIAGNOSE Code lC
Clear I/O Recording.242
DIAGNOSE Code 20
General I/O. • •
.242
DIAGNOSE Code 24
Device Type and
Features • • • •
• .243
DIAGNOSE Code 28 -- Channel Program
Modification. •
• .244
DIAGNOSE Code 2C -- Return DASD Start
of LOGREC • • •
• .245
DIAGNOSE Code 30 -- Read One Page of
LOGREC Data • • • • • • • • • • • • • • 245
DIAGNOSE Code 34 -- Read System Dump
spool File • • • • • • • • • • • • • • • 245
DIAGNOSE Code 38 -- Read System Symbol
Table • • • • • • • • • • • • • • • • • 246
DIAGNOSE Code 3C -- VM/370 Directory • • 246
DIAGNOSE Code 4C -- Generate Accounting
Cards for the Virtual User • • • • • • • 246
DIAGNOSE Code 50 -- Save the 3704/3705
Control Program Image. • •
• .247
DIAGNOSE Code 58 -- 3270 Virtual
Console Interface. • • • • • •
• .247
DIAGNOSE Code 5C: Error Message Editing.248
CP CONVENTIONS • • • • • •
CP Coding Conventions. • •
CP Loadlist Requirements
• • • • 249
• .249
• .251
HOW TO ADD A CONSOLE FUNCTION TO CPo • • 253
OS/VS2 RELEASE 2 UNIPROCESSOR UNDER
VM/370. • • • •
• • • • .219
DOS UNDER VM/370
System Generation. • • • • •
Standard Label Cylinder.
System Residence • • • • •
• 220
.220
.220
.220
VM/370 OPERATING IN A VIRTUAL MACHINE
ENVIRONMENT • • • • • • • • • • • • • • 221
VM/370 Directory Definition. • • • • • .221
Virtual Machine Configuration • • • • • • 222
virtual System Residence Considerations.222
Virtual IPL and Operation. • •
.223
Accessing Devices. • • • • • • • • • .224
PRINT BUFFERS AND FORMS CONTROL • • •
Adding New Print Buffer Images •
ues Buffer Images • • • • • • •
USCB Buffer Images • •
• • • •
Forms Control Buffer •
•
•
•
•
•
.254
.255
.255
.257
.260
PART 3: CONVERSATIONAL MONITOR SYSTEM
(CM S) • • • • • • • •
• .263
INTRODUCTION TO CMS • • •
The CMS Command Language •
The File System • • • •
Program Development • • • •
•
•
•
•
.265
.265
.266
.268
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
INTERRUPT HANDLING IN CMS.
SVC Interruptions • • • • • • •
Internal Linkage SVCs. • •
at her SVCs • • •
Input/Output Interruptions
Terminal Interruptions • •
Reader/Punch/Frinter Interruptions
User Controlled Device Interruptions •
Program Interruptions • • • • • • • • •
External Interruptions • • • •
Machine Check Interruptions • • • • • •
FUNCTIONAL INFORMATION •
Register Usage • • • • •
structure of DMSNUC. .
USERSECT (User Area)
DEVTAB (Device Table) • • •
structure of CMS Storage •
Free Storage Management • •
GETMAIN Free Storage Management.
DMSFREE Free storage Management.
Releasing Allocated storage. • •
DMSFREE Service Routines • • • •
Error Codes from DMSFRES, DMSFREE,
and DMSFRET • • • • • • •
CMS Handling of PSW Keys • • • • • •
CMS SVC Handling • • • • • • • • • •
SVC Types and Linkage Conventions • •
Search Hierarchy for SVC 202 • •
User and Transient Program Areas • •
Called Routine Start-up Table. • • •
Returning to the Calling Routine • •
CMS Interface for Display Terminals • •
.269
.269
.269
.269
.270
.271
~271
.271
• 271
.272
• 272
.273
.273
.273
.274
.274
.275
.278
.278
.279
.284
.284
.286
.287
.288
.288
.290
.291
.294
.295
.297
HOW TO ADD A COMMAND OR EXEC PROCEDURE
TO CMS.
• • • • • • • • •
.299
OS MACRO SIMULATION UNDER CMS • • •
OS Data Management Simulation. •
Handling Files that Reside on CMS
Disks • • • • • • • • • •
Handling Files that Reside on 05 or
DOS Disks • • • • • •
Simulation Notes • • • •
Access Method support • •
Reading OS Data Sets and DOS Files •
The FILEDEF Command.
.300
.300
SAVING THE CMS SYSTEM • • •
Saved System Restrictions for CMS.
.312
.312
.300
.301
.303
.307
.309
.311
CMS BATCH FACILITY. • • • • • • •
.313
Resetting Batch Facility System Limits .313
Writing Routines To Handle Special
Installation Input • • • • • • • • • • • 313
BATEXIT1: Processing User-Specified
Control Language • • • • • • • • • • • 314
BATEXIT2: Processing the Batch
Facility /JOB Control Card • • • • • • 314
EXEC Procedures for the Batch Facility
Virtual Machine • • • • • • • • • • • • 314
Data Security under the Batch Facility .315
IPL Performance Using a Saved System • • 315
AUXILIARY DIRECTORIES • • • • • • • • • • 316
How To Add an Auxiliary Directory • • • • 316
Generation of the Auxiliary Directory.316
Initializing the Auxiliary Directory .316
Establishing the Proper Linkage • • • • 317
An Example of Creating an Auxiliary
Directory • • • • • • • • • • • • • • • 318
ASSEMBLER VIRTUAL STORAGE REQUIREMENTS
Overlay structures • • • •
•
Prestructured Overlay. •
•
Dynamic Load Overlay • • •
•
.320
.320
.320
.322
PART 4: IBM 3704 AND 3705
COMMUNICATIONS CONTROLLERS.
.323
INTRODUCTION TO THE IBM 3704 and 3705
COMMUNICATIONS CONTROLLERS.
• .325
VM/370 support of the 3704 and 3705 • • • 325
Emulation Program (EP) with VMj370 • .326
Network Control Program (NCP) with
VM/370 • • • • • • • • • • • • • • • • 326
Partitioned Emulation Program (PEP)
with VM/370 • • • • • • • • •
• .327
Generating a VM/370 System that
Supports the 3704 and 3705 • • • • • • • 327
LOADING THE 3704/3705 CONTROL PROGRAM • • 328
Save the 3704/3705 Control Program
Image on Disk • • • • • • • • • • • • • 328
The SAVENCP Command • • • • • • • • • • 328
Execution of the SAVENCP Program • • • 329
Load the 3704/3705 Control Program • • • 330
The NETWORK LOAD Command Line • • • • • 330
Execution of the NETWORK LOAD Command.330
Special Considerations for Loading
the EP 3704/3705 Control Program • • • 331
special considerations for Loading
the NCP and PEP 3704/3705 Control
Programs. • • • • • • • • • •
• .331
Logging on Through the 3704/3705 • • • • 332
Turn the Power On • • • • • • • • • • • 332
Check for an Online Message • • • • • • 332
Follow the special Sign-on Procedures
for 3704/3705 Lines that Are in NCP
Mode and also Have the MTA Feature • • 333
Logging on After an NCP Control
Program Has Abnormally Terminated • • 334
Applying PTFs to the 3704/3705 Load
Library. • • • • • • • • • • •
• .334
The ZAP Service Program. • •
• .334
ZAP Input Control Records • • • • • • • 336
Special Considerations For Using
The ZAP Service Program • • • • • • 336.6
TESTING THE 3704/3705 CONTROL PROGRAM.
NETWORK. • • • • • • • • • • • • •
Bow to Use the NETWORK Com.and •
NCPDUMP Service Program and How to Use
It. • • • • • • • • • • • • • •
•
Using the NCPDUMP Command. • • •
.337
.337
.337
.345
.345
PART 5: REMOTE SPOOLING COMMUNICATIONS
• .347
SUBSYSTEM (RSCS). • •
INTRODUCTION TO RSCS
Locations And Links • •
Remote Stations • • •
VM/370 Spool System Interface • •
RSCS Command Language • • • • • •
•
•
•
•
•
.349
.349
.349
.350
.350
STRUCTURE OF RSCS VIRTUAL STORAGE • • • • 352
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
RSCS Supervisor • • • • • • • • • • • •
su perv isor Queue Extension • • • • • •
Free Storage • • • • • • • • • • • • •
System Control Task. • • •
••• •
Free Storage and Line Drivers • •
Line Allocation Task • • •
Spool File Access Task • • • • • • • •
• 353
.353
• 353
.354
.354
.354
.354
FUNCTIONAL INFORMATION • • • •
Virtual Storage Management
Page Allocation. • • • • • •
Queue Element Management
File Management. • • • • • • •
Tag slot Queues • • • • • • •
Spool File Access. • • •
Task-to-Task Communication • •
RSCS Command processing.
RSCS Message Handling • •
Interruption Handling. • • • •
External Interruptions
SVC Interruptions.
I/O Interruptions. • •
.355
.355
.355
• 355
• 356
.356
.356
.357
.357
.358
.358
.358
.358
.359
LeGGING I/O ACTIVITY •
• .360
AFPENDIX A: SYSTEM/370 INFORMATION • . . 363
Control Registers. • • • •
• .363
APPENDIX B: MULTILEAVING
MULTI-LEAVING in VM/370. •
MULTI-LEAVING Philosophy • •
MULTI-LEAVING Control specification.
Record Control Byte (RCB). • •
Sub-Record Control Byte (SRCB) • •
String Control Byte (SeB). • • • •
Block Control Byte (BCB) • • • • •
Function Control Sequence (FCS). •
•
•
•
•
•
•
•
•
•
AFPENDIX C: VM MONITOR TAPE FORMAT
AND CONTENT • • • • • • •
Header Record. •
Data Records •
.374.1
.374.1
.374.2
INDEX. • • •
• .377
.367
.367
.367
.369
.370
.371
.373
.373
.374
FIGURES
Figure
Figure
Figure
Figure
1.
2.
3.
4.
Figure
5.
Figure
6.
Figure
7.
Figure
8.
Figure 9.
Figure 10.
Figure 11.
Figure 12.
Figure 13.
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
14.
15.
16.
17.
18.
19.
20.
21.
22.
ABEND Messages ••••••••••••••• 14
VM/370 Problem Types ••••••••• 18
Does a Problem Exist?====~==23
Debug Procedures for Waits
and Loops •••••••••••••••••••• 24
Debug Procedures for
Unexpected Results and an
ABEND •••••••••••••••••••••••• 25
Summary of VM/370 Debugging
Tools •••••••••••••••••••••••• 39
Comparison of CP and CMS
Facilities for Debugging ••••• 44
Annotated Sample of Output
from the TYPE and PRINT
Functions of the DDR
Program •••••••••••••••••••••• 92
CP Trace Table Entries ••••••• 95
CP ABEND Codes •••••••••••••• 106
CP Control Block
Relationships ••••••••••••••• 124
CP Device Classes, Types,
Models, and Features •••••••• 131
Summary of SVC Trace Output
Lines ••••••••••••••••••••••• 163
Sample CMS Load Map ••••••••• 166
CMS Control Blocks=~e.e= •••• 168
CMS ABEND Codes ••••••••••••• 169
CP Initialization ••••••••••• 189
Real I/O Control Blocks ••••• 190
Virtual I/O Control Blocks •• 191
SVC Interrupt Handling •••••• 192
External Interrupt Handling.193
Program Interrupt Handling •• 194
Figure
Figure
Figure
Figure
Figure
23.
24.
25.
26.
27.
Figure 28.
Figure 29.
Figure 30.
Figure 31.
Figure 32.
Figure 33.
Figure 34.
Figure 35.
Figure 36.
Figure 37.
Figure
Figure
Figure
Figure
Figure
38.
39.
40.
41.
42.
Figure 43.
Figure 44.
Paging •••••••••••••••••••••• 195
Virtual Spooling •••••••••••• 196
Real Spooling ••••••••••••••• 197
Virtual Tracing ••••••••••••• 198
Virtual-to-Real Address
Translation ••••••••••••••••• 199
storage in a Virtual=Real
Machine ••••••••••••••••••••• 207
Formats of Pseudo Timer
Information ••••••••••••••••• 237
UCSB Associative Field
Chart ••••••••••••••••••••••• 258
eMS File System ••••••••••••• 267
Devices Supported by a CMS
Virtual Machine ••••••••••••• 275
CMS Storage Map ••••••••••••• 277
CMS Command (and Reques~
processing ••••••••••••••••• 293
PSW Fields When Called
Routine Starts •••••••••••••• 294
Register Contents When
Called Routine Starts ••••••• 294
Simulated OS Supervisor
Calls ••••••••••••••••••••••• 302
An Overlay Structure •••••••• 321
RSCS Command Summary •••••••• 351
RSCS Storage Allocation ••••• 352
Control Register Allocation.363
Control Register
Assignments ••••••••••••••••• 364
The Extended Control PSW
(Program status Word) ••••••• 365
A Typical MULTI-LEAVING
Transmission Block •••••••••• 368
Part 1: Debugging with Vr-ll./370
This debugging section contains the
followi~g
information:
•
•
How to star~ debugging
How to use VM/370 facilities to debug
results, loops, and waits
summary of VM/370 debugging too~s
comparison of CP and eMS debugging tools
•
•
•
•
•
•
•
•
Debugging CP on a virtual machine
Commands useful in debugging
DASD Dump Restore program
Internal trace table
Restrictions
ABEND dumps
Reading CP ABEND dumps
Control block summary
•
•
•
•
•
Debugging commands
DASD Dump Restore Program
Nucleus load map
Reading CMS ABEND dumps
Control block summary
•
•
ABE8Ds,
unexpected
Part 1: Debugging with VM/370
11
Introduction to Debugging
The Vft/310 Control Program manages the resources of a single computer
such that multiple computing systems appear to exist.
Each "virtual
computing system," or virtual machine, is the functional equivalent of
an IBft System/310. Therefore, the person trying to determine the cause
of a Vft/310 software problem must consider three separate areas:
1.
The Control Program
machine.
(CP) which controls the resources
2.
The virtual machine operating system running under
CP, such as CftS, RSCS, OS, or DOS.
3.
The problem program, which executes under
machine operating system.
of the real
the control of
the control of a virtual
Once the area causing the problem is identified, the appropriate
person should take all available information and dete.rmine the cause of
the problem.
ftost likely, the IBft Pield Engineering program systems
Representative or system programmer handles all problems with CP, CftS,
and RSCS; information that is helpful in debugging CP and CftS is
contained in this publication. The application programmer handles all
problem program errors; techniques for application program debugging are
found in the !~L1IQ: ~Q!.a~~ La~~y~~ ~yig~ fo~ ~~~~~al Us~!§.
If the problem is caused by a virtual machine operating system (other
than CftS and RSCS), refer to the publications pertaining to that
operating system for specific information. However, use the CP debugging
facilities, such as the CP commands, to perform the recommended
debugging procedures discussed in that other publication. The IBft Pield
Engineering Program systems Representative or system programmer most
likely handles problems with virtual machine operating systems.
If it becomes necessary to apply a PTP (Program Temporary
component of Vft/310, refer to the !ALllQ: PI~~i~~ ~!~ ~yste~
iY!~§ for detailed information on applying PTFs.
Fix) to a
Gen~~!i~!
Before you can correct any problem, you must recognize that one exists.
Next, you must identify the problem, collect information and determine
the cause so that the problem can be fixed. When running Vft/310, you
must also decide whether the problem is in CP, the virtual machine, or
the problem program.
A good approach to debugging is:
1.
Recognize that a problem exists.
2.
Identify the problem type and the area affected.
3.
Analyze the data you have available, collect more data if you need
it, then isolate the data that pertains to your problem.
4.
Pinally, determine the cause of the problem and correct it.
Part 1: Debugging with Vft/310
13
DOES A PROBLEM EXIST?
There are four types of problems:
1.
2.
3.
4.
Loop
wait state
ABEND (Abnormal End)
Incorrect results
The most obvious indication of a problem is the abnormal termination
of a program. Whenever a program abnormally terminates, a message is
issued. Figure 1 lists the possible ABEND messages and identifies the
type of ABEND for these messages.
Message
(Alarm rings)
DMKDMP9081 SYSTEM FAILURE CODE xxxxxx
CP ABEND, system dumps to
disk. Restart is automatic.
DMKDMP90SW SYSTEM DUMP FAILURE;
PROGRAM CHECK
DMKDMP906W SYSTEM FAILURE; MACHINE
CHECK, RUN SEREP
DMKDMP907W SYSTEM DUMP FAILURE; FATAL
I/O ERROR
If the dump program encounters a program check, machine check or fatal I/O
error, a message is issued
indicating the error. CP
enters the wait state with
code 3 in the PSW.
DMKCKP900W SYSTEM RECOVERY FAILURE;
PROGRAM CHECK
DMKCKP901W SYSTEM RECOVERY FAILURE;
MACHINE CHECK, RUN SEREP
DMKCKP902W SYSTEM RECOVERY FAILURE;
FATAL I/O ERROR - NUCL CYL
- WARM CYL
DMKCKP904W SYSTEM RECOVERY FAILURE;
INVALID WARM START DATA
DMKCKP910W SYSTEM RECOVERY FAILURE;
INVALID WARM START CYLINDER
DMKCKP911W SYSTEM RECOVERY FAILURE;
WARM START AREA FULL
If the checkpoint program
encounters a program check,
a machine check, a fatal I/O
error or an error relating
to a certain warm start
cylinder or warm start data
conditions, a message is
issued indicating the error
and CP enters the wait state
with code 7 in the PSW.
DMKWRM902W SYSTEM RECOVERY FAILURE;
FATAL I/O ERROR
DMKWRM903W SYSTEM RECOVERY FAILURE;
VOLID xxxxx ALLOCATION ERROR
CYLINDER xxx
DMKWRM904W SYSTEM RECOVERY FAILURE;
INVALID WARM START DATA
DMKWRM909W SYSTEM RECOVERY FAILURE;
VOLID xxxxxx NOT MOUNTED
If the warm start program
encounters a severe error, a
message is issued indicating
the error and CP enters the
wait state with code 9
in the PSW.
Figure
14
Type of ABEND
1.
ABEND Messages (Part 1 of 3)
IBM VM/370: System Programmer's Guide
r--------------------------------------------------------------·----------~
Message
Type of ABEND
DMKDMP9081 SYSTEM FAILURE, CODE xxxxxx ICP ABEND, system dumps to
DMKCKP960! SYSTEM WARM START DATA SAVED' tape or printer. The system
DMKCKP961W SYSTEM SHUTDOWN COMPLETE
stops; the operator must IPL
the system to start again.
DMKDMP905W SYSTEM DUMP
PROGRAM CHECK
DMKDMP906W SYSTEM DUMP
MACHINE CHECK, RUN
DMKDMP907W SYSTEM DUMP
I/O ERROR
FAILURE;
If the dump program encounters a program check, a machine check or fatal I/O
error, a message is issued
indicating the error. CP
enters the wait state with
code 3 in th~ PSi.
FAILURE;
SEREP
FAILURE; FATAL
If the dump cannot find a
defined dump device and if
no printer is defined for
the dump, CP enters a disabled wait state with code 4
in the PSW.
CP termination with automatic
restart.
DMKMCH6101 MACHINE CHECK SUPERVISOR
DAMAGE
The machine check handler encountered a nonrecoverable
error with the VM/370 control program.
DMKMCH6111 MACHINE CHECK SYSTEM
INTEGRITY LOST
The machine check handler encountered an error that can-I
not be diagnosed; system
I
integrity, at this point,
I
is not reliable.
I
L-_____________________________________________________________________________
~I
Figure
1.
ABEND Messages (Part 2 of 3)
Part 1: Debugging with VM/370
15
Type of ABEND
CP ter.ination without automatic restart.
DMKCCH603W CHANNEL ERROR, RUB SEREP,
RESTART SYSTEM
There was a channel check
condition from which the
channel check handler could
not recover. CP enters the
wait state with code 2 in
the PSW.
DMKCPI955W INSUPPICIENT STORAG! FOR
The generated system requires
more real storage than is
available. CP enters the
disabled wait state with
code OOD in the PSW.
'M/370
DMSABN148T SYSTEM ABEND xxx
CALLED PRO" xxxxxx
IC"S ABEND, system will accept
I commands from the terminal.
I Enter the DEBUG command and
I then the DUMP subcommand to
I have C"S dump storage on the
I printer.
others
Refer to OS and DOS publication
for the abnormal termination
messages.
IWhen OS or DOS abnormally
I terminates on a virtual
I machine, the messages issued
I and the dumps taken are the
I same as they would be if OS
I or DOS abnormally terminated
I on a real machine.
Figure
1.
ABEND "essages (Part 3 of 3)
Another obvious indication of a problem is unexpected output. If your
output is missing, incorrect, or in a different format than expected,
some problem exists.
Unproductive processing time is another symptom of a problem. This
problem is not as easily recognized, especially in a time sharing
environment.
IDENTIFYING THE PROBLE"
Two types of problems are easily identified: abnormal termination is
indicated by an error message, and unexpected results become aFparent
once the output is examined. The looping and wait state conditions are
not as easily identified.
When using V"1370, you are normally sitting at a terminal and do not
have the lights of the CPU control panel to help you. You may have a
looping condition if your program takes longer to execute than you
anticipated. Also, check your output. If the number of output records or
print lines is greater than expected, the output may really be the same
information repeated many times. Repetitive output usually indicates a
program loop.
16
IBM '"1370: System Programmer's Guide
Another way to identify a loop is to periodically examine the current
PSW. If the PSW instruction address always has the same value, or if the
instruction address has a series of repeating values, the program
probably is looping.
The wait state is also difficult to recognize when at the terminal.
Again, the console lights are unavailable. If your program is taking
longer than expected to execute, the virtual machine may be in a wait
state. Display the current PSW on the terminal. periodically, issue the
CP command
QUERY TIME
and compare the elapsed processing time. When the elapsed processing
time does not increase, the wait state probably exists.
Figure 2 helps you to identify problem types and the areas where they
aay occur.
Part 1: Debugging with V8/370
17
~.-----------------------------------------------------------------------,
IProbleml
Where
I
I Type IABBND Occurs I
Distinguishing Characteristics
1-----------------------------------------------------------------------The alarm rings and the message
ABBND
CP ABBND
DMKDMP9081 SYSTBM FAILURB, CODE xxx xxx
appears on the CPU console. In this instance,
the system dump device is a disk, so the system
dumps to disk and automatically restarts. If
an error occurs in the dump, checkpoint, or
warmstart program, CP enters the wait state
after issuing one or more of the following
messages:
DMKDMP905W SYSTEM DUMP FAILURE; PROGRAM CHECK
DMKDMP906W SYSTEM DUMP FAILURE; MACHINE CHECK,
RUN SERBP
DMKDMP907W SYSTEM DUMP FAILURE; FATAL I/O ERROR
DMKCKP900W SYSTBM RBCOVERY FAILURE; PROGRAM
CHECK
DMKCKP901W SYSTBM RECOVERY FAILURE; MACHINE
CHECK, RUN SEREP
DMKCKP902W SYSTEM RECOVERY FAILURE; FATAL I/O
ERROR
DMKCKP904W SYSTEM RECOVERY FAILURE;
INVALID WARM START DATA
DMKCKP910W SYSTEM RECOVERY FAILURE;
INVALID WARM START CYLINDER
DMKCKP911W SYSTEM RECOVERY FAILURE;
WARM START AREA FULL
DMKWRM902W SYSTEM RECOVERY FAILURE; FATAL I/O
ERROR
DMKWRM903W SYSTEM RECOVERY FAILURE;
VOLID xxxxxx ALLOCATION ERROR
CYLINDER xxx
DMKWRM904W SYSTEM RECOVERY FAILURE; INVALID
WARM START DATA
DMKWRM909W SYSTEM RECOVERY FAILURE; VOLID
xxxxxx NOT MOUNTED
CP ABEND
igure
18
2.
The following messages appears on the CPU console
DMKDMP9081 SYSTEM FAILURE, CODE xxxxxx
DMKDMP9601 SYSTEM WARM START DATA SAVED
DMKDMP961W SYSTEM SHUTDOWN COMPLETE
The system dumps to tape or printer and stops.
The operator must IPL the system to restart. If
an error occurs in the dump or checkpoint programs, CP enters the wait state after issuing
one or more of the following messages:
DMKDMP905W SYSTEM DUMP FAILURE; PROGRAM CHECK
DMKDMP906W SYSTEM DUMP FAILURE; MACHINE CHECK,
RUN SEREP
DMKDMP907W SYSTEM DUMP FAILURE; FATAL I/O ERROR
DMKCKP900W SYSTEM RECOVERY FAILURE; PROGRAM
CHECK
DMKCKP901W SYSTEM RECOVERY FAILURE; MACHINE
CHECK, RUN SEREP
DMKCKP902W SYSTEM RECOVERY FAILURE; FATAL I/O
ERROR
DMKCKP910W SYSTEM RECOVERY FAILURE;
INVALID WARM START CYLINDER
DMKCKP911W SYSTEM RECOVERY FAILURE;
WARM START AREA FULL
VM/370 Problem Types (Part 1 of 5)
IBM VM/370: System Programmer's Guide
Problem
Type
Where
ABEN D Occurs
Distinguishing Characteristics
CP terminationlAn unrecoverable machine check error has
with autoI occurred. One of the following messages:
i
matic start I DMKMCH610I MACHINE CHECK SUPERVISOR DAMAGE
I DMKMCH611I MACHINE CHECK INTEGRITY LOST
I appears on the CPU console. The system is
I automatically restarted.
ABEND
(Cont. )
CP termination IAn unrecoverable channel check error has
without auto-I occurred. The message:
matic restartl DMKCCH603W CHANNEL ERROR, RUN SEREP,
RESTART SYSTEM
I
appears on the CPU console, and CP enters
wait state.
I
IVirtual
I Machine
I ABEND (CM S)
I
I
"I
I
IThe CMS message
I DMSABM148T SYSTEM ABEND xxx CALLED FROM
I
xxxxxx
I appears on the terminal. The system stops
I and waits for a command to be entered on
I the terminal. In order to have a dump
I taken, issue the CMS DEBUG command and then
the DUMP subcommand.
""
When OS or DOS abnormally terminates on a
Virtual
Machine ABEND virtual machine, the messages issued and
the dumps taken are the same as they would
(other than
be if OS or DOS abnormally terminated on a
CMS)
real machine.
VM/370 may terminate or reset a virtual
machine if a nonrecoverable channel check
or machine check occurs in that virtual
machine. One of the following messages:
DMKMCH616I MACHINE CHECK; USER userid
TERMINATED
DMKCCH604I CHANNEL ERROR; DEV xxx; USER
userid; MACHINE RESET
to the system operator at the CPU console.
Also, the virtual user is notified that qis
machine was terminated or reset by one of
following messages:
DMKMCH6191 MACHINE CHECK; OPERATOR
TERMINATED
DMKCCH606I CHANNEL ERROR; OPERATOR
TERMINATED
IIf an operating system, other than CMS,
executes properly on a real machine, but
I not properly with CP, a problem exists.
I Inaccurate data on disk or system files
I (such as spool files) is an error.
Unexpected I CP
Results
I
I
I
I
1-----------------------------------------------------------IIf a program executes properly under the
Iyirtual
I Machine
I
I
I
Figure
2.
V~/370
I
I
I
I
control of a particular operating system
on a real machine, but does not execute
correctly under the same operating system
with VM/370, a problem exists.
Problem Types (Part 2 of 5)
Part 1: Debugging with VM/370
19
Problem
Type
Where
ABEND Occurs
I
Distinguishing Characteristics
1
1
-------------------------------------------------------------------1
wait
Disabled CP
The CPU wait light is on. Also, pressing
I
wait
I
I Enabled CP
1 wait
the REQUEST key on the operator's console, 1
or the equivalent action, leaves the
1
REQUEST PENDING light on. If the message
1
D"K"CB612W "ACHINE CHECK TI"ING FACILITIESI
DAftAGE, RUN SEREP
1
appears on the CPU console, a machine check
(probable hardware error) caused the CP
disabled wait state. If the message
D"KCCB603W CHANNEL ERROR, RUN SEREP,
RESTART SISTE"
appears on the CPU console, a channel check
(probable hardware error) caused the CP
disabled wait state. If the message
D"KCPI955W INSUFFICIENT STORAGE FOR V"/370
appears on the CPU console, the control
program has entered a disabled wait state
with code OOD in the PSW. Either the
generated system is larger than the real
machine size, or a hardware machine malfunction prevents V"/370 from using the
necessary amount of storage. If the message
D"KPAG415E CONTINUOUS PAGING ERRORS FROft
DASD xxx
appears on the CPU console, the control
program (CP) has entered a disabled wait
state with code OOF in the PSW. Consecutive
hardware errors are occurring on one or
more V"/370 paging devices.
IThe CPU console light is on, but the system
I accepts interrupts from I/O devices.
Disabled
IThe V"/370 Control Program does not allow a
virtual
I virtual machine to enter a disabled wait
machine wait I state or certain program loops. Instead, CP
I issues one of the following messages:
I D"KDSP450W CP ENTERED; DISABLED WAIT PSi
I DftKDSP451W CP ENTERED; INVALID PSW
I D"KDSP452W CP ENTERED; EXTERNAL INTERRUPT
I
LOOP
I DftKDSP453W CP ENTERED; PROGRA" INTERRUPT
I
LOOP
Enabled
virtual
machine wait
Figure
20
2.
A PSi enabled fer I/O interrupts is leaded.
Nothing happens if an I/O device fails to
issue an I/O interrupt. If a program is
taking longer to execute than expected,
periodically issue the CP command, QUERY
TlftE. If the processing time remains unchanged, there is probably a virtual
.achine enabled wait.
C"S types a blip character for every 2
seconds of elapsed processing time. If the
program does not end and blip characters
stop typing, an enabled wait state probably
exists.
Vft/370 Problem Types (Part 3 of 5)
IBft V"/370: System Programmer's Guide
Problell
Type
wait
(cant. )
Where
ABEND Occurs
Disabled RSCS
wait
Distinguishing Characteristics
The RSCS operator is notified of the wait
state by CP issuing the message
DMKDSP450W CP ENTERED; DISABLED WAIT PSW
If, in addition, the message
DMTINI402T IPL DEVICE READ I/O ERROR
appears on the RSCS console, an unrecoverable error has occurred while reading the
RSCS nucleus from DASD storage. RSCS
enters a disabled wait state with a code
of 011 in the PSW.
If a program check occurs before the
program check handler is activated, RSCS
enters a disabled wait state with a code of
007 in the PSW.
If a prograll check occurs after the program
check handler is activated, Rses enters a
disabled wait state with a code of 001 in
the PSW. One of the following messages may
also appear on the RSCS console:
DMTREX090T PROGRAM CHECK IN SUPERVISOR
RSCS SHUTDOWN
DMTREX091T INITIALIZATION PAILURE -- RSCS
SHUTDOWN
Loop
Enabled Rses
wait
IRSeS has no task ready for execution. A
I PSW, enabled for external and I/O
I interrupts, is loaded with a wait code of
I all zeroes.
CP disabled
loop
IThe CPU console wait light is off. The
i problem state bit of the real PSi is off.
I No I/O interrupts are accepted.
CP enabled
loop
IThere is no such condition.
I
Virtual
IThe program is taking longer to execute than
machine
I anticipated. Signalling attention from the
disabled loopl terminal does not cause an interrupt in the
I virtual lIachine. The virtual machine opera-I
I tor cannot communicate with the virtual
I
I machine's operating system by signalling
I
I attention.
I,
Pigure
2.
VM/370 Problem Types (Part 4 of 5)
Part 1: Debugging with VM/370
21
Problem
Type
Where
ABEND Occurs
Loop
(cont.)
Distinguishing Characteristics
,Virtual
,Excessive processing time is often an indi, machine
cation of a loop. Use the CP QUERY TIME
, enabled loop
command to check the elapsed processing
time. In CMS, the continued typing of the
blip characters indicates that processing
time is elapsing. If time has elapsed,
I
periodically display the virtual PSW and
check the instruction address. If the same
I
instruction, or series of instructions,
continues to appear in the PSW, a loop
I
probably exists.
,,
,
,
,
Figure
2.
VM/370 Problem Types (Part 5 of 5)
ANALYZING THE PROBLEM
Once the type of problem is identified, the cause of it must be
determined.
There
are recommended procedures to
follow.
These
procedures are helpful, but do not identify the cause of the problem in
every case. Be resourceful. Use whatever data you have available. If
the cause of the problem is not found after the recommended debugging
procedures are followed, it may be necessary to undertake the tedious
job of desk-checking.
The section, "How To Use VM/370 Facilities To Debug," describes
procedures to follow in determining the cause of various problems that
can occur in the Control Program or in the virtual machine.
(See the
!~Lll~:
~2!!2~~ 12~~Q~~~
§~ig~ !2~ §~~~~~! Q§~!§
for information on
using VM/370 facilities to debug a problem program.)
If it becomes necessary to apply a Program Temporary Fix (PTF) to a
VM/370 component, refer to the VMLl1Q: ~la~~ing ~!g EY2i~~ Generation
§~ig~ for detailed information on applying PTFs.
Figure 3, Figure-4;
and Figure 5 summarize the debugging process from identifying the
problem to finding the cause.
22
IBM VM/370: System Programmer's Guide
r- Is there an ABEND condition? - - - - - -..
II
t
If the message
DMKDMP9081 SYSTEM FAILURE, CODE XXX XXX
aPP6ar:; vii the CCr1i50:6 iiild
the alarm rings,
this is a CP ABEND.
The system dumps to disk
and automatically
~
performs IPL.
•
Is there a wait or Loop? _ _ _ _ _ _ _ _ _..
a
~
II
If the messages
DMKDMP9081 SYSTEM FAILURE, CODE XXXXXX
DMKCKP9601 SYSTEM WARMSTART DATA SAVED
DMKCKP961W SYSTEM SHUTDOWN COMPLETE
appear on the console,
this is a CP ABEND.
The system dumps to tape
or printer and stops. ~
II
rs;;l
V
If pressing the REQUEST ke\' on the operator's
console leaves the REQUEST PENDING light on,
a CP disabled wait state exists.
The CPU console light will be on. _ _
~
II
If the CPU console wait light is on,
the system is in a CP enabled wait state. __
~
II
If the real PSW problem bit is OFF,
II
If the message
DMSABNI48T SYSTEM ABEND XXX,
CALLED FROM YYYYYY
appears on the terminal,
this is a CMS ABEND.---C5J
II
,
If an ABEND message
from the virtual machine appears
on the terminal,
this is an ABEND in the
operating system controlling
~
If any of the following messages
DMKDSP450W CP ENTERED; DISABLED WAIT PSW
DMKDSP451W CP ENTERED; INVALID PSW
DMKDSP452W CP ENTERED; EXTERNAL INTERRUPT
LOOP
DMKDSP453W CP ENTERED; PROGRAM INTERRUPT
LOOP
appears on the terminal,
there is a disabled wait or an interrupt loop in the
virtual machine. - - - - - - - -....
'\
Unexpected R e s u l t s ? - - - - - - - - -...
II
li
lt processi~g has ceased in the virtual
machine without reaching end-of-job,
the virtual machine is in an
enabled wait state and no I/O interrupt
has occurred.
If an operating system which
executes properly on a real machine
fails to execute properly under VM/370,
there are unexpected results
in CPo - - - - - -...-
II
In
II
the virtual machine. - - -
'V
If the program's output is
maccurate or mlssmg,
there are unexpected results
in the problem program. _ _ _ _ _ _ _' -_ _
If the output is redundant
check for a loop. - - -
II
rs:J
V
If a program which executes under
the control of an operating system on
a real machine fails to execute correctly
with the same operating system under
VM/370,
there are unexpected results
~
C5J
II
If pressing the ATTN key once does not cause
an Interrupt,
there is a disabled loop in the virtual machine. )
Otherwise, an ABEND
condition does not exist,
GO TO=) _ _ _ _ _ _ _ _ _ _ _.J
(0
•
No problem exists
this virtual machine. ~C5J
II
thtre is a CP loop.
II
~
.~
If processing time exceeds normal expectations,
the virtual machine may have an enabled loop. )
f4al
II Otherwise,~
(0
V
____
____________
Refer to the IBM Vir.tual Machine Facility/370:
Command Language Guide for General Users
GC20-1804.
'
r::'\
\.!J
Otherwise, check for a wait or
~___IO_OP_.~---------------------J
(0
Figure
3.
Does a Problem Exist?
Part 1: Debugging with V"/370
23
Debug Procedures for a Wait
CP Disabled Wait - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ,
••
•
•
Use ALTER/DISPLAY console mode (if available), to display real PSW and CSW. Also,
display general and extended control registers and storage locations X'OO'-X'l00'.
Press SYSTEM RESTART button to cause a CP ABEND
dump to be taken.
IPL.
CP Enabled Wait
----------------------------------4
Press SYSTEM RESTART button to cause a
CP ABEND dump to be taken.
Use the dump to check the status of each VMBLOK. Also,
check RCHBLOK, RCUBLOK, and RDEVBLOK for each device.
Virtual Machine Disabled Wait
----------------------------1
Use CP commands (CMS users may use the CMS DEBUG command) to display
the PSW, CSW, general registers, and control registers.
Use the CP DUMP command (or CMS DUMP subcommand) to
take a dump.
Virtual Machine Enabled Wait
----------------------------1
Take a dump.
Debug Procedures for a Loop
CPLoop---------------------------------------------------------------,
••
••
•
••
Use ALTER/DISPLAY console mode (if available) to
display real PSW, general registers, control
registers, and storage locations X'OO'-X'100'.
Press SYSTEM RESTART button to cause a CP
ABEND dump to be taken.
Examine the CP internal trace table to see where the loop is.
Virtual Machine Disabled Loop
Use the CP TRACE command to trace the loop.
Display the general registers and control registers
via the CP DISPLAY command.
Take a dump using the CP DUMP command.
Examine the source code.
Virtual Machine Enabled Loop
Figure
24
4.
----------------------------1
----------------------------1
Trace the loop. Display the PSW, general registers,
and extended control registers.
Take a dump.
Examine source code.
Debug Procedures for waits and LOOps
IBM VM/370: System Programmer's Guide
Debug Procedures for Unexpected Results
Unexpected Results in CP - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ,
••
•
••
Check that the program is not violating any
CP restrictions.
Check that the program and operating system running
on the virtual machine are exactly the same as those
that ran on the real machine.
Use the CP TRACE command to trace CCWs, SIOs, and interrupts.
Look for an error in CCW translation or interrupt reflection.
If disk 1/0 error, use the CP DDR (CASe Dump Restore)
program to print the contents of any disk.
Unexpected results in a virtual machine
-------------------------4
Check that the program executmg on the virtual machine is
exactly the same as the one that ran on the real machine.
Make sure that operating system restrictions
are not violated.
Use CP TRACE to trace all I/O operations.
Debug Procedures for an ABEND
CPABEND--------------------------------------------------------,
••
•
Find out why CP abnormally terminated. Examine the
PROPSW, INTPR, SVCOPSW, and CPABEND fields in the PSA
from the dump.
Identify the module that caused the ABEND.
Examine the SAVEAREA, BALRSAVE, and FREESAVE areas of the dump.
If liO operation, examine the real and virtual I/O
control blocks.
CMSABEND--------------------------------------------------------~
Determine reason for ABEND from code in ABEND
message DMSABN148T.
Enter debug environment or CP console function mode
to use the commands, to display the PSW, and to examine
low storage areas:
LASTLMOD and LASTTMOD
LASTCMND and PREVCMND
LASTEXEC and PREVEXEC and DEVICE
Look at the last instruction executed.
Take dump if need be.
Virtual Machine ABEND (other than CMS)
-----------------------1
Examine dump, if there is one.
Figure
5.
••
Use CP commands to examine registers and
control words.
Use CP TRACE to trace the processing up to
the point where the error occurred.
Debug Procedures for Unexpected Results and an ABEND
Part 1: Debugging with V8/370
25
Once t~e prcblem, and the area where it occurs, is identified, you can
gather the information needed to determine the cause of the problem. The
type of information you want to look at varies with the type of problem.
The tools used to gather the information vary depending upon the area in
which the problem occurs.
For exa~ple, if the problem is looping, you
will want to examine the PSW.
For a CP loop,
you have to use the
operator's console to display the PSW,
but for a virtual machine loop
you can display the PS~ via the CP DISPLAY command.
The following sections describe specific debugging procedures for the
various error conditions.
The procedures will tell you what to do and
what debug tool to use.
For example, the procedure may say dump storage
using the CP DUMP command.
The procedure will not tell you how to use
the debug tool.
Refer to the "CP Commands to Debug the virtual Machine"
and "CMS Debugging Commands" sections for a detailed description of each
debug tool, including how to invoke it.
AEEND
When a system does not know how to continue, it abnormally terminates.
When the VM/370 Control Program abnormally terminates, a dump is taken.
This dump can be directed to tape or printer or dynamically allocated to
a direct access storage device. The output device for a CP ABEND dump is
spec~fied by the
CP SET command.
See the "ABEND Dumps" section for a
description of the SET and VMFDUMP commands.
Use the dump to find what caused the Contrel Program to terminate.
First, find why the system abnormally terminated and then see how the
condition can be correc~ed.
See the "Reading CP ABEND Dumps" discussion
for detailed information on reading a CP ABEND dump.
REASON FOR 1~~ ABEND:
CP will
terminate
teriI~atIon dump under-three conditions:
1.
and
take
abnormal
Program Check in CP
Examine the PROPSW and INTPR fields in the Prefix
determine the failing module.
2.
an
Storage Area to
Module Issuing an SVC 0
Examine the SVC old PSW (SVCOPSW) and ABEND code (CPABEND) fields
in the Prefix Storage Area to determine the module that issued the
SVC 0 and the reason it was issued.
CPABEND contains an abnormal termination code.
The first three
characters identify the failing module (for example, ABEND code
TRCOO~ indicates DMKTRC is the fuiling module).
~.
Operator Pressing SYSTEM RESTART Button on CPU Console
Ex~mine
the old PSW at location X'08' to find the location of the
instruction that was executing w~en the operat~r pressed SYSTEM
26
IBM VM/370:
S~stem
Programmer's Guide
RESTART. The operator presses
disabled wait state or loop.
SYSTEM RESTART
when
CP
is in
a
~!!MIB] 1Q! ~lQ!!§~ !!~!E: The information
in low storage tells you the
status of the system at the time CP terminated= status information is
stored in the Prefix storage Area (PSA). You should be able to tell the
module that was executing by looking at the PSA. Refer to the
appropriate save area (SAVEAREA, BALRSAVE, or FREESAVE) to see how that
module started to execute. The Prefix Storage Area is described in the
!~37Q: ~2n~I2! RIQgI~! (CP) RIQEI~~ 1QEi£ publication.
Examine the real and virtual control blocks to find the status of I/O
operations. Figure 11 shows the relationship of CP Control Blocks.
Examine the CP internal trace table. This table can be extremely
helpful in determining the events that preceded the ABEND. The "CP
Internal Trace Table" description tells you how to use the trace table.
The values in the general registers can help you tc locate the
current IOBLOK and VMBLOK and the save area. Refer to "Reading CP ABEND
Dumps" for detailed information on
the contents of the general
registers.
If the program check old PSi (PROPSi) or the SVC old PSi (SVCOPSi)
points to an address beyond the end of the resident nucleus, the module
that caused the ABEND is a pageable module. Refer to "Reading CP ABEND
Dumps" to find out how to identify that pageable module. Use the CP load
map that was created when the VM/370 system was generated to find the
address of the end of the resident nucleus.
Two types of severe machine checks
to terminate:
•
•
can cause the VM/370 control program
An unrecoverable machine check in the control program
A machine check that cannot be diagnosed
A machine check error cannot be diagnosed if either the machine check
old PSi or the machine check interrupt code is invalid.
These severe
machine checks cause the control program to terminate, but no dump is
taken since the error is recorded on the error recording cylinders. The
system is automatically restarted and a message is issued identifying
the machine check error.
If an unrecoverable machine check occurs
message
in the control program, the
DMKMCH610I MACHINE CHECK SUPERVISOR DAMAGE
appears on the CPU console. The
automatically restarted.
control
program
is terminated
and
If the machine check handler cannot diagnose a certain machine check,
the integrity of the system is questionable. The message
DMKMCH6111 MACHINE CHECK SYSTEM INTEGRITY LOST
appears
on the CPU console, the
restarted.
control
program
is terminated
and
automatic~lly
Part 1: Debugging with VM/370
27
Hardware errors are probably the cause of these severe aachine
checks. The system operator should run the CP!REP program and save the
output for the installation hardware aaintenance personnel.
When CftS abnormally
the terminal:
terminates, the following error
message appears on
DftSABR148T SYSTEft ABERD xxx CALLED FROft yyyyyy
where xxx is the ABEND code and yyyyyy is the address of the instruction
causing the ABERD. The DftSABR module issues this messag~. Then, CftS
waits for a command to be entered from the terminal.
Because CftS is an interactive system, you will probably want to use
its debug facilities to examine status. You may be able to determine the
cause of the ABEND without taking a dump.
The debug program is located in the resident nucleus of CftS and has
its own save and work areas. Because the debug program itself does not
alter the status of the system, you can use its options knowing that
routines and data cannot be overlaid unless you specifically request
it. Likewise, you can use the CP commands in debugging knowing that you
cannot inadvertently overlay storage because the CP and CftS storage
areas are completely separate.
REASON FOR THE ABEND:
First determine the reason CftS abnormally
termInated: There are-four types of CftS abnormal terminations:
1.
program Exception
control is given to the DftSITP routine whenever a hardware program
exception occurs. If a routine other than a SPIE exit routine is in
control, DftSITP issues the message
DftSITP141T xxxxxxxx EXCEPTION OCCURRED AT xxxxxx IN ROUTINE
xxxxxxxx
and invokes DftSABN (the ABEND routine). The ABEND
where x is the program exception number (O-F).
programming exceptions are:
£od~
o
1
2
3
4
5
6
7
8
9
A
B
C
D
E
F
28
~~~!~g
Imprecise
Operation
privileged operation
Execute
Protection
Addressing
specification
Decimal data
Fixed-point overflow
Fixed-point divide
Deciaal overflow
Decimal divide
Exponent overflow
Exponent underflow
Significance
Floating-point divide
IBft Vft/370: System Prograa.er's Guide
code is OCx,
The possible
2.
ABEND ftacro
control is given to the DftSSAB routine whenever a user routine
executes the ABEND macro. The ABEND code specified in the ABEND
macro appears in the abnormal termination message DftSABN148T.
3•
Halt Ex ecution (HX)
Whenever the virtual machine operator signals attention
HX, CftS terminates and, types "CftS".
4.
and types
System AEEID
A CftS system routine can abnormally terminate by issuing the DftSABN
macro. The first three hexadecimal digits of the system ABEND code
type in the efts ABEND message, DftSABN148T. The format of the
DftSABN macro is:
[ label]
DftSABN
code
(reg)
r
r"
L
L
II
IBALR II
I,TYPCALL=I~!£
....
label
is any valid assembler language label.
code
is the abnormal
appears
in the
message.
(reg)
is the register containing
code.
TYPCALL=SVC
TYPCALL= BALR
specifies how control is passed to the abnormal
termination routine, DftSABN. Routines that do not
reside in the nucleus should use TYPCALL=SVC to
generate CftS SVC 203 linkage.
Nucleus-resident
routines should specify TYPC1LL=BALR 50 that a
direct branch to DftSABN is generated.
termina tion
DftSABN149T
code (0-111) that
system
termination
the abnormal termination
If a CftS SVC handler abnormally terminates, that routine can set an
ABEND flag and store an ABEND code in NUCON (the CMS nucleus
constant area). After the SVC handler has finished processing, the
ABEND condition is recognized. The DMSABN ABEND routine types the
ABEND message, DMSABN148T, with the ABEND code stored in NUCON.
WHAT TO DO ~HI] £ftS A~!QRMALLY TERMINATES: After an ABEND, two courses
of-actlon- are available in CMs.--In-addItion, by signalling attention,
you can enter the CP command mode and use CP's debugging facilities.
Two courses of action available in CftS are:
1.
Issue the DEBUG command and enter the debug environment. After
using all the DEBUG subcommands that you wish, exit from the debug
environment. Then, either issue the RETURN command to return to
DMSABN so that ABEND recovery will occur, or issue the GO command
to resume processing at the point the ABEND occurred.
2.
Issue a CMS command other than DEBUG and the ABEND routine, DMSABN,
performs its ABEND recovery and then passes control to the DMSINT
routine to process the command just entered.
Part 1: Debugging with VM/370
29
The ABEID recovery function performs the following:
1.
The SVC handler, DMSITS, is
areas are released.
re-initialized, and all
stacked save
2.
"FINIS * * *" is invoked by means of SVC 202,
and to update the master file directory.
3.
If the ElECTOR module is in real storage, it is released.
4.
All link blocks allocated by DMSSLB are freed.
5.
All FCB pointers are set to zero.
6.
All user storage is released.
7.
The amount of system free storage which
computed. This figure 1S compared to the
that is actually allocated.
8.
The console input stack is purged.
to close all files,
§~QY1~
be allocated is
amount of free storage
When the amount of storage actually allocated is less than the amount
that should be allocated, the message
DMSABN149T xxxx DOUBLEWORDS OP SYSTEM STORAGE HAVE BEEN DESTROYED
appears on the terminal. If the amount of storage actually allocated is
greater than the amount that should be allocated, the message
DMSABN150W nnn (HEX xxx)
RECOVERED
DOUBLEWORDS
OP SYSTEM
STORAGE WERE
NOT
appears on the terminal.
A DEBUGGING PROCEDURE:
When a CMS ABEND occurs, you will probably want
to-use--the DEBU~subcommands or CP commands to examine the PSW and
certain areas of low storage.
Refer to "CMS Debugging Commands" for
detailed description of how to use the CMS DEBUG subcommands. See "CP
Commands Used to Debug the Virtual Machine" and "CP Commands Used to
Debug CP" for a detailed description of how to use the CP commands.
Also refer to Pigure 7 for a comparison of the CP and CMS debugging
facilities.
The following procedure
CMS ABEND:
1.
may be useful in determining the
cause of a
Display the PSW.
(Use the CP DISPLAY command or CMS debug PSW
subcommand.)
Compare the PSW instruction address to the current
CMS load map trying to determine the module that caused the ABEND.
The CMS storage-resident nucleus routines reside in fixed storage
locations.
Also check the interruption code in the PSW.
2.
Examine areas of low storage. The information in low
tell you more about the cause of the ABEND.
!igl~
LASTLMOD
LASTTMOD
30
Contents
contaIns the name of the last module
storage via the LOADMOD command.
Contains the name
transient area.
of the last module
IBM VM/370: System Programmer's Guide
storage can
loaded
into
loaded into the
1!~Jg
contains
PREVCMND
Contains
issued.
LASTEXEC
Contains the name of the last EXEC procedure.
PREVEXEC
Contains the name of the next to last EXEC procedure.
DEVICE
Identifies
interrupt.
LASTCMND
contents
the name of the last ccmmand issued.
the name
the
of the
device
next to
that
the last
caused
the
command
last
I/O
The'low storage areas examined depend on the type of ABEND.
3.
Once you have identified the module that caused the ABEND, examine
the specific instruction. Refer to the listing.
4.
If you have not identified the problem at this time, take a dump by
issuing the debug DUMP subcommand. Refer to "Reading CMS ABEND
Dumps" for information on reading a CMS dump. If you can reproduce
the problem, try the CP or CMS tracing facilities.
The abnormal termination of an operating system (such as OS or DOS)
running under VM/370 appears the same as a like termination on a real
machine. Refer to publications for that operating system for debugging
information.
However, all of the CP debugging facilities may be used to
help you gather the information you need.
Because certain operating
systems
(OS/VS1, OS/VS2,
and DOS/VS)
manage their virtual storage
themselves, CP commands that examine or alter virtual storage locations
should be used only in virtual=real storage space with OS/VS1, OS/VS2,
and DOS/VS.
If a dump was taken, it was sent to the virtual printer. Issue a
CLOSE command to the virtual printer to have the dump print on the real
printer.
If you choose to run a standalone dump program to dump the storage in
your virtual machine, be sure to specify the NOCLEAR option when you
issue the CP IPL command.
At any rate, a portion of your virtual
storage is overlaid by cpts virtual IPL simulation.
If the problem can be reproduced, it can be helpful to trace the
processing using the CP TRACE command.
Also, you can set address stops,
and display and alter registers, control words (such as the PSi), and
data areas. The CP commands can be very helpful in debugging because you
can gather information at various stages in processing. A dump is static
and represents the system at only one particular time. Debugging on a
virtual machine can often be more flexible than debugging on a real
machine.
VM/370 may terminate or reset a virtual machine if a nonrecoverable
channel check or machine check occurs in that virtual machine. Hardware
Part 1: Debugging with VM/370
31
errors usually cause this type of virtual machine
the following messages:
termination.
One of
D"KMCH6161 "ACHINE CHECK; USER userid TERMINATED
DMKCCH6041 CHANNEL ERROR; DEV xxx; USER userid; "ACHINE RESET
appears on the CPU console.
UNEXPECTED RESULTS
The type of errors classified as unexpected results vary from operating
systems improperly functioning under V"/370 to printed output in the
wrong format.
If an operating system executes properly on a real machine but does not
execute properly with VM/370, a problem exists.
Also, if a program
executes properly under the control of a particular operating system on
a real machine but does not execute correctly under the same operating
system with V"/370, a problem exists.
First, there are conditions (such as time-dependent programs) that CP
does not support.
Be sure that one of these conditions is not causing
the unexpected results in CP. Refer to the "CP Restrictions" section for
a list of the restrictions.
Next, be sure that the program and operating system running on the
virtual machine are ~~~ctlI the same as the one that ran on the real
machine. Check for
•
•
•
The same job stream
The same copy of the operating system (and program)
The same libraries
If the problem still is not found, look for an I/O problem.
Try to
reproduce the problem, this tiae tracing all CCWs, SIOs, and interrupts
via the CP TRACE command. Compare the real and virtual CCWs from the
trace.
A discrepancy in the CCWs may indicate that one of the CP
restrictions was inadvertently violated, or that an error occurred in
the Control Program.
When a program executes correctly under the control of a particular
operating system on a real machine but has unexpected results executing
under the control of the same operating system with V"/370, a problem
exists. Usually you will find that something was changed. Check that the
job stream, the operating system, and the system libraries are the
same.
If unexpected results occur (such as TEXT records interspersed in
printed output), you may wish to examine the contents of the system or
user disk files. Non-CMS users may execute any of the utilities
included in the operating system they are using to examine and rearrange
32
IB" VM/370: System Programmer's Guide
files. Refer to the utilities publication for the operating system
running in the virtual machine for information on how to use the
utilities.
eMS users should use the DASD Dump Restore (DDR) serV1ce program to
print or move the data stored on direct access devices. The Yft/370 D1SD
Dump Restore (DDR) program can be invoked by the CftS DDR command in a
virtual machine controlled by CftS. The DDR program has five functions:
1.
DUKP
dumps
magnetic tape.
part, or
all of
the data
from a
D1SD device
to
2.
RESTORE -- transfers data from tapes created by DDR DUftP to a
direct-access device. The direct access device that the data is
being restored to must be the same type of device as the direct
access device originally containing that data.
3.
~OP!
4.
E~!!~
5.
~I~~
-- copies data from one device to another device of the same
type. Data may be reordered, by cylinder, when copied from disk to
disk. In order to copy one tape to another, the oriqinal tape must
have been created by the DDR DUftP function.
selectively
prints the
hexadecimal
and
EBCDIC
representation of DASD and tape records on the virtual printer.
selectively
displays
the
hexadecimal and
representation of DASD and tape records on the terminal.
CKS users should
instructions on using
contains information
virtual machine and a
EBCDIC
refer to the "Debugging with CftS" section for
the DDR command.
The "Debugging with cpu section
about executing the DDR program in a real or
description of the DDR control statements.
LOOP
The real cause of a loop usually is an instruction that sets or branches
on the condition code incorrectly. The existence of a loop can usually
be recognized by the ceasing of productive processing and a continual
returning of the PSi instruction address to the same address. If I/O
operations are involved, and the loop is a very large one, it may be
extremely difficult to define, and may even comprise nested loops.
Probably the most difficult case of looping to determine is entry to the
loop from a wild branch. The problem in loop analysis is finding either
the instruction that should open the loop or the instruction that passed
control to the set of looping instructions.
The CPU operator should perform the following sequence
information to find the cause of a disabled loop.
when gathering
1.
Use the alter/display console mode to display the real PSi, general
registers, control registers and storage locations X'OO' - X'100'.
2.
Press the SYSTEM
taken.
3.
Save the information collected for the system programmer
Field Engineering Program Systems Representative.
RESTART
button to
cause an
ABEND
dump to
be
or IBK
Part 1: Debugging with YM/370
33
After the CPU operator has collected the information, the system
programmer or Field Engineering representative examines it. If the cause
of the loop is not apparent,
1.
Examine the CP internal trace table to determine
may be involved in the loop.
the modules that
2.
If the cause is not yet determined, assume that a wild branch
caused the loop entry and search the source code for this wild
branch.
When a disabled loop in a virtual machine exists, the virtual machine
operator cannot communicate with the virtual machine's operating system.
That means tpat signalling attention does not cause an interrupt.
Enter the CP console function mode.
1.
Use the CP TRACE command to trace the entire loop. Display general
arid extended control registers via the CP DISPLAY command.
2.
Take a dump via the CP DUMP command.
3.
Examine the source code.
Use the information just gathered, along with
find the entry into the loop.
listings, to
try to
!21~:
You can IPL a standalone dump program such as the BPS Storage
Print to dump the storage of your virtual machine.
If you choose to use
a standalone dump program, be sure to specify NOCLEAR on the IPL
command.
Also, be aware that the CP IPL simulation destroys a page of
storage in your virtual machine and the standalone dump alters your
virtual storage while the CP DUMP command does not.
However,
if the operating system in the virtual machine itself
manages virtual storage, it is usually better to use that operating
system's dump program.
CP does not retrieve pages which exist only on
the virtual machine's paging device.
The virtual machine operator should perform the following sequence when
attempting to find the cause of an enabled leop:
1.
Use the CP TRACE command to trace the entire loop.
and the general registers.
2.
If your virtual machine has the Extended Control (EC) mode and the
EC option, also display the control registers.
3.
Use the CP DUMP command to dump your virtual storage.
CMS users
can use the debug DUMP subcommand.
A standalone dump may be used,
but be aware that such a dump destroys the contents of some areas
of storage.
34
IBM VM/370: System Programmer's Guide
Display the PSW
4.
Consult the source code to search for the faulty instructions,
exam1n1ng previously executed modules if necessary. Begin by
scanning for instructions that set the condition code or branch on
it.
5.
If the .anner of loop entry is still undetermined, assume
wild branch has occurred and begin a search for its origin.
that a
WAIT
No processing occurs in the virtual machine when it is in a wait state.
When the wait state is an enabled one, an I/O interrupt causes
processing to resume.
Likewise, when the Control Program is in a wait
state, its processing ceases:
A disabled wait state usually results from a hardware malfunction.
During the IPL process, normally correctable hardware errors may cause a
wait state because the operating system error recovery procedures are
not accessible at this point. These conditions are recorded in the
current PSW.
CP may be in an enabled wait state with channel 0 disabled when it is
attempting to acquire more free storage. Examine EC register 2 to see
whether or not the multiplexer channel is disabled. A severe machine
check could also cause a CP disabled wait state.
If a severe machine check or channel check caused a CP disabled wait,
one of the following mesSages will appear:
DMKMCH612W MACHINE CHECK TIMING FACILITIES DAMAGE; RUN SEREP
DMKCCH603W CHANNEL ERROR, RUN SEREP, RESTART SYSTEM
If the generated system cannot run on the real machine because of
insufficient storage, CP enters the disabled wait state with code OOD in
the PSW. The insufficient storage condition occurs if:
1.
The generated system is larger than the real machine size
2.
A hardware malfunction occurs which reduced the available amount of
real storage to less than that required by the generated system.
g~
The message
DMKCPI955W INSUFFICIENT STORAGE FOR VM/370
appears on the CPU console.
If CP cannot continue because consecutive hardware
occurring on one or more VM/370 paging devices, the message
DMKPAG415E
errors
are
CONTINUOUS PAGING ERRORS FROM DASD xxx
appears on the CPU console and CP
code OOF in the PSW.
enters the disabled wait
state with
Part 1: Debugging with VM/370
35
If more than one paging device is available, disable the device on
which the hardware errors are occurring and IPL the system again. If
the VM/370 system is encountering hardware errors on its only paging
device, move the paging volume to another physical device and IPL
again.
Rote: This error condition may occur if the VM/370 paging volume was not
properly formatted.
The following procedure should
record the needed information.
be followed by
the CPU
operator to
1.
Using the alter/display mode of the CPU console, display the real
PSW and CSW. Also, display the general registers and the control
registers.
2.
Press the
dump.
3.
IPL the system.
SYSTEM RESTART
button in
order to
get a
system ABEND
Examine this information and attempt to find what caused the wait.
If you cannot find the cause, attempt to reconstruct the situation tha~
existed just before the wait state was entered.
If you determine that CP is in an enabled wait state, but that no I/O
interrupts are occurring, there may be an error in CP routine or CP may
be failing to get an interrupt from a hardware device. Press the SYSTEM
RESTART button on the operator's console to cause an ABEND dump to be
taken. Use the ABERD dump to determine the cause of the enabled (and
noninterrupted) wait state. After the dump is taken, IPL the system.
Using the dump, examine the VMBLOK for each user and the real device,
channel, and control unit blocks. If each user is waiting because of a
request for storage and no more storage is available, there is an error
in CP. There may be looping in a routine that requests storage. Refer to
"Reading CP ABEND Dumps" for specific informaticn on how to analyze a CP
dump.
The VM/370 Control Program does not allow the virtual machine to enter a
disabled wait state or certain interrupt loops. Instead, CP notifies
the virtual machine operator of the condition with one of the following
aessages:
DMKDSP450W
CP ENTERED; DISABLED WAIT PSi
DMKDSP451i
CP ENTERED; INVALID PSW
DMKDSP452i
CP ENTERED; EXTERBAL INTERRUPT LOOP
DMKDSP453W
CP ENTERED; PROGRAM INTERRUPT LOOP
and enters the console function mode. Use the CP commands to display the
following inforaation on the terainal.
36
IBM VM/370: System Programmer's Guide
•
•
•
•
PSW
CSW
General registers
Control registers
Then use the CP DUftP command to take a dump.
If you cannot find the cause of the wait or loop from the inforaation
just gathered, try to reproduce the problem, this time tracing the
processing via the CP TRACE command.
If CftS is running in the virtual machine, the CftS debugging
facilities may also be used to display information, take a dump, or
trace the processing. The CftS SVCTRACE and the CP TRACE commands record
different information. Figure 7 compares the two.
If the virtual machine is in an enabled wait state, try to find out why
no I/O interrupt has occurred to allow processing to resume.
The Control Program treats one case of an enabled wait in a virtual
.achine the same as a disabled wait. If the virtual machine does not
have the "real timer" option and loads a PSW enabled only for external
interrupts, CP issues the message
DftKDSP450W
CP ENTERED; DISABLED WAIT STATE
since the virtual timer is not decremented while the virtual machine
is in a wait state, it cannot cause the exter~al interrupt.
A "real
timer" runs in both the problem state and wait state and can cause an
external interrupt which will allow processing to resume.
Three disabled wait conditions can occur during the operation of the
RSCS component of Vft/370.
They can result from either hardware
malfunctions or system generation errors. CP notifies the RSCS operator
of the wait condition by issuing the message
DftKDSP450W CP ENTERED; DISABLED WAIT PSW
to the RSCS operator's console. Using CP commands, the operator can
display the virtual machine's PSW.
The rightmost three hexadecimal
characters indicate the error condition.
~!!I ~I!I~ £~~~ !~QQ1~:
If no RSCS message was issued, a program check
interrupt occurred during the execution of the program check handler. A
programming error is the probable cause.
If the RSCS message
DftTREX091T INITIALIZATION FAILURE -- RSCS SHUTDOWN
was issued, RSCS operation has been terminated due to an error in the
loading of DftTAXS or DftTLAX. A dump of virtual storage is automatically
taken. Verify that the CftS files 'DftTAXS TEXT' and 'DftTLAX TEXT' are
correctly written and resident on the RSCS system-residence device.
Part 1: Debugging with Vft/370
37
If the RSCS message
DMTREX090T PROGRAM CHECK IN SUPERVISOR -- RSCS SHUTDOWN
was issued, the program check handler has terminated RSCS due to a
program check interrupt in other than a dispatched line driver.
1 dump
of virtual storage is automatically taken. 1 program.ing error is the
probable cause.
The wait state code is loaded by DMTREX
automatically during program check handling.
If neither of the last two
command to dump the contents of
Load to restart the system.
installation support personnel.
at
RSCS termination
or
messages was issued, use the CP Duep
virtual storage. Do an Initial Program
If the problem persists, notify the
IAIT ~I!I~ £~~~ !~QI~: A program check interrupt has occurred during
initial processing,
before the program
check handler
could be
activated. This may be caused by a programming error or by an attempt
to load RSCS into an incompatible virtual machine. The latter case can
occur if the virtual machine has
(1) an incomplete instruction set, (2)
less than 512K of virtual storage, or (3)
does not have the required
Ve/370 DIAGNOSE interface support.
The wait state code is loaded
automatically during the initial loading and execution of the RSCS
supervisor, DeTIII, DeTREX, DeT1IS or DeTLAI.
verify that the RSCS virtual machine configuration has been correctly
specified and that the "retrieve subsequent file descriptor" function of
Diagnose code 1'14' is supported. Dump the contents of virtual storage
via the CP Duep command.
If
the problem persists, notify the
installation support personnel.
WAIT STATE CODE 1'011': An unrecoverable error occurred when reading the
-nncleus-fro;--nAsD storage. This may be caused by a hardware
malfunction of the DASD device. It may also be the result of an
incorrect virtual DASD device definition, an attempt to use a system
residence device unsupported by RSCS, incorrect RSCS system generation
procedures, or the subsequent overwriting of the RSCS nucleus on the
system residence device. The wait state code is loaded by DeTINI after
an attempt, successful or not, to issue the message:
RSCS
DeTINI402T IPL DEVICE READ I/O ERROR
Verify that the RSCS system residence device has been properly
defined as a virtual DASD device and that the real DASD device 1S
mounted and operable.
If the problem persists, dump virtual storage via
the CP Duep command and notify the installation support personnel. The
RSCS system residence device may have to be restored or the RSCS system
may have to be regenerated.
Whenever Rses has no task ready for execution, DeTDSP loads a masked-on
wait state PSi with a code of hexadecimal zeroes. This occurs during
normal Rses operation and does not indicate an error condition.
An
external interrupt due to command entry or an I/O interrupt due to the
arrival of files automatically resumes processing.
38
IBe VM/370: System Programmer's Guide
Figure 6 summarizes the VM/370 commands that are useful
commands are classified by the function they perform.
r-
, Function
comments
CP Command
Stop execu- Set the adtion at a
dress stop
specified
before the
location.
program
reaches the
specified
address.
CMS allows
16 address
stops to
be active
while CP
allows only
one
The CP
and CMS
CMS Com Bland
ADSTOP hexloc
DEBUG
BREAK id {symbol}
{hexloc}
Resume
,Resume
BEGIN
execution. I execution
, where pro, gram was
,
, interrupted I
I
I Continue
BEGIN hexloc
I execution I
I at a speci-I
I fic loca- I
I tion
I
,
,
,,
in debugging.
I Dump data. IDump the
I
I contents oflDUMP { hexlocl }
specific
{Lhexloc 1 }
I
I
storage
I
I
I locations I
I
I
I
I
I
I
[ *dumpid]
I
I
I
,,
,
DEBUG
GO
DEBUG
GO {symbol}
{hexloc}
IDEBUG
I
r
,DUMP I symbolll
L
I hexloc11
I
I
, I I
Q
I
I r
L
I{.}I bytecount , , I
II I
I I~!!Q
L L
[ ident]
I
I
r
r
I{ -}I hexloc2"
I{ : }I~!!Q
II
,
"
.,
....
,
.
r
,
Isymbol21
Ihexloc2,
I
*
I
I
11~
,
L
.
L
Figure
6.
Summary of VM/370 Debugging Tools (Part 1 of 5)
Part 1: Debugging with VM/370
39
-,
Function
Display
data.
CP Command
Comments
IDisplay
I
I contents oflDISPLAY
I storage 10-1
I cations (in I
I hexadeci- I
I mal)
I
I
I
I
I
I
I Display
I
I contents oflDISPLAY
I storage
I
I locations I
I (in hexa- I
I decimal andl
I EBCDIC)
I
I
I
I
IDisplay
I storage keYIDISPLAY
I of specific I
I storage
I
I locations I
I in hexaI
I decimal
I
I
I
I
I Display
I
IDISPLAY
I general
I registers I
I
CMS Command
"IDEBUG
r
r
hexloc1 I{ - }lhexloc211lX
I{ : } I]!]
III
L
J II
I
, II
I r
I{.}I bytecount I I I
III
I lEND
L
L
JJ I
,
r
!
r
I
I
40
L
{
r
,
L
J
{
I n I
{hexloc I ~ I
{
,
DEBUG
GPR reg1 [reg2 ]
!
DEBUG
PSW
'--
6.
{
r
r
" I
Khexloc 11{ -}I hexloc2111
I{ : } I]!]
III
L
J II
I
, II
I r
l{.}1 bytecount I I I
III
I lEND
L
L
JJ I
Greg11{ -} [re g 2]
I{ :} ~!!!
Summary of VM/370 Debugging Tools (Part 2 of 5)
IBM VM/370: System Programmer's Guide
,
r
r
r
" I
Thexloc 11 { - } I hexloc21 I I
I{ : } I~!!!
III
L
J II
I
, II
I r
I{.}I bytecoun t I I I
I lEND
III
L
L
JJ I
I{ • } I regcount II
I
I
lEND
I
I
II
I
L
JJ
L
I
I
I
,
I Display
r
I
I floating- I DISPLAY Yreg 11{ - }[re g 2]
I
I { : } ~!Q
I point
I
I
, I
I registers I
I
r
l{ • } I regcount I I
I
I
I
I
I
II
I~!!!
JJ
L
L
I
I
I
,
I Display
I
r
I DISPLAY Xreg 11 {- }[re g 2]
I control
I
I{ :} ~!!!
I registers I
I
, I
I
I
I
r
I{ • } I regcount I I
I
I
lEND
I
I
I
II
L
JJ
L
I
I
I
PSW
I Display
IDISPLAY
I contents ofl
I current
I
I virtual PSWI
I in hexaI
I decimal
I
I format
I
Figure
{
}
{ symbol I n
I }
{
I !!H!91h I }
J
}
}
}
}
}
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
r--------------------------------------------------------------------------------------,
CftS Coaaand
Coallents
CP COllmand
Function
Display
data
(cont.)
IDisplay
IDISPLAY
1 contents ofl
1 CAW
1
CAW
DEBUG
Cli
1---------------------------------------------------------------------DEBUG
CSW
I Display
IDISPLAY
CSW
1 contents ofl
1 CSW
I
store data. store
I
specified ISTORE Shexloc hexdata •••
inforllatio n I
into con- I
secutive
I
storage
I
locations I
without
I
alignment I
DEBUG
STORE {syabol }
hexloc
hexinfo[hexinfo[hexinfo]]
store
specified I STORE {heXIOC }
I
Lhexloc
words of
inforllationl
into con- I
{hexword1[hexword2 ••• ]}
secutive
I
fullword
I
storage
I
locations I
store
ISTORE Greg hexword 1
[ hexword2 ••• ]
specified I
words of
I
inforllationl
into con- I
secutive
I
general
I
registers I
IDEBUG
ISET GPR reg hexinfo[hexinfo]
I
I
I
I
I
I
store
I STORE Yreg hexword 1
specified I
[ hexword2 ••• ]
words of
i
information 1
into con- I
secutive
1
floating- I
point
I
I
L-____________.registers
________________________________________________________________________
Figure
6.
~
Sumaary of V8/370 Debugging Tools (Part 3 of 5)
Part 1: Debugging with V8/370
41
Function
comments
store data
(cont. )
CP Command
store
ISTORE Xreg hexword1 [ bexword 2 •••
specified I
words of
I
data into I
consecutive I
control
I
registers I
CMS Command
)I
store
ISTORE PSW [hexword1] bexword2
information I
into PSW
I
store
I
information I
in CSW
I
I
I
I
I
I
I
I DEBUG
ISET PSW hexinfo [hexinfo]
I
I DEBUG
ISET CSW hexinfo [hexinfo]
I
store
I
information I
in CAW
I
I DEBUG
I SET CAW hexinfo
I
Trace
ITrace all
TRACE
execution. 1 instrucI tions,
I
1 interrupts, 1
I and
1
1 branches
1
ALL
1----------------------------------------------------------------------------------------SVCTRACE ON
TRACE SVC
ITrace SVC
1 interrupts
1
ITrace I/O
1 interrupts
TRACl
I/O
ITrace
1 program
1 interrupts
TRACE
PROGRAM
Trace
external
interrupts
TRACE
EXTERNAL
Trace
privileged
instructions
TRACE
PRIV
Trace all
user I/O
operations
TRACl
SIO
I
Figure
42
6.
Summary of VM/370 Debugging Tools (Part 4 of 5)
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
r
Function
Trace
comments
! Tr'::ior=.-..
I
execution I virtual andl
(cont. )
I real CCws I
I
ITrace
I all user
I interrupts
i and sucI cessful
I branches
I
ITrace
I all inI structions
I
lEnd all.
I tracing
I activity
I~.LU."'~
CP Command
TRACE
SIO
TRACE
CCW
CMS Command
TRACE BRANCH
TRACE INSTRUCTION
SVCTRACE OFF
TRACE END
Trace real ITrace
MOBITOR START CPTRACE
machine
I events in
events
I real
I machine
I
Istop tracingl MONITOR STOP CPTRACE
I events in I
I the real
I
machine
L-____________
__
I .________________________________________________________
I
Figure
6.
Summary of VM/370 Debugging Tools (Part 5 of 5)
Part 1: Debugging with VM/370
43
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
If you are debugging problems while running CMS, you can choose the CP
or CMS debugging tools. Refer to Figure 7 for a comparison of the CP
and CMS debugging tools.
1 Function
1 address
1 stops.
CMS
CP
1------------------------------ICan set only one address
ISetting
1 at a time.
stoplCan set up to 16 address
stops at a time.
I
1
IDumping
1 contents
1 of stor1 age to
1 the
1 printer.
1
1
IThe dump is printed in hexa- IThe dump is printed in hexadecimal format with EBCDIC
I decimal format. The storage
translation. The storage ad-I address of the first byte of
dress of the first byte of
I each line is identified at
each line is identified at I the left. The contents of
the left. The control blocksl general and floating-point
are formatted.
I registers are printed at the
I beginning of the dump.
DisplayinglThe display is typed in hexa- The display is typed in hexadecimal format. The CMS comthe con- 1 decimal format with EBCDIC
mands gg ~g! display storage
tents of 1 translation. The CP command
keys, floating-point regisstorage I displays storage keys,
and
I floating-point registers and ters or control registers as
the CP command does.
control
1 control registers.
registersl
at the
I
terminal. 1
storing
information.
The CMS command stores up to
The amount of information
12 bytes of information. CMS
stored by the CP command is
stores data in the general
limited onl~ by the length
registers but not in the
of the input line. The infloating-point or control
formation can be fullword
registers. CMS stores data
aligned when stored. CP
in the PSW, CAW, and CSW.
stores data in the PSW, but
not in the CAW or CSW. However, data can be stored in
the CSW or CAW by specifying
the hardware address in the
STORE command. CP also
stores the status of the
virtual machine in the
extended logout area.
Tracing
information.
CP traces:
• All interrupts, instructions and branches
• SVC interrupts
• I/O interrupts
• Program interrupts
• External interrupts
• Privileged instructions
• All user I/O operations
• Virtual and real CCW's
• All instructions
CMS traces all SVC interrupts. CMS displays the
contents of general and
floating-point registers
before and after a routine
is called. The parameter
list is recorded before a
routine is called.
The CP trace is interactive.
You can stop and display
other fields.
Figure
44
7.
Comparison of CP and CMS Facilities for Debugging
IBM VM/370: System Programmer's Guide
Debugging with CP
This section contains information you may want to refer to while
debugging and a discussion of when and how to use the CP debugging
tools. Also included is a discussion of how to read a CP ABEND dump •.
The first section, "Introduction
to Debugging," described the
debugging procedures to XOllOW ana ~n1S section tells you hew to use the
debugging tools and commands mentioned in that first section.
The
following topics are discussed in this section.
•
•
•
•
•
•
•
•
Debugging CP in a v1r~ual maCD1ne
CP commands useful for debugging
DASD dump restore program
CP Internal Trace Table
CP restrictions
ABEND dumps
Reading ABEND dumps
Control block summary
The VM/370 Control Program has a set of interactive commands that
control the VM/370 system and enable the user to control his virtual
machines and associated control program facilities. The virtual machine
operator using these commands can gather much the same information about
his virtual machine that an operator of a real machine gathers using the
CPU console.
The CP commands are eight characters or less in length. The commands
can be abbreviated by truncating them to the minimum permitted length
shown in the format description.
When truncation is permitted, the
shortest acceptable version of the command is represented by capital
'~~~~r~wi~h thpoptional nart renresented bv lower case letters.
B~t~: h~we;;~~ -that you can ~~t~r-a~y CP command with any mixture of
upper and lower case letters.
The operands, if any, follow the command on the same line and must be
separated from the com.and by a blank. Lines cannot be continued.
Generally, the operands are positional, but some commands have reserved
words and keywords to assist processing.
Blanks must separate the
command from any operands and the operands from each other.
several of these commands (for example, STORE or DISPLAY) examine or
alter virtual storage locations.
When CP is in complete control of
virtual storage (as in the case of .DOS, MFT, MVT, PCP, CMS, and RSCS)
these commands execute as expected.
However, when the operating system
in the virtual machine itself manipulates virtual storage (OS/VS1,
05/V52, or DOS/VS), these CP commands should not be used.
Each CP user has one or more privilege classes as indicated in his
VM/370 directory entry.
Class G commands useful for debugging are
discussed in the following paragraphs. For a discussion of all the CP
Class G commands and the CP command privilege classes, refer to the
!~LJIQ: £Q!!~~g l~~gy~gg §Yi~~ ior §en~~~l M§~£§.
The remainder of this
section discusses the CP Class G commands that provide material and
techniques that are useful in debugging.
Part 1: Debugging with VM/370
45
Use the ADSTOP command to halt execution at a virtual instruction
address. Execution halts when the instruction at the specified address
is. the next instruction to be executed.
When execution halts, the CP command mode is entered and a message is
displayed. At this point, you may invoke other CP debugging co.mands.
To resume operation of the virtual machine, issue the BEGIN command.
Once an ADSTep location is set, it may be removed by one of the
following:
•
•
•
•
Reaching the virtual storage location specified in the ADSTOP command
Performing a virtual IPL or SYSTEM RESET
Issuing the ADSTOP OFF command
Specifying a different location with a new ADSTOP hexloc command
The format of the ADSTOP command is:
ADSTOP
{
hexloc }
OFF
hexloc
is the hexadecimal representation of the virtual instruction
address where execution is to be halted.
The specified
address cannot be in a storage segment shared with other
users, since the ADSTOP function modifies storage.
OFF
cancels any previous ADSTOP setting.
1.
Since the ADSTOP function modifies storage (by placing a CP SVC
X'B3' at the specified location) your program should not examine
the two bytes at the instruction address. CP does not verify that
the location specified contains a valid CPU instruction.
2.
Address stops may not be set in an OS/VS or DOS/VS virtual
machine's virtual storage; address stops may only be set in the
virtual equals real partitions or
regions of those virtual
machines.
46
IBM VM/370: System Programmer's Guide
3.
If the SVC handling portion of the virtual machine assist feature
is enabled on your virtual machine, CP turns it off when an address
stop is set. lfter the address stop is removed, CP returns the
assist feature SVC handling to its previous status.
ADSTOP AT xxxxxx
The instruction whose address is xxxxxx is the next instruction
scheduled for execution.
The virtual machine is in a stopped
state. Any CP command (including an ADSTOP command to set the next
address stop) can be issued.
Enter the CP command BEGIN to resume
execution at the instruction location xxxxxx, or at any other
location desired.
Use the ADSTOP command to stop the execution of a program at a specific
instruction location. The address stop should be set after the program
is loaded, but before it executes.
When the specified location is
reached during program execution, execution halts and the CP environment
is entered. The message
ADSTOP AT xxxxxx
appears on the terminal indicating that program execution has halted.
The virtual machine operator may issue other CP commands to examine and
alter the status of the program at this time.
set an address stop at a location in the program where an error is
suspected. Then display registers, control words, and data areas to
check the program at that point in its execution. This procedure helps
you to locate program errors. You may be able to alter the contents of
storage in such a way that the program will execute correctlv. The
detected error is then corrected and the program is compil~d, if
necessar1, and executed again.
lote: In order to successfully set an address stop, the virtual
Instruction address must be in real storage at the time the ADSTOP
command is issued.
Part 1: Debugging with VM/370
47
Use the BEGIN co •• and to continue or resu.e execution in the virtual
machine at either a specified storage location or the location pointed
to be the virtual aachine's current PSi. The format of the BEGIN
command is:
I•
Begin
[hexloc]
L ______- - - - - - - - - - - -________________________________________________________
hexloc
~
is the hexadecimal storage location where execution is to
begin. ihen BEGIN is issued without hexloc, execution begins
at the storage address pointed to by the current virtual
machine PSi.
Unless the PSi has been altered since the CP
command mode was given control, the location stored in the PSi
is the location where the virtual machine stopped.
ihen BEGIN is issued with a storage location specified,
execution begins at the specified storage location.
The
specified address replaces the instruction address in the PSi,
then the PSi is loaded.
None.
The virtual machine begins execution.
Use the BEGI) command to continue or resume program execution. When
BEGIN is issued without an operand, execution begins at the storage
address pointed to by the current virtual machine PSi.
Unless the PSi
has been altered since the CP environment was given control, the
location stored in the PSi is the location where the virtual machine
stopped.
ihen BEGIN is issued with a storage location specified,
execution begins at the specified storage location.
The specified
address replaces the instruction address in the PSi, then the PSi is
loaded.
48
IB" V"/310: System Programmer's Guide
Use the DISPLAY
components:
•
•
•
•
•
•
command
to examine
the
following
virtual
machine
Virtual storage locations
Gener~l reg~sters .
~'~~+~ft~_~~1ft+
~~va~~u~~v~u~
Control
Program
Channel
Channel
~~~1~+~~~
~~~~~~~~~
registers
status word (PSW)
address word (CAW)
status word (CSW)
If a command line with an invalid operand is entered, the DISPLAY
command terminates when it encounters the invalid operand; however, any
previous valid operands are
processed tefore termination occurs.
storage locations, registers, and control words can be displayed using a
single command line. The format of the DISPLAY command is:
,
r
Display
I hexloc11
I Khexloc11
ILhexloc 11
I Thexloc 11
Q
I
I
L
.J
r
I{ - }I hexloc2 I
I
I : I1BH2
L
.J
I
I
r
I{ • }I bytecount I
I
I
11l!~
,
L
r
,,
r
L
r
.J
\
hexloc1
Lhexloc1
Thexloc1
Khexloc1
Q
Psw
CAW
CSW
L
.J
,
,
Greg1 I { -} I reg21
Yreg1 I
: IJl!J2 I
L
.J
Xreg1 I
I
r
I { • } I regcount I
I
I
IJ!!~
L
I
I
I
I
I
I
,
I
I
I
I
I
I
.J
.J
}
is the first, or only, hexadecimal storage location
whose contents are to be displayed at the terminal. If
L is specified, the storage contents are displayed in
hexadecimal. If T is specified, the storage contents
are displayed in hexadecimal, with EBCDIC translation.
If K is specified, the storage keys are displayed in
hexadecimal.
If hexloc1 is followed by a period and is not
fullword boundary, it is rounded down to the
lowest fullword.
on a
next
If hexloc1 is not specified, the display begins at
storage location O.
If L, T, or K are entered either
Part 1: Debugging with V"/370
49
without any operands, or followed immediately by a
blank, the contents of all storage locations are
displayed.
If L, T, or K are not specified and this is
the first operand, then the default value of zero is
assumed.
The address,
hexloc1,
may be one to six
hexadecimal digits; leading zeros are optional.
-}heXlOC2
{ : 1112
{ ·lbytecount
~!~
is the last of the
range of hexadecimal storage
locations whose contents are to be displayed at the
terminal. Either or: must be specified to display
the contents of more than one location by storage
address. If hexloc2 is not specified, the contents of
all storage locations from hexloc1 to the end of
virtual storage are displayed. If specified, hexloc2
must be equal to or greater than hexloc1 and within the
virtual storage size.
The address, hexloc2, may be
from one to six hexadecimal digits; leading zeros are
optional.
is a hexadecimal integer designating the number of
bytes of storage (starting with the byte at hexloc1) to
be displayed at the terminal. The period, ., must be
specified to display the contents of more than one
storage location by byte count. The sum of hexloc1 and
bytecount must be an address that does not exceed the
virtual machine size.
If this addres~ is not on a
fullword boundary, it is rounded up to the next highest
fullword.
The value, bytecount, must have a value of
at least one and may be from one to six hexadecimal
digits; leading zeros are optional.
Greg1
is a decimal number from 0-15 or a hexadecimal integer
from O-F representing the first, or only, general
register whose contents are to be displayed at the
terminal. If G is specified without a register number,
the contents of all the general registers are displayed
at the terminal.
Yreg1
is an integer
(0, 2, 4, or 6)
representing the first,
or only, floating-point register whose contents are to
be displayed at the terminal.
If Y is specified
without a register number, the contents of all of the
floating-point
registers
are
displayed
at
the
terminal.
xreg1
is a decimal number from 0-15 or a hexadecimal number
from O-F representing the first, or only, control
register whose contents are to be displayed at the
terminal. If X is specified without a register number,
the contents of all of the control registers are
displayed at the terminal. If Xreg1 is specified for a
virtual machine
without extended
mode operations
available, only control register 0 is displayed.
-}reg2
{ : 1112
50
is a number representing the
last register whose
contents are to be displayed at the terminal. Either or : must be specified to display the contents of more
than one register by register number. If reg2 is not
specified, the contents of all registers from reg1
through the last register of this type are displayed.
IBM VM/370: System Programmer's Guide
The operand, reg2, must be equal to or greater than
reg1.
If Greg1 or Xreg1 are specified, reg2 may be a
decimal number from 0-15 or a hexadecimal number from
O-F. If Yreg1 is specified, reg2 may be 0, 2, 4, or
6. The contents of reqisters reql throuqh reg2 are
displayed at the terminai.
-{ • }regcount
].!!]
is a decimal number from
1 to 16 or a hexadecimal
number from 1 to F specifying the number of registers
(starting with reg1) whose contents are to be displayed
at the terminal. If the display type G or X is
specified, regcount can te a decimal number from 1 to
16 or a hexadecimal number from 1 to F. If display type
Y is specified, regcount must be 1, 2, 3, or 4. The
sum of reg1 and regcount must be a number that does not
exceed the maximum register number for the type of
registers being displayed.
PSW
displays the current virtual machine
status word) as two hexadecimal words.
CAW
displays as one hexadecimal word the contents
hexadecimal location 48 (channel address word).
CSW
displays as two hexadecimal words the contents of the
channel status word (double word at hexadecimal location
40) •
PSW
(program
of
When multiple operands are entered on a line for location or register
displays, the default display type is the same as the previous explicit
display type. The explicit specification of a display type defines the
default for subsequent operands for the current display function.
Blanks are used to separate operands or sets of operands if more than
one operand is entered on the same command line. Blanks must not be
used to the right or left of range or length delimiters (:
~):
unless it is intended to take the default value of the missing operand
defined by the blank. For example:
display 10 20 T40 80 G12 5 L60-100
displays the following:
hexadecimal location 10
hexadecimal location 20
hexadecimal location 40 with EBCDIC translation
hexadecimal location 80 with EBCDIC translation
general register 12
general register 5
hexadecimal locations 60 through 100
One or more of the following
operands specified.
responses is displayed, depending upon the
Part 1: Debugging with VM/370
51
xxxxxx word1 word2 word3 word4 [key] *EBCDIC TRANSLATION*
This is the response you
receive when you display storage
locations; XXXIXX is the hexadecimal storage location of word1.
Word1
is displayed
(word-aligned)
for
a single
location
specification. Up to four words are displayed on a line, followed,
optionally, by an EBCDIC translation of those four words.
Periods
are printed for unprintable characters. Multiple line are used (if
required) for a range of locations.
If translation to EBCDIC is
requested (Thexloc), alignment is made to the next lower 16-byte
boundary; otherwise, alignment is made to the next lower fullword
boundary.
If the location is at a 2K page boundary, the key for
that page is also displayed.
xxxxxx TO XXXXXX
KEY = kk
This is the response you receive when you display storage keys;
xxxxxx is a storage location and kk is the associated storage key.
GPR n = genreg1 genreg2 genreg3 genreg4
This is the response you
receive when you display general
registers; n is the register whose contents are genreg1.
The
contents of the following consecutive registers are genreg2 and so
on. The contents of the registers are displayed in hecadecimal.
Up to four registers per line are displayed for a range of
registers.
Multiple lines are displayed if required, with a
maximum of four lines needed to display all 16 general registers.
FPR n = xxxxxxxxxxxxxxxx
.xxxxxxxxxxxxxxxxx
E xx
This is the response you receive when you display floating-point
registers; n is the even-number floating-point register whose
contents are displayed on this line. The contents of the requested
floating-point registers are displayed
in both the internal
hexadecimal format and the E format. One register is displayed per
line.
Multiple lines are displayed for a range of registers.
52
IBM VM/370: Systea Programmer's Guide
ECR n = ctlreg1 ctlreg2 ctlreg3 ctlreg4
This is the response you
receive when you display control
registers;
n is the register whose contents are ctlreg1.
The
contents of the following consecutive registers are ctlreg2 and so
on. The contents of the requested control registers are displayed
in hexadecimal. Up to four registers per line are displayed.
Multiple lines are displayed if required.
PSW = xxxxxxxx
xxxxxxxx
The contents of the PSW are displayed in hexadecimal.
CAW
= xxxxxxxx
The contents of the CAW (hexadecimal
hexadecimal.
CSW
= xxxxxxxx
location 48) are displayed in
xxxxxxxx
The contents of the CSW (hexadecimal
hexadecimal.
location 40) are displayed in
Press the Attention key
(or its equivalent)
to terminate this
function while data is being displayed at the terminal. When the
display terminates, another command may be entered.
Use the DISPLAY co.mand to display the contents of various storage
locations, registers, and control words at the terminal. By examining
this type of information during the program's execution, you may be able
to determine the cause of program errors. Usually, an address stop is
set to stop the program execution at a specified point.
The system
enters the CP environment and you may then issue the DISPLAY command.
The DISPLAY command terminates if an invalid operand is specified
however, all operands preceding the invalid operand are processed before
DISPLAY terminates. To intentionally terminate the DISPLAY console
function, signal attention. The display terminates and another command
may be entered.
Part 1: Debugging with VM/370
53
Use the DUMP co •• and to print the contents of various components of the
virtual machine on the virtual spooled printer. The following items are
printed:
•
virtual program status word (PSi)
•
General registers
•
Floating-point registers
•
control registers
(if you have the
VM/370 directory entry)
•
storage keys
•
virtual storage locations
ECMODE option specified
in your
The DUMP com.and prints the virtual PSi and the virtual registers
(general, floating-point,
and control) •
If only this information is
desired, at least one virtual address must be specified, such as:
DUMP 0
The output format for the virtual storage locations is eight words
per line with EBCDIC translation on the right.
Each fullword consists
of eight hexadecimal characters. All the rest of the information (PSi,
general floating-point and storage keys)
is printed in hexadecimal. If
you have the ECMODE option in your VM/370 directory entry, the control
registers are also printed. To print the dump on the real printer, a
CLOSE command must be issued for the spooled virtual printer.
The
format of the DUMP command is:
DUMP
r
, r
r
,
ILhexloc111{-}lhexloc2 I
IThexlocll I : lEI]
I
I he xl 0 c 1 I I
L
.I
I
.Q
II
r
,
L
.I I{. 11 bytecount I
I
IlUH!
I
,
I
I
I
I
I
I
[*dumpid]
L
L
.I
.I
L-____________________________________________
.____________________________~
Lhexloc1
Thexloc1
hexloc1
Q
is the first or only hexadecimal storage location to
be dumped. If you enter L or T without operands, the
contents of all virtual storage locations are dumped.
The address, hexloc1, may be one to six hexadecimal
digits; leading zeros are optional.
If hexloc1 is not
specified, the dump begins at storage location O.
If hexloc1 is followed by a period and is not on a
fullword boundary, it is rounded down to the next lowest
fullword.
54
IBM VM/370: System Programmer's Guide
-}heXlOC2
{ : EN~
is the last hexadecimal storage location whose contents
are to be dumped to the printer. The operand, hexloc2,
must be equal to or greater than hexloc1 and within the
virtual storage size. To dump to the end of storage, you
can specify END instead of hexloc2 or you can leave the
field blank, since the default is END. If you specify
:END or -END, the contents of storage from hexloc1 to END
are dumped.
The contents of storage locations hexloc1
through hexloc2 are printed with EBCDIC translation at
the printer. The operand, hexloc2, may be from one to six
hexadecimal digits; leading zeros are optional.
{ • }bytecount
is a hexadecimal integer designating the number of bytes
of storage (starting with the byte at hexloc1) to be
dumped to the printer. The period, ., must be specified
to dump the contents of more than one storage location by
byte count. The sum of hexloc1 and bytecount must be an
address that does not exceed the virtual machine size.
If this address is not on a fullword boundary, it is
rounded up to the next highest fullword. The value,
bytecount, must be one or greater and can be no longer
than
six hexadecimal
digits.
Leading zeros
are
optional.
]1!~
*dumpid
can be entered for descriptive purposes.
If specified,
it becomes the first line printed preceding the dump
data. Up to 100 characters, with or without blanks, may
be specified after the
asterisk prefix.
No error
messages are issued, but only 100 characters are used,
including asterisks and embedded blanks.
Normally, you should
following manner:
define beginning and ending dump
dump Lhexloc1-hexloc2
dump Lhexloc1.bvtecount
dump Lhexloc1-hexloc2 hexloc1.bytecount
locations in the
*
dumpid
If, however, a blank follows the type character (L or T) or the
character and the hexloc, the default dump starting and ending locations
are assumed to be the beginning and/or end of virtual storage. Blanks
are used to separate operands or sets of operands if more than one
operand is entered on the same command line. Blanks must not be used to
the right or left of range or length delimiters ( : - • ), unless it is
intended to take the default value of the missing operand defined by the
blank. Thus, all of the following produce full storage dumps:
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump
1
t
.
1t1:
t:
1.
t.
00:
O.
I-end
't-end
dump
dump
dump
dump
dump
dump
dump
O-end
l:end
t:end
O:end
l.end
t.end
O.end
The following produces three full dumps:
dump 1
dump
..
t
:
Part 1 : Debugging with VM/370
55
DUMPING LOC hexloc
As the dump is processing, the following message is displayed at
the terminal indicating that the dump is continuing from the next
64K boundary: where hexloc is the segment (64~
boundary address
for the dump continuation, such as 020000, 030000, or 040000.
If you press the Attention key, or its equivalent, on the terminal
while the message is being displayed, the dump function is
terminated.
COMMAND COMPLETE
This response indicates normal completion of the dump function.
Use the DUMP command to dump to the virtual spooled printer the contents
of the specified storage locations. Issue the CLOSE command to the
spool printer to have the dump print at the real printer.
When debugging, issue the DUMP command to print information you want
to look at after the program executes.
Because the real printer may be
at a different location than your terminal, you cannot always look at
the printed output while the program is executing.
When you must examine large portions of storage, use the DUMP command
rather than the DISPLAY command. Because the terminal operates at a
much slower speed than the printer, only limited amounts of storage
should be printed (via the DISPLAY command) at the terminal.
The CP DUMP command executes in an area of storage separate from your
virtual machine storage and does not destroy any portion of your
storage.
56
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNt GN20-2662, March ..J.,1
I ,
Use the
system.
SET command to control various functions within
The format of the SET command is:
SET
10"7C
1.7 I..J
your virtual
ACNT
MSG
WNG
IMSG
RUN
1,1 NEDi t
ECmode
ISAM
NO TRans
PAGEX
EMSG
ON
}
OFF
{ CODE
, TEXT,
TIMER
Q!
OFF }
{ REAL
,
,
r
r
ION I ISVC
I
I INOSVCI
I
ASsist
L
1
l
1~~1~Y!!Q
PPnn
L
J
(
OFF
r
PFnn IIMMed
L
J
,
I [pfdata1#pfdata2# ••• pfdatan]
I
J
[TAB n1 n2 •••
PFnn COPY [resid]
L-___________________________________________________________
__
J
ACNT {ON }
OFF
controls whether accounting information is displayed at
the terminal or not (ON and OFF respectively)
when the
operator issues the CP ACNT command. When you log on
VM/370, ACNT is set on.
MSG {ON }
OFF.
controls whether messages sent ~y the MSG command from
other users are to be received at the terminal.
If ON is
specified, the messages are displayed.
OFF specifies
that no messages are received.
When you log on VM/370,
MSG is set on.
WNG {ON }
OFF
controls whether warning messages are displayed at the
terminal. If ON is specified, all warning messages sent
Part 1: Debugging with VM/370
57
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
via the CP WARNING command from the system operator are
received at the terminal. If OFF is specified, no
warning messages are received. When you log on VM/370,
WNG is set on.
IMSG {ON }
OFF
controls whether certain informational responses issued
by the CP CHANGE, DEFINE, DETACH, ORDER, PURGE, and
TRANSFER commands are displayed at the terminal or not.
The descriptions
of these CP commands
tell which
responses are
affected.
If
ON is
specified the
informational responses
are displayed.
If OFF
is
specified, they are not. The SET IMSG ON or OFF command
line has no effect on the handling of error messages set
by the SET EMSG command. When you log on VM/370, IMSG is
set on.
RUN {ON }
OFF
controls whether the virtual machine stops when the
Attention key is pressed. ON allows you to activate the
Attention key
(causing a read of a CP command) without
stopping your virtual machine. When the CP command is
entered, it is immediately executed and the virtual
machine resumes execution.
OFF
places the virtual
machine in the normal CP environment, so that when the
Attention key is pressed, the virtual machine stops.
When you log on VM/370, RUN is set off.
LINEDIT {ON }
OFF
controls the line editing functions.
ON specifies that
the line editing functions and the symbols of the VM/370
system are to be used to edit virtual CPU console input
requests. This establishes line editing features in
systems that do not normally provide them. OFF specifies
that no character or line editing is to be used for the
virtual machine operating system.
When you log on
VM/370, LINEDIT is set on.
ECMODE
controls whether
the
virtual
machine
operating
system may use System/370 extended control mode and
control registers 1 through 15. Control register zero may
be used with ECMODE either ON or OFF. When you log on
VM/370, ECMODE is set according to the user's directory
option; ON if ECMODE was specified and OFF if not.
Note: Execution of the SET ECMODE {ONIOFF} command always
causes a virtual system reset.
ISAM
controls whether
additional
checking
is
performed
on virtual I/O requests to DASD in order to support the
use of the as Indexed Sequential Access Method (ISAM).
When you log on VM/370, ISAM is set according to the
user's directory options; ON if ISAM was specified and
OFF if not.
NOTRA NS {ON }
OFF
controls CCW
translation for
CP.
NOTRANS can
be
specified only by a virtual machine that occupies the
virtual=real space.
It causes all virtual I/O from the
issuing
virtual
machine
to bypass
the
CP
CCW
translation.
To be in
effect in the virtual=real
58
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1q75
environment, SET NOTRANS ON must be issued after the
virtual=real machine is loaded via the IPL command.
(IPL
sets the NOTRANS option to an OFF condition.)
PAGEX {ON }
OFF
controls the
pseudo
page
fault
portion
of
the
VM/VS Handshaking feature. PAGEX ON or OFF should only be
issued for an OS/VS1 virtual machine that has the VM/VS
Handshaking feature active. It can only be specified for
a virtual machine that has the extended control mode
(ECMODE) option. PAGEX ON sets on the pseudo page fault
portion of handshaking; PAGEX OFF sets it off. When you
log on to VM/370, PAGEX is set OFF.
"'If~ro
controls error message handling. ON specifies that both
the error code and text are displayed at the terminal.
TEXT specifies that
only text
is displayed.
CODE
specifies that only the error code be displayed. OFF
specifies that no error message is to be displayed. When
you log on VM/370, EMSG is set to TEXT.
~nuu
{
VI'
"I.,
\,
OFF \
CODE'
TEXT'
Note, CMS recognizes EMSG settings for all error
(E),
information (I), and warning
(W) messages, but ignores
the EMSG setting and displays the complete message (error
code and text) for all response (R), severe error (S),
and terminal (T) messages.
controls the virtual
timer. ON specifies
that the
virtual timer is to be updated only when the virtual CPU
is running. OFF specifies that the virtual timer is not
be updated. REAL specifies that the virtual timer is to
be updated during virtual CPU run time and also during
virtual wait time. If the REALTIMER option is specified
in your VM/370 directory entry, TIMER is set to REAL when
you log on; otherwise it is set to ON when you log on.
TIMER {ON }
OFF
REAL
ASSIST
~
'?
I
rION , I rISVC
I
I INOSVC I
L
(
.J
OFF
L
.J
)
controls the availability of the virtual machine assist
feature for your virtual machine. The assist feature is
available to your virtual machine when you log on if (1)
the real CPU has the feature installed and (2) the system
operator has not turned the feature off. The SVC handling
portion of the assist feature is invoked when you log on
unless your VM/370 directory entry has the SVCOFF option.
Issue the QUERY SET command line to see if the assist
feature is activated and whether the assist feature or
VM/370 is handling SVC interrupts.
All SVC 76 requests are passed to CP
regardless of the SVC and NOSVC operands.
for
handling,
If you issue the SET ASSIST command line and specify SVC
or NOSVC while the virtual machine assist feature is
turned off, the appropriate bits are set. Later, if the
feature is turned on again, the operand you specified
while it was off becomes effective.
Part 1: Debugging with VM/370
59
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
eN sets the assist feature on for the virtual machine;
OFF turns it off. SVC specifies that the assist feature
handles all SVC interrupts except SVC 76 for the virtual
machine; NOSVC means VM/370 handles the SVC interrupts.
See the "Virtual Machine Assist Feature" discussion in
"Part 2: Control Program (CP)" for information on how to
use the assist feature.
r
,
PFnn IIMMED
I [pfdatal.pfdata2 •••• pfdatan]
IDELAYED I
L
defines a program function for a program function key on
a 3277 Display Station and indicates when that function
is to be executed. See the Y~Lll~: 1~!~!n~1 Q§~!~§ §~!Q~
for a description of how to use the 3277 program function
keys.
The value, nn, is a number from
1 (or 01) to 12 that
corresponds to a key on a 3277. The program function is a
"function", or programming capability, you create by
defining a series of VM/370 commands or data you want
executed. This series of commands executes when you press
the appropriate program function key.
IMMED specifes that the program function is executed
immediately after you press the program function key.
DELAYED specifies that execution of the program function
is delayed for a display terminal. When the program
function is entered, it is displayed in the input area
and not executed until you press the Enter key. DELAYED
is the default value for display terminals.
pfdatal.pfdata2 •••. pfdatan defines the VM/370 command or
data lines that constitute the program function. If more
than one command line is to be entered, the pound sign
(I) must separate the lines.
If you use the pound sign
(') to separate commands that you want executed with the
designated PF key, you must precede the command line with
ICP, turn line editing off, or precede each pound sign
with the logical escape character
("). For further
explanation, see
the "Examples of
setting Program
Function Keys" section that follows.
If no command lines
are entered, PFnn is a null command.
Program functions
cannot be embedded within one another.
PFnn TAB nl n2
specifies a program function number to be associated with
tab settings on a terminal. The number of the PF key, nn,
can be a value from 1 (or 01)
to 12. See the !~LJ1Q:
~~!1 §~!g~ for examples of how this feature is used.
TAB is a keyword identifying the tab setting function.
The tab settings may be entered in any order.
PFnn COPY [resid]
specifies that the program function key, numbered nn,
performs a COpy function for a remote 3270 terminal. nn
must be a value of 1 or 01 to 12. The COpy function
produces a printed output of the entire screen display at
the time the PF key is actuated. The output is printed on
an IBM 3284, 3286 or 3288 printer connected to the same
control unit as your display terminal.
60
IBM VM/370: System Programmer's Guide
GC20-1807-3
Modified by
March 3 i,
i975
The resid operand may be specified if more than one
printer is connected to the same control unit as your
display terminal. It is a three-character hexadecimal
resource identification number assigned to a specific
printer. If resid is entered, the printed copy is
directed to a specific printer; if not,
the copy is
printed on the printer with the lowest resid number. The
resid numbers of the printers available to your display
terminal can be obtained from your system operator. If
only one printer is available,
resid need not be
specified.
If the command is invalid or if the designated or default
printer is not free (other display terminals may be using
it) or is not connected to the same control uuit a~ your
display terminal, a NOT ACCEPTED message appears on the
screen,
If the printer was busy,
retry the operation
until the printer honors your request.
You may include your own identification on the printed
output by entering the data into the user input area of
the
screen before
you
press
the PF
key.
The
identification appears in the lower left of the printed
copy.
This example shows you how the SET PFnn command is processed if you do
not turn line editing off or use the logical escape character.
Enter one of the following commands while in CMS mode:
SET PF02 IMMED Q RDR'Q PTR'Q PUN
or
CP SET PF02 IMMED Q RDR'Q PTR'Q PUN
Now press the ENTER key:
1.
The ENTER key causes immediate execution,
2.
Only the Q PTR and Q PUN commands execute, and
3.
Q PTR and Q PUN are stripped from the PF02 key assignment leaving Q
RDR, which was not executed.
The following examples
problem.
demonstrate
two
methods for
avoiding
the
Enter one of the following commands while in CMS mode:
Part 1: Debugging with VM/370
60.1
ICP SET PF02 IMMED Q RDRIQ PTRIQ PUN
-- or
CP SET PF02 IMMED Q RDR"'Q PTR"IQ PUN
or
SET PF02 IMMED Q RDR"'Q PTR"'Q PUN
Now press the ENTER key.
CP assigns the three QUERY commands as functions of the
Pressing the PF02 key executes the three QUERY commands.
PF02 key.
Enter the following command while in CMS mode:
SET LINEDIT OFF
and press the ENTER key.
Then enter:
SET PF02 IMMED Q RDR'Q PTR'Q PUN
or
CP SET PF02 IMMED Q RDRIQ PTRIQ PUN
and press the ENTER key.
CP assigns the three QUERY commands as functions of the PF02 key.
Then enter:
SET LINEDIT ON
and press the ENTER key.
pressing the PF02 key executes the three QUERY commands.
* PFnn UNDEFINED
This response appears in the user area of the screen on
Display station if a PF key that is undefined is pressed.
a 3277
Use the SET command to control various systems options. In particular,
The messages
set the MSG, WNG, and EMSG options ON when debugging.
printing at the terminal may provide information that 'is immediately
helpful.
Part 1: Debugging with VM/370
61
Use the STORE co •• and to alter the contents of specified registers and
locations of the virtual aachine. The contents of the folloving can be
al tered:
•
•
•
•
•
Virtual storage locations
General registers
Floating-point registers
Control registers (if available)
program status vord
The STORE command can also save virtual machine data in lov storage.
The operands may be combined in any order desired, separated by one
or more blanks, for up to one full line of input.
If an invalid operand
is encountered, an error aessage is issued and the store function is
terminated. Hovever, all valid operands entered, before the invalid
one, are processed properly.
Storage locations, registers, the PSW, and status can be stored using
a single command line. When you combine the operands for storing into
storage, registers, the PSi, or the status area on a single command
line, all operands must be specified; default values do not aFply in
this case.
The format of the STORE command is:
STore
hexloc
Lhexloc
hexvordl [hexvord2 ••• ]
Shexloc
hexda ta •••
Greg}
{ Yreg
Xreg
Psv
hexvordl [hexvord2 ••• ]
[ hexvord 1] hexvord2
STATUS
hexloc
Lhexloc
hexvord 1 [hexvord2 ••• ]
stores the
specified data
(hexvordl [hexvord2 ••• ])
in
successive fullvord
locations starting
at the
addres~
specified by hexloc. The smallest group of hexadecimal values
that can be stored using this form is one fullvord. Alignment
is made to the nearest fullvord boundary.
Either form (hexloc
or Lhexloc) can be used.
The operands (hexvordl hexvord2 ••• ) each represent up to eight
hexadecimal digits. If the value tein9 stored is less than a
fullvord (eight hexadecimal digits), it is right-adjusted in
62
IBM VM/370: System Programmer's Guide
the word and the high order bytes of the word are filled with
zeros. If two or aore hexwords are specified, they must be
separated by one or more blanks.
Shexloc hexdata •••
stores the
data specified (hexdata ••• ) in
the address
specified by hexloc, without word alignment. The shortest
string that can be stored is one byte (two hexadecimal
digits). If the string contains an odd number of characters,
the last character is not stored, an error message is sent,
and the function is terminated.
The operand, hexdata, is a string of two
digits with no embedded blanks.
or more hexadecimal
Greg hexword 1 [hexword2 ••• ]
stores the hexadecillal da ta
(hexword 1 [hexword2 ••• ]) in
successive general
registers starting
at the
register
specified by reg. The reg operand must be either a decimal
number from 0-15 or a hexadecimal digit from O-F.
The operands (hexword1 [hexword2 ••• ]) each represent up to
eight hexadecimal digits. If less than eight digits are
specified, the string is right justified in a full word and
left-filled with zeros. If two or lIore hex words are specified,
they must be separated by one or more blanks.
Yreg hexword 1 [hexword2 ••• ]
stores the hexadecimal data
(hexword1 [hexword2 ••• ]) in
successive floating-point registers starting at the register
specified by reg.
The reg operand must be a digit from 0-6.
If reg is an odd number, it is adjusted to the preceding even
number.
The operands (hexword1 [hexword2 ••• ] each represent up to
eight hexadecimal digits. If less than eight digits are
specified, the string is right justified in a fullword and
left-filled with zeros. If two or more hexwords are specified,
they must be separated by one or more blanks.
Xreg hexword1 [hexword2 ••• ]
stores the hexadecimal data
(hexword 1 [hexword2 ••• ]) in
successive control
registers starting
at the
register
specified by reg. The reg operand must either be a decimal
number from 0-15 or a hexadecimal digit from O-F. If the
virtual machine is in basic control mode, you can store data
in register 0 only.
The operands (hexword1 [hexword2 ••• ]) each represent up to
eight hexadecimal digits. If less than eight digits are
specified, the string is right justified in a fullword and
left-filled with zeros. If two or more hexwords are specified,
they must be separated by one or more blanks.
PSi [hexword1] hexword2
stores the hexadecimal data ([hexword1] hexword2) in the first
and second words of the virtual machine's program status word
(FSi). If only hexword2 is specified, it is stored into the
second word of the PSi.
The operands hexword1 and hexword2
must be separated by one or more blanks. They represent up to
eight hexadecimal digits. If less than eight digits are
specified, the string is right justified and left-filled with
zeros.
Part 1: Debugging with '"/370
63
STATUS
stores selected virtual machine data in certain low storage
locations of the virtual machine, siaulating the hardware
store status
facility. These locations
are peraanently
assigned locations in real storage.
To use the STATUS
operand, your virtual machine must be in the Extended control
Mode. The STATUS operand should not be issued for CftS virtual
machines or for
DOS virtual machines generated for a CPU
smaller than a Systea/360 Model 40. The STATUS operand stores
the following data in low storage:
Deciaal
Hexadecimal
Length
!gg!~§§
!gg!~§§---
in~I1~§
216
224
256
352
384
448
D8
EO
100
160
180
lCO
8
8
8
32
64
64
Data
CPU-Timer
clock Comparator
Current PSW
Floating-point registers 0-6
General registers 0-15
Control registers 0-15
STORE COMPLETE
Use the STORE command to alter the contents of virtual storage
locations, registers, and the PSi. ihen debugging, you may find it
advantageous to alter storage, registers, or the PSi and then continue
execution. This is a good procedure for testing a proposed change.
Also, you can make a temporary correction and then continue to check
that the rest of execution is trouble-free.
With the STORE command, data is stored
with fullword boundary alignment or in
alignment.
either in units of one word
units of one byte without
The STORE STATUS command stores data in the extended logout area.
The STORE STATUS command stores CPU Timer and Clock Comparator values
that may then be displayed at the terminal via the DISPLAY co.mand. The
procedure is the only way to get timer information at the terminal.
One debugging use of STORE STATUS would be as follows:
1.
Issue the STORB
to debug.
2.
When execution stops (because an address stop was reached or
because of a failure) display the extended logout area. This area
contains the status that was stored before entering the routine.
3.
Issue STORE STATUS again and display the extended logout area
again.
You now have the status information before and after the
failure.
This inforaation could help you solve your problem.
64
STATUS co.mand before entering a
IBM VM/370: Systea Programmer's Guide
routine you wish
Use the SYSTEM command to simulate the action of the RESET and RESTART
buttons on the real computer console, and to clear storage. The RESET
function and the CLEAR function leave the virtual machine in a stopped
state. An IPt command must be issued after a SYSTEM CLEAR command.
After a SYSTEM RESTART, the virtual machine is automatically restarted
at the location loaded into the PSi from tbe doubleword at virtual
location zero. The format of the SYSTEM command is:
System
CLEAR }
RESET
{ RESTART
CLEAR
clears
zeros.
virtual storage
and virtual
RESET
clears all
machine.
RESTART
simulates the hardware system RESTART function by storing the
current PSi at virtual location eight and loading, as the new
PSi, the doubleword from virtual location zero.
Interrupt
conditions and storage remain unaffected.
pending interrupts and
storage
keys to
conditions in
binary
the virtual
STORAGE CLEARED - SYSTEM RESET
This response is given if the com.and SYSTEM CLEAR is entered.
SYSTEM RESET
This response is given if the command SYSTEM RESET is entered.
If the command SYSTEM RESTART is entered, no response is given; the
virtual macbine resumes execution at the address in the virtual PSi
loaded from virtual storage location zero.
Use the SYSTEM command to simulate the Reset and PSi Restart buttons on
the computer console. Also, use the SYSTEM command to clear storage and
its associated storage keys. It is a good practice to clear storage to
binary zeros before you IPL a system.
Part 1: Debugging with VM/370
65
After issuing the SYSTEft com.and with RESET or CLEAR specified,
either STORE a PSi and issue EEGIN or issue EEGIN with a hexadecimal
storage location specified, to resuae operation. The virtual machine
automatically restarts at the location specified in the new PSi (which
is loaded from the doubleword at location zero) after the SYSTEM RESTART
co •• and is processed.
66
lEft V8/370: System Programmer's Guide
Use the TRACE command to trace specified virtual machine activity and to
record the results at the terminal, on a virtual spooled printer, or on
both terminal and printer. If trace output is being reccrded at the
terminal, the virtual machine stops execution and CP command mode is
entered after each output message. This simulates the single ~yc~e
function. To resume operation at the virtual machine, the BEGIN command
must be entered. If the RUN operand is specified, the virtual machine is
not stopped after each output message.
If trace output is being
recorded on a virtual sPooled printer. a CLOSE command must be issued to
that printer in order for the- trace" output to be printed. Successful
branches to
the next
sequential instruction
and branch-to-self
instructions are not detected by TRACE. Instructions that modify or
examine the first two bytes of the next sequential instruction cause
erroneous processing for BRANCH and INSTRUCT tracing.
When tracing on a virtual machine with only one printer, the trace
data is intermixed with other data sent to the virtual printer. To
separate trace information from other data, define another printer with
a lower virtual address than the previously defined printer. For
example, on a system with OOE defined as ~ne only printer, define a
second printer as OOB. The regular output goes to OOE and the trace
output goes to OOB.
When operation of a
options cannot be used:
traced, the
following
I/O operations for virtual channel-to-channel adapters, with
connected to the same virtual machine, cannot be traced.
both ends
•
•
•
shared system
is being
BRANCH
INSTRUCT
ALL
The format of the TRACE command is:
TRace
,
r
1 I Printer
,SVC
I/O
I r
PROgram
I 111~~inall
EXTernal
I IBOTH
I
J
PRIV
I L
SIO
I
CCW
I OFf
L
BRanch
INSTruct
ALL
CSW
,
,
I
I
I
I
I
I
r
I!Q~Y~I
IRUN
L
J
I
I
J
END
1More than one of these activities may be traced by using a single
TRACE command. For example:
TRACE SVC PROGRAM SIO PRINTER
Part 1: Debugging with VM/370
67
GC20-1807-3 Paqe Modified by TNL GN20-266L, March 31,
1975
SVC
traces virtual machine SVC interrupts.
1/0
traces virtual machine 1/ 0 interrupts.
PROGR~M
traces virtual machine program interrupts.
EXTERNAL
traces virtual machine external interrupts.
PRIV
traces all virtual machine non-I/O privileged instructions.
SIO
traces TIO, CLRIO, HIO, HDV and TCH instructions to all
virtual devices.
Will also trace SIO and SIOF instructions
for non-console and non-spool devices only.
CCW
traces virtual and real CCWs for non-Spool/non-Console device
I/O operations. When CCW tracing is requested, SIO and TIO
instructions are also traced.
BRANCH
traces all virtual machine interrupts, all
and all successful branches.
INSTRUCT
traces all instructions,
successful branches.
ALL
traces all instructions,
interrupts, successful branches,
privilege instructions, and virtual machine I/O operations.
CSW
provides contents of virtual and
1/0 interrupt.
END
terminates
all
tracing
PSW instructions,
machine
virtual
interrupts
and
real channel status words at
activity and
prints
a
termination
message.
PRINTER
PRT
directs tracing output to a virtual spooled printer.
±]B~l!!~
directs tracing
console).
BOTH
directs tracing output
the terminal.
OFF
halts tracing of the specified
and terminal.
output
to
the
terminal
to both a virtual
(virtual
machine
spooled printer and
activities on both the printer
stops program execution after the trace output to the terminal
and enters CP command mode.
lig~~:
If a Diagnose code X'008'
is being traced, NORUN has no
effect and program execution does not stop.
RUN
continues the program execution after the trace output to the
terminal has completed and does not enter CP command mode.
Notes:
-1:--If your virtual machine has the virtual=real option and NOTRANS set
on, CP forces CCW translation while tracing either SIO or CCW. When
tracing is terminated with the TRACE END command, CCW translation
is bypassed again.
2.
68
If the virtual machine assist feature is enabled on your virtual
machine, CP turns it off while tracing SVC and program interrupts
IBM VM/370: System Programmer's Guide
GC20-i807-3 page Modified by TNL GN20-2662, March 31, 1975
(SVC,
PRIV, BRANCH,
INSTRUCT, or ALL). After the tracing is
terminated with the TRACE END command line, CP turns the assist
feature on again.
The following symbols are used in the responses received from TRACE:
.§.Y!!£21
vvvvvv
tttttt
rrrrrr
xxxxxxxx
yyyyyyyy
ss
ns
zz
zzzzzzzz
type
V vadd
R radd
mnem
int
code
CC n
IDAL
***
==)
~g~!!!!!g
virtual storage address
virtual transfer address or new PSW address
real storage address
virtual instruction, channel command word, CSW status
real instruction, CCW
argument byte (SSM-byte) for SSM instruction
new system mask after execution of STOSM/STNSM
low order byte of Rl register in an execute instruction
(not shown if Rl register is register 0)
referenced data
virtual device name (DASD, TAPE, LINE, CONS, RDR,
PRT, PUN, GRAF, DEV)
virtual device address
real device address
mnemonic for instruction
interrupt type (SVC, PROG, EXT, I/O)
interrupt code number (in hexadecimal)
condition-code number (0, 1, 2, or 3)
Indirect data address list
virtual machine interrupt
privileged operations
transfer of control
TRACE STARTED
This response is issued when tracing is initiated.
TRACE ENDED
This response is issued when tracing is suspended.
I/O vvvvvv TCH xxxxxxxx type vadd CC n
I/O vvvvvv mnem xxxxxxxx type vadd CC n type radd CSW xxxx
I/O vvvvvv mnem xxxxxxxx type vadd CC n type radd CSW xxxx CAW vvvvvvvv
CCW vvvvvv xxxxxxxx xxxxxxxx rrrrrr yyyyyyyy yyyyy-!yy
CCW IDAL vvvvvvvv vvvvvvvv IDAL OOrrrrrr OOrrrrrr
CCW SEEK xxxxxxxx xxxxxx
SEEK yyyyyyyy yyyy
Part 1: Debugging with VM/370
69
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
The IDAL or SEEK line is included only if applicable. The virtual IDAL
is not printed if the real eew opcode does not match the real eew.
!!!.§1!B!£1!Q1!
1~!£!1!'§:
~£!!!l~g~g .!!!§~!:'!!£~.!.Q!!:
· ..
· ..
· ..
· ..
· ..
· ..
· ..
· ..
· ..
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
SSM
SSM
STOSI!
STOSI!
STNSM
STBSM
LPSW
LPSW
mnem
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
ss
ss
ns
ns
ns
ns
==)
(normal SSM)
(switch to/from translate mode)
(normal STOSI!)
tttttt
(switch to translate mode)
(normal STNSM)
(switch from translate mode)
tttttt
tttttttt tttttttt
(WAIT bit on)
tttttttt tttttttt
(WAIT bit not on)
(all others)
tttttt
vvvvvv EX xxxxxxxx zz vvvvvv mnem xxxx xxxxxxxx
For an executed instruction, where zz (see preceding explanation of
symbols) is nonzero, the mnemonic for the executed instruction is given
as if the zz byte had been put into the instruction with an OR
operation.
vvvvvv mnem xxxxxxxx xxxx
vvvvvv mnem xxxxxxxx
*** vvvvvv int code
!LQ
l!Il!!Hi.Q~1
==)
tttttt
==) t t t t t t
(First line given only if
"esw" was specified):
esw V vadd xxxxxxxx xxxxxxxx R radd yyyyyyyy yyyyyyyy
*** vvvvvv I/O vadd ==) tttttt esw xxxx
]~!!£]
IR!£l!: (ALL option selected)
Entry for 'branch from' instruction
vvvvvv mnem xxxxxxxx
tttttt
Entry for 'branch to' instruction
==)
vvvvvv mnem xxxxxxxxxxxx
70
IBM VM/370: System Programmer's Guide
Use the TRACE command to trace specified virtual machine activity and to
record the results at the terminal, at a virtual printer r or at both.
This command is useful in debugging programs because it allows you to
trace only the information that pertains to a particular problem.
When the terminal is used for the trace output, the virtual machine
stops executing after each output message is printed and the system
enters the CP environment. At this time, other commands may be issued
to display, dump, or alter storage. Using the terminal for trace output
thus simulates the single cycle execution function of the computer
console. To resume execution, the BEGIN command must be issued.
When the virtual printer is used for trace output, a CLOSE command
must be issued to the virtual printer in order for the trace information
to print at the real printer.
A successful branch to the next sequential instruction and a branch
to self instruction are not traced.
Any instruction that modifies or
examines the first two bytes of the next sequential instruction causes
erroneous processing for BRANCH and INSTRUCT tracing.
Part 1: Debugging with ,"/370
71
CP real machine debugging is reserved for Class C users
(system
programmers) and Class E users (system analysts). CP has facilities to
examine data in real storage (via the DCP and D"CP commands)
and to
store data into real storage (via. the STCP co •• and).
There is no
facility to examine or alter real machine registers, PSi, or storage
words.
Remember, real storage is changing even
to examine and alter it.
as you issue the CP commands
system programmers and analysts may also want to use the CP internal
trace table.
This table records events that occur on the real machine.
72
IB" V"1370: System Programmer's Guide
Use the DCP command to display the contents of real storage locations at
the terminal.
If an invalid argument is entered, the DCP command terminates
however, any previous valid arguments are processed before termination
occurs. The format of the DCP command is:
r---------------------------------.---------------------------------------,
r
DCP
,r
r
"
L
L
.J
ILheXIOC111{-}1 hexloc2 I
IThexlocll I : 1 ~!~
1
1 hexloc 11 1
L
.J
.Q
11
1
L
.J 1
1
r
,
I{. }Ibytecount 1
1
IEN~
1
Lhexloc1
Thexlocl
hexloc1
I
I
1
1
1
1
1
I
.J
is the first or only storage location to be displayed
in hexadecimal. If hexloc1 is not specified, L or T must
be specified and the display begins with storage location
O. If hexlocl is specified and L or T is not specified,
the display is the same as if L were specified. If T is
specified, an EBCDIC translation is included with the
hexadecimal display.
o
If hexlocl is followed by a period and is not on a
fullword boundary, it is rounded down to the next lower
fullword.
r
,
1hexloc21
I ~!Q
I
L
r
.J
specifies that a range of locations is to be displayed.
To display
the contents
of one
or more
storage
locations by specified storage address location the "-"
or ":" must be used. The hexloc2 operand must be 1 to 6
hexadecimal
digits;
leading zeroes
need
not
be
specified.
In addition, The hexloc2 operand must be
equal to hexloc1 and it should not not exceed the size of
real storage.
If END is specified, real storage from
hexlocl through the end of real is displayed. If hexloc2
is not specified, END is assumed by default. Note that
this occurs only if "-"or";" follows the first operand.
,
{. }Ibytecountl is a hexadecimal integer designating
the number of
1 j!~
1 the number of bytes of real storage (starting with
L
.J the byte
at hexloc1) to be displayed on the terminal.
The sum of hexloc1 and the bytecount must be an address
that does not exceed the size of real storage. If this
address is not on a fullword boundary, it is rounded up
to the next higher fullword.
The bytecount operand must
be a value of 1 or greater and may not exceed 6
hexadecimal digits.
Part 1: Debugging with VM/370
73
Normally,
a user will or should define the
locations of storage in the following aanner:
dcp
dcp
dcp
dcp.
dcp
beginning
and
ending
Lhexloc1-hexloc2
Thexlocl-hexloc2
hexloc1:hexloc2
hexloc1.bytecount
hexloc1:hexloc2 hexlocl.bytecount
lote that no blanks can be entered between the liait or range symbols
(:, -, or.)
or any of the operands except for the blank or blanks
between the coaaand name and the first operand.
1 blank is also
required between each set of operands when more than one set of operands
are entered on one coaaand line.
If,
how~ver,
a blank imaediately
follows the designated type
character
(T or L) DCP displays all of real storage.
If the next
operand is either a colon (:), a hyphen (-), or a period (.) followed by
a blank character, the system again defaults to a display of all storage
locations as this operand assuaes a second set of operands.
!2te: Blanks separate operands or sets of operands if more than one
operand is entered on the same co.aand line. Blanks should not occur on
the right or left of range or length syabols, unless it is intended to
take the default value of the missing operand defined by the blank.
The following are
displays.
dcp
dcp
dcp
dcp
dcp
dcp
dcp
1
t
-
examples of DCP entries that
dcp
dcp
dcp
dcp
dcp
dcp
dcp
•
11:
The following
eabedded blanks:
t:
1.
t.
00:
1-end
t-end
displays all
dcp
dcp
dcp
dcp
dcp
dcp
produce full storage
O-end
t:end
t:end
O:end
I.end
O.end
of storage
three times
because of
the
dcp 1 • t
Requested locations are displayed in the following format:
xxxxxx
= wordl
word2 word3 word4 [key]
*BBCDIC trans1ation*
where xxx xxx is the real storage location of wordl.
"word1" is
displayed (word aligned) for a single hexadecimal specification.
Up to four words are displayed on a line. If required, multiple
lines are displayed.
The EBCDIC translation is displayed aligned
to the next lower 16-byte boundary if Thex10c is specified.
Nonprintab1e characters display as a ".".
If the location is at a
2K page boundary the key for that page is also displayed. The
output can be stopped and the command terminated by pressing the
1TTN key (or its equivalent).
74
IBM VM/370: System Programmer's Guide
Use the DCP command to display real storage locations at the terainal.
The requested locations are typed in the following format:
xxxxxx = WORD1 WORD2 WORD3 WORD4 [EBCDIC translation]
where XXX XIX is the real storage location of WORD1. WORD1 is displayed
(word aligned) for a single hexloc specification. Up to four words are
displayed on a line. If required, multiple lines are printed. The EBCDIC
translation is displayed if Thexloc is specified.
Part 1: Debugging with V"/370
75
Use the DftCP co •• and to print the contents of real storage locations on
the user's virtual spooled printer. The output format is eight words
per line with EBCDIC translation. ftultiple storage locations and ranges
may be specified.
To get the output printed on the real printer, the
virtual spooled printer must be terminated with a CLOSE co •• and. The
format of the DMCP com.and is:
r
DftCP
, r
ILhexloc1
I Thexloc 1
I hexloc1
I
.Q
L
Q
L
.I
.I
,
is a range of real storage locations to be dumped.
To dump to the end of real storage, hexloc2 may be
specified as ERD or not specified at all, in which case
END is assumed by default.
I hexloc21
11!!~
I
r
I [*dumpid]
I
I
I
I
I
I
I
is the first or only storage location to be dumped. If
hexloc1 is not specified, L or T must be specified and
dumping starts with location O.
If hexloc1 is specified
and L or T are not specified, an EBCDIC translation is
included with the hexadecimal dump contents. If hexloc1
is followed by a period and is not on a fullvord
boundary, it is rounded down to the next lower fullword.
Lhexloc1
Thexloc1
hexloc1
L
,,
,
L
r
r
II{ - }I hexloc2 I
I I : I ~I~
I
L
.I
II
II
.I I
I
r
I{. Jlbytecount I
IERD
I
I
.I
,
{. }Ibytecountl is a hexadecimal integer designating
the number of
IEN~
I bytes of
real
storage
(starting
with
the
byte
L
.I at
hexloc1) to be typed at the printer.
The sum of
hexloc1 and the bytecount must be an address that does
not exceed the size of real storage. If this address is
not on a fullword boundary, it is rounded up to the next
higher fullword.
If the "." is used for a range, hexloc2 is defined as the
number of hexadecimal storage locations (in bytes) to be
dumped starting at hexloc1. If hexloc2 is specified as a
length, it must have a value such that when added to
hexloc1 it will not exceed the storage size.
*dum~id
16
is specified for identification purposes. If specified,
it becomes the first line printed preceding the dump
data. Up to 100 characters with or without blanks may be
specified after the asterisk prefix.
If dumpid is
specified, hexloc2 or bytecount must be specified. The
asterisk (*) is required to identify the dumpid.
IBM Vft/310: System Programmer's Guide
Normally, a user would define beginning and ending dump locations in the
following manner:
dmcp Lhexloc-hexloc
or
dmcp hexloc.bytecount
Note that there are no blanks between length or range symbols (-,:,
or.) or between any of the operands except for the blank(s) between
the command and the first operand. A blank is also required between
each set of operands when more than one set of operands are entered.
Hote, only one ., :, or - or no delimiter may be used within each set of
operands.
If, however, a blank immediately
follows the designated type
character, the default dump starting and ending locations are assumed to
be the beginning and/or end of virtual storage. similarly, if the range
or length symbol separates the first character from a blank or END, all
of real storage is dumped.
Blanks separate operands or sets of operands if more than one
operand 1S entered on the same command line. Blanks should not occur on
the right or left of the range or length symbol, unless it is intended
to take the default value of the missing operand defined by the blank.
Thus, all of the following produce full storage dumps.
!Q!~:
dmcp 1
dmcp t
dmcp dmcp
dmcp
.
dmcp
dmcp
dmcp
dmcp
dmcp
1-
t1:
t:
1.
Each of the following
embedded blanks:
dmcp
dmcp
dmcp
dmcp
dmcp
dmcp
dmcp
dmcp
dmcp
dmcp
t.
00:
O.
1-end
produces three
full
t-end
O:end
l.end
l.end
O.end
dumps
because of
the
dmcp 1 • t
dmcp In cases where multiple storage ranges or limits are specified on
one command line and the line contains errors, command execution
successfully processes all correct operands to the encountered error.
The encountered error and the remainder of the command line is rejected
and an appropriate error message is displayed.
!Q!~:
As the dump proceeds, the following message appears at the terminal
indicating that the dump is continuing from the next 64K boundary:
DUMPING LOC hexloc
where "hexloc" is the segment (64K) address for
such as 020000, 030000, 040000.
the dump continuation,
If the user signals attention on the terminal !hi!g the above message
is displayed, the dump ends.
COMMAND COMPLETE
indicates normal completion of the dump.
Part 1: Debugging with VM/370
77
Use the DMCP command to dump the contents of real storage locations to
your virtual spooled printer. The output format is eight words per line
with EBCDIC translation.
If a du.pid is used, it aay be up to 100
characters, including blanks. In order to print the output at the real
printer, the virtual spooled printer must be terminated with a CLOSE.
78
IBM VM/370: System Programmer's Guide
com.and to find the addresses of CP control
a particular user, a user's virtual device, or
The control blocks and their use are described
Pro~l:!! (~f) fl:~gl:!! 1~g!£.
The format of the
Use the LOCATE
associated with
system device.
!~nl.Q: ~~1!!l:~.!
blocks
a real
in the
LOCATE
command is:
! userid
LOCate
lraddr
[vaddr] \
J
userid
is the user identification of the logged on user. The address
of this user's virtual machine block (V~BLOK) is printed.
vaddr
causes the virtual channel block (VCBBLOK), virtual control
unit block (VCUBLOK), and virtual device block
(VDEVBLOK)
addresses associated with this virtual device address to be
printed with the VMBLOK address.
raddr
causes the real channel block (RCBBLOK), real control unit
block (RCUBLOK),
and the real device
block
(RDEVBLOK)
addresses associated with this real device address to be
printed.
V~BLOK
= XXXXXX
VMBLOK
VCBBLOK
VCUBLOK
VDEVBLOK
XXXXXX
xxxxxx
XXX XXX
xxxxxx
RCBBLOK
RCUBLOK
RDEVBLOK
xxxxxx
XXX XXX
XXX XXX
Use the LOCATE command to find the addresses of the system control
blocks associated with a particular user, a user's virtual device, or a
real system device.
Part 1: Debugging with VM/370
79
Once you know the location of the system control blocks you can
exaaine (dump or display) the block you want to see.
When you want to
examine specific control blocks, use the co.mands LOCATE and DOftP or
DISPLAY to examine the control blocks, instead of taking a dump. A
discussion of the most important fields of the VftBLOK, VCHBLOK, VCOBLOK,
VDEVBLOK, BCHBLOK, BCOBLOK, and BDEVBLOK are included in the "Beading CP
ABEND Dumps" section.
80
IBft Vft/370: System Programmer's Guide
GC20-i807-3 Page Hodified by TNL GN20-2662, Harch 3i, i975
Use the MONITOR command to initiate or terminate the recording of events
that occur in the real machine. This recording is always active after a
VM/370 IPL (manual or automatic). The events that are recorded in the
CP internal trace table are:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
External interruptions
SVC interruptions
Program interruptions
Machine check interruptions
I/O interruptions
Free storage requests
Release of free storage
Entry into scheduler
Queue drop
Run user requests
start I/O
Unstack I/O interruptions
storing a virtual CSW
Test I/O
Halt device
Unstack IOELOK or TRQELOK
NCP BTU (Network control Program Basic Transmission Unit)
Use the trace table to determine the events that preceded a CP system
failure.
Refer to the "CP Internal Trace Table" section of this manual
for information on finding and using the internal trace table.
The
format of the MONITOR command for tracing events in the real machine is:
I r---------------·--------·----------STArt CPTRACE'l
I I MONitor
{ STOP CPT RACE f
I I
I L
START CPT RACE
starts the tracing of events that occur on the real machine.
The events are recorded on the CP internal trace table in
chronological order.
When the end of the table is reached,
recording continues at the beginning of the table, overlaying
data previously recorded.
I STOP CPTRACE
terminates the internal trace table event tracing.
Event
recording ceases but the pages of storage containing the CP
internal trace table are not released.
Tracing can be
restarted at any time by issuing the MONITOR START CPTRACE
command.
COMMAND COMPLETE
The MONITOR command was processed successfully.
Part 1: Debugging with VM/370
81
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Use the QUERY command to request system status and machine configuration
information.
(For 3704 or 3705 Communication Controllers see also the
NETWORK command.)
Not all operands are available in every privilege
class. Operands available to the specified privilege classes are given
below. The format of the Class A and E QUERY command is:
Query
I {PAGing
}
I PRIORity use rid
I SASsist
PAGING
displays the current system paging activity.
PRIORITY userid
displays the current priority of the specified
userid. This is established in the VM/370 directory
but can be overridden by the SET PRIORITY nn
command.
SASSIST
displays the current status of the virtual Machine
Assist feature for the VM/370 system.
PAGING nn, SET mm, RATE nnn/SEC INTERVAL= xx:xx:xx
82
nn
specifies the percentage of time the
page wait during this time interval.
mm
is the
system paging activity
index
(threshold
value). This value affects the paging rate and degree
of multiprogramming that VM/370 tries to attain. The
value mm is normally 16.
nnn/SEC
is the current CP paging rate in pages per second.
xx:xx:xx
is the time interval
PAGING commands.
IBM VM/370: System Programmer's Guide
between the
system was
issuance of
in
QUERY
userid PRIORITY = nn
nn is the the assigned priority of the
lower the value, the higher the priority.
ON or OFF is indicative that
specified user.
The
the virtual ftachine Assist feature
is enabled or disabled from the system.
The QUERY comJand tells you the value of the paging activity index and
the priority.
This information ca~ be useful in evaluating the
usefulness of the perforJance options and in examining dispatching
functions.
See "Part 4. IBft 3704 and
description of this command.
3705
Communications Controllers"
for
Part 1: Debugging with Vft/370
a
83
Use the SAVESIS command to save a virtual machine storage space wi th
registers and PSi as they currently exist. The format of the SAVESIS
com.and is:
SAVESIS
systemname
systemname
must be a predefined name representing a definition of
installation requirements of the named system.
The
definition indicates the number of pages to be saved, the
DASD volume on which the system is to be saved, and the
shared segments (if any).
Refer to the discussion of
named systems in Named systems" section of for further
information concerning saved systems.
SISTEft SAVED
See the "Generating Named Systems" section of "Part 2. Control Program
(CP)" for a complete discussion of when and how to save a named system.
84
lBB Vft/370: System Programmer's Guide
Use the STCP command to alter the contents of real storage.
The real
PSi or real registers cannot be altered with this command. The format
of the STCP command is:
r-======~~~--------------------------------------------------------------~
STCP
heXIOC}
{ Lhexloc
{
Shexloc
hexword1 [hexword2 ••• ] }
hexdata
L
hexloc
Lhexloc
stores the data given in hexword1 [hexword2 ••• ] in successive
fullword locations starting at the address specified by
hexloc. The saallest group of hexadecimal values that can be
stored using this specification is one fullword. Data is
aligned to the nearest fullword boundary. If the data being
stored is less than a fullword (eight hexadecimal digits), it
is right-adjusted in the word and the high order bytes of the
word are filled with zeros.
Either specification
(hexloc or
Lhexloc) may be used.
Shexloc
stores the data given in hex data in the address specified by
hexloc without word alignment. The shortest string that can
be stored is one byte (two hexadecimal digits). If the string
contains an odd nuaber of characters, the last character is
not stored.
An error message occurs and the function ends.
hexword
specifies up to eight hexadecimal digits.
If less than eight
digits are specified, the string is right justified in a
fullword and left-filled with zeros.
If two or aore hexwords
are specified, they must be separated by at least one blank.
hex data
specifies a string
embedded blanks.
of two or aore hexadeciaal
digits with no
STORE COMPLETE
Use the STCP command to alter the contents of real storage.
PSi or real registers may !2! be altered by this command.
The real
Part 1: Debugging with V"/370
85
The DASD Dump Restore (DDR) program can be run standalone in the real or
virtual machine.
To run DASD Dump Restore standalone, IPL an input
device that contains all the necessary control statements. The centrol
statements necessary to run the DDR program are:
•
•
I/O Definition statements
Function statements
DDR CONTROL STATEftENTS
Control statements describe the processing that is to take place and the
I/O devices that are to be used. I/O definition statements must be
specified first.
All control statements may be entered from the system console or a
card reader.
Only columns 1 to 71 are inspected by the program. All
data after the last possible parameter in a statement is ignored. An
output tape must have the DASD cylinder header records in ascending
sequences; therefore, the extents must be entered in sequence by
recorded cylinders. Only one type of function - dump, restore, or copy may be performed in one execution, but up to 20 statements describing
cylinder extents may be entered. The function statements are delimited
by detection of an input or output statement, or by a null line if the
console is used for input. If additional additional functions are to be
performed, the sequence must be repeated. Only those statements needed
to redefine the I/O devices are necessary for subsequent steps.
All
other I/O definitions remain the same.
To return to CftS, enter a null
the prompting message (ENTER:).
line (carriage return) in response to
The PRINT and TYPE statements work differently in that they operate
on only one data extent at a time. If the input is from a tape created
by the dump function, it must be positioned at the header record for
each step.
The PRINT and TYPE statements have an implied output of
either the console (type) or system printer (print). Therefore, PRINT
and TYPE statements need not be delimited by an input or output
statement.
The I/O definition statements describe the tape, DASD, and
devices used while executing the DASD Dump Restore program.
An INPUT or OUTPUT statement describes each
The format of the INPUT/OUTPUT statement is:
86
IBft VM/370: System Programmer's Guide
tape and DASD
printer
unit used.
r
INput
OUTput
ccu
type
,
Ivolserl
laltape I
L
[ (options ••• ) ]
2Elio!!§:
.J
r
,
r
,
IMOde 6250 I I LEave I
I SKip nn I IMOde 1600 I I REWind I
laIiE Q I IMOde 800 I I!!Nl~~ I
r
,
L
.JL
.JL
.J
cell
is the unit address of the device.
type
is the device type (2314, 2319, 3330, 3330-11, 3340-35 (3340
access device equipped with a 3348-35 megabyte disk pack),
3340-10 (3340 access device equipped with a 3348-10 megabyte
disk pack), 2305-1, 2305-2, 2400, 2420, or 3420). There is no
1 track support.
volser
is the volume serial number of a DASD device. If the keyword
'SCRATCH' is specified instead of the volume serial number, no
label verification is performed.
altape
is the address of an alternate tape drive.
If multiple reels of tape are required and "altape" is
not specified, DDR displays the following at the end of the
reel: "END OF VOLUME CYL xxx HD xx, MOUNT NEXT TAPE." After
the new tape is mounted, DDR continues automatically.
!gl~:
SKIP nn
forward spaces nn files on the tape. nn is any number up to
255. The SKIP option is reset to zero after the tape has been
positioned.
MODE 6250 causes all output tapes that are opened for the first time
MODE 1600 and at the load point to be written or read in the specified
MODE 800 mode. All subsequent tapes mounted are also set to the
specified mode. If no mode option is specified, then no mode
set is performed.
REWIND
rewinds the tape at the end of a function.
UNLOAD
rewinds and unloads the tape at the end of a function.
LEAVE
leaves the tape positioned
of a function.
at the end of the file
at the end
Use the SYSPRINT control statement to describe a printer device that is
used to print data extents specified by the PRINT statement for the
standalone version of DDR. It is also used to print a map of the
cylinder extents from the DUMP, RESTORE, or COPY statement. If the
SYSPRINT statement is not provided, the printer assignment defaults to
OOE. The SYSFRINT control statement is used by the standalone version
of DDR to define the printer device if it is other than OOE. DDR,
Part 1: Debugging with VM/310
81
running under the control of
the C~S printer is OOE. The
is:
SYsprint
ccu
C~S,
ignores this control statement since
format of the SYSPRINT control statement
ccu
specifies the unit address of the device.
The function statements tell the DDR program what action to perform.
The function commands also describe the extents to be dumped, copied, or
restored.
The format of the DU~P/COPY/RESTORE control statement is:
,
r
DUmp
COpy
REstore
Icyl1 [To]
ICPvol
IAL!
INUcleus
L
[cyl2 [Reorder] [To] [cyI3]]1
I
I
I
~
requests the program to move data from a direct access volume
onto a magnetic tape or tapes. The data is moved cylinder by
cylinder. Any number of cylinders may be moved. The format
of the resulting tape is:
DU~P
Record 1: a
volume header
describing the volumes.
record,
consisting
of
data
Record 2: a track header record, consisting of a list of count
fields to restore the track, and the number of data records
written on tape. After the last count field the record
contains key and data records to fill the 4K buffer.
Record 3: track
records packed
truncated.
data
into
records, consisting of
4K blocks,
with the
key and data
last record
Record 4: either the end of volume or end of job trailer
label. The end of volume label contains the same information
as the next volume header record except that the ID field
contains EOV. The end of job trailer label contains the same
information as record 1 except that the cylinder number field
contains the disk address of the last record on tape and the
ID field contains EOJ.
88
IB~
V~/370:
System Programmer's Guide
COpy
requests the program to copy data from one device to another
device of the same or equivalent type. Data may be recorded on
a cylinder basis from input device to output device.
A
tape-to-tape copy can be accomplished only with data dumped by
this program.
RESTORE
requests the program to return data that has been dumped by
this program. Data can be restored only to a DASD volume of
the same or equivalent device type as it was dumped from. It
is possible to dump from a real disk and restore to a
minidisk.
cyll [TO] [cyl2 [REORDER] [TO] [cyI3]
Only those cylinders specified are moved, starting with the
first track of the first cylinder (cyll), and ending with the
last track of the second cylinder (cyI2). If cyl2 is not
specified, only the first cylinder (cyll) is operated on. The
REORDER operand causes the output to be reordered, starting at
the specified cylinder (cyI3) or at the starting cylinder
(cyll) if (cyl3) is not specified. The REORDER operand may
not be used with the CPVOL, ALL, or NUCLEUS operands.
CPVOL
specifies that cylinder 0 and all active directory and
permanent disk space are to be copied, dumped, or restored.
This indicates that both source and target disks should be in
CP format, that is, they must have been formatted by the CP
Format/Allocate program.
A~~
specifies that
cylinders.
NUCLEUS
specifies that record 2 on cylinder 0, track 0 and the nucleus
cylinders will be dumped, copied, or restored.
the
operation
is to
be
performed
on
all
1.
Each track must contain a valid home address,
cylinder and track location.
2.
Record zero must
characters.
3.
For the IBM 2314, 2319, and 2305, flagged tracks will be treated as
any other track , that is, no attempt will be made to substitute
the alternate track data when a defective primary track is read.
In addition, tracks will not be inspected to determine whether they
were
previously flagged
when
written.
Therefore,
volumes
containing flagged tracks should be restored to the volume from
which they were dumped. The message DMKDDB115E is displayed each
time a defective track is dumped, copied, or restored, and the
operation continues.
4.
For the IBM 3330, flagged tracks are automatically handled by the
control unit and should never be detected by the program. However,
if a flagged track is detected, message DMKDDR115E is displayed and
the operation terminates.
not
contain more
than
containing the real
eight
key and/or
Part 1: Debugging with VM/310
data
89
INPUT 191 3330 SYSRES
OUTPUT 180 2400 181 (ftODE 800
SYSPRIIT OOP
DUftP CPVOL
INPUT 130 3330 ftIIIOl
DUftP 1 TO 50 REORDER 51
60 70 101
This example sets the mode to 800 bpi, then dumps all pertinent data
from the volume labeled 'SYSRES' onto the tape that is .ounted on unit
180. If the program runs out of room on the first tape, it continues
dumping onto the alternate device (181).
While dumping, a map of the
cylinders dumped is printed on unit OOP.
When the first function is
complete, the volume labeled 'ftIII01' is dumped onto a new tape. Its
cylinder header records are labeled 51 to 100. 1 map of the cylinders
dumped is printed on unit OOP. lext, cylinders 60 to 70 are dumped and
labeled 101 to 111. This extent is added to the cylinder map on unit
OOP. When the DDR processing is complete, the tapes are unloaded and
the program stops.
If cylinder extents are being defined from the console, the following
is displayed:
ENTER CYLINDER EXTENTS
ENTER:
For any extent after the first extent, the message
ENTER NEXT EXTENT OR NULL LINE
ENTER:
is displayed.
The user may then enter additional extents to be dumped, restored, or
copied. A null line causes the job step to start.
90
IBft Vft/370: System Programmer's Guide
AI-_-__in hexadecimal format
re
Record 1 --+--____-
Cylinder, head, and
record numbers in
decimal
7rth;:;:;a length field is : ; z e : - -
I /
Record ID
(hexadecimal)
. . .__________ / X
y ___
~
/
•
•
l
A heading is printed containing the
data length from the count field first in
decimal, then in hexadecimal
The data is then printed in hexadecimal
with graphic interpretation to the right
~tshownhere).
I
I
J
____
~
04096 1000 DATA LENGTH .....
00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAME AS !1.BOVE ...
IstHalfof-+---~CYL
Record 2
Note: Data Length field repeated
in heading.
019.HD 00 REC 002 COUNT 0013000002 00 09A8
02472 09A8 DATA LENGTH
00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAME AS ABOVE ...
ABOVE RECORD WRITTEN USING RECORD OVERFLOW
e
f":::j--------,
statement indicates that this portion
Ie ofThisRecord
2 was written using the Write
I
I
IL
Special Count, Key, and Data command. The
remainder of Record 2 is found on the next
track _
as the first
record
after_
Record_
O.
_
_
_
...J
Home Address +---.._. CYL 019 HD 01 HOME ADDRESS 0000130001 RECORD ZERO 0013000100 00 0008 00000000 00000000
Record 0
CYL 019 HD 01 REC 002 COUNT 0013000102 00 0 6 5 8 - - ' - - - - - - - - - - - - - - - - - - - - /
2nd Half of
Record 2
01624 0658 DATA LENGTH
00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAME AS ABOVE ...
re--If t~y length ~ is-;: z;;;: - - - - - - -,
I
I
Record 3
_--+_____-
eYL 019 HD 01 REe 003 COUNT 0013000103
001280080 KEY
4!
OF80
•
~•
/
; /
A headmg IS printed containing the key length
first in decimal, then in hexadecimal.
The key is then printed in hexadecimal WIth
lU"aphic mterpretatJon to the right (not shown here)'
_0- -- -
- __
0
- - '
I
I
.J
LENGTH~-------7
00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAM6 AS ABOVE ...
03968 OF80 DATA LENGTH
00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAME AS ABOVE ...
Record 4
---i-------- CYL
019 HD 01 REC 004 COUNT 0013000104 00 0000
END OF FILE RECORD
r:::-------...,
I
II~
I
Whenever the data length field is zero
an end-of-file prints next.
L
Figure
8.
Annotated
Program
Sample
of Output
from the TYPE
_ _ _ _ _ _ _ .....J
and PRINT
Functions of
the DDR
Part 1: Debugging with VM/370
91
Use the PRINT and TYPE function state.ent to print or display a
hexadecimal and EBCDIC translation of each record specified. The input
device .ust be defined as direct access or tape. The output is directed
to the system console for the TYPE function, or to the SYSPRIIT device
for the PRINT function. (This does not cause redefinition of the output
unit definition.) The format of the PRIIT/TYPE control state.ent is:
PRint
TYpe
cc 1 [hh 1 [rr 1 ]]
QE!ions:
[Hex] [Graphic]
[TO cc2 [hh2 [rr2 ]]]
[(options)]
[Count]
ccl
is the starting cylinder.
hh1
is the starting track. If present,
operand. The default is track zero.
rr1
is the starting record.
If present, it must follow the hhl
operand. The default is home address and record zero.
[TO] cc2
is the ending cylinder.
If more than 1 cylinder is
printed or displayed "TO cc2" must be specified.
hh2
is the ending
operand.
The
cylinder.
rr2
is the record ID of the last record to print.
the last record on the ending track.
HEX
prints or displays a hexadecimal representation of each record
specified.
GRAPHIC
prints or
specified.
displays
COUNT
prints or
specified.
displays only
it must
track.
If present, it must
default is the last track
an EBCDIC
the
translation
count
follow the
The default is
of
each
record
field for
each
record
Prints all of the records from cylinders 0, 1, 2, and 3.
PRINT 0 1 3
Prints only one record, from cylinder 0, track 1, record 3.
92
IBM VM/370: System Programmer's Guide
to be
follow the cc2
on the ending
PRINT 0 TO 3
PR IN T 1 10 3 TO 1 15 4
ccl
prints all records starting with cylinder 1,
ending with cylinder 1, track 15, record 4.
track 10, record
3, and
The example in Pigure 8 shows the information that would be displayed
at the console (TYPE function) or system printer (PRINT function) by the
DDR program.
The listing has been annotated to describe some of the
data fields.
"any CP problems can be isolated without standalone machine testing. It
is possible to debug CP by running it in a virtual machine.
In most
instances, the virtual machine system is an exact replica cf the system
running on the real machine.
TO set up a CP system on a virtual
machine, use the same procedure that is used to generate a CP system on
a real machine. However, remember that the entire procedure of running
service programs is now done on a virtual machine. llso, the virtual
machine must be described in the real V"/370 directory. See the "V"/370
Operating in a virtual Machine Environment" section of "Part II. Control
Program (CP)" for directions for setting up the virtual machine.
CP has an internal trace table which records events that occur
real machine. The events that are traced are:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
I.
in the
External interruptions
SVC interruptions
program interruptions
Machine check interruptions
I/O interruptions
Pree Storage requests
Release of free storage
Entry into scheduler
Queue drop
Run user requests
Start I/O
Unstack I/O interruptions
storing a virtual CSW
Test I/O
BaIt Device
unstack IOBLOK or TRQBLOK
RCP BTU (Network Control Program Basic Transmission Unit)
The size of the trace table depends on the amount of real storage
available at IPL time. Por each 256K bytes (or part thereof) of real
storage available at IPL time, one page (4096 bytes) is allocated to the
CP trace table. Each entry in the CP trace table is 16 bytes long.
There are 17 possible types of trace table entries; one for each type of
event recorded.
The first byte of each trace table entry, the
identification code, identifies the type of event being recorded.
The trace table is allocated by the main initialization routine,
D"KCPI. The first event traced is placed ~n the lowest trace table
address. Each subsequent event is recorded 1n the next available trace
table entry. Once the trace table is full, events are recorded at the
lowest address (overlaying the data previously recorded there). Tracing
continues with each new entry replacing an entry from a previous cycle.
Part 1: Debugging with V"/370
93
Use the trace table to determine the events that preceded a CP system
failure.
An ABEND dump contains the CP internal trace table and the
pointers to it. The address of the start of the trace table, TRACSTRT,
is at location X'OC'. The address of the byte following the end of the
trace table, TRACEND, is at location X'10'.
And the address of the next
available trace table entry, TRACCURR,
is at location X'14'. Substract
16 bytes (X'10')
from the address stored at X'14'
(TRACCURR) to obtain
the trace table entry for the last event completed.
The CP internal trace table is initialized during IPL. If you do not
wish to record events in the trace table, issue the MONITOR STOP com.and
to suppress recording.
The pages allocated to the trace table are not
released and recording can be restarted at any time by issuing the
MONITOR START com.and.
If the VM/370 system should abnormally terminate
and automatically restart, the tracing of events on the real machine
viII be active.
After a VM/370 IPL (manual or automatic), CP internal
tracing is alway active.
There are 17 possible types of trace table entries, each uniguely
identified by the value of the first byte. Figure 9 describes the
format of each type of trace table entry.
94
IBM VM/370: System Programmer's Guide
Module
Identification
Code
(hexadecimal)
External interrupt
DMKPSA
01
X'OOOOOOOOOO'
SVC interrupt
DMKPSA
02
GR 15
SVCOld PSW
Program interrupt
DMKPRG
03
First 3 bytes
ofVMPSW
Program Old PSW
I DMKMCH
04
Address of
VMBlOK
1/0 interrupt
DMKIOS
05
Free Storage (FREE)
DMKFRE
06
Return storage (FRET)
DMKFRE
Enter Scheduler
Type of Event
Machine Check
!~'!c:-:-i..iPt
Format of Trace Table Entry
External Old PSW
Machine Check Old PSW
I/O Old PSW +4
CSW
Address of
VMBLOK
GR Oat entry
GR 1 at exit
07
Address of
VMBLOK
GR 0 at entry
GR 1 at entry
DMKSCH
08
Address of
VMBLOK
Queue drop
OM KSCH
09
Address of VMBLOK
Run user
DMKDSP
OA
Start 1/0
DMKCNS
DMKIOS
DMKVIO
OB
Unstack 1/0 interrupt
DMKDSP
OC
Address of VMBLOK
Virtual CSW
Virtual CSW store
DMKVIO
OD
Address of VMBLOK
Virtual CSW
Test 1/0
DMKCNS
DMKIOS
DMKVIO
OE
Address of 10BLOK
CAW
ForCe= ~.CS~"':+';
otherwise this field is
not used
Halt Device
DMKCNS
DMKIOS
DMKVIO
OF
Address of 10BLOK
CAW
For CC = 1. CSW +4
otherwise this field is
not used
Unstack
10BLOKor
TROBLOK
DMKDSP
10
NCP BTU
(see note)
DMKRNH
11
Note:
Figure
9.
X'OOOOOO'
Value of VI\o1RSTAT,
VMDSTA T. VMOSTAT.
andVMOSTAT
Value of VMOLEVEL.
VMCLEVEL. VMTlEVEl.
RUNUSER value
fromPSA
RUNPSW value from PSA
Address of 10BLOK
CAW
12
Address of
IOBLOK or TRQBLOK
ForCC = 1. CSW +4
otherwise this field is
not used
Interrupt Return
Address
Bytes 2 through 15 of a code 11 trace record represent a Basic Transmission Unit, sent or received by a 3704/3705. If CONSYSR!CONEXTR are zero,
the BTU was transmitted to the 3704/3705. If they are non·zero, the BTU was received, If CONTCMD equals X'7700', this is an unsolicited BTU response.
CP Trace Table Entries
Part 1: Debugging with V"/370
95
~R
BESTBICTI01~
1 virtual aachine created by '8/310 is capable of running an IBB
Systea/360 or Systea/310 operating systea as long as certain '8/310
restrictions are not violated.
If your virtual aachine produces
unexpected results, be sure that none of the following restrictions are
violated.
In general, virtual aachines aay not execute channel prograas that are
dynaaically aodified (that is, channel prograas that are changed between
the tiae the ST1BT 1/0 (510) is issued and the end of the input/output
occurs, either by the channel prograa itself or by the CPO). Bowever,
soae dynaaically aodified channel prograas are given special handling by
CP: specifically, those generated by the Indexed seguential lccess
8ethod (lSI!) running under OS/PCP, OS/8PT, and OS/B'T: those generated
by 1518 running in an 05/'5 virtual=real partition: and those generated
by the 05/'5 Telecoaaunications lccess Bethod (TCI8) LevelS, with the
'8/310 option.
The self-modifying channel prograas that 151ft generates for soae of
its. operations receive special handling if 'B/310 is generated with the
1518 option and if the virtual aachine using 1518 has that option
specified in its 'B/310 directory entry. There is no such restriction
for DOS lSI!, or for 1518 if it is running in an 05/'5 virtual=virtual
partition. If 151ft is to run in an 05/'5 virtual=real partition, you
.ust specify the 151ft option in the 'ft/310 directory entry for the 05/'5
virtual aachine.
'irtual machines using 05/'5 TC18 (LevelS, generated or invoked with
the '"/310 option) issue a DI1GNOSE instruction when the channel prograa
is modified.
This instruction causes CP to reflect the change in the
virtual CCI string to the real CCI string being executed by the channel.
CP is then able to execute the dynaaically aodified channel prograa
properly.
The restriction against dynaaically aodified channel prograas does
not apply if the virtual aachine has the virtual=real perforaance option
and the NOTBIIS option has been set on.
The following restrictions exist for ainidisks:
1.
In the case of Bead Boae lddress with the skip bit off, '8/310
modifies the hoae address data in user storage at the coapletion of
the channel prograa because the addresses aust be converted for
minidisks: therefore, the data buffer area aay not be dynaaically
modified during the input/output operation.
2.
On a .inidisk, if a CCI
string uses aultitrack search on
input/output operations, subseguent operations to that disk aust
have preceding seeks or continue to use aultitrack operations.
There is no restriction for dedicated disks.
3.
OS/PCP, ftPT, and ft'T 151ft aay be used with a ainidisk only if the
ainidisk is located at the beginning of the physical disk (that is,
96
IBft '"/310: System Programaerts Guide
GC20-1807-3 page
at cylinder zero) •
ISAM.
M~dified
by TNL GN20-2662, March 31, 1975
There is no such restriction for
DOS or OS/VS
4~
VM/370 does not return an end of cylinder condition to
machine that has a virtual 2311 mapped to the top half
tracks 0 through 9) of 2314 or 2319 cylinders.
5.
If the user's channel program (CCWs)
for a minidisk do not perform
a Seek operation, then to prevent accidental accessing, VM/370
inserts a positioning Seek operation into the user's CCWs. Thus,
certain channel programs may generate a condition code (CC) of zero
on a SIO instead of an expected CC of one, which is reflected to
the virtual machine. The final status is reflected to the virtual
machine as an interrupt.
6.
DASD channel programs directed to minidisks on 3330 or 3340 devices
may give different results than on dedicated drives if the channel
program includes multiple-track operations and depends on a Search
ID High or a Search ID High or Equal to terminate the program.
This is because the record 0 count fields on the 3330 and 3340 must
contain the real cylinder number of the track on which they reside;
therefore, a Search ID High based on a low virtual cylinder number
may terminate prematurely if a real record 0 is encountered. This
restriction does not apply to minidisks with a relocation factor of
zero.
This restriction does apply to minidisks with a VTOC greater
than one track that are used with OS (Release 20.6 and later) or
OS/VS (any release), since the VTOC Locate function uses a Search
ID High to stop at the end of the VTOC.
a virtual
(that is,
!Q~~:
If the 'R' byte of 'CCHHR' is equal to zero at the time a
virtual Start I/O is issued,
but the 'CCHHR' field is read in
dynamically by the channel program before the SEARCH ID CCW is
executed, then the real SEARCH ID CCW uses the relocated 'CCHHR'
field instead of the 'CCHHR' field that was dynamically read in.
This causes erroneous results. To avoid this problem, the virtual
machine should not default the'R' byte of 'CCHHR' to binary zero if
the search arguments are to be read in dynamically and a SEARCH ID
on Record RO is not intended.
7.
The IBCDASDI program cannot assign alternate tracks for a 3330.
Timing dependencies in input/output devices
function consistently under VM/370:
1.
or
programming
do
not
The following telecommunication access methods (or the designated
option)
violate the restriction on timing dependency by using
program-controlled interrupt techniques and/or the restriction on
dynamically modified channel programs:
•
OS Basic Telecommunications
dynamic buffering option.
Access
Method
(BTAM)
•
OS Queued Telecommunications Access Method
•
DOS Queued Telecommunications Access Method (QTAM).
•
OS Telecommunications Access Method (TCAM).
•
OS/VS Telecommunications Access Method
(TCAM)
earlier, and LevelS if TCAM is not generated or
the VM/370 option.
with
the
(QTAM).
Level 4 or
invoked with
Part 1: Debugging with VM/370
97
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
These access methods may run in a virtual=real machine with CCW
translation suppressed by the SET NOTRANS ON command.
(OS BTA" can
be generated without dynamic buffering, in which case no virtual
machine execution violations occur.
However, the BTA" reset poll
macro will not execute under V"/370 if issued from third level
storage. For example, a reset poll macro has a NOP effect if
executed from a virtual=virtual storage under VS1 which is running
under V"/370.)
2.
Programming that makes use of the PCI channel interrupt for channel
program modification or processor signalling must be written so
that processing can continue normally if the PCI is not recognized
until I/O completion or if the modifications performed are not
executed by the channel.
3.
Devices that expect a response to an interrupt within a fixed
period of time may not function correctly because of execution
delays caused by normal VM/370 system processing. An example of
such a device is the IB" 1419 Magnetic Character Reader.
4.
The operation of a virtual block multiplexer channel is timing
dependent. For this reason, the channel appears available to the
virtual machine operating system,
and channel available interrupts
are not observed. However, operations on virtual block-multiplexing
devices should use the available features like Rotational Position
Sensing to enhance utilization of the real channels.
On the System/370 Model 158 only, the virtual Machine Assist feature
cannot operate concurrently with the 7070/7074 compatibility feature
(Feature t7117).
Programs written for CPU model-dependent functions may not execute
properly in the virtual machine under VM/370.
The following points
should be noted:
1.
Programs written to examine the machine logout area do not have
meaningful data since VM/370 does not reflect the machine logout
data to a virtual machine.
2.
Programs written to obtain CPU identification (via the Store CPU ID
instruction, STIDP) receive the real machine value.
When the STIDP
instruction is issued by a virtual machine, the version code
contains the value 256 in hexadecimal ("PP") to represent a virtual
machine.
3.
Programs written to obtain channel identification (via the Store
Channel ID instruction, STIDC) receive information from the virtual
channel block.
only the virtual channel type is reflected; the
other fields contain zeroes.
4.
No simulation of other CPU models is attempted by V"/370.
Other characteristics that exist for a
as follows:
98
virtual machine under V"/370 are
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
1.
If the virtual=real option is selected for a virtual machine,
input/output operations specifying data transfer into or out of the
virtual machine's page zero, or into or out of storage locations
whose addresses are greater than the storage allocated by the
virtual=real option, must not occur.
The storage-protect-key
mechanism of the IBM System/370 CPU and channels operates in these
situations but is unable to provide predictable protection to other
virtual machines.
In addition, violation of this restriction may
compromise the
integrity of the
system.
The
results are
unpredictable.
2.
VM/370 has no multiple path support and, hence, does not take
advantage of the two-channel switch. However, a two-channel switch
can be used between the IBM system/370 running a virtual machine
under V!/370 and another cpu.
3.
The DIAGNOSE instruction cannot be issued by the virtual machine
for its normal function.
VM/370 uses this instruction to allow the
virtual machine to communicate system services requests.
The
Diagnose interface requires the operand storage addresses passed to
it to be real to the virtual machine issuing the DIAGNOSE
instruction. For more information about the DIAGNOSE instruction in
a virtual machine, see the !~LllQ: ~I§!~! ~!Qy!~!me~~§ ~~!g~.
4.
A control unit normally never appears busy to a virtual machine.
An exception exists when a forward space file or backward space
file command is executed for a tape drive.
Subsequent I/O
operations to the same virtual control unit result in a control
unit busy condition until the forward space file or backward space
file command completes. If the real tape control unit is shared by
more than one virtual machine, a control unit busy condition is
reflected only to the virtual machine executing the forward space
file or backward space file command.
When a virtual machine
attempts an I/O operation to a device for which its real control
unit is busy,
the virtual machine is placed
in I/O wait
(non-dispatchable) until the real control unit is available.
If
the virtual machine executed a SIOF instruction
(rather than SIO)
and was enabled for block-multiplexing, it is not placed in I/O
wait for the above condition.
5.
The number of pages used for input/output must not exceed the total
number of user pages available in real storage; violation of this
restriction causes the real computing system to be put into an
enabled wait state.
6.
The CP IPL command cannot simulate self-modifying IPL sequences off
dedicated unit record devices
or certain self-modifying IPL
sequences off tape devices.
7.
The VM/370 spooling facilities do not support punch-feed-read,
stacker selection, or column binary operations.
Detection of
carriage control channels is supported for a virtual 3211 only.
8.
VM/370 does not support
operator's console.
9.
Programs that use the integrated emulators function only if the
real computing system has the appropriate compatibility feature.
VM/370 does not attempt simulation.
The DOS emulators are not
supported.
10.
The READ DIRECT and WRITE DIRECT instructions are not supported for
a virtual machine.
11.
The
system/370 SET
CLOCK
count
control
instruction
on
the
cannot be
virtual
simulated
Part 1: Debugging with VM/370
1052
and,
99
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
hence, is ignored if issued by a virtual machine. The System/370
STORE CLOCK instruction is a nonprivileged instruction and cannot
be trapped by VM/370; it provides the true TaD clock value from the
real cpu.
12.
The 1050/1052 Model 2 Data Communication system is supported only
as a keyboard operator's console.
Card reading, paper tape I/O,
and other modes of operation are not recognized as unique, and
hence may not work properly.
This restriction applies only when
the 1050 system is used as a virtual machine operator's console.
It does not apply when the 1050 system is attached to a virtual
machine via a virtual 2701, 2702, or 2703 line.
13.
The pseudo-timer
(usually device address OFF, device type TIMER)
does not return an interrupt from a start I/O; therefore, do not
use EXCP to read this device.
14.
A virtual machine IPL with the NOCLEAR option renders one page of
the virtual machine invalid. The IPL simulator uses one page of
the virtual machine to initiate the IPL function. The starting
address of the invalid page is either the result of the following
formula:
virtual machine size
starting address of invalid page
2
or the hexadecimal value 20,000, whichever is smaller.
15.
To maintain system integrity, data transfer sequences to and from a
virtual system console are limited to a maximum of 2032 bytes.
Channel programs containing data transfer sequences that violate
this restriction are terminated with an interrupt whose CSW status
indicates incorrect length and a channel program check.
!2~~:
A data transfer sequence is defined as one or more read or
write CCWs connected via chain data. The introduction of command
chaining defines the start of a new data transfer sequence.
16.
If you intend to define more than 73 virtual devices for a single
virtual machine, be aware that any single request for free storage
in excess of 512 doublewords (a full page) will cause the VM/370
system to abnormally terminate
(ABEND code PTR007) if the extra
storage is not available on a contiguous page. Therefore, two
contiguous pages of free storage must be available in order to log
on a virtual machine with more than 73 virtual devices
(three
contiguous pages for a virtual machine with more than 146 virtual
devices, etc.).
Contiguous pages of free storage are sure to be
available only immediately after IPL, before other virtual machines
have logged on. Therefore, a virtual machine with more than 73
devices should be the first to log on after IPt.
17.
When an I/O error occurs on a device, the System/370 hardware
maintains a contingent connection for that device until a SENSE
channel command is executed and sense data is recorded. That is, no
other I/O activity can occur on the device during this time. Under
VM/370, the ~ontingent connection is maintained until the SENSE
command is executed, but I/O activity from other virtual machines
can begin on the device while the sense data is being reflected to
the virtual machine. Therefore, the user should be aware that on a
shared disk, the access mechanism may have moved during this time.
18.
The mode setting for 7-track tape devices is maintained by the
control unit.
Therefore, when a virtual machine issues the SET
100
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31,
1975
MODE channel command to a 7-track tape device, it changes the mode
setting of all 7-track tape devices attached to that control unit.
This has no effect on virtual machines (such as OS or DOS) that
issue SET MODE each time a CCW strinq is to be executed. However,
it can cause a problem if a
virtual-machine fails to issue a SET
mode with each CCW string executed.
Another virtual machine may
change the mode setting for another device on the same control
unit, thereby changing the mode setting of all 7-track tape devices
attached to that control unit.
19.
OS/VS2 is supported in uniprocessor mode only:
20.
For remote 3270s,
VM/370 supports a
maximum
of
16 binary
synchronous lines, minus the number of 3704/3705 Communications
Controllers in NCP mode minus one
(if there are any 3704/3705
Communications Controllers in emulation mode).
21.
If an I/O device (such as a disk or tape drive) drops ready status
while it is processing virtual I/O activity, any virtual machine
users performing I/O on that device are unable to continue
processing or to log off.
Also,
the LOGOFF and FORCE commands are
not effective because they do not complete until all outstanding
I/O is finished. The system operator should determine which I/O
device is involved and make that device ready once more.
The following restrictions apply to CMS, the conversational subsystem of
VM/370:
1.
CMS executes only on a virtual IBM system/370 provided by VM/370.
2.
The maximum sizes of CMS minidisks are as follows:
Qi~!
2314/2319
3330 Series
3340 Model 35
3340 Model 70
~~~i~g~ ~y!igQ~£~
203
246
349
682
Unit record equipment cannot be dedicated
facilities of VM/370 must be used.
4.
Only those OS facilities that are simulated by CMS can be used to
execute OS programs produced by language processors under CMS.
5.
Many types of object programs produced by CMS (and OS) languages
can be executed under CMS using CMS's simulation of OS supervisory
functions.
The following functions, although supported in DOS and
OS virtual machines under VM/370, are not supported under CMS:
6.
to CMS;
the spooling
3.
•
The execution of DOS object programs.
Although DOS programs can
be assembled under CMS (using the VM/370 Assembler), DOS object
programs cannot execute under CMS.
•
The writing or updating of OS data sets and DOS files.
CMS can read sequential and partitioned OS data sets and sequential
DOS files, by simulating certain OS macros.
Part 1: Debugging with VM/370
101
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
The following restrictions
reside on OS disks:
apply when CMS reads OS
data sets that
•
Read-password-protected data sets are not read.
•
VSAM, BDAM, and ISAM data sets are not read.
•
Multi-volume data sets are read as single-volume data sets.
End-of-volume is treated as end-of-file
and there is no
end-of-volume switching.
•
Keys in
read.
•
User labels in user-labeled data sets are bypassed.
data sets with
The following restrictions
reside on DOS disks:
keys are ignored
apply when
and only the
CMS reads
data is
DOS files
that
•
No DOS macros are simulated.
•
Only DOS sequential files can be read. CMS options and operands
that do not apply to OS sequential data sets {such as the MEMBER
and CONCAT options of FILED!F and the PDS option of MOVEFILE}
also do not apply to DOS sequential files.
•
The following types of DOS files cannot be read:
--DOS VSAM, DAM, and ISAM files.
--DOS core image, relocatable, source statement and procedure
libraries.
--Files with the input security indicator on.
--DOS files that contain more than 16 user label and/or data
extents.
(If the file has user labels, they occupy the
first extent; therefore the file must contain no more than
15 data extents.)
read
as
as
single-volume
end-of-file.
There
files.
is
no
•
Multi-volume
files
are
End-of-volume
is treated
end-of-volume switching.
•
User labels in user-labeled files are bypassed.
•
Since DOS files do not contain BLKSIZE, 'RECFM, or LRECL
parameters, these parameters must be specified via FILEDEF or
DCB parameters, otherwise, defaults of BLOCKSIZE=32760 and
RECFM=U are assigned. LRECL is not used for RECFM=U files.
If you intend to run VM/370 Release 1 and Release 2 systems alternately,
apply Release 1 PLC 14 or higher
(APAR Vl179) to your Release 1 system,
to provide compatibility and to prevent loss of spool files in case of a
warm start.
102
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNl GN20-2662, March 31, 1975
There are three kinds of abnormal termination dumps possible when using
If the problem program cannot continue, it terminates and in some
cases attempts to issue a dump.
Likewise, if the operating system for
your virtual machine cannot continue, it terminates and, in some cases,
attempts to issue a dump.
In the VM/370 environment,
both the problem
program and the virtual machine's operating system dumps go to the
virtual printer. A CLOSE must be issued to the virtual printer to have
either dump print on the real printer.
CP.
The third type of dump occurs when the CP system cannot continue.
The CP abnormal termination dumps can be directed to a printer or tape
or be dynamically allocated to DASD.
If the dump is directed to a tape,
the dumped data must fit on one reel of tape.
Multiple tape volumes are
not supported by VM/370.
The historical data on the tape is in print
line format and can be processes by user created programs or via CMS
commands.
Specify the output device for CP ABEND dumps with the CP SET
command. The format of the SET command used is:
r-
I
I Set
!
I
I
DUMP
},
{ AUTO
raddr
,
r
I
£~
I
ALL
I
L
I
J
L
AUTO
automatically directs the ABEND dump to disk.
raddr
directs
printer
device,
support
CP
dumps only the CP storage area.
ALL
dumps all of real storage.
the ABEND dump to the specified unit address (either a
or a tape unit).
If the address specifies a tape
the dump data must fit on one reel; VMj370 does not
multiple tape volumes.
I USING THE VMFDUMP COMMAND
When the CP ABEND dump is sent to a disk, use the CMS VMFDUMP command to
print the dump on the real printer.
The format of the VMFDUMP command
is:
r
,.
,
I
I
I
I VMFDUMP I I
I
I I DUMPxx I
I
I I
I
.J
I
I L
I
I
I
I
,
r
I
I
I
I
I
L
ERASl
NOMAP
NOHEX
NOFORM
NOVIRT
I
I
I
I
I
.J
,
I
I
I
I
I
I
I
.J
L-
Part 1: Debugging with VMj370
103
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
DUMPxx
specifies the name of the CP dump file to be formatted and
printed. xx may be any value from 00 to 09.
Class 0 spool
files will contain only CP dump files.
These files are
searched for the indicated dump file.
When the file is found,
it is used to create a CMS file which, in turn, is formatted
and printed.
ERASE
specifies that the CMS file which is being formatted
printed is to be erased at the conclusion of the program.
NOMAP
specifies that a load map is not to be printed.
NOBEX
specifies that a hexadecimal dump is not to be printed.
NOFORM
specifies that no formatted control blccks are to be printed.
NOVIRT
specifies that only the real machine control blocks are to be
formatted.
This option
is ignored if NOFORM
is also
specified.
Use the VMFDUMP command to format and
VM/370 system ABEND dump. specify
print a current
and
or previous
VMFDUMP
to obtain a complete formatted, hexadecimal printout.
When the dump has been printed, one of two messages will be printed.
DUMP FILE - DUMP xx - PRINTED AND KEPT
-- or -DUMP FILE - DUMP xx - PRINTED AND ERASED.
BOW TO PRINT A CP ABEND DUMP FROM TAPE
When the CP ABEND dump is sent to a tape, the records are 133 characters
long, unblocked, and contain carriage control characters.
To print the tape, first make sure the tape drive is attached to your
system. Next, define the printer and tape file.
FILEDEF ddname1 PRINTER (RECFM F LRECL 133)
FILEDEF ddname2 {TAP2} (9-track DEN 1600 RECFM F LRECL 133 BLOCK 133)
TAP1
Then use the MOVEFILE command to print the tape:
MOVEFILE ddname2 ddname1
Two types of printed dumps occur when CP abnormally
the options specified in the CP SET DUMP command.
104
IBM VM/370: System Programmer's Guide
ends, depending on
When the dump is
GC20~1807-3
Page Modified by TNL GN20-2662, March 3i, i975
directed to a direct access device, VMFDUMP must be used
print the dump. VMFDUMP formats and prints:
•
•
•
•
•
•
•
to format and
control blocks
General registers
Floating-point registers
Control registers
TOD (Time of Day) Clock
CPU Timer
storage
Storage is printed in hexadecimal notation,
eight words to the line,
with EBCDIC translation at the right.
The hexadecimal address of the
first byte printed on each line is indicated at the left.
If the CF SET DUMP command di~e~ted the dump to tape or ~ne printer,
the printed format of the dump is the same as with VMFDUMP, except that
the control blocks are not formatted and printed.
When the Control Program can no longer continue and abnormally
terminates, you must first determine the condition that caused the
ABEND, and then find the cause of that condition.
You should know the
structure and function of the Control Program. "Part 2: Control Program
(CP) " contains information that will help you understand the major
Part 1: Cebugging with VM/370
104.1
functions of CP. The following discussion on reading CP dumps includes
many references to CP control blocks and control block fields. Refer to
!~L]70: ~~!~2! frOqI~~
(~f) fI2g~~! 12g!£ for a description
of the CP
control blocks.
Pigure 11 shows the relationships of the CP control
blocks. Also, you will need the current load map for CP to be able to
identify the .odules from their locations.
REASON POR THE ABEND
Determine the immediate reason for the ABEND. You need to examine
several fields in the PSA (prefix storage Area) which is located in low
storage, to find the reason for the ABEND.
1.
Examine the program old PSi and program interrupt code to find out
if a program check occurred in CP. The program old PSi (PROPSW) is
located at X'2S' and the program interrupt code (INTPR) is at
X'SE'. If a program check has occurred in supervisor mode, use the
CP system load map to identify the module. If you cannot find the
module using the load map, refer to "Identifying a pageable
Module."
Pigure 43 in
"Appendix A: System/370 Information"
describes the format of an Extended Control PSi.
2.
Examine the SVC old PSi, the SVC interrupt code, and the ABEND code
to find out if a CP routine issued an SVC O.
The SVC old PSi
(SVCOPSi) is located at X'20', the SVC interrupt code (INTSVC) is
at X'SA', and the ABEID code (CPABEID) is at X'374'.
The modules that may issue an SVC
DMKBLD
DftKCPI
D8KCVT
DftKD.RD
Dft«DSP
DMKPRE
DHKHVC
DMKIOS
DftKPGT
DMKPRG
DftKPSA
DMKPTR
DMKRNH
DftKRPA
o
are:
DMKSCH
DftKTDK
DftKTRC
DftKUDR
DftKV DB
DftKVIO
DHKVSP
The ABEID code (CPABEND) is a fullword in length. The first three
bytes identify the module that issued the SVC 0 and the fourth byte
is a binary field whose value indicates the reason for issuing an
SVC O. See Pigure 10 for the possible values of CPABEID.
Use the CP system load map to identify the module issuing the SVC
O. If you cannot find the module using the CP system load map,
refer to "Identifying a Pageable Module".
Pigure 43 in Appendix A
describes the format of an Extended Control PSi.
3.
Examine the old PSi at X'OS'.
If the operator has pressed the
System Restart button on the CPU console, the old PSi indicates the
instruction executing when the ABEND (caused by pressing the System
Restart button) was recognized. Pigure 43 in Appendix A describes
the for.at of an Extended Control PSi.
4.
Por a machine check, examine the machine check old PSi and the
logout area. The machine check old PSi (MCOPSi) is found at X'30'
and the fixed logout area is at X'100'. Also examine the machine
check interrupt code (IITHC) at X'ES'.
Part 1: Debugging with V8/370
105
ABEND
Code
Reason for ABEND
Action
BLD001
Register 8 should contain Verify that general register 8
a pointer to the
points to a RDEVBLOK for a
RDEVBLOK for the user's
terminal. If it does not, there is
terminal. This routine
probably an error in the calling
(DMKBLDVM) attempts to
program. Identify the calling
create and partially
program by means of the return
initialize a VMBLOK for
address and the base register in
a user. DMKBLDVM
the save area pointed to by
abnormally terminates if general register 13. Then, attempt
general register 8 does
to identify the source of the
not contain a pointer to incorrect RDEVBLOK address.
the user.
CPI001
The RDEVBLOK for the DASD Verify that the volume serial
on which the SYSRES
number on the SYSRES volume from
volume is mounted cannot which the IPL was attempted, is
be located, or the IPL
the same as that specified in the
volume is not the SYSRES field DMKSYSVL. If the volume
volume. The SYSRES
serial number is not the same, it
volume is specified in
may have been altered by the CLIP
the SYSRES macro in the
utility. Or, the image of the same
DMKSYS module.
nucleus saved on the SYSRES may
have been partially destroyed and
the SYSRES specification altered.
Load or restore the nucleus from a
backup copy to the SYSRES volume
and attempt to IPL again.
CPI002
A valid system directory
file could not be
located.
CPI003 IThe system TOD clock is
I not operational.
Display the volume labels for all
owned volumes. If the volumes de
not contain an active directory
pointer, run DMKDIR (the
standalone directory program) to
recreate the system directory on
an owned volume. If an active
directory pointer is present in at
least one volume label, verify
that the device on which the
volume is mounted is online and
ready before attempting to IPL the
system.
ICall your IBM FE representative to
I fix the clock.
-----------------------------------1
CVT001 IThe system TOD clock is 1
I in error or is not
I operational.
Figure 10.
106
I
I
CP ABEND Codes (Part 1 of 14)
IBM VM/370: Syste. Programmer's Guide
ABEND
Code
Action
Reason for ABEND
DRD001 IThe device code index in
the compressed DASD
address for the system
dump file points to a
RDEVBLOK for an invalid
DASD. The valid DASDs
are 2305 series, 3330
series, or 2314/2319.
IVerify that the contents and order
I of the owned list have not been
I altered since the dump was taken.
I If these fields have not been
I altered, the SPBLOK for the dump
I file may have been destroyed. The
I owned list is specified by the
SYSOWN macro 1ll the DMKSYS module.
IThe integrity of the user's virtual
DSP001 IDuring I/O Interrupt
I Unstack and Reflection, I I/O configuration has probably
been violated. The unit addresses
DMKSCNVU could not
or indexes in the virtual control
locate all of the
virtual control blocks
blocks are in error, or the
virtual configuration has been
for the interrupting
unit.
altered by ATTACH/DETACH w~ile I/O
was in progress. Check for a
device reset failure in DftKCFPRD.
DSP002 IThe dispatcher (DMKDSP)
IMost likely, a free storage
violation has occurred. First look
I is attempting to
at the DMKPRi and DMKiAT modules.
dispatch a virtual
relocate user whose
Examine the real, virtual, and
shadow segment tables orl shadow translation tables for
virtual extended controll consistency of entry size and
register 0 are invalid. I format. Also compare page and
I segment size.
ICheck the timer fields in real
DSP003 IThe interval timer was
storage. The value of the real
not incremented
properly. This is most
interval timer is at real storage
likely a hardware error.1 location X'SO'. The dispatcher
The dispatcher tests fori loads the value of the real
interval timer errors
I interval timer in real storage
and abnormally
I location X'S4' when a user is
terminates if such errorl dispatched. The value of the real
occurs. Results would bel interval timer is loaded into real.
unpredictable if CP
i storage location X'4C' when an
continued when the
I interrupt occurs. If the value
interval timer was in
I stored at X'4C' is not less than
error.
I the value stored at X'S4', the
I dispatcher abnormally terminates.
I Check the routines that control
I the value of the time fields at
I X'4C', X'SO', and X'S4'.
DSP004 IWhile tracing SIOs or I/OIExamine the operator's console
interrupts, the virtual I sheet and the user's terminal
device was detached.
I sheet to see who detached the
Now, the VDEVELOK cannot I device. Warn the person
be found.
I responsible that devices should
I not be detached during I/O
I tracing.
Figure 10.
CP ABEND Codes (Part 2 of 14)
Part 1: Debugging with VM/370
107
ABERD
Code
Action
Reason for ABERD
FRE001 IThe size of the block
IUsing FR!!R14 and FBEER12 in the
being returned (via GR 1 PSA, identify the CP module
0) is less than or equall releasing the storage. Check for
to o.
I an error in calculating the size
I of the block or for a .odification
1 to the stored block size for
1 variable-size blocks.
FRE002 IThe address of the free
1 storage block being
1 returned matches the
1 address of a block
I already in the free
I storage chain.
I
,I
1
1
1
I
1
1
1
Identify the program returning the
storage by means of the return
address and base registers stored
(FREE14 and FREE12 in DftKFRE's
save area in PSA). The most co.mon
cause of this type of failure is a
module that returns a free storage
block but fails to clear a pointer
to the block that has been saved
elsewhere. All modules that return
blocks via a call to DftKPRET
should first verify that the saved
pointer is nonzero; then, after
returning the block, any saved
pointers should be set to zero.
PRE003
A free storage pointer may have
been destroyed. Also, the module
releasing the lower (overlapped)
block may have returned too much
storage. Examine the lower block
and determine its use and former
owner. Or, identify the program
returning the storage by means of
the return address and base
registers stored (PREER14 and
PREER12 in DftKFRE's save area in
PSA). The most co •• on cause of
this type of failure is a module
that returns a free storage block
but fails to clear a pointer to
the block that has been saved
elsewhere. All modules that return
blocks via a call to DMKPRET
should first verify that the saved
pointer is nonzero; then, after
returning the block, any saved
pointers should be set to zero.
The address of the free
storage block being
returned overlaps the
next lower block on the
free storage chain.
FRE004 IThe address of the free IA free storage pointer may have
1 storage block being
I been destroyed. Also, the module
1 returned overlaps the
I releasing the higher (overlapped)
1 next higher block on thel block may have returned too much
1 free storage chain.
I storage, or the module may be
I
I attempting to release storage at
l i t h e wrong address.
igure 10.
108
CP ABEND Codes (Part 3 of 14)
IBft VM/370: system Programmer's Guide
AB!ND
Code
Reason for ABEND
Action
FRE005 IA module is attempting tolA module is probably attempting to
release storage in the I release location o. Check for the
resident VK/370 nucleus. I module picking up a pointer to a
I free storage block without first
I testing the pointer for O. Use
I FREER14 and FRBER12 in the PSA to
I identify the .odule.
FRB006 IA module is requesting a I Using FREER14 and FREER12 in the
block of storage whose I PSA, identify the module. Check
size (contained in GR 0) I for an error in calculating the
is less than or equal tal block size. Improper use of the
zero.
I halfword instructions ICK and STCK
I can cause truncation of high order
I bits that results in a calculation
I error.
A module is atte.pting to Kost likely, a free storage pointer
release a block of
has been destroyed. Attempt to
storage whose address
identify the owners of the free
exceeds the size of real storage blocks adjacent to the one
storage.
containing the pointer that was
destroyed. Check for moves and
translation where initial counts
of zero have been decremented to
minus 1, thus generating an
executed length code of X'FF', or
an effective length of 256 bytes.
FRE007
FRE008 IThe address of the free
I storage block being
I returned matches the
I address of the first
I block in the sub pool
I for that size.
I Identify the program returning the
I storage by means of the return
I address and base registers stored
I (FREER14 and FREER12 in DKKFRE's
I save area in the PSA). The most
I common cause of this type of
failure is a module that returns a
I free storaqe block but fails to
i clear a pointer to the block that
J has been saved elsewhere. All
I modules that return blocks via a
I call to DKKFRET should first
I verify that the saved pointer is
I nonzero; then, after returning the
I block, any saved pointers should
I be set to zero.
------------------------------------1
FRE009 IThe address of the free
I
I
I
I
I
I
I
I
storage block being
returned matches the
second block in the
subpool for that size.
FRE010 IA program is attempting I Examine the EITSAVE save area in
to extend free storage I DKKFREE to determine which module
while storage itself is I requested an excessive amount of
L-________________________________________________________________________
being extended.
I storage.
Figure 10.
~
CP ABEND Codes (Part 4 of 14)
Part 1: Debugging with VK/370
109
ABEND
Code
FRE011
Reason for ABEND
Action
A CP module has attempted Identify the ~rogram returning the
to return a block of
storage by means of the return
storage that is in the
address and base registers stored
user dynamic paging
(FREER14 and FREER12 in D"KFRE's
area.
save area in the PSA). The most
common cause of this type of
failure is a module that returns a
free storage block but fails to
clear a pointer to the block that
has been saved elsewhere. All
modules that return blocks via a
call to D"KFRET should first
verify that the saved pointer is
nonzero; then, after returning the
block, any saved pointers should
be set to zero.
BVC001 IThe user pointed to by GRIThe RDEVBLOK for the SYSRES device
I 11 issued a DIAGNOSE
I was probably destroyed, or a
I instruction while
I volume with the same serial number
I attempting to format thel as the SYSRES volume was mounted.
I I/O Error or Channel
I If a volume with the same serial
I Check/Machine Check
I number was mounted"check the
I recording areas: the
I ATTACH processing in the DMKVDB
I SYSRES device type is
I routine.
I unrecognizable.
I
105001 IThe caller is attempting
I to reset an active
I IOBLOK from the RCHBLGK
I queue, but that IOBLOK
I contains an invalid
I address.
The IOBLOK may have been returned
(via DMKFRET) or destroyed. Verify
that the IOBLOK was valid and use
the IOBLOK and RDEVBLOK to
determine the last operation.
105002 IDMKIOS is attempting to
I restart an IOBLOK from
I the RCBBLOK queue, but
I that IOBLOK contains an
I invalid address.
105003 ID"KIOS is attempting to
I remove an IOBLOK from a
I queue, but that IOBLOK
I contains an invalid
I address.
I
I
I
Figure 10.
110
IRegister 2 points to the RCHBLOK,
I RCUBLOK, or RDEVBLOK from whose
I queue the IOBLOK is being removed.
I Register 10 points to the IOBLOK.
I Use the CP internal trace table to
I determine which module called
I DMKIOS twice to start the same
I IOBLOK.
CP ABEND Codes (Part 5 of 14)
IBM VM/370: System Programmer's Guide
ABBND
Code
NLD001
Action
Reason for ABBND
During execution of a
ICorrect the RDBVICB macro specifyNBTWORK DUMP command, orl ing the 3704 or 3705, reassemble
during an automatic dumpl the DMKRIO module, and regenerate
of a 3704 or 3705,
I the V8/370 CP nucleus with the
VM/370 detected that it I corrected module.
had not allocated suffi-I
cient spool DISD space I
.- --"..
'-v
~"
,",V",-Q.LII
.~'-11'1::
~--\,lUlU):'
~.LU-
.
I
formation from the 3704 I
or 3705. The MODBL oper-I
and on the RDEVICB macrol
describing the 3704 or
3705 was not specified
correctly. VM/370
determines the storage
size of a 3704 or 3705
by the model specified
on the RDBVICB macro.
PGT001
The number of cylinders
Inspect the chains of paging and
in use stored in the
spooling allocation blocks
allocation block
anchored at RDBVPIGE and RDEVRECS
on the RDEVBLOK for the device in
(ALOCBLOK) is less than
the maximum but the
qUestion, and verify that a
DMKPGT module was unable cylinder allocation block
(RBCBLOK) exists for each cylinder
to find available
marked and allocated in the
cylinders.
lLOCBLOK. If RBCBLOKs for some
cylinders are missing, it is
possible that the bit map in the
ALOCBLOK has been destroyed. If
all cylinders are accounted for,
the updating of the count field
is in error.
PGT002 IThe count of pages in usellf the RBCBLOK is question is in
I in a page allocation
I use for paqinq, then locate a
I block (RBCBLOK) is less I SWPTABL!-entry for each page allo-I
I than the maximum but thel cated on the cylinder. However, if I
I D8KPGT module was unablel the cylinder is in use for spool- I
I
I to find available pages.1 ing, it is possible that the
I
I RECBLOK itself has been destroyed, I
I
I
I or that the updating of the use
L-______________________________________________
I
I count is _faulty.
I
Figure 10.
CP ABBND Codes (Part 6 of 14)
Part 1: Debugging with V8/370
111
~----------------------------------------------------------------------,
lBEID
Code
Beason for lBllD
lction
I
I
-----------------------------------------------------------------1
PGT003 The D1SD page slot being Identify the aodule atteapting to I
released is not aarked
allocated.
release the page by aeans of the I
caller's return address and base I
register stored in B1LB14 and
I
B1LB12 in the B1LBS1'1 saye area I
in PSI. Locate the source (controll
block or SWPT1BLI entry) of the
I
D1SD address being released and
I
yerify that they haye not been
I
inadYertently destroyed. If the
I
D1SD page is in a spool file, it I
is possible that the file or the I
BECBLOK chain haye been incorrectly checkpointed and warastarted
after a systea shutdown or a
systea crash.
PGT004 IThe duaay RBCBLOK indi- IThe spool file pOinters aay haye
I been destroyed while the file was
I cating the spooling
I D1SD pages on the
I being processed, or the allocation
I cylinder that are to be I chain aay be in error. I cold
I released contains a pagel start will probably be necessary.
I count greater than the I If feasible, use the D1SD Duap
I nuaberof pages alloI Restore prograa to print the D1SD
I cated on the cylinder. I areas containing the affected
I
I file, and try to locate the
I
I incorrect pointers.
PGTOOS
1 aodule is atteapting to Use B1LB14 and B1LR12 in the
release a D1SD page slot B1LBS1VI area of the PSI to
on a cylinder for which
identify the aodule atteapting to
no page allocation block release the page. Verify that the
(BECBLOK) exists.
D1SD cylinder address is yalid fori
the deyice in question. If it is, I
and the rest of the D1SD address I
is yalid, yerify that the cylinder I
is in the dynaaically allocatable 1
area. If these restrictions are
I
.et, the D1SD page slot aust haye I
been used by aore than one user. I
-------------------------------------------------·-----------------1
PGT006 IThe last D1SD page slot
lLOCBLOK has probably been
I
I~he
I
I
I
I
I
I
I
I
I
Pigure 10.
112
in a BBCBLOK has been
I destroyed, or the chain pointer inl
deallocated but the bit I the RDEVBLOK is in error.
I
representing the cylin- I
I
der in the cylinder
I
I
allocation block
I
I
(lLOCBLOK) is not cur- I
I
rently set to one, indi-I
I
cating that the cylinderl
I
was not allocated.
I
I
CP lBBID Codes (Part 1 of 14)
IBft Vft/310: System Programmer's Guide
I
ABEID
Code
I
Reason for ABEID
Action
I
-----------------------------------------------------------------------1
PGT001 A module is attempting to Use BALR14 and BALR12 in the
I
release a page of virtual storage being used
by the V"/310 control
program that has not
been marked allocated.
PGT008 IThe system's virtual
I storage buffers have
I been exhausted because
I of an excessive number
I of open spool files.
BALRSAVE area of the PSI to iden- I
tify the module attempting to re- I
lease the page. Locate the control I
block containing the virtual page i
address that is being released. It
is possible that the address has
been destroyed, or a pointer to a
virtual page has been retained
after the page was destroyed.
IRequest users to close all spool
I files that are no longer active.
I
I
I
PRG001 IProgram check (operation) Examine the ABEID dump. In particI in the control program.
ular, exa.ine the old PSi and
identify the module that had the
PRG002 IProgram check (privileged program check.
I operation) in the
I control program.
PRG003 Iprogram check (execute)
I in the control program.
PRG004 IProgra. check (protecI tion) in the control
I program.
PRGOOS IProgram check (addressI ing) in the control
I program.
PRG006 IProgram check (specifiI cation) in the control
I program.
PRG001 IProgram check (data) in
I the control program.
PRG008 IProgram check (fixedI point overflow) in the
I control progra ••
PRG009 IProgram check (fixedI point divide) in the
I control program.
PRG010 IProgram check (decimal
I overflow) in the control
I program.
PRG011 IProgram check (decimal
divide) in the control
program.
Figure 10.
CP ABEID Codes (Part 8 of 14)
Part 1: Debugging with V"/310
113
r------------------------------------------------------------------------~
I ABEND
I Code
Action
Reason for ABEND
1------------------------------------------------------------------Examine the ABERD dump. In particI PRG012 IProgram check (exponenI tial overflow) in the
I control program.
I
I
1---------------------------------
ular, examine the old PSi and
identify the module that had the
program check.
I PRG013 IProgram check (exponenI tial underflow) in the
I
I control program.
I
PRG014 I program check (signifiI cancel ,in the control
I program.
PRG015 IProgram check (floatingI point divide) in the
I control program.
PRG016 IProgram check (segment)
I in the control program.
PRG017 IProgram check (paging)
I in the control program.
PRG018 IProgram check (translaI tion) in the control
I program.
PRG019 IProgram check (special
I operation) in the
I control program.
PRG254 IA translation specificaI tion exception has been
I received for a virtual
I machine that is not in
I Extended Control Mode.
I
I
IIf the set of translaticn tables
I pointed to by RUNCR1 is correct, a
I hardware failure has occurred,
I possibly with Dynamic Address
I Translation. Otherwise, call your
I IBM FE representative for software
I support.
PRG255 IA PER (Program Event
IRetry the program causing the
Recording) has been re- I error; if the problem persists,
ceived for a virtual
I call your IBM FE representative.
machine that is running I
with PER disabled in itsl
virtual PSi.
I
PSA001 INo free storage is avail-I Try to identify the extreme load
able for save areas.
condition that caused the problem.
Verify that a routine has not
requested an inordinate amount of
storage. If the storage requests
are valid and the problem occurs
regularly, alter the DMKCPI module
to allocate more than six pages of
free storage per 256K bytes of
storage.
Figure 10.
114
CP ABEND Codes (Part 9 of 14)
IBM VM/370: System Programmer's Guide
ABEND
Code
Action
Reason for ABEND
PSA002 IThe 'PSi Restart' key on !Examine the resulting ABEND dump
I the console was activa- I for a dynamic picture cf the sysI ted to cause this ABBND.I tem's status.
I This action is normally I
I taken when an unusual
I
I system condition occurs, I
I such as a system loop orl
I a slow-running machine. I
PSA003 IA fatal DASD I/O error
I on a paging device
i occurred.
I
I
ICheck the unit address in the I/O
I old PSi to find the paging device
I in error. This is a hardware
I error. Call your IBft PB RepresentI ative for service.
PTR001 IA segment exception or a
translation specification has occurred while
executing a LRA (Load
Real Address) instruction in the DftKPTR
.odule.
I Inspect the contents of Control
I Registers 0 and 1, and the format
I of the Segment Table pointed to by
I CR 1. One or more of these tables
I &nd registers may contain invalid
I data. If CR 1 is invalid, check
I the contents of the V8BLOK pointed
I to by GR 11, especially the adI dress in the VftSEG field.
PTR002 IA program is attempting
to unlock a page frame
I whose address exceeds
I ~he size of real
I storage.
IUse BALR14 and BALR12 in the
BAL~SAVE area of the PSA to idenI tify the module attempting to
I unlock the page frame. Check for
I the sourCE of the invalid address.
I
----------~--------------------I
PTR003 IA program is attempting I
I to unlock a real storagel
I page frame whose
I
I CORTABLE entry is not
I
I flagged as locked.
I
PTR004 IThe lock count in the
I COR TABLE entry for the
I page frame being unI locked has been decreI mented to a value that
I is less than O.
igure 10.
ICheck the routines that update the
I lock count field and CORTABLE
I entry.
I
I
I
CP ABEND Codes (Part 10 of 14)
Part 1: Debugging with Vft/370
115
t
ABEND
Code
Reason for ABBND
Action
1
1
-------------------------------------------------------------------1
PTB007 DBKPRE requested a page
Exa.ine the dump for one of the
I
for fixed free storage
but DBKPTR deter.ined
that there were no pages
left in the dyna.ic
paging area.
PTR008 IA CORTABLE entry on the
I free list points to a
I valid PTE (Page Table
I Entry), but the page is
I allocated.
I
following conditions:
1
1. Excessive a.ounts of free storage have been allocated by CP
and not released via DBKPRBT.
Look for blocks of identical
data and deter.ine which .odules built that data.
2. A block of storage greater than
4096 bytes was requested. Requests for large blocks of free
storage require contiguous
pages from DB'fTR and as a
result have a higher probability of failure than requests
for one page or less. If possible, change the application
to reduce the size cf storage
requests. otherwise, schedule
the application when storage is
less fragmented.
IPages on the free list should not
I contain valid PTEs. Examine the
I dump to determine which module
I called DBKPTRPR. The mcdule that
I called DBKPTBPR probably contains
I an error.
PTR009 IThe count of the number IThe field DBKPTRSC contains the
I of resident shared pagesl number of resident shared pages
I was incorrectly decre- 1 and the field DBKDSPNP contains
I· mented so that the countl the number of pageable pages.
I is now less than zero. 1 DBKDSPNP must always be greater
1
I than DBKPTRSC. If ABEND PTR009
I
1 occurs, check the routines that
I
I update these two count fields.
PTR010 IThe count of the number
1 of resident reserved
1 pages was incorrectly
I decremented so that the
I count is now less than
I zero.
I
PTBOll IA CORTABLE entry to be
placed on the free list
points to a valid PTE
(page table entry), but
the page is allocated.
An ABEND occurs trying
to honor a deferred
request.
Pigure 10.
116
IThe field, DBKPTRRC, contains the
I number of reserved pages. DBKPTRRC
I must always be less than DBKDSPNP.
I If ABEND PTR010 occurs, check the
I routines that update these two
i count fields (DBKDSPNP and
I DBKPTRRC).
IPages to be put on the free list
I should not contain valid PTEs.
I Examine the dump to determine why
I the page was not marked invalid
I before the call to DBKPTRPT.
I
I
I
CP ABEND Codes (Part 11 of 14)
IBB V"/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL
f'lJ'1"_'1CC'1
\.JI1.1LV
LUVL,
March
... 1
.) I ,
r-------------------------ABEND
Code
Reason for ABEND
PTR012 IA CORTABLE entry to be
I placed on the free list
I points to a valid PTE
(page table entry), but
the page is allocated.
RGF001
Action
IPages to be put on the free list
I should not contain valid PTEs.
I Examine the dump to determine why
i the page was not marked invalid
I before the call to DMKPTRFT.
The reflected device
IPL to restart the system. If the
status in the CSW is not problem persists, call your IBM FE
supported for certain
representative.
3270 remote device and
line protocol I/O
operations.
Specifically, the returned CSW
contains a device status
other than CE, DE, and
UE; and, the ending CCW
contains an embedded
teleprocessing code of
02, 03, or 06.
I
RGF002 IThe status flag (BSCFLAG) I
I in the ESCBLOK indicatesl
a condition that is net
valid for a 3270 line
reset function (teleprocessing code 09).
RNH001
IA fatal I/O error
IRetry. If the problem persists,
I occurred during read or
ensure that the 3704/3705 and
I write for the 3704/3705.1 channel hardware are functioning
I Status indicates programl correctly.
I failure.
I
RNH002 IA response that should
I not occur was received
I from the 3704/3705
I control program.
RPAOOl
IVerify that the 3704/3705 NCP is
I operating correctly.
Use the
I NETWORK TRACE command to determine
I the exact cause of the response.
IThe virtual address
I supplied to DMKRPAGT is
I outside of the virtual
I storage being
I referenced.
RPA002
Figure 10.
IThe virtual storage belengs either
I to the user whose VMBLOK is
I pointed to by GR 11 or, if GR 2 in
I the SAVEAREA indicates a PARM of
I SYSTEM, to the system VMBLOK.
Identify the calling program by
means of the return address and
The virtual address
base register saved in the
supplied to DMKRPAPT is
SAVEAREA pointed to by GR 13. If
outside of the virtual
the virtual address was obtained
storage being
from the system's virtual storage,
referenced.
examine the virtual page
allocation routine, DMKPTRVG. If
the virtual page refers to a
user's storage, attempt to
identify the routine that has
generated the incorrect address.
Verify that the VMSIZE in the
relevant VMBLOK reflects the
correct storage size for the
system or user being referenced.
CP ABEND Codes (Part 12 of 14)
Part 1: Debugging with VM/370
117
GC20-1807-3 Page Modlfled by TNL GN20-2662, March 31,
., n
-,r
I ;1 , .J
r
ABEND
Code
RPA003 IThe user page count in
I the VMBLOK became
I negative.
I
I
SCH001
Action
Reason for ABEND
IA module has attempted to release
more pages than it originally
received. The module that last
called DMKRPA is probably the
module in error.
IThe total number of userslThe field SCHN1 is the count of
(interactive users plus I the number of interactive users
batch users) in the
I and the field SCHN2 is the count
scheduler's queue is
I of the number of batch users.
less than zero. A
I Check the routines that update
counter was probably
I these two count fields (SCHN1 and
decremented incorrectly. I SCHN2) to determine why their sum
I was negative.
TDK001
IA program is attempting
IVerify that GR 8 points to a
to deallocate a cylinderl RDEVBLOK for a CP-owned volume. If
of T-DISK space for
I it does not, the error probably
which no cylinder
I originated in the calling program.
allocation block
I Identify the caller by means of
(ALOCBLOK) exists.
I the return address and base
register in the SAVEAREA pointed
TDK002 A program is attempting
to by GR 13, and attempt to
to deallocate
identify the source of the
cylinder(s} of T-DISK
incorrect RDEVBLOK address. If the
space that are not
RDEVBLOK is valid, it is possible
marked allocated.
that the cylinder number passed is
incorrect. The VDEVBLOK for the
device for which the T-DISK was
defined may have been destroyed.
If the cylinder number appears
valid, examine the allocation
record on the real volume by
running DMKFMT (VM/370 FORMAT
program), invoking the ALLOCATE
option without allocating any new
space. If the output indicates the
deallocated cylinder falls within
an area defined for T-DISK
allocation, the ALOCBLOK chained
to the RDEVBLOK may have been
destroyed.
I
I UDR001 IThe user directory modulelUse the DASD Dump Restore program
I is looping trying to
I to print the UDIRBLOK page buffers
I
I read all of the UDIRBLOKI from the directory device.
I
I page buffers from the
I Determine if the chain pointers
I
I directory device. Or, a I are valid.
I
I directory containing
I
I
lover 10,816 users was
I
I
I loaded.
I
I
I
I VDB002 IThe system-owned list haslIPL to restart. If the problem
I an invalid format.
persists, check the SYSOWN macro
I
I in DMKSYS for validity. If the
I
I
I macro is good, print the dump and
I
I
I examine it.
I
I
L
Figure 10.
118
CP ABEND Codes (Part 13 of 14)
IBM VM/370: system Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
r
, ABEND
, Code
,
,,, VDR003
Action
Reason for ABEND
,The DASD link chain is
IIPL to restart. If the problem
persists, examine the RDEVSYS
invalid. In the case of
flag. If the RDEVSYS flag is off,
minidisks, attaching a
minidisk that points to
the problem is especially serious:
an RDEVBLOK whose count , print the dump and examine it.
of users is already zero, Examine the VDEVBLOK and RDEVBLOK
causes this ABEND.
I checking the link chain.
VI0002
DMKSCNVU was unable to
locate all of the
virtual I/O contrel
blocks for the virtual
unit address associated
with the interrupt just
stacked.
VI0003 IDMKIOS has returned an
I IOBLOK indicating a
I condition code of 2 was
, received from the start
I I/O for the operation.
I
I
verify that the unit address in the
field IOBVADD in the IOBLOK
pointed to by GR 10 is valid for
the user who initiated the I/O.
The field IOBUSER contains the
address of the user's VMBLOK. If
the address is valid, the
integrity of the user's virtual
I/O configuration has probably
been destroyed. If the address is
not valid, the IOBLOK has been
altered, or was built incorrectly
in the first place.
ICondition code 2 should never be
I returned to the virtual I/O
I interrupt handler. Its presence
I indicates either a failure in the
I I/O Supervisor (DMKIOS), or that
I the status field in the IOBLOK
I (IOBSTAT) has been destroyed.
VSP001 IThe virtual spooling
IVerify that the unit address
manager could not locatel (IOBVADD) in the IOBLOK is valid.
all virtual control
I If the address is valid, the
blocks for an interI integrity of the virtual I/O
rupting unit.
I configuration has probably been
I destroyed. If the address is not
I valid, the IOBLOK has been alteredl
I or was built incorrectly.
I
Figure 10.
CP ABEND Codes (Part 14 of 14)
Part 1: Debugging with VM/370
119
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
COLLECT INFORMATION
Examine several other fields in the PSA to analyze the status of the
system.
As you progress in reading the dump, you may return to the PSA
to pick up pointers to specific areas
(such as pointers to the real
control blocks) or to examine other status fields.
The following
information.
1.
areas
of
the
PSA
may
contain
useful
debugging
CP Running status Field
The CP running status is stored in CPSTAT at location X'34S'. The
value of this field indicates the running status of CP since the
last entry to the dispatcher.
Value of
_~R'§1!1_
X'SO'
X'40'
X'20'
2.
Comments
cp-Is-In
wait state
CP is running the user in RUNUSER
CP is executing a stacked request
Current User
The PSi that was most recently loaded by the dispatcher is saved in
RUNPSi at location X'330', and the address of the dispatched VMELOK
is saved in RUNUSER at location X'33S'.
Also, examine the contents
of control registers 0 and 1 as they were when the last PSi was
dispatched.
See RUBCRO
(X'340') and RUNCRl
(X'344')
for the
control registers.
Also, examine the CP internal trace table to determine the events
that preceded the abnormal termination.
start with the last event
recorded in the trace table and proceed backward through the trace table
entries. The last event recorded is the last event that was completed.
The trace table is at least one page (4096 tytes) long. One page is
allocated to the trace table for each block of 256K bytes of real
storage available at IPL time.
!ach trace table entry is 16 bytes long.
The TRACSTRT field (location X'OC') contains the address of the start of
the trace table. The TRACEND field
(location X'10')
contains the
address of the byte following the end of the trace table.
And, the
address of the next available trace table entry is found in the TRACCURR
field (location X '14') •
Subtract 16 (X'10') bytes from the value at X'14' (TRACCURR) to find
the address of the last trace table entry recorded.
Figure 9, earlier
in this section, describes the format of each of the 16 possible types
of trace table entries.
REGISTER USAGE
In order to trace control blocks and
the CP register usage conventions.
modules, it is necessary
to know
The 16 general registers have many uses that vary depending upon the
operation. The following table shows the general use of some of the
general registers.
120
IBM VM/370: system Programmer's Guide
!!§.9!§.!§f
GR 1
GR 2
GR 6,7,8
GR 10
GR 14, 15
Contents
The-vIrtual address to be translated.
The real address or parameters.
The virtual or real channel, control unit,
control blocks.
The address of the active IOBLOK.
The external branch linkage.
and device
The following general registers always contain the same information.
Contents
The-address of the active VftBLOK.
The base register for the module executing.
The address of the current save area, if the module was
called via an SVC.
!!§.91§.!§!
GR 11
GR 12
GR 13
use these registers along with the CP contrel blocks and the data in
the Prefix storage Area to determine the error that caused the CP
ABERD •
.SAVE AREA CONVENTIONS
There are three save areas that may be helpful in debugging CP. If a
module was called by an SVC, examine the SAVEAREA. SAVEAREA is not in
the PSA; the address of the SAVEAREA is found in general register 13.
If a module was called by a branch and link, the general registers are
saved in the PSA in an area called BALRSAVE (X'240').
The DftKFRE save
area and work area is also in the PSA: these areas are only used by the
DftKFREE and DftKFRET routines.
The DftKFRE save area (FREESAVE) is at
location X'280' and its work area (FREEWORK) follows at location
X' 2CO ' •
Use the
executed.
1.
save areas to trace
backwards and find the
previous module
SAVEAREA
An active save area contains the caller's return address in
SAVERETN (displacement X'OO'). The caller's base register is saved
in SAVER12 (displacement X'04'), and the address of the save area
for the caller is saved in SAVER13 (displacement X'08'). Using
SAVER13, you can trace backwards again.
2.
BALRSAVE
All the general registers are saved in BALRSAVE after branching and
linking (via BALR) to another routine.
Look at BALR14 for the
return address saved, BALR13 for the caller's save area, and BALR12
for the caller's base register, and you can trace module control
backwards.
3.
FREESAVE
All the general registers are saved in FREESAVE before DftKFRE
executes. Use this address to trace module control backwards.
Part 1: Debugging with Vft/370
121
lig.!g
FREER15
FREER14
FREER13
FREER12
FREER1
FREERO
Contents
The-entry point (DMKFREE or DMKFRET).
The saved return address.
The caller's save area (unless the caller was called via
BALR).
The caller's base register.
Points to the block returned (for calls to DMKFRET) •
Contains
the number
of
doublewords requested
or
returned.
VIRTUAL AND REAL CONTROL BLOCK STATUS
Examine the virtual and real control blocks for more informaticn on the
status of the CP system. Figure 11 describes the relationship of the CP
control blocks; several are described in detail in the following
paragraphs.
The address of the VMBLOK is in general register 11.
Examine the following VMBLOK fields:
1•
The virtual machine running status
The value of
(displacement X'5S').
running status:
is contained in VMRSTAT
this field indicates the
Value of
l].!t~I!!_
X'SO'
X' 40'
X'20'
X '1 0 '
X' OS'
X' 04 •
X'02'
X' 01 '
2.
~Q!!~H!i~
waiting
executing console function
Waiting
page operation
Waiting -- scheduled IOBLOK start
Waiting -- virtual PSW wait state
Waiting -- instruction simulation
User not yet logged on
User logging off
virtual machine in idle wait state
The virtual machine dispatching status is
(displacement X'59').
The value of this
dispatching status:
contained in VMDSTAT
field indicates the
value of
!~12§!!!_
X'SO'
X'40'
X'20'
X' 10'
X'OS'
X'04'
122
Comments
iIrtual-machine
Virtual machine
virtual machine
virtual machine
virtual machine
Virtual machine
is dispatched RUNUSER
is compute bound
in-queue time slice end
in TIO/SIO busy loop
runnable
in a queue
IBM VM/370: System Programmer's Guide
......
......
Cl
n
I\J
C)
I
~
.ern
IT
O
CBLOK
RCUBLOKs
RCUCHA
_
/
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
3.
Examine the virtual
instruction.
The
(displacement X'A8')
instruction is saved
4.
Find the name of the
(displacement X' 148') •
5.
Check the status of I/O activity.
pertinent information.
a.
PSW and the last virtual machine privileged
virtual machine
PSW is
saved in
VMPSW
and the virtual machine privileged or tracing
in VMINST (displacement X'98').
last CP
command that
executed in
The following
VMCOMND
fields contain
VMPEND
(displacement X'63') contains the interrupt pending
summary flag. The value of VMPEND identifies the type of
interrupt.
Value of
_!~R1B!!L
X'40'
X'20'
X' 10'
X'02'
X'Ol'
b.
Comments
vIrtual-PER (Program Event Recording)
interrupt pending
virtual program interrupt deferred
Virtual SVC interrupt deferred
Virtual I/O interrupt pending
virtual external interrupt pending
VMEXTINT (displacement X'68') contains the external interrupt
pending flags. The value of the flag identifies the external
interrupt.
Value of
YJt~!:!:!!:!:
X'08'
X'04'
Comments
Clock-comparator interrupt pending
CPU timer interrupt pending
Value of
!11~!I!!I_.!l
X'80'
X'40'
X'2F'
c.
Comments
Interval timer interrupt pending
Operator's external button interrupt
pending
External signals pending
VMIOINT (displacement X'6A') contains the I/O interrupt pending
flag.
Each bit represents a channel (0-15). An interrupt
pending is indicated by a 1 in the corresponding bit position.
Value of
!~!Q!!:!:-
d.
124
10000000 00000000
01000000 00000000
Interrupt pending channel a
Interrupt pending channel 1
00000000 00000001
Interrupt pending channel 15
VMIOACTV (displacement X'36')
active channel is indicated
position.
is the active channel mask. An
by a 1 in the corresponding bit
IBM VM/370: System Programmer's Guide
The address of the VCBBLOK table is found in the V"CHSTRT field
(displacement X'18') of the VMBLOK. General register 6 contains the
address of the active VCBBLOK. Examine the following fields:
1.
The virtual
channel address is
contained in
VCHADD (displacement
X'OO').
2.
The status of the virtual channel is found in the VCHSTIT field
(displacement 1;06;;. The value of this field indicates the virtual
channel status:
Value of
VCBSTIT
i'80'-X' 40'
X'Ol'
3.
COllllents
iIrtual-channel busy
virtual channel class interrupt pending
virtual channel dedicated
The value of the VCHTYPE field (displacement
virtual channel type:
X'07') indicates the
value of
.Y~HI.!.f~
X'80'
X'40'
Comments
Virtual-selector channel
virtual block multiplexer
The address of the VCUBLOK table is found in the VCUSTRT field
(displacement X'lC') of the VMBLOK. General register 7 contains the
address of the active VCUBLOK. Useful information is contained in the
following fields:
1.
The virtual control unit address
(displacement X'OO')~
is
found in
2.
The value of the VCUSTAT field (displacement
status of the virtual control unit:
the VCUADD
field
X'06') indicates the
Value of
!~J1~l!I
X'80'
X' 40'
X' 20 '
X' 10'
X '08
3.
'
Com.ents
iIrtual-subchannel busy
Interrupt pending in subchannel
Virtual control unit busy
Virtual control unit interrupt pending
virtual control unit end pending
The value of the VCUTYPE field (displacement
type of the virtual control unit:
X'07') indicates the
Value of
.Y~.Ylli~
X'80'
X' 40 '
Comments
vIrtual-control unit on shared subchannel
virtual control
unit is
a channel-to-channel
adapter
Part 1: Debugging with VM/370
125
The address of the VDEVBLOK table is found in the VMDVSTRT field
(displacement X'20') of the VMBLOK. General register 8 contains the
address of the active VDEVBLOK. Useful information is contained in the
following fields:
The value of the VDEVSTAT field (displacement X'06') describes the
status of the virtual device:
X'80'
X'40'
X'20'
X'10'
X'08'
X'04 '
X'02'
X'Ol'
3.
found
in
field
2.
Value of
is
VDEVADD
The virtual device
(displacement X'OO').
!Q!!~I!I
address
the
1.
Comllents
iIrtuiI-subchannel busy
virtual channel interrupt pending
Virtual device busy
Virtual device interrupt pending
Virtual control unit end
Virtual device not ready
virtual device attached by console function
VDEVREAL is dedicated to device RDEVBLOK
The value of the VDEVFLAG field (displacement X'07') indicates the
device dependent information:
Value of
VDEVFLAG
i'80'--X'SO'
X'40'
X '40'
X'40'
X '20'
X' 10'
X '10'
X'08'
X '02'
X' 0 l'
Comments
nAsn-==-read/only device
virtual 2701/2702/2703 device
line enabled
DASD -- TDISK space allocated by CP
virtual 2701/2702/2703 device
line connected
Console -- activity spooled
DASD -- 2311 device simulated on top half of 2314
DASD -- 2311 device simulated on bottom half of 2314
Console and spooling device -- processing first CCw
DASD -- executing standalone seek
RESERVE/RELEASE are valid CCW operation codes.
virtual device sense bytes present
4.
The VDEVCSW field (displacement X'OS') contains the virtual channel
status word for the last interrupt.
5.
The VDEVREAL field (displacement X'24') contains the pointer to the
real device block, RDEVBLOK.
6.
The VDEVIOB field (displacement X'34')
active IOBLOK.
7.
For console devices, the value of the VDEVCFLG field (displacellent
X'26') describes the virtual console flags:
contains the pointer to the
Value of
!Q!!~l~§
X'SO'
X'40'
X'20'
X' 10'
X'OS'
126
COllments
User-signalled attention too many times
Last CCW processed was a TIC
Data transfer occurred during this channel program
virtual console function in progress
Automatic carriage return on first read
IBM VM/370: System Programmer's Guide
8.
For spooling devices, the value of the VDEVSFLG field (displacement
X'27') describes the virtual spooling flags:
Value of
.!~E.!~1.L2
X'80'
X'80'
X'40'
X'20'
X' 10'
X'08'
X'08'
X'04'
X'02'
X'02'
X' 0 l'
9.
Comments
Spool-reader
last command was a feed
Spool output
transfered to VSPXXUSR
Spool device
continuous operation
Hold output -- save input
Spool output -- for user and distribution
Spool input -- set unit exception at EOF
Terminal output required for spooled console
Device closed by console function
Spool output -- purge file at close
Spool input -- device opened by DIAG~OSE
Spool output -- DMKVSP entered via svc
For output spooling devices, the VDlVEXTB field (displacement
X'10') contains the pointer to the virtual spool extension block,
VSPXBLOK.
The address of the first RCHBLOK is found in the ARIOCH field
(displacement X'3B4') of the PSA (Prefix storage Area). General register
6 contains the address of the active RCHBLOK. Examine the following
fields:
1.
The real channel address is found in the RCHADD field (displacement
X'OO') •
2.
The value of the RCHSTAT field (displacement
status of the real channel.
R~!L~!!!
X'80'
X'40'
X'20'
X' 0 l'
3.
X'04') describes the
Com.ents
Channel-busy
lOB scheduled on channel
Channel disabled
Channel dedicated
The value of the RCHTYPE field (displacement
real channel type:
X'OS') describes the
value of
R~1!!!f~
X'80'
X' 40' '
X'20'
X' 01'
4.
Comllents
selector channel
Block lIultiplexer channel
Byte multiplexer channel
S/370 type channel (S/370 instruction support)
The RCHFIOB field (displacement X'08') is the pointer to the first
IOBLOK in the queue and the RCHLIOB field (displacement X'OC') is
the pointer to the last IOBLOK in the queue.
Part 1: Debugging with Vft/370
127
The address of the first RCUBLOK is found in the ARIOCU field
(displacement X'3BS') of the PSA. General register 7 points to the
current RCUBLOK. Exaaine the following fields:
1.
The RCUAtD field (displacement
unit address.
2.
The value of the RCUSTAT field (displacement
status of the control unit:
Value of
RCUSTAT
i18o'-'X'40'
X'20'
X' 0 l '
3.
X'OO') contains
the real
control
X'04') describes the
Com.ents
Control-unit busy
lOB scheduled on control unit
Control unit disabled
Control unit dedicated
The value of the RCUTYPE field (displacement
type of the real control unit:
X'OS'} describes the
Value of
!!~!!%!f~
X'SO'
X' 0 1 '
X'02'
X'03'
4.
Com.ents
ThIS-control unit can attach to only one subchannel
TCU is a 2701
TCU is a 2702
TCU is a 2703
The RCUFIOB field
(displacement X'OS') points to
in the queue and the RCULIOB field (displacement
the last IOBLOK in the queue.
the first IOBLOK
X'OC') points to
The address of the first RDEVBLOK is found in the ARIODV field
(displacement X'3BC') of the PSA. General register 8 peints to the
current RDEVBLOK. Also, the VDEVREAL field (displacement X'24') of each
VDEVBLOK contains the address of the associated RDEVBLOK. Examine the
following fields of the RDEVBLOK:
1.
The RDEVADD
address.
2.
The values of the RDEVSTAT (displacement X'04') and RDEVSTA2
(displacement X'45') fields describe the status of the real device:
Value of
RDEVSTAT
X'80'--X'40'
X'20'
X' 10'
X' 08'
X'04'
X' 0 l'
Value of
RDEVSTA2
i'80'--X'40'
X'20'
12S
field (displacement
X'OO') centains
the real
Comments
DevIcebusy
lOB scheduled on device
Device disabled (offline)
Device reserved
Device in intensive error recording mode
Device intervention required
Dedicated device (attached to a user)
Comments
Active-device is being reset
Device is busy with the channel
Contingent connection present
IBM VM/370: System Programmer's Guide
device
3.
The value of
device flags.
Value of
RDEVFLIG
i'80'--X'40'
X'20'
X'10'
X'08'
X'80'
X'40'
X'20'
X'10'
X' 08'
X '04'
x'02'
X'Ol'
X' 80'
X'40'
X'20'
X '10'
X'08'
X '04 '
X'02'
X '01 '
X'80'
X '40 '
X' 20'
X '10 '
X'08'
X '04 '
X'02'
X' 01 '
the BDEVFLAG field (displacement X'OS')
These flags are device dependent.
indica tes
~.Q.!.!!!nt.§
DASD
ascending order seek que?ing
DASD
volume preferred for pag1ng
DISD
volume attached to system
DISD
CP owned volume
DASD
volume mounted but not attached
Console
terminal has print suppress
Console
terminal executing prepare co •• and
Console
IOBLOK pending; queue request
Console
2741 terminal code identified
Console
device is enabled
Console
next interrupt from a halt I/O
Console
device is to be disabled
Console
3704/370S ICP resource in EP mode
spooling
device output drained
spooling
device output terminated
Spooling
device busy with accounting
Spooling
force printer to single space
spooling
restart current file
Spooling
backspace the current file
Spooling
print/punch job separator
Spooling
UCS buffer verified
Special
network control program is active
Special
2701/2702/2703 e.ulation program is active
Special
3704/370S is in buffer slowdown mode
Special
automatic dump/load is enabled
Special
IOBLOK is pending; queue requests
Special
emulator lines are in use by system
Special
automatic dump/load process is active
Special
basic terminal unit trace requested
4.
The value of the RDEVTYPC field (displacement X'06') describes the
device type class and the value of the RDEVTYPE field (displacement
X'07') describes the device type. Refer to Figure 12 for the list
of possible device type class and device type values.
S.
The RDEVAIOB field (displacement X'24') contains the address of the
active IOBLOK.
6.
The RDEVUSER field (displacement X'28') points
dedicated user.
7.
The BDEVITT field
virtual address.
8.
The BDEVIOEB field (displacement X'48') contains the address of the
IOERBLOK for the last CP error.
9.
For spooling unit record devices, the RDEVSPL
X'18') points to the active RSPLCTL block.
10.
(displacement
X'2C')
to the VMBLOK for a
contains
the
attached
field (displacement
For real 3704/370S Communications Controllers, several pointer
fields are defined. The RDEVEPDV field (displacement X'lC') points
to the start of the free BD!VBLOK list for EP lines. The RDEVRICL
field (displace.ent X'38')
points to the network control list and
the RDEVCKPT field (displacement X'3C') points to the CKPBLOK for
re-enable. Also, the RDEVMIX field (displacement X'2E') is the
highest valid ICP resource name and the RDEVICP field (displacement
X'30') is the reference name of the active 370S RCP.
Part 1: Debugging with VM/370
129
11 •
For terminal
the RDEVTFLG
flags:
devices, additional flags are defined. The value of
field (displacement X'3E') describes the additional
Value of
~J1~!Ill~
X'SO'
X'40'
x'20'
X'SO'
X' 40'
X'20'
X' 10'
X'OS'
X' 04'
X' 02 '
12.
Comments
TeriIiiiI
Terminal
Teraina1
Graphic
Graphic
Graphic
Graphic
Graphic
Graphic
Graphic
logon process has been initiated
terminal in reset process
suppress attention signal
screen full, in held status
screen full, more data waiting
screen in running status
read pending for screen input
last input not accepted
timer request pending
CP command interrupt pending
For terminals, an additional flag is
RDEVTMCD field
(displacement X'46')
translation to be used:
Value of
!!DE!I~£J1
130
Coaments
X' 10'
uisci~=- S level
X'OC'
X'OS'
X'04'
X'OO'
APL correspondence
APL PTTC/EBCD
Correspondence
PTTC/EBCD
IBM VM/370: System Programmer's Guide
defined. The value of the
describes the line code
r-------------------------------------------------------------------------,
DEVICE CLASS CODES (COLUMN 33 IN ACCOUNTING CARD)
~Qg~
X'80'
X' 40'
X'20'
X' 10'
X'08'
X' 04'
X'02;
Device Class
TermInal-Device
Graphics Device
unit Record Input Device
unit Record Output Device
Magnetic Tape Device
Direct Access storage Device
Special Device
DEVICE TYPE CODES (COLUMN 34 IN ACCOUNTING CARD)
1.
For Terminal Device Class
£QQ.~
X' 40'
X'40'
X' 20'
X '20'
X' 10'
X' 18 '
Xii 8 i
X '14 '
X' lC'
X'OO'
X'OO'
X'OO'
X' 00'
X'OO'
2.
J2!!!i~ !IE~
2700 Binary synchronous Line
2955 Communication Line
Telegraph Terminal Control Type II
Teletype Terminal
IBM Terminal contro1 Type I
IBM 2741 Communication Terminal
IBM 3767 Communication Terminal
IBM 1050 Data Communication System
Undefined Terminal Device
IBM 3210 Console
IBM 3215 Console
IBM 2150 Console
IBM 1052 Console
IBM 7412 Console
For Graphics Device Class
~.Qg~
X'80'
X' 40'
X'20'
X' 10'
X'08'
X' 04'
X '02'
X' 02'
igure 12.
J2~!.!£~ lI.E!!
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
2250
2260
2265
3066
1053
3277
3284
3286
Display
Display
Display
Console
Printer
Display
Printer
Printer
Unit
station
station
station
CP Device Classes, Types, Models, and Features (Part 1 of 3)
Part 1: Debugging with VM/370
131
3.
Por unit Record Input Device Class
Code
~evice ~
X'Sl'
X'S2'
X'S4'
X'SS'
X'90'
X'40'
X'20'
X'21'
X'22'
X'24'
Card Reader
IBft 2501 Card Reader
IBft 2540 Card Reader
IBft 3505 Card Reader
IBft 1442 Card Reader/Punch
IBft 2520 Card Reader/Punch
Tiaer.
Tape Reader
IBft 2495 ftagnetic Tape Cartridge Reader
IBft 2611 Paper Tape Reader
IBft 1011 Paper Tape Reader
i,so'
4.
Por Unit Record output Device Class
~~ice Ill~
~Qg~
Card Punch
IBft 2540 Card Punch
IBft 3525 Card Punch
IBft 1442 Card Punch
IBft 2520 Card Punch
Printer
IBft 1403 Printer
IBft 3211 Printer
IBft 1443 Printer
Tape Punch
IBft 101S Paper Tape Punch
X'SO'
X'S2'
X'S4'
X'SS'
X'90'
X'40'
X'41'
X'42'
X'44'
X'20'
X'24'
5.
Por
~agnetic
Code
I'eo'
X'40'
X'20'
X' 10'
X'OS'
6.
~~.!ice Ta:E~
IBft
IBft
IBft
IBft
IBft
2401 Tape
2415 Tape
2420 Tape
3420 Tape
3410/3411
Drive
Drive
Drive
Drive
Tape Drive
Por Direct Access Storage Device Class
Code
i'so'
X'40'
X'40'
X'20'
X' 10'
X' 10'
X'OS'
X'04'
X'02'
X'Ol'
Figure 12.
132
Tape Device Class
~~!ic~ I:l.E~
IBft
IBft
IBft
IBft
IBft
IBft
IBft
IBft
IBft
IBft
2311
2314
2319
2321
3330
3333
2301
2303
2305
3340
Disk storage Drive
Disk storage Facility
Disk storage Facility
Data Cell Drive
Disk storage Facility
Disk Storage and Control
Parallel Drum
Serial Drum
Fixed Head storage Device
Disk Storage Facility
CP Device Classes, Types, ftodels, and Features (Part 2 of 3)
IBft Vft/310: System Programmer's Guide
r-----------------------------------------------------------------------~
7.
For Special Device Class
Code
X'80'
X'40'
X' 01'
~evi£~ ~IE~
Channel-to-Channel Adapter (CTCA)
3704/3705 programmable-Communications Controller
Device unsupported by VM/370
MODEL CODES (CCLUMN 35 IN ACCOUNTING CARD)
As specified in the RDEVIC! macro at system generation.
FEATURE CODES (COLUMN 36 IN ACCOUNTING CARD)
1.
For printer Devices
2.
For Magnetic Tape Devices
£Q~~
X'SO'
X '40 '
X' 20'
X '1 0 '
3.
Dual Density
Translate
Data Conversion
For Direct Access Storage Devices
Code
X'8Q'
X' 20'
X '1 0 '
X' OS'
X'04'
X' 02'
4.
Feature
7=Track
Feature
RotatIonal position Sensing (RPS) installed (3340)
Top Half of 2314 Used as 2311
Bottom Half of 2314 Used as 2311
35MB Data Module (mounted)
70MB Data Module (mounted)
Reserved/Release are valid CCi operation codes
For special devices
£Q~~
X' 10'
X'20'
Figure 12.
Feature
rype-i-channel adapter for 3704/3705
Type II channel adapter for 3704/3705
CP Device Classes, Types, Models, and Features (Part 3 of 3)
IDENTIFYING A PAGEABLE MODULE
If a program check PSi or SVC PSi points to an address beyond the end of
the CP resident nucleus, the failing module is a pageable module. The
CP system load map tells you where the end of the resident nucleus is.
Go to the address indicated in the PSi. Backtrack to the beginning
of !!~! page frame. The first eight bytes of that page frame (the page
frame containing the address pointed to by the PSi) contains the name of
the failing module. If multiple modules exist within the same page
frame, identify the module using the load map and failing address
displacement within the page frame.
Part 1: Debugging with VM/370
133
Debugging with eMS
This section describes the debug tools that CMS provides. These tools
can be used to help you debug CMS or a problem progra..
In addition, a
CMS user can use the CP commands to debug.
Information that is often
useful in debugging is also included.
The following topics are
discussed in this section:
•
•
•
•
•
CMS debugging commands
DASD dump restore program
Load maps
Reading CMS dumps
control block summary
CMS provides two commands that are useful in debugging:
SVCTRACE.
Eoth commands execute from the terminal.
DEBUG
and
The debug environment is entered whenever:
•
•
•
The DEBUG command is issued
A breakpoint is reached
An external or program interrupt occurs
CMS will not accept other commands while in
However, while in the debug environment, the
cOllmand can:
•
set breakpoints (address
specific locations.
•
Display the contents of the CAW
(channel address word), CSW (channel
status word), old PSW (program status word), or general registers at
the terminal.
•
Change the contents
general registers.
•
Dump all or part of virtual storage at the printer.
•
Display the
terllinal.
•
store data in virtual storage locations.
•
Allow an origin or base address to be specified for the program.
•
Assign symbolic names to specific storage locations.
•
Close all open
directory.
•
Exit from the debug environment.
13q
stops)
of the
contents of
files and
which
the debug environment.
options of the DEBUG
stop program
control words
up to 56
bytes of
I/O devices
IBM VM/370: System Programmer's Guide
(CAW, CSW
execution
and PSW)
virtual storage
and update
the master
at
and
at the
file
The SVCTRACE command records information for all SVC calls. When the
trace is terminated, the information recorded up to that point is
printed at the system printer.
In addition, several CftS commands produce or print load maps. These
load maps are often used to locate storage areas while debugging
programs.
nt:lDnr
jJJjjJU U
The DEBUG command provides support for debugging programs at a terminal.
The virtual machine operator can stop the program at a specified
location and examine and alter virtual storage, registers, and various
control words. Once CMS is in its debug environment, the virtual
machine operator can request the various DEBUG options. However, in the
debug environment, all of the other CMS commands are considered
invalid.
Any DEBUG subcommand may be
environment and if the keyboard is
to DEBUG subcommands:
entered if CMS is in the debug
unlocked. The following rules apply
1•
No operand should be longer than eight characters.
longer than eight characters are left justified and
the right after the eighth character.
2.
The DEFINE subcommand must be
DEBUG symbol table.
3.
The DEBUG subcommands can be truncated. The following is a list of
all valid DEBUG subcommands and the1r minimum truncation.
create all entries
in the
Minimum
.'E!:!!!!£!tio!!
BR
CAW
CSW
DEF
DU
GO
GPR
HX
OR
PSW
RET
SET
ST
.§Y~£.Q!!g!!g
BREAK
CAW
CSW
DEFINE
DUMP
GO
GPR
HX
ORIGIN
PSW
RETURN
SET
STORE
X
One way to enter
command. The message
used to
All operands
truncated on
X
the
debug
environment
is
to issue
the
DEBUG
DMSDBG7281 DEBUG ENTERED
appears at the terminal. Any of the DEBUG subcommands may be entered.
To continue normal processing, issue the RETURN subcommand.
Whenever a program check occurs, the DMSABN routine gains control.
Issue the DEBUG command at this time if you wish CMS to enter its debug
environment.
Part 1: Debugging with VM/370
135
Whenever a
.essage
breakpoint is encountered,
a program check
occurs.
The
DEBUG ENTERED
BREAKPOINT II AT XXXXX
D~SDBG7281
appears on the terminal.
Pollow the same procedure to enter subco.mands
and resume processing as with a regular progra. check.
An external interrupt, which occurs when the CP EXTERNAL co •• and is
issued, causes CftS to enter its debug environment. The message
D~SDBG7281
DEBUG ENTERED
EXTERNAL INTERRUPT
appears on the console. Any of the DEBUG subco.mands may be issued.
exit from the debug environment after an external interrupt, use GO •
To
•
While CMS is in its Debug environment, the control words and low
storage locations contain the Debug program values.
The Debug program
saves the control words and low storage contents (X'OO' - X'100') of the
interrupted routine at location X'CO'.
The following
subcommands.
is
a
detailed
discussion
of
the
possible
DEBUG
The format of the BREAK subcommand is
r----------------------------------------------------------------------------,
I BReak
id { Symbol}
I
hexloc
L ____- -____________________________________________________________________~
id
is a decimal
breakpoint.
symbol
is a name assigned to
the storage location where the
breakpoint is set.
The symbolic name must be previously
assigned to the storage address using the DEP subcommand of
the DEBUG command.
hexloc
is the hexadecimal storage location (relative to
origin) where the breakpoint is set.
number,
from 0
to
15,
which identifies
the
the current
Use the BREAK subcommand to set breakpoints which stop execution of a
program or module at specific instruction locations, called breakpoints.
Issuing the BREAK subcommand causes a single breakpoint to be set. A
separate BREAK subcommand must be issued for each breakpoint desired.
A
maximum of 16 breakpoints (with identification numbers 0 through 15) may
be in effect at one time; any attempt to set more than 16 breakpoints is'
rejected.
Breakpoints should be set after a program is loaded, but before it
executes.
When a breakpoint is encountered during program execution,
136
IBM VM/370: system Progra.mer's Guide
execution stops and the debug environment is entered. The virtual
aachine operator can then use the other DEBUG subco •• ands to analyze the
prograa at that particular point. Registers, storage, and control words
can be examined and altered.
After the virtual machine operator
finishes analyzing the program at this point in its execution, he issues
the GO subcommand to resume program execution.
Breakpoints are set before the program executes.
They are set on
instruction (halfword)
boundaries at locations that contain operation
codes.
After setting all the desired breakpoints, issue the RETURN
subcommand to exit from the debug environment. Then issue the efts START
command to begin program execution.
The first
operand of the
BREAK subcom.and
(id)
assigns an
identification number (0-15)
to the breakpoint. If the identification
number specified is the same as a currently set breakpoint, the previous
breakpoint is cleared and the new one is set.
The second operand of the BRBAK subcommand
(symbol or hexloc)
indicates the storage location of the breakpoint~ If the operand
contains any nonhexadecimal characters, the DEBUG symbol table is
searched for a matching symbol entry.
If a match is found, the
breakpoint is set at the storage address corresponding to that symbol,
provided that the storage address is on an even (halfword) boundary. If
no match is found in the DEBUG symbol table (and the operand is a valid
hexadecimal nuaber), the second operand is treated as the hexadecimal
representation of the storage address. When the second operand is a
valid hexadecimal number, this number is added to the program origin.
If the resulting storage address is on a halfword boundary and is not
greater than the user's virtual storage size, the breakpoint is set.
When the debug program sets a breakpoint, it saves the contents of the
halfword at the location specified by the second operand of the BREAK
subcommand.
This halfword is replaced by B2EX, where x is the
hexadecimal equivalent of the identification number, specified in the
first operand of the BRBAK subcommand. The storage location specified
for a breakpoint must contain an operation code. It is the user's
responsibility to see .that breakpoints are set only at locations
containing operation codes.
After breakpoints are set and during
program execution, the value B2EO through B2BP is encountered at a
location where an operation code should appear. A program check occurs
because all values B2EO through B2EP are invalid operation codes and
control is transferred to the debug environment.
DEBUG recognizes the
invalid operation code as a breakpoint.
The original operation code
replaces the invalid operation code, and a message
D"SDBG728I DEBUG ENTERED
BREAKPOINT yy AT xxxxxx
appears at the terminal.
"yy" is the bre~kpoint identification number
and xxxxxx is the storage address of the breakpoint.
After the message
is typed, the keyboard is unlocked to accept any DEBUG subcommands
except RETURN.
A breakpoint is cleared when it is encountered during
program execution.
Part 1: Debugging with V"/370
137
It is the responsibility of the user to ensure that breakpoints are
set only at operation code locations.
Otherwise, the breakpoint is not
recognized;
data or some part of the instruction other than the
operation code is
overlaid.
Thus,
errors may
be generated if
breakpoints are set at locations that do not contain operation codes.
The following
subcommand.
error
messages
may appear
while
entering
the
BREAK
INVALID OPERAND
This message indicates that the breakpoint identification number
specified in the first operand is not a decimal number between 0 and
15 inclusive, or the second operand cannot be located in the DEBUG
symbol table and is not a valid hexadecimal number. If the second
operand is intended to be a symbol, a DEF subcommand must have been
previously issued for that symbol; if not, the operand must be a
valid hexadecimal storage location.
INVALID STORAGE REFERENCE
The location indicated by the second operand is uneven (not on a
halfword boundary) or the sum of the second operand and the current
origin value is greater than the user's virtual storage size.
If the
current origin value is unknown, it may be reset to the desired value
by issuing the ORIGIN subcommand.
MISSING OPERAND
The minimum number of operands has not been supplied.
TOO
~ANY
OPERANDS
The user entered more than two operands.
HEXLOC 'hexaddr' IN SHARED STORAGE
A shared system was loaded (via IPL) and an attempt was made to
modify a storage location between X'10000' and X'20000', the shared
storage. To set a breakpoint in this address range, IPL a nonshared
system.
138
IBM VM/370: System Programmer's Guide
The format of the CAW subcommand is:
I __________________________________________________
CAW I
L
- -______________________~
The CAW subcommand has no operands.
The ~AW subcommand may be issued whenever the debug environment is
entered. Issuing the CAW subcommand causes the contents of the CAW
(channel address word), as it existed at the time the debug environment
was entered, to appear at the terminal. The CAW located at storage
location X'48' is saved at the time the debug environment is entered and
displayed on the terminal whenever the CAW subcommand is issued. If the
subcommand is issued correctly, the contents of the CAW are typed in
hexadecimal representation at the terminal.
The format of the CAW is:
KEY I 0000 I
o
3 4
Command Address
7 8
31
Contents
The-protection key for all commands associated with start I/O.
The protection key in the CAW is compared to a key in storage
whenever a reference is made to storage.
4-7
This field is not used and must contain binary zeros.
8-31
The command address field contains the storage address (in
hexadecimal representation) of the first CCW (channel command
word) associated with the next or most recent start I/O.
The three low-order bits of the command address field must be zeros
in order for the CCW to be on a doubleword boundary. If the CCW is not
on a doubleword boundary or if the command a6dress-specifies a location
protected from fetching or outside the storage of a particular user,
start I/O causes the status portion of the CSW to be stored with the
program check or protection check bit on. In this event, the I/O
operation is not initiated.
Issue the CAW subcommand to check that the command address field
contains a valid CCW address, or to find the address of the current CCW
so you can examine it.
The following
subcommand.
error
message
may
appear
while
entering
the
CAW
TOO MANY OPERANDS
An operand was entered on the command line; the CAW subcommand has no
operands.
Part 1: Debugging with V8/370
139
The format of the esw subcoamand is:
esw
The esw subcommand has no operands.
The esw subco.aand aay be issued whenever the debug environment is
entered. Issuing the esw subcommand causes the contents of the esw
(channel status word), as it existed at the time the debug environment
was entered, to appear at the terminal. The esw indicates the status of
the channel or an input/output device, or the conditions under which an
I/O operation terainated.
The esw is formed in the channel and stored
in storage location X'40' when an I/O interrupt occurs.
If I/O
interruptions are suppressed, the esw is stored when the next start I/O,
Test I/O, or BaIt I/O instruction is executed. The esw is saved when
DEBUG is entered.
If the subcommand is issued correctly, the contents of the
displayed at the ter.inal in hexadecimal representation.
esw are
The format of the esw is:
I
status
Command Address
IKEYIOOOOI
03478
31 32
Byte Count
47 48
63
Contents
The--protection key is moved to the esw from the elW.
It
indicates the protection key at the time the I/O started. The
contents of this field are not affected by programming errors
detected by
the channel or
by the
condition causing
termination of the operation.
4-7
This field is not used and must contain binary zeros.
8-31
The command address contains a storage address (in hexadecimal
representation) eight bytes greater than the address of the
last eew executed.
32-47
The status bits indicate the conditions
channel that caused the esw to be stored.
48-63
The residual count is the difference between the number of
bytes specified in the last executed eew and the number of
bytes that were actually transferred. When an input operation
is terminated, the difference between the original count in
the eew and the residual count in the esw is equal to the
number of bytes
transferred to storage; on
an output
operation, the difference is equal to the number of bytes
transferred to the I/O device.
in
the device
or
Whenever an I/O operation abnormally terminates, issue the esw
subcommand. The status and residual count information in the esw is
very useful in debugging.
Also, use the esw to calculate the address of
the last executed eew (subtract 8 bytes from the command address to find
the address of the last eew executed).
140
IBft VM/370: System Programmer's Guide
The following
subcommand.
error
message
may
appear
when
you
enter
the
CSW
TOO ftANY OPERANDS
An operand was entered on the command line; the CSW subcommand has no
operands.
Part 1: Debugging with VM/370
141
The format of the DEFINE subcommand is:
r
DEFine
symbol
hexloc
,
lbytecountl
I
~
I
L
symbol
is the name to be assigned to the storage
from the second operand, hexloc.
hexloc
is the hexadecimal storage location,
in relation to the
current origin, to which the name specified in the first
operand (symbol), is assigned.
bytecount
is a decimal number, between 1 and 56 inclusive, which
specifies the length in bytes of the field whose name is
specifed by the first operand
(symbol) and whose starting
location is specified by the second operand (hexloc). When
the bytecount operand is not specified, a default bytecount
of 4 is assumed.
address derived
Use the DEFINE subcommand to assign symbolic names to a specific
storage address.
Once a symbolic name is assigned to a storage address,
that symbolic name can be used to refer to that address in any of the
other DEBUG subcommands.
However, the symbol is valid only in the debug
environment.
The first operand (symbol) may be from one to eight characters long.
It must contain at least one nonhexadecimal character.
Any symbolic
name longer than eight characters is left-justified and truncated on the
right after the eighth character.
The second operand (hexloc), a hexadecimal number, is added to the
current origin established by the ORIGIN subcommand.
The sum of the
second operand (hexloc)
and the origin is the storage address to which
the symbolic name is assigned. In order to assign the symbolic name to
the correct location be sure to know the current origin. The existing
DEBUG symbol table entries remain unchanged when the ORIGIN subcommand
is issued.
The third operand (bytecount), a decimal number between 1 and 56
inclusive, specifies the length of the field whose name is specified by
§I~~Q! and whose starting address is specified by ~~~l~f.
Issuing the DEFINE subcommand creates an entry in the DEBUG symbol
table. The entry consists of the symbol name, the storage address, and
the length of the field. A maximum of
16 symbols can be defined in the
DEBUG symbol table at a given time.
When a DEFINE subcommand specifies a symbol that already exists in
the DEBUG symbol table, the storage address derived from the current
request replaces the previous storage address. Several symbols may be
assigned to the same storage address, but each of these symbols
constitutes one entry in the DEBUG symbol table. The symbols remain
defined until a new DEF is issued for them or until an IPt request loads
a new copy of c~s.
142
IBM
V~/370:
system Programmer's Guide
The following
issued:
error messages may appear
when the DEFINE
subcommand is
INVALID OPERAND
This message indicates that the name specified in the first operand
contains all numeric characters, the second operand is not a valid
hexadecimal number, or the third operand is not a decimal number
between 1 and 56 inclusive.
INVALID STORAGE ADDRESS
The sum of the second operand and the current origin is greater than
the user's virtual storage size.
If the current origin size is
unknown, reset it to the desired value by issuing the ORIGIN
subcommand and then reissue the DEF subcommand.
16 SYMBOLS ALREADY DEFINED
The DEBUG symbol table is full and no new symbols may be defined
until the current definitions are cleared ~y obtaining a new copy of
eMS. However, an existing symbol may be assigned to a new storage
location by issuing another DEF subcommand for that symbel.
MISSING OPERAND
The DEFINE subcommand requires at least
two were entered.
two operands and
less than
TOO MANY OPERANDS
Three is the maximum number of operands for the DEFINE subcommand and
more than three were entered.
Part 1: Debugging with VM/370
143
Q~~f
The format of the DU"P subcommand is:
rI
I
I
I
I
I
DUmp
r
I
I
I
L
,
sy.boll
hexlocl
~
I
I
I
J
,
r
I
I
I
I
L
symbo12
hexloc2
*
11
I
I
I
I
[ident]
J
L-
symboll
is the name assigned
(via the DEFINE subcommand)
storage address that begins the dump.
to
the
hexlocl
is the hexadecimal storage location,
current origin, that begins the dump.
relation
to
the
symbo12
is the name assigned
(via the DEFINE subcommand)
storage address that ends the dump.
to
the
hexloc2
is the hexadecimal storage location,
current origin, that ends the dump.
to
the
*
indicates that the dump
storage address.
ident
is the name
(up to
particular printout.
ends
at
in
in
relation
the user's
eight characters)
last
virtual
that identifies
this
Use the DUMP subcommand to Frint part or all of a user's virtual
storage on the printer. The requested information is printed offline as
soon as the printer is available. First, a heading:
ident FRO" starting location TO ending location
is printed.
Next,
the general registers 0-7 and 8-15, and the
floating-point registers 0-6 are printed. Then the specified portion of
virtual storage is printed with the storage address of the first byte in
the line printed at the left,
followed by the alphameric interpretation
of 32 bytes of storage.
The first and second operands specify the starting and ending
addresses, respectively, of the area of storage to be dumped.
If DUMP
is issued without the first and second operands. 32 bytes of storage are
dumped starting at the current origin.
If DUMP is issued without the
second operand, 32 bytes of storage are dumped starting at the location
indicated by the first operand.
The first and second operands, if specified,
must be either valid
symbols or hexadecimal numbers.
When a symbol is specified, the DEBUG
symbol table is searched.
If a match is found, the storage location
corresponding to that symbol is used as the starting or ending address
for the dump.
When a hexadecimal number is specified, it is added to
the current origin to calculate the starting or ending storage address
for the dump.
The first and second operands must designate storage
addreSses that are not greater than the user's virtual storage size.
144
IBM V"1370: System Programmer's Guide
Also, the storage address derived from the second operand must be
greater than the storage address derived from the first operand. An
asterisk may be specified for the second operand. In this case, all of
storage from the starting address (first operand) to the end of storage
is dumped to the printer.
The following
subcommand.
error
messages
may appear
when
you
issue
the
DUftP
INVALID OPERAND
This message is issued if the address specified by the second operand
is less than that specified by the first operand, or if the first or
second operands cannot be located in the DBBUG symbol table and are
not valid hexadecimal nu.bers. If either operand is intended to be a
symbol, a DBlINB subcommand must previously have been issued for that
syabol: if not, the operand must specify a valid hexadecimal
location.
INVALID STORAGE ADDRESS
The hexadecimal number specified in the first or second operand, when
added to the current.or~g~n, is greater than the user's virtual
storage size.
If the current origin value is unknown, reset it to
the desired value by issuing the ORIGIN subcommand and then reissue
the DUMP subcommand.
TOO
~ANY
OPERABDS
Three is the maximua number of operands for the DUMP subcommand; aore
than three operands were entered.
Part 1: Debugging with VM/370
145
The format of the GO subcommand is:
r---------r
,
I
I symbol I
I GO
I hexloc I
I
L
IL-__________________________________________________________________________
~
symbol
is the name,
already assigned by the DEFINE
storage location where execution begins.
subcommand, to a
hexloc
is the hexadecimal location, in
origin, where execution begins.
to
relation
the
current
Use th~ GO subcommand to exit from the debug environment and begin
execution in the CMS environment. The old PSW for the interrupt that
caused the debug environment to be entered is saved and later loaded to
resume processing. Issuing the GO subcommand loads the old PSi.
When the GO subcommand is issued, the general
registers, CAW
(channel address word), and CSW (channel status word) are restored
either to their contents upon entering the debug environment,
or, if
they have been modified while in the debug environment, to their
modified contents. Then the old PSi is loaded and becomes the current
PSW.
Execution begins at the instruction address contained in bits
40-63 of the PSW.
By specifying an operand with the GO subcommand, it is possible to
alter the address where execution is to begin.
This operand must be
specified whenever the GO subcommand is issued if the debug environment
is entered by issuing the DEBUG command.
The operand may be a symbol or a hexadecimal location.
When a symbol
is specified, the DEBUG symbol table is searched.
If a match is found,
the storage address corresponding to the symbol replaces the instruction
address in the old PSW. ihen a hexadecimal number is specified, it is
added to the current origin to calculate the storage address that
replaces the instruction address in the old PSW.
In either case, the
derived storage address must not be greater than the user's virtual
storage size.
Further, it is the user's responsibility to make sure
that the address referred to by the operand of the GO subcommand
contains an operation code.
If the debug environment was entered due to a breakpoint, external
interrupt, or program interrupt, then the GO subcommand does not need an
operand specifying the starting address.
The following
subcommand.
error
messages
may
appear
while
entering
the
GO
INVALID OPERAND
An operand specified in the GO subcommand cannot be located
DEBUG symbol table and is not a valid hexadecimal number.
146
IBM VM/370: system Programmer's Guide
in the
If the
operand is intended to be a symbol, a DEFINE subcommand must have
been previously issued for that symbol; if not, the operand must
specify a valid hexadecimal storage location.
INVALID STORAGE ADDRESS
The address at which execution is to begin is not on a halfword
boundary (indicating that an operation code is not located at that
address) or the sum of the GO operand and the current origin value is
greater than the user's ~irtual storage size. If the current value
is unknown, it may be reset to the desired value by issuing the
ORIGIN subcommand.
INCORRECT DEBUG EXIT
The GO subcommand without an operand has been issued when DEBUG had
not been entered due to a breakpoint or external interrupt.
The
RETURN subcommand must be issued if DEBUG had been entered via the
DEBUG command.
TOO MANY OPERANDS
The GO subcommand has a maximum of one operand; more than one operand
was entered.
Part 1: Debugging with V"/370
147
The format of the GPB subcommand is:
I GPB I reg1
[reg2]
L ______- - - - - - - - - - - - - - - - - - - - - -______________________________________________
~
reg1
is a decimal number (from 0-15 inclusive)
indicating the first
or only general register whose contents are to be typed.
reg2
is a decimal number (from 0-15 inclusive) indicating the last
general register whose contents are to be typed. This operand
is optional and is only specified when more than one register's
contents are to be printed • .
Use the GPB subcommand to print the contents of one or more general
registers at the terminal.
When only one operand is specified, only the
contents of that general register are typed at the terminal. When two
registers are specified, the contents of all general registers from the
register indicated by the first operand through the register indicated
by the second operand are typed at the terminal. Both operands must be
decimal numbers from 0-15 inclusive, and the second operand must be
greater than the first.
The following error messages may
subcommand is entered.
appear on
the terminal when
the GPR
INVALID OPERAND
The operand (s) specified are not decimal numbers between 0
inclusive, or the second operand is less than the first.
and 15
KISSING OPEBAID
The GPR
entered.
subo.mand requires
at
least
one
operand, and
none
was
TOO KANY OPERANDS
The GPR subcommand has
operands vere entered.
148
a maximum of two operands, and
IBK VK/370: System Programmer's Guide
more than two
The format of the HX subcommand is:
HX
The HX subcommand has no operands.
Use the HX subcommand to close all open files and I/O devices, and to
update the master file directory. This subcommand may be issued
whenever the keyboard is unlocked in the debug environment, regardless
of the reason the debug environment was entered.
The following error message may appear
the HX subcommand.
on the terminal
while entering
TOO BANY OPERANDS
The HX subcommand has
entered.
no operands,
and one
or more
operands were
Part 1: Debugging with VM/370
149
The format of the ORIGIN subcommand is:
oRigin I { Symbol}
I hexloc
symbol
is a name that was previously
subcommand) to a storage address.
hexloc
is a hexadecimal
virtual storage.
assigned
location within
(via
the limits
the
DEFINE
of the
user's
The ORIGIN subcommand sets an origin or base address to be used in
the debug environment. Use the ORIGIN subcommand to set the origin
equal to the program load point, then in all debug subcommands you can
specify instruction addresses in relation to the program load point,
rather than to O.
The
hexadecimal location specified in DEBUG
subcommands then represents a specific location within a program, the
origin represents the storage location of the beginning of the program;
and the two values added together represent the actual storage location
of that specific point in the program.
When the ORIGIN subcommand specifies a symbol, the DEBUG symbol table
is searched. If a match is found, the value corresponding to the symbol
becomes the new origin. When a hexadecimal location is specified, that
value becomes the origin.
In either case, the operand cannet specify an
address greater than the user's virtual storage size.
Any origin set by an ORIGIN subcommand remains in effect until
another ORIGIN subcommand is issued, or until you obtain a new copy of
eMS. Whenever a new ORIGIN subcommand is issued, the value specified in
that subcommand overlays the previous origin setting.
If you obtain a
new copy of eMS (via IPL), the origin is set to 0 until a new ORIGIN
subcommand is issued.
The following error
su bcommand.
messages may
appear
while you
enter the
ORIGIN
INVALID OPERAND
The operand specified in the ORIGIN subcommand cannot be located in
the DEBUG symbol table and is not a valid hexadecimal number. If the
operand is intended to be a symbol, a DEFINE subcommand must have
been previously issued for that symbol; if not, the operand must
specify a valid hexadecimal location.
INVALID STORAGE ADDRESS
The address specified by the
user's virtual storage size.
150
ORIGIN
IBM VM/370: System Programmer's Guide
operand is
greater than
the
MISSING OPERAND
The ORIGIN subcommand requires one operand, and
none vas entered.
TOO MANY OPERANDS
The ORIGIN subcommand requires only one
was entered.
operand, and more
than one
Part 1: Debugging with VM/370
151
The format of the PSi subcommand is:
,
PSi
I
The PSi subcomaand has no operands.
Use the PSi subcommand to type the contents of the old PSi (program
status word)
for the interrupt that caused DEBUG to be entered. If
DEBUG was entered due to an external interrupt, the PSi subcommand
causes the contents of the external old PSi to be typed at the terminal.
If a program interrupt caused DEBUG to be entered, the contents of the
program old PSi are typed.
If DEBUG was entered for any other reason,
the following is typed in response to the PSi subcommand:
01000000 xxxxxxxx
where the 1 in the first byte means that external interrupts are allowed
and xxxxxxxx is the hexadecimal storage address of the DEBUG program.
The PSi contains some information not contained in storage or
registers but required for proper program execution. In general, the
PSi is used to control instruction sequencing and to hold and indicate
the status of the system in
relation to the program currently
executing. Refer to Figure 43 in "Appendix A: System/370 Information"
for a description of the PSi.
The following
subcommand.
error
message
may
appear
while
entering
the
TOO MANY OPERANDS
The PSi subcommand has no operands and one or more was entered.
152
IBM VM/370: System Programmer's Guide
PSi
The format of the RETURN subcommand is:
RETurn
The RETURN subcommand has no operands.
Use the RETURN subco.mand to exit from the debug environment to the
CftS command environment.
RETURN should be used only when DEBUG is
entered by issuing the DEBUG command.
When RETURN is issued, the information contained in the general
registers at the time DEBUG was entered is restored or, if this
information was changed while in the debug environment, the changed
information is restored. In either case, register 15, the error code
register, is set to zero.
A branch is then made to the address
contained in register 14, the normal CftS return register.
If DEBUG is
entered by issuing the DEBUG command, register 14 contains the address
of a central C~S service routine and control transfers directly to the
CftS command environment.
The Ready message followed by a carriage
return and an unlocked keyboard indicates that the RETURN subcommand has
successfully executed and that control has transferred from the DEBUG
environment to the CftS command environment.
The following
subcommand.
error messages
may
appear
while entering
the
RETURN
TOO ftAIY OPERANDS
The RETURN
specified.
subcommand
has
no
operands,
and
one
or
more
were
INCORRECT DEBUG EXIT
If DEBUG is entered due to a program or external interrupt, a
breakpoint or an unrecoverable error, this message is displayed in
response to the
RETURN subcommand.
To exit
from the DEBUG
environment under the above circumstances, issue GO.
Part 1: Debugging with Vft/370
153
The format of the SET subcommand is:
r---------------------------------------------------------------------------~
I SET
I
I
I
CAW
CSW
{ PSW
GPR
hexinfo
hexinfo
hexinfo
reg
[ hexinfo]
[hexinfo]
hexinfo
[bexinfo 1
I
!
CA W hexinfo
indicates that the specified information
(hexinfo)
is stored in the CAW
(channel
address word) that existed at the time DEBUG
was entered.
CSW hexinfo [hexinfo]
indicates that the specified information
(hexinfo [hexinfo]) is stored in the CSW
(channel status word) that existed at the
time DEBUG was entered.
PSW hexinfo [hexinfo]
indicates that the specified information
(hexinfo [hexinfo]) is stored in old PSW
(program status word) for the interrupt that
caused DEBUG to be entered.
GPR reg hexinfo [hexinfo]
indicates that the specified information
(hexinfo
[hexinfo])
is
stored in
the
specified general register (reg).
Use the SET subcommand to change the contents of the control words
and general registers which are saved when the debug environment is
entered.
The contents of these registers are restored when control
transfers from DEBUG to another environment. If register contents were
modified in DEBUG, the changed contents are stored.
The SET subcommand can only change the contents of one control word
at a time. For example, the SET subcommand must be issued three times:
SET
SET
SET
CAW
CSW
PSW
hexinfo
hexinfo [hexinfo]
hexinfo [ hexinfo]
to change the contents of the three control words.
The SET subcommand can change the contents of one or two general
registers each time it is issued.
When four or less bytes of
information are specified, only the contents of the specified register
are changed.
When more than four bytes of information is specified, the
contents of the specified register and the next sequential register are
changed. For example, the SET subcommand:
SET
GPR
changes only
su bcommand:
SET
GPR
2 xxxxxxxx
the
contents
register
2 xxxxxxxx xxxxxxxx
changes the contents of
154
of general
general
registers 2 and 3.
IB" V"1370: System programmer's Guide
2.
But,
the
SET
Each hexinfo operand should be from one to four bytes long.
If an
operand is less than four bytes and contains an uneven number of
hexadecimal digits (representing half-byte information), the information
is right-justified and the left half of the uneven byte is set to zero.
If more than eioht hexadecimal dioits are specified in a sinqle operand.
the information-is left-justified and truncated on the right after the
eighth digit.
The number of bytes that can be stored using the SET subcommand
varies depending on the form of the subcommand. with the CAW form, up
to four bytes of information may be stored. with the CSW, GPR, and PSW
forms, up to eight bytes of information may be stored, but these bytes
must be represented in two operands of four bytes each. When two
operands of information are specified, the information is stored in
consecutive locations (or registers), even it one or both operands
contain less than four bytes of information.
'
The contents of registers changed using the SET subcommand are not
displayed after the subcommand is issued.
TO inspect the contents of
control words and registers, the CAW, CSW, PSW, or GPR subcommands must
be issued.
The following
subcommand.
error
messages
may
appear
while
entering
the
SET
INVALID OPERAND
The first operand is not CAW, CSW, PSW, or GPR, or the first operand
is GPR and the second operand is not a decimal number between 0 and
15 inclusive, or one or more of the hexinfo operands does not contain
hexadecimal information.
MISSING OPERAID
The minimum number of operands has not been entered;
TOO MANY OPERAIDS
More than the required number of operands were specified.
Part 1: Debugging with V8/370
155
The format of the STORE subcommand is:
II
STore I {Symbol}
I hexloc
hexinfo
[hexinfo [hexinfo]]
symbol
is the name assigned (via the DEFINE subco.mand) to the
storage address where the
first byte of specified
inforaation is stored.
hexloc
is the hexadecimal location, relative to the current
origin, where the first byte of information is stored.
hexinfo
is any hexadecimal information,
length, to be stored.
four bytes
or less
in
Use the STORE subcommand to store up to 12 bytes of hexadecimal
information in any valid virtual storage address. The information is
stored starting in the location derived from the first operand (symbol
or hexloc).
If the first operand contains any non hexadecimal characters, the
DEBUG symbol table is searched for a matching symbol entry. If a match
is found in the DEBUG symbol table, or if thE first operand contains
only hexadecimal characters, the current or1g1n is added to the
specified operand and the resulting storage address is used, provided it
is not greater than the user's virtual storage size.
The information
the second through
one to four bytes
an operand is less
hexadecimal digits
is right-justified
If more than eight
the information is
eighth digit.
to be stored is specified in hexadecimal format in
the fourth operands.
Each of these operands is from
(that is, two to eight hexadeciaml digits) long. If
than four bytes long and contains an uneven number of
(representing half-byte information), the information
and the left half of the uneven byte is set to zero.
hexadecimal digits are specified in a single operand,
left-justified and truncated on the right after the
The STORE subcommand can store a maximum of 12 bytes at one time. By
specifying all three information operands, each containing four bytes of
information, the maximum 12 bytes can be stored.
If less than four
bytes are specified in any or all of the operands, the information given
is arranged into a string- of consecutive bytes, and that string is
stored starting at the location derived from the first operand. Stored
information is not typed at the terminal.
To inspect the changed
contents of storage aftQr a STOBE subcommand, issue an X subcommand.
The following error messages may
the STORE subcommand.
a~pear
on the
terminal while entering
INVALID OPERAND
The first operand cannot be located in the DEBUG symbol table and is
not a valid hexadecimal number, or the information specified in the
156
IB" V"1370: System Programmer's Guide
second, third, or fourth operands is not in hexadecimal format. If
the first operand is intended to be a symbol, a DEFINE subcommand
must have been previously issued for that symbol;
if not, the
operand must specify a valid hexadecimal storage location.
INVALID STORAGE ADDRESS
The current origin value, when added to the hexadecimal number
specified as the first operand, gives an address greater than the
user's virtual storage S1ze. If the origin value is unknown, reset
it to the desired value using the ORIGIN subcommand and reissue the
STORE subcommand.
MISSING OPERAID
Less than two operands were specified.
TOO MANY OPERA IDS
More than four operands were specified.
HEXLoe 'hexaddr' II SHARED STORAGE
A shared system has been loaded (via IPL) and an attempt was made to
modify a storage location between X'10000' and X'20000'.
To store
into this address range, IPL a nonshared system.
Data was stored up to the point where the address violation was
detected. Shared storage remains the same.
~2i~:
Part 1: Debugging with VM/370
157
The format of the X (examine) subcommand is:
symbol
X
r
I n
I len~!!
L
hexloc
r
I n
I ~
L
,
I
I
~
,
I
I
~
symbol
is the name assigned (via the DElINE subcommand)
storage address of the first byte to be examined.
to
hexloc
is the hexadecimal location, in relation
origin, of the first byte to be examined.
current
n
is a decimal number from 1 to 56 inclusive, that specifies the
number of bytes to be examined. If a symbol is specified
without a second operand, the length attribute associated with
that symbol in the DEBUG symbol table specifies the number of
bytes to be examined. If a hexadecimal location is specified
without a second operand, four bytes are examined.
to
the
the
Use the X subcommand to examine and display the contents of specific
locations in virtual storage.
The information is displayed at the
terminal in hexadecimal format.
The first operand of the subcommand specifies the beginning address
of the portion of storage to be examined. If the operand contains any
nonhexadeciaal characters, the DEBUG symbol table is searched for a
matching symbol entry. If a match is found, the storage address to
which that sy.bol refers is used as the location of the first byte to be
examined. If no match is found, or if the first operand contains only
hexadecimal characters, the current origin as established by the ORIGIN
subcommand is added to the specified operand and the resulting storage
address is used as the location of the first byte to be examined. The
derived address must not be greater than the user's virtual storage
size.
The second operand of the X subcommand is optional. If specified, it
indicates the number of bytes (up to a maximum of 56) whose contents are
to be displayed. If the second operand is omitted and the first operand
is a hexadecimal location, a default value of four bytes is assumed. If
the second operand is omitted and the first operand is a symbol, the
length attribute associated with that symbol in the DEBUG symbol table
is used as the number of bytes to be displayed.
The following error messages may
subcommand is entered.
158
appear on
IB! V!/370: system Progra.mer's Guide
the terminal
when the
X
INVALID OPERAND
The first operand cannot be located in the DEBUG symbol table and is
not a valid hexadecimal number, or the second operand is not a
decimal number between 1 and 56 inclusive. If the first operand is
intended to be a symbol, it must have been defined in a previous
DEFINE subcommand; otherwise, the operand must specify a valid
hexadecimal number.
INVALID STORAGE ADDRESS
The hexadecimal number specified in the first operand, when added to
the current origin, is greater than the storage size of the machine
being used. If the current origin value is unknown, reset it to the
desired value by issuing the ORIGIN subcommand and reissue the X
subcommand.
8ISSING OPERAND
No operands were entered; at least one is required.
TOO !ANY OPERANDS
80re than the maximum of two operands were entered.
Part 1: Debugging with V8/370
159
SiCTR1CE
The SVCTR1CE co •• and traces internal transfers of inforaation resulting
from SiC (supervisor call) instructions. Issuing the SVCTR1CE co.mand
causes switches to be set. These switches, in turn, cause inforaation
to be recorded at appropriate times.
When the trace is ter.inated, the
recorded infor.ation is printed at the syste. printer.
The infor.ation recorded for a normal SVC call is:
•
•
•
•
•
•
storage address of the SVC calling instruction
Bame of the program being called
contents of the SVC old PSi
storage address of the return from the called program
The general registers and floating-point registers
The parameter list at the time the SVC is issued.
The for.at of the SVCTRACE co.mand is:
ISVCTrace
I
l
ON
indicates tracing for all SVC calls.
OFF
discontinues all SVC tracing.
The trace information is:
•
The general registers both before the SVC-called program
control and after a return from that program.
•
The floating-point registers both before the SVC-called
given control and after a return from that program.
•
The parameter list, as it existed when the SVC was issued.
is given
program is
To terminate tracing set by the SYCTRACE command, issue the HO or
SVCTRACE OFF command.
Both SYCTRACE OFF and HO cause all trace
information recorded up to the point they are issued to be printed at
the system printer.
SYCTRACE OFF can be issued only when the keyboard
is unlocked to accept input to the CftS command environment.
To
terminate tracing at any other point in system processing, HO must be
issued. If a HX subcommand to the DEBUG environment or a logout from
the control program is issued before terminating SVCTRACE, the switches
are cleared automatically and all recorded trace information is printed
at the system printer.
A variety of information is printed whenever the
SVCTRACE OB
command is issued.
160
IBft Vft/370: System Programmer's Guide
The first line of trace output starts with a -, +,
of the first line of trace output is:
lS -: fl N/D
:;
xxx/dd naae FROl! Icc OLDPSW
= ps.l
or
*.
The format
GOPSW = ps.2 [He -- rc J
!!!!~I~:
indicates information recorded before processing the SVC.
+
indicates information recorded
applies.
after processing the SVC,
unless *
*
indicates information recorded after processing a CftS SVC whicb had
an error return.
I/D
is an abbreviation for SVC lumber and Depth (or level).
xxx
is the number of the SVC call (they are numbered sequentially).
dd
is the nesting level of the SVC call.
name is the macro or routine being called.
loc
is the program location from which the SVC was issued.
psw1 is the PSi at the time the
svc
was called.
psw2 the PSi with which the routine (e.g. BDBUF) being called is
invoked, if the first character of this line is a minus sign (-).
If the first character of this line is a plus sign or asterisk (+
or *), PSi2 represents the PSi which returns control to the user.
rc
is the return code passed from the svc handling routine in general
register 15. This field is omitted if the first character of this
line is a minus sign (-), or if this is an as svc call. For a CftS
SVC, this field is zero if the line begins with a plus sign (+),
and nonzero for an asterisk (*). Also, this field equals the
contents of Register 15 in the "GPRS AFTER" line.
The next two lines
registers when control
output is identified at
is:
eGPRSB
=h
=h
of output are the contents of the general
is passed to the SVC handling routine. This
the left by "eGPRSB". The format of the output
h h h h h h h *dddddddd*
h h h h h h h *dddddddd*
where h represents the contents of a general register in hexadecimal
format-and ~ represents the EBCDIC translation of the contents of a
general register. The contents of general registers 0-7 are printed on
the first line, with the contents of registers 8-F on the second line.
The hexadecimal contents of the registers are printed first, following
by the EBCDIC translation. The EBCDIC translation is preceded and
followed by an asterisk (*).
The next line of output is the contents of general registers 0, 1 and
15 when control is returned to the user's program. The output is
identified at the left by neGPRS AlTER :". The format of the output is:
-GPRS AFTER: RO-R1
=h
h *dd* R15
=h
*d*
where h represents the hexadecimal contents of a general register and ~
is the- EBCDIC translation of the contents of a general register. The
Part 1: Debugging with Vft/370
161
only general registers that C"S routines alter are registers 0, 1, and
15 so only those registers are printed when control returns to the user
program. The EBCDIC translation is preceded and followed by an asterisk
(*) •
The next two lines
registers when the SVC
output is identified at
is:
-GPRSS
=h
=h
of output are the contents of the general
handling routine is finished processing. This
the left by "-GPRSS". The format of the output
h h h h h h h *dddddddd*
h h h h h h h *dddddddd*
where E represents the hexadecimal contents of a general register and g
represents the EBCDIC translation of
the contents of a general
register. General registers 0-7 are printed on the first line with
registers 8-P on the second line. The EBCDIC translation is preceded and
followed by an asterisk (*).
'
line of
output is the
contents of
the caller's
The next
floating-point registers. The output is identified at the left by
"-PPRS." The format of the output is:
-PPRS = f f f f *gggg*
where! represents the hexadecimal contents of a floating-point register
and ~ is the EBCDIC translation of a floating-point register.
Each
floating-point register is a doubleword: each ! and g represents a
doubleword of data. The EBCDIC translation is preceded and followed by
an asterisk (*).
~he next line
of output is the contents of floating-point registers
when the SVC-handling routine is finished processing. The output is
identified by "-PPRSS" at the left. The format of the output is:
-PPRSS = f f f f *gggg*
where! represents the hexadecimal contents of a floating-point register
and ~ is the EBDCIC translation. Each floating-point register is a
doubleword and each i and g represents a douhleword of data. The EBCDIC
translation is preceded and followed by an asterisk (*).
The last two lines of output are only printed if the address in
Register 1 is a valid address for the virtual machine. If printed, the
output is the parameter list passed to the SVC. The output is identified
by "-PARM" at the left. The output format is:
-PARM = h h h h h h h h *dddddddd*
= h h h h h h h h *dddddddd*
where h represents a word of hexadecimal data and ~ is the EBCDIC
translation. The parameter list is found at the address contained in
register 1 before control is passed to the SVC-handling program. The
EBCDIC translation is preceded and followed by an asterisk (*).
Pigure 13 summarizes the types of SVC trace output.
162
IB" VM/370: System Programmer's Guide
Identification I comments
f( ~*
~ HID
The SVC and the routine which issued the SVC.
)
-GPRSB
Contents of general registers when control passed to
the SVC handling routine.
- GPRS APTER
Contents of general registers 0, 1, and 15 when con6 __ 1
~LU~
~~
~~
__ 6"_n_~
~~~u~u~u
+_
~u
+~o
"~O~
~UV
W~~~
"rnnr2m
r~~~.~~.
-GPRSS
contents of the general registers when the SVC handling routine is finished processing.
-PPRS
contents of floating-point registers before the
SVC-called program is given control and after returning from that program.
- PPRSS
contents of the floating-point registers when the
SVC handling routine is finished processing.
The parameter list, when one is passed to the SVC.
Figure 13.
Summary of SVC Trace Output Lines
Part 1: Debugging with V"/370
163
Use the DASD Dump Bestore (DDB)
service program to dump, restore, copy,
display, or print Vft/370 user .inidisks. The DDB program .ay run as a
standalone progra., or under CftS via the DDR co •• and.
IBVOKING DDR UNDER CftS
The format of the DDR command is:
r
DDR
,
[filena.e [filetype I file.ode I
I
I
L
*
]
.J
filename filetype [file.ode]
is the identification of the file containing the control
statements for the DDR program.
If no file identification is
provided, the
DDR program
attempts to
obtain control
statements from the console. The filemode defaults to • if a
value is not provided.
INVOKING DDR AS A STANDALONE PROGRAft
To use DDB as a standalone program, the operator should IPL it from a
real or virtual IPL device as he would any other standalone progra ••
Then indicate where the DDR program is to obtain its control statements
by responding to prompting messages at the console.
See the "DDB Control Statements" discussion in the "Debugging with
CP" section.
The control statements for running standalone and under
CMS are identical, except that CftS ignores the SYSPRINT centrol
statement.
164
IBM VM/370: System Progra.mer's Guide
Each time the CftS resident nucleus is loaded on a DASD, and an IPL can
be performed on that DASD, a load map is produced. Save this load ma~.
It lists the virtual storage locations of nucleus-resident routines and
work areas.
Transient modules will not be included in this load map.
When debugging CftS, you can locate routines using this map.
The load map may be saved as a disk file and printed at any time. A
copy of the nucleus load map is contained on the system with file
identification of 'filename BUCftApl. Issue the
LISTF
*
NUCftAP S
command to determine the filename.
Then issue
PRINT filename NUCftAP
to obtain a copy of the current nucleus load map.
Figure 14 shows a sample CftS load map. Notice that the
area (DBGSECT) and DftSIN! module have been located.
DEBUG work
The load map of a disk resident command module contains the location of
control sections and entry points loaded into storage. It may also
contain certain messages and card images of any invalid cards or replace
cards that exist in the loaded files.
The loadmap is contained in the
third record of the !ODULE file.
This load map is useful in debugging.
When using the Debug
environment to analyze a program, use the. program's load map to help in
displaying information.
There are several ways
to get a load map.
1.
When loading relocatable object code into storage, make sure that
the ftAP option is in effect when the LOAD command is issued. since
!AP is the default option, just be sure that NO!AP is not
specified. A load map is then created on the primary disk each
time a LOAD command is issued.
2.
When generating the absolute image form of files already loaded
into storage, make sure that the MAP option is in effect when the
GENMOD command is issued. Since MAP is the default option, just be
sure that IOMAP is not specified. Issue the MODMAP command to type
the load map associated with the specified MODULE file on the
terminal. The format of the !ODMAP command is:
MODmap
filename
I filename
is the module whose map is to be displayed.
be MODULE.
The filetype must
Part 1: Debugging with VM/370
165
FILE: LOAD
CMSMAP
INVALID CARD ••• :READ
DMSNUC
DMSNUCU
NUCON
SYSREF
lEIBM
CMNDLINE
SUBFLAG
IADT
DBVICE
DBVTAB
CONSOLE
ADISK
DDISK
SDISK
YDISK
TABEND
lDTSECT
lFTSTART
BXTSECT
EXTPSW
IOSECT
IONTABL
PGMSECT
PIE
SVCSECT
DIOSECT
*
*
*
*000000
AT
AT 002800
AT 000000
AT 000600
AT 000274
AT 0007AO
AT 0005E9
AT 000644
AT 00026C
AT 000C90
AT 000C90
AT OOOCAO
AT OOOCDO
AT 000D10
AT 000D20
AT OOODFO
AT OOODFO
AT 001200
AT 001500
AT 0015A8
AT 0015DO
AT 001610
AT 001660
AT 001668
AT 0016F8
AT 001998
FVS
AT 001A88
ADTFVS
AT 001E48
KXFLAG
AT 001C2F
UFDEUSY AT 001C2E
CMSCVT
AT 001C80
DBGSECT, AT 001D~Q
DMSERT
AT 002098
DMSlRT
AT 002208
DMSAEW
AT 002258
OPSECT
AT 002800
DMSERL
AT 002935
TSOELKS AT 0029BO
SUESECT AT 002A40
USERSECT AT 002AD8
INVALID CARD ••• :READ
ABBREV
AT 003000
USABRV
AT 0030DO
INVALID CARD ••• :READ
CMSTIMER AT 003200
GETCLK
AT 003200
DMSINM .......... AT 003200
INVALID CARD ••• :READ
TAPBIO
AT 003308
DMSTIO
AT 003308
Figure 14.
166
CONVERSATIONAL MONITOR SYSTEM
C
DM SN UC
UPLIB
CMSLIB
OSMACRO
DMSNUC
TEXT
MACLIB
MACLIB
MACLIB
ASSEMBLE
C1
D1
D1
Y2
C1
CMS191
CMS191
CMS191
CMS19E
SOURCE
9:01
9/21/72
9/21/72 8:47
9/21/72 8:44
7/19/72 18:11
9/18/72 23:09
DMSINA
TEXT
C1 CMS191
9/19/72
15:37
DMSINM
TEXT
C1 CMS191
9/18/72
20:36
DMSTIO
TEXT
C1 CMS191
9/19/72
10:33
Sa.ple ces Load eap
IBft Vft/370: Syste. Progra.mer's Guide
ihen CMS abnormally terminates, the terminal operator must enter the
DEBUG co.mand and then the DUMP subcommand if an ABEND dump is desired.
The DUMP formats and prints the following:
•
•
•
•
•
•
General registers
Extended control registers
Ploating-point registers
storage boundaries with their corresponding storage protect key
Current PSi
selected storage
storage is printed in hexadecimal representation, eight words to the
line, with EBCDIC translation at the right. The hexadecimal storage
address corresponding to the first byte of each line is printed at the
left.
ihen the Conversational ftonitor system can no longer continue, it
abnormally terminates. yOU must first determine the condition that
caused the ABEND and then find why the condition occurred. In order to
find the cause of a eftS problem, you mu~t be familiar with the structure
and functions of CftS. Befer to "Part 3: Conversational Monitor System
(CMS) " for functional information. The following discussion on reading
CftS dumps will refer to several CftS control tlocks and fields in the
control blocks. Refer to the VftL11~: ~2n!~~!!ional !~~i!2! Syste~ (~)
R~gg~~~ 12g!£
for a description of each CMS control block.
Pigure 15
shows the relationships of CftS control blocks.
You will also need a
current CftS nucleus load map in order to analyze the dump.
REASON POR THE ABEND
Determine the immediate reason for the ABEND and identify the failing
module. The ABEND message DMSABN148T contains an ABEND code and failing
address. Figure i6 lists all the eMS ABEND codes, identifies the .odule
that caused the module to ABEND, and describes the action that should be
taken whenever CftS abnormally terminates.
You may have to examine several fields in the
(NUCON) of low storage.
Nucleus Constant Area
1.
Examine the program old PSi (PGMOPSi) at location 1'28'. Using the
PSi and current CMS load map, determine the failing address.
2.
Examine the SVC old PSi (SVCOPSi) at location 1'20'.
3.
Examine the external old PSi (EXTOPSi) at location X'18'. If the
virtual machine operator terminated CftS, this PSi points to the
instruction executing when the termination request was recognized.
4.
For a machine check, examine the machine check old PSi (MCKOPSi) at
location X'30'. Refer to Figure 43 in "Appendix A: system/370
Information" for a description of the PSi.
Part 1: Debugging with VM/370
167
DMSNUC
USERSECT
SUBSECT
OPSECT
SYSREF
DMSABW
600
CMSCB
608
DMSFRT
610
DMSERT
618
620
DBGSECT (Debug work areal
628
Some fields are filled in
630
638
FVS
640
648
DCB
DIOSECT
650
658
DECB
SVCSECT
660
PGMSECT
668
670
IOSECT
678
680
EXTSECT
688
AFTSECT (Create when the file is
opened. There is room for 5 AFTs in
DMSNUC, others are in free storage.
690
698
ADTSECT (Space is allocated when
DMSNUC is assembled, fields are
filled in when ACCESS command is
issued. There is one ADT entry for
each of the 10 possible disks.)
6A8
6BO
688
DEVTAB
6CO
6C8
Terminal Buffers and Saveareas
600
NUCON
Figure 15.
168
CMS Control Blocks
IBM VM/370: System Programmer's Guide
I
CMSAVE
I
B
Cause of ABEND
ABENDI Module
Code I
Action
001
DMSSCT IThe problem program encoun- IMessage DMSSCT120S
tered an input/output error I indicates the possible
processing an os _acro.
I cause of the error.
Either the associated DCB
I Examine the error
did not have a SYNAD routinel message and take the
specified or the I/O error I action indicated.
was encountered processing I
an OS CLOSE macro.
I
OCx
DMSITP IThe specified hardware excep- Type DEBUG to examine
I tion occurred at a specified the PSW and registers
at the time of the
I location. "x" is the type
exception.
I of exception:
I x
~~
I '0
IMPRECISE
I 1
OPERATION
I 2
PRIVILEGED OPERATION
J 3
EXECUTE
4
PROTECTION
5
ADDRESSING
6
SPECIPICATION
7
DECIMAL DATA
8
PIXED-POINT OVERPLOW
9
PIXED-POINT DIVIDE
A
DECIMAL OVERFLOW
B
DECIMAL DIVIDE
EXPOIENT OVERPLOW
C
D
EXPONENT UNDERFLOW
E
SIGIIPICAICE
FLOATING-POINT DIVIDE
P
OP 1
DMSITS IAn invalid halfword code is
I associated with SVC 203.
IEnter DEBUG and type GO.
I Execution continues.
OF2
DMSITS IThe CMS nesting level of 20
I has been exceeded.
I
INone. ABEND recovery
I will take place when
I the next command is
I
I
"
........ "
~u'"~
... .....
.... ,...;1
~
OP3
DMSITS ICMS SVC (202 or 203) instruc-JEnter DEBUG and type GO.
tion was executed and no
I Control will return to
provision was made for an
I point to which a normal
error return from the
I return would have been
routine processing the SVC I made.
call.
I
OF4
DMSITS IThe DMSKEY key stack overI flowed.
I
I
IEnter DEBUG and type GO.
I Execution will continue
I and the DMSKEY macro
I will be ignored.
----------------------------------------------1
OF5
DMSITS IThe DMSKEY key stack under- I
I flowed.
Pigure 16.
I
CMS ABEND Codes (Part 1 of 2)
Part 1: Debugging with VM/370
169
ABENDI Module
Code I
Cause of ABERD
Action
OF6
DMSITS IThe DMSKEY key stack was not IEnter DEBUG and type GO.
empty when control returned
control will return
from a co •• and or function.
from the command or
function as if the key
stack had been empty.
OF7
DMSFRE 10ccurs when TYPCALL=SVC (the lIn the case of a system
I default) is specified in thel ABERD, the user .ay
I DMSFREE or DMSFRET macro.
I employ DEBUG to attempt
I
I recovery.
OF8
DMSFRE 10ccurs when TYPCALL=BALR is lIn the case of a system
I specified in the DMSFREE or I ABEND, use DEBUG to
I DMSFRET "acro devices.
I attempt recovery.
101
D"SSVN IThe wait count specified in
I an OS WAIT macro was larger
I than the number of ECB' s
I specified.
155
D"SSLN IError during LOADMOD after ani See last LOAD MOD (DMSMOD
I OS LINK, LOAD, ICTL, or
error message for error
I ATTACH. The compiler switch
description. In the
I is on.
case of an I/O error,
I
recreate the module; if
I
the module is missing,
I
create it.
15A
ISee last LOAD error
DftSSLN ISevere error during load
(phase not found) after an
message (D"SLIO) for
the error description.
OS LINK, LOAD, ICTL, or
ATTACH. The compiler switch
In the case of an I/O
error, recreate the
is on.
text deck or txtlib. If
either is missing,
create it.
240
DMSSVT INO work area was provided in ICheck RDJFCB specifiI the parameter list for an OSI cation.
I RDJFCB macro.
I
400
DMSSVT IAn invalid or unsupported
I form of the OS XDAP macro
I has been issued by the
I problem program.
AOA
DftSS"B IAn OS GET"AIN or FRlE"AIN
IExamine the error
I macro has been issued.
I messages and take the
Either there is not enough t action indicated.
storage to satisfy the
I
request, or the free chain I
has been destroyed, or the I
parameters passed to GET"AINI
or FREE"AIB were invalid.
I
Figure 16.
170
C"S Abend Codes (Part 2 of 2)
IBM V"/370: System Programmer's Guide
IExamine the program for
I excessive wait count
I specification.
I
IExamine program for
I unsupported XDAP macro
I or for SVC O.
I
COLLECT INFORMATION
Examine several other fields in NUCON to analyze the status of the CMS
system. As you proceed with the dump, you may return to NUCON to pick up
pointers to specific areas (such as po~n~ers to file tables) or to
examine other status fields. The complete contents of NUCON and the
other CMS control blocks are described in the !~LJIQ: £~~~~£§~tio~~J
~Qni!Q£ ~I§!~!
(£~~) R£Qg£~! 1Q9if.
The following areas of NUCON may
contain useful debugging information.
•
Save area for low storage.
Before executing, DEBUG saves the first 160 bytes of low storage in a
NUCO! field called LOWS!VE. LOWS!V! begins at X'CO'~
•
Register save area.
DMSABN, the ABEND
general registers.
li~!g
FPRLOG
GPRLOG
ECRLOG
•
Location
i'160"-X'1S0'
X'1CO'
routine, saves
floating-point
and
Device.
the last
I/O interrupt
is in
the
Last Two Commands or Procedures Executed.
l!~!g
L!STCMND
PREVCMND
LASTEXEC
PREVEXEC
•
user's
contents
user-floating-point registers
User general registers
User extended control registers
The name of the device causing
DEVICE field at X'26C'.
•
the
1Qcat.i~~
X'2AO'
X' 2AS'
X'2BO'
X' 2BS '
Contents
Last-cis
command issued
Next to last CMS command issued
Last EXEC procedure invoked
Next to last EXEC procedure invoked
Last module load into free storage and transient area.
The name of the last module loaded into free storage via a LOADMOD is
in the field LASTLKOD (location X'2CO'). The name of the last module
loaded into the transient area via a LOAD MOD is in the field LASTTMOD
(location X'2CS').
•
Pointer to CKSCB.
The pointer to the CMSCB is in the FCBT!B field located at X'SCO'.
CMSCB contains the simulated OS control blocks. These simulated OS
control blocks are in free storage. The CMSCB contains a PLIST for
CMS I/O functions, a simulated Job File Control Block (JFCB), a
simulated Data Event Block (DEB), and the first in a chain of I/O
Blocks (lOBs).
Part 1: Debugging with VM/370
171
•
The Last Co •• and.
The last command entered from the terminal is stored in an area
called CMNDLINE (X'7AO'), and its corresponding PLIST is stored at
CMNDLIST (I'S4S').
•
External Interrupt Work Area.
EXTSECT (X'1550') is a vork area
It contains:
for the external interrupt handler.
The PSW, EXTPSW (X'15FS')
Register save areas, EXSAVEl (X'15BS')
Separate area for timer interrupts, EXSAVE (X'1550')
•
I/O Interrupt Work Area.
IOSECT (X'1620')
is a vork area for the I/O interrupt handler. The
oldest and nevest PSW and CSW are saved. Also, there is a register
save area.
•
Program Check Interrupt Work Area.
PGMSECT (X'16BO') is a vork area for the program check interrupt
handler. The old PSW and the address of register 13 save area are
stored in PGMSECT.
•
SVC Work Area.
SVCSECT (X' 174S') is a vork area for the SVC interrupt handler. It
also contains the first four register save areas assigned. The SFLAG
(X'175S') indicates the mode of the called routine.
Value of
_§Il!!~
__
X'SO'
X'40'
X'20'
X'Ol'
Descri.pti~l!
SVC protect key is zero
Transient area routine
lucleus routine
Invalid re-entry flag
Also, the SVC ABEND code, SVCAB, is located at X'175A'.
•
Simulated CVT (Communications vector Table) •
The CVT, as supported by CMS, is CVTSECT (X'lCCS').
supported ty CMS are filled in.
•
Active Device Table and Active File Table.
For file system problems, examine the ADT (Active
AFT (Active File Table) in NUCON.
172
Only the fields
IBM VM/370: System Progra.mer's Guide
Device Table), or
REGISTER USAGE
In order to trace control blocks and
the C~S register usage conventions.
B~~ist~~
GR1
GR12
GR13
GR14
GR15
modules, it is important
to know
contents
Address-of the PLIST
Program's entry point
Address of a 12-doubleword work area for an svc call
.Return address
Program entry point or the return code
The preceding information should help you to read a c~S dump. If it
becomes necessary to trace file system control blocks, refer to Figure
31 in "Part 2: Conversational ~onitor System" for more information. with
a dump, the control block diagrams, and a c~S load map you should be
able to find the cause of the ABlID.
Part 1: Debugging with
V~/370
173
GC20-i807-3 Page Modified by TNL GN20-2662, March 31, 1975
Part 2: Control Program (CP)
Part 2 contains the following information:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Introduction to VM/370
Program states
Using CPU Resources
Interruption Handling
Functional Information
Performance Guidelines
Performance Observation and Analysis
Accounting Information
Generating Named Systems and Saving Systems
VM/VS Handshaking
OS/VS2 Release 2 Uniprocessor under VM/370
DOS under VM/370
Running VM/370 in a Virtual Machine
Timers
DIAGNCSE Instruction
CP Conventions
How to Add a Console Function
How to Add a New print or Forms Buffer Image
Part 2: Control Program (CP)
175
VM/370
The V8/370 Control Program manages the resources of a single computer in
such a manner that multiple computing systems appear to exist. Each
"virtual" computing system, or virtual machine, is the functional
equivalent of an IBM System/370.
A virtual machine is configured by recording appropriate information
in the VM/370 directory.
The virtual machine configuration includes
counterparts of the components of a real IB8 System/370:
•
•
•
•
A virtual operator's console
virtual storage
A virtual CPU
virtual I/O devices
CP makes these components appear real to whichever operating system
is controlling the work flow of the virtual machine.
The virtual machines
techniques.
CP overlaps
execution in another.
operate
the idle
concurrently
time of one
via multiprogramming
virtual machine with
Each virtual machine is managed at two levels. The work to be done
by the virtual machine is scheduled and controlled by some System/360 or
System/370 operating system.
The concurrent execution of multiple
virtual machines is managed by the control program.
A virtual machine is created for a user ,when he logs on V8/370, on the
basis of information stored in his V8/370 directory entry.
The entry
for each user identification includes a list of the virtual input/output
devices associated with the particular virtual machine.
Additional information about the virtual machine is kept in the
V8/370 directory entry.
Included are the VM/370 command privilege
class, accounting data, normal and maX1mum virtual storage sizes,
dispatching priority, and optional virtual machine characteristics such
as extended control mode.
The Control Program supervises the execution of virtual machines by
(1) permitting only problem state execution except in its own routines,
and (2) receiving control after all real computing system interrupts.
CP intercepts each privileged instruction and simulates it if the
current program status word of the issuing virtual machine indicates a
virtual supervisor state; if the virtual machine is executing in
virtual problem state, the attempt to execute the privileged instruction
is reflected back to the virtual machine as a program interrupt. All
virtual machine interrupts (including
those caused by attempting
privileged instructions) are first handled by CP, and are reflected to
the virtual machine if an analogous interrupt would have occurred on a
real machine.
Part 2: Control Program (CP)
177
VIRTUAL KACHINE TIKE MANAGEKENT
The real CPU simulates multiple virtual CPUs. virtual machines that are
executing in a conversational manner are given access to the real CPU
more frequently than those that are not; these conversational machines
are assigned the smaller of two possible time slices.
CP determines
execution characteristics of a virtual machine at the end of each time
slice on the basis of the recent frequency of its console requests or
terminal interrupts. The virtual machine is queued for subsequent CPU
utilization
according to
whether
it
is a
conversational
or
nonconversational user of system resources.
A virtual machine can gain cbntrol of the CPU only if it is not
waiting for some activity or resource. The virtual machine itself may
enter a virtual wait state after an input/output operation has begun.
The virtual machine cannot gain control of the real CPU if it is waiting
for a page of storage, if it is waiting for an input/output operation to
be translated and started, or if it is waiting for a CP command to
finish execution.
A virtual machine can be assigned a priority of executicn. priority
is a parameter affecting the execution of a particular virtual machine
as compared with other virtual machines that have the same general
execution characteristics. priority is a parameter in the virtual
machine's VM/370 directory entry.
The system operator can reset the
value with the Class A SET command.
VIRTUAL MACHINE STORAGE MANAGEMENT
The normal and maximum storage sizes of a virtual machine are defined as
part of the virtual machine configuration in the VK/370 directory. You
may redefine virtual storage size to any value that is a mu1tiple of 4K
and not greater than the maximum defined value. VM/370 implements this
storage as virtual storage. The storage may appear as paged or unpaged
to the virtual machine, depending upon whether or not the extended
control mode option was specified for that virtual machine. This option
is required if operating systems that control virtual storage, such as
OS/VS1 or VK/370, are run in the virtual machine.
Storage in the virtual machine is logically divided into 4096 byte
areas called pages. A complete set of segment and page tables is used
to describe the storage of each virtual machine.
These tables are
updated by CP and reflect the allocation of virtual storage pages to
blocks of real storage.
These page and segment tables allow virtual
storage addressing in a System/370 machine. storage in the real machine
is logically and physically divided into 4096 byte areas called page
frames.
only referenced virtual storage pages are kept in real storage, thus
optimizing real storage utilization. Further, a page can be brought into
any available page frame; the necessary relocation is done during
program execution by a combination of V6/370 and dynamic address
translation on
the System/370.
The active pages from all logged on
virtual machines and from the pageable routines of CP compete for
available page frames.
When the number of page frames available for
allocation falls below a threshold value, CP determines which virtual
storage pages currently allocated to real storage are relatively
inactive and initiates suitable page-out operations for them.
If an
Inactive pages are kept on a direct access storage device.
inactive page has been changed at some time during virtual machine
178
IBK VM/370: System Programmer's Guide
GC20~1807-3
Page Modified by TNL GN20-2662, March 31, 1915
execution, CP assigns it to a paging device, selecting the fastest such
device with available space. If the page has not changed, it remains
allocated in its original direct access location and is paged into real
storage from there the next time the virtual machine references that
page. A virtual machine program can use the DIAGNOSE instruction to
tell CP that the information from specific pages of virtual storage is
no longer needed; CP then releases the areas of the paging devices which
were assigned to hold the specified pages.
Paging is done on demand by CP.
This means that a page of virtual
storage is not read (paged)
from the paging device to a real storage
block until it is actually needed for virtual machine execution.
CP
makes no attempt to anticipate what pages might be required by a virtual
machine.
While a paging operation is performed for one virtual machine,
another virtual machine can be
executing~
Any paging operation
initiated by CP is transparent to the virtual machine.
If the virtual machine is executing in extended control mode with
translate on,
then two additional sets of segment and page tables are
kept. The virtual machine operating system is responsible for mapping
the virtual storage created by it to the storage of the virtual machine.
CP uses this set of tables in conjunction with the page and segment
tables created for the virtual machine at logon time to build shadow
page tables for the virtual machine.
These shadow tables map the
virtual storage created by the virtual machine operating system to the
storage of the real computing system. The tables created by the virtual
machine operating system may describe any page and segment size
permissible in the IBM System/370.
VM/370 provides both fetch and store protection for real storage. The
contents of real storage are protected from destruction or misuse caused
by erroneous or unauthorized storing or fetching by the program.
Storage is protected from improper storing or from both improper storing
and fetching, but not from improper fetching alone.
When protection applies to a storage access, the key in storage is
compared with the protection key associated with the request for storage
access.
A store or fetch is permitted only when the key in storage
aatches the protection key.
When a store access is prohibited because of protection, the contents
of the protected location remain unchanged.
On fetching, the protected
information is not loaded into an addressable register, moved to another
storage location, or provided to an I/O device.
When a CPU access is prohibited because of protection, the operation
is suppressed or terminated, and a program interruption for a protection
exception takes place.
When a
channel access is prohibited, a
protection-check condition is indicated in the channel status word (CSW)
stored as a result of the operation.
When the access to storage is inhibited by the CPU, and protection
applies, the protection key of the CPU occupies bit positions 8-11 of
the PSi.
When the reference is made by a channel, and protection
applies, the protection key associated with the I/O operation is used as
the comparand. The protection key for an I/O operation is specified in
bit positions 0-3 of the channel-address word (CAW) and is recorded in
bit positions 0-3 of the channel status word (CSW) stored as a result of
the I/O operation.
Part 2: Control Program
(CP)
179
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
To use fetch protection, a virtual machine must execute the set
storage key
(SSK)
instruction referring to the data areas to be
protected, with the fetch protect bit set on in the key.
VM/370
subsequently:
1.
Checks for a fetch protect violation
nonprivileged instructions.
in handling
privileged and
2.
Saves and restores the fetch protect bit (in the virtual storage
key) when writing and recovering virtual machine pages from the
paging device.
3.
Checks for a fetch protection violation
spooling or console devices).
on a write CCW (except for
The CMS nucleus resides in a shared segment.
case for storage protection since the nucleus
still shared among many CMS users. To protect
shared segment, user programs and disk-resident
different key than the nucleus code.
This presents a special
must be protected and
the CMS nucleus in the
CMS commands run with a
The system operator may assign the reserved page frames option to a
single virtual machine.
This option, specified by the SET RESERVE
command, assigns a specific amount of the storage of the real machine to
the virtual machine. CP will dynamically build up a set of reserved
real storage page frames for this virtual machine during its execution
until the maximum number "reserved" is reached.
Since other virtual
machines' pages are not allocated from this reserved set, the effect is
that the most active pages of the selected virtual machine remain in
real storage.
During CP system generation, the installation may specify an option
called virtual=real. With this option, the virtual machine's storage is
allocated directly from real storage at the time the virtual machine
logs on (if it has the VIRT=REAL option in it's directory). All pages
except page zero are allocated to the corresponding real storage
locations. In order to control the real computing system, real page
zero must be controlled by CP. Consequently, the real storage size must
be large enough to accommodate the CP nucleus, the entire virtual=real
virtual machine, and the remaining pageable storage requirements of CP
and the other virtual machines.
The virtual=real option improves performance in the selected virtual
machine since it removes the need for CP paging operations for the
selected virtual machine. The virtual=real option is necessary whenever
programs that contain dynamically modified channel programs (excepting
those of OS ISAM and OS/VS TCAM Level 5) are to execute under control of
CP.
For additional information on running systems with dynamically
modified channel programs, see "Dynamically Modified Channel Programs"
in "part 1: Debugging with VM/370."
VIRTUAL MACHINE I/O MANAGEMENT
A real disk device can be shared among multiple virtual machines.
Virtual device sharing is specified in the VM/370 directory entry or by
a user command.
If specified by the user, an appropriate password must
be supplied before gaining access to the virtual device.
A particular
virtual machine may be assigned read-only or read/write access to a
shared disk device.
CP checks each virtual machine input/output
180
IBM VM/370: System Programmer's Guide
operation against the parameters in the virtual machine configuration to
ensure device integrity.
The virtual machine operating system is responsible for the operation
of all virtual devices associated with it~ These virtual devices may be
defined in the VM/370 directory entry of the virtual machine, or they
may be
attached to
(or detached
from)
the
virtual machine's
configuration while it remains logged on.
Virtual devices may be
dedicated, as when mapped to a fully equivalent real device; shared, as
when mapped to a minidisk or when specified as a shared virtual device;
or spooled by CP to intermediate direct access storage.
In a real machine running
under control of as, input/output
operations are normally initiated when a problem program requests as to
issue a START I/O instruction to a specific device. Device error
recovery is bandIed by the operating system. In a virtual machine, os
can perform these same functions, but the device address specified and
the storage locations referenced will both be virtual.
It is the
responsibility of CP to translate the virtual specifications to real.
In addition, the interrupts caused by the input/output operation are
reflected to the virtual machine for its interpretation and processing.
If input/output errors occur, CP records them but does not initiate
error recovery operations. The virtual machine operating system must
handle error recovery, but does not record the error (if SVC 76 is
used).
Input/output operations initiated by CP
and spooling),
are performed directly
translation.
for its own purposes (paging
and are not
subject to
SPOOLING FUNCTIONS
A virtual unit record device, which is mapped directly to a real unit
record device, is said to be dedicated.
The real device is then
controlled completely by the virtual machine's operating system.
CP facilities allow multiple virtual machines to share unit record
devices.
since virtual machines controlled by CMS ordinarily have
modest requirements for unit record input/output devices, such device
sharing is advantageous, and it is the standard mode of system
operation.
Spooling operations cease if the direct access storage space assigned
to spooling is exhausted, and the virtual unit record devices appear in
a not ready status. The system operator may make additional spooling
space available by purging existing spool files or by assigning
additional direct access storage space to the spooling function.
Specific files can be transferred from the spooled card punch or
printer of a virtual machine to the card reader of the same or another
virtual machine. Files transferred between virtual unit record devices
by the spooling routines are not physically punched or printed. with
this method, files can be made available to multiple virtual machines,
or to different operating systems executing at different times in the
same virtual machine.
Files may also be spooled to remote stations via the Remote spooling
Communications Subsystem
(RSCS), a component
of VM/370.
For a
description of RSCS and the remote stations that it supports see "Part
5. Remote Spooling Communications Subsystem (RSCS)."
Part 2: Control Program (CP)
181
CP spooling includes .any desirable options for the virtual machine
user and the real machine operator.
These options include printing
aultiple copies of a single SFool file,
backspacing any number of
printer pages, and defining spooling classes for the scheduling of real
output. Each output spool file has, associated with it, a 136 byte area
known as the spool file tag. The information contained in this area and
its syntax are determined by the originator and receiver of the file.
For example, whenever an output spool file is destined for transmission
to a remote location via the Remote Spooling Communications Subsystem,
RSCS expects to find the destination identification in the file tag. Tag
data is set, changed, and queried using the CP TAG command.
It is possible to spool terminal input and output.
All data sent to
the terminal, whether it be from the virtual machine, the control
program or the virtual machine operator, can be spooled.
Spooling is
particularly desirable when a virtual machine is run with its console
disconnected.
CP COMMANDS
The CP commands allow you to control the virtual machine from the
terminal, much as an operator controls a real machine. virtual machine
execution can be stopped at any time by use of the terminal's attention
key (for 3066 and 3270 terminals, the ENTER key is used); it can be
restarted by entering the approFriate CP command. External, attention,
and device ready interrupts can be simulated on the virtual machine.
Virtual storage and virtual machine registers can be inspected and
modified, as can status words such as the PSi and the CSi. Extensive
trace facilities are provided for the virtual machine, as well as a
single-instruction mode.
Commands are available to invoke the spooling
and disk sharing functions of CP.
CP commands are classified by
privilege classes.
The VM/370
directory entry for each user assigns one or more privilege classes.
The classes are primary system operator, system resource operat?r,
system
programmer,
spooling operator,
system
analyst,
serV1ce
representative, and general user. Commands in the system analysts class
may be used to inspect real storage locations, but may not be used to
make modifications to real storage.
Commands in the operator class
provide real resource control capabilities. System operator commands
include all commands related to virtual machine performance options,
such as assigning a set of reserved page frames to a selected virtual
aachine.
For descriptions of all the CP commands, see the VM/370:
fQ!!~Bg
19B9ygg~ Gu!g~
!Q~ g~B~!~!
~§~§ and
the !~L37Q: Operator'§
2Yig~.
182
IBM VM/370: System Programmer's Guide
Program States
When instructions in the Control Program are being executed, the real
computer is in the supervisor state; at all other times, when running
virtual machines, the real computer is in the problem state. Therefcre,
privileged instructions cannot be executed by the virtual machine.
Programs running on a virtual machine can issue privileged instructions;
but such an instruction either (1)
causes an interruption that is
handled by the Control Program, or (2) is intercepted and handled by the
CPU, if the virtual machine assist feature is enabled and supports that
instruction. CP examines the operating status of the virtual machine
PSi.
If the virtual aachine indicates that it is functioning in
supervisor mode, the privileged instruction is simulated according to
its type.
If the virtual machine is in problem mode, the privileged
interrupt is reflected to the virtual machine.
Only the Control Program aay operate in the supervisor state on the
real machine.
All programs other than CP operate in the problem state
on the real machine.
All user interrupts, including those caused by
attempted privileged operations, are handled by either the control
program or the
CPU
(if the virtual Bachine
assist feature is
available).
Cnly those interrupts that the user program would expect
from a real machine are reflected to it. A problem program will execute
on the virtual machine in a manner identical to its execution on a real
system/370 CPU, as long as it does not violate the CP restrictions. See
the "CP Restrictions" discussion in "part 1: Debugging with CP" for a
list of the restrictions.
Part 2: Control Program (CP)
183
Using CPU Resources
CP allocates the CPU resource to virtual machines according to their
operating
characteristics,
priority, and
the
system
resources
available.
virtual aachines are dynamically categorized at the end of each tiae
slice as interactive or noninteractive, depending on the frequency of
operations to or from either the virtual system console or a terminal
controlled by the virtual machine.
Virtual machines are dispatched from one of two queues, called Queue
1 and Queue 2. To be dispatched from either queue, a virtual machine
must be considered executable (that is, not waiting for some activity or
for some other system resource). virtual machines are net considered
dispatchable if the virtual machine:
1.
Enters a virtual wait state after an I/O operation has begun.
2.
Is waiting for a page frame of real storage.
3.
Is waiting
started.
4.
Is waiting for CP to simulate its privileged instructions.
5.
Is waiting for a CP console function to be performed.
for an
I/O
operation
to
be
translated by
CP
and
2Y1YJ 1
Virtual machines in Queue 1 (Q1)
are considered conversational or
interactive users, and enter this queue when an interrupt from a
terminal is reflected to the virtual machine. There are two lists of
users in Q1, executable and nonexecutable.
The executable users are
stacked in a first in, first out
(FIFO) basis. When a nonexecutable
user becomes executable, he is placed at the bottom of the executable
list. If a virtual machine uses more than 50 milliseconds
(ms) of CPU
time without entering a virtual wait state, that user is placed at the
bottom of the executable list.
virtual machines are dropped from Q1 when they complete their time
slice of CPU usage, and are placed in an "eligible list".
virtual
machines entering CP command mode are also dropped from Q1.
When the
virtual machine becomes executable again
(returns to execution mode) it
is placed at the bottom of the executable list in Q1.
Virtual machines in Queue 2
(Q2) are considered noninteractive users.
Users are selected to enter 02 from a list "of eligible virtual machines
(the "eligible list"). The list of eligible virtual machines is sorted
on a FIFO basis within user priority
(normally defined in the USER
record in the VM/370 directory, but may be altered by the system
opera tor) •
184
IBM VM/370: System Programmer's Guide
A virtual machine is selected to enter Q2 only if its "working set"
is not greater than the number of real page frames available for
allocation at the time.
The working set of a virtual machine is
calculated and saved each time a user is dropped from Q2 and is based on
the nu.ber of virtual pages referred to bi the virtual machine during
its stay in 02, and the number of its virtual pages that are resident in
real storage at the time it is dropped from the queue.
If the calculated working set of the highest priority virtual machine
in the eligible list is greater than the number of page frames available
for allocation, CP continues through the eligible list in user priority
order.
There are two lists of users in 02, executable and nonexecutable.
Executable virtual machines are sorted by "dispatching priority". This
priority is calculated each time a user is dropped from a queue and is
the ratio of CPU time used while in the queue to elapsed time in the
queue. Infrequent CPU users are placed at the top of the list and are
followed by more frequent CPU users.
When a nonexecutable user becomes
executable, he is placed in the executable list based on his dispatching
priority.
When a virtual machine completes its time slice of CPU usage, it is
dropped from Q2 and placed in the eligible list by user priority. When
a user in 02 enters CP command mode, he is removed from Q2~
When he
becomes executable (returns to virtual machine execution mode) he is
placed in the eligible list based on user priority.
If a user's virtual machine is not in 01 or 02, it is because:
1.
The virtual machine is on the "eligible list", waiting to be put on
02, or
2.
The virtual machine execution is suspended because the
CP .ode executing CP commands.
user is in
To leave CP mode and return his virtual machine to the "eligible
list" for 02, the user can issue one of the CP commands that transfer
control to the virtual machine operating system for execution (for
example, BEGI., IPt, EITERIAt, and RESTART).
In CP, interactive users (Q1), if any, are considered for dispatching
before noninteractive users (Q2). This means that CftS users entering
co.mands which do not involve disk or tape I/O operations should get
fast responses from the VM/370 system even with a large number of active
users.
An installation may choose to override the CP scheduling and
dispatching scheme and force allocation of the CPU resource to a
specified user, regardless of its priority or operating characteristics.
The favored execution facility allows an installation to:
1.
Specify that one particular virtual machine is to receive
specified percentage of CPU time.
up to a
2.
Specify that any number of virtual machines are to remain in the
queues at all times. Assignment of the favored execution option is
discussed in the "Preferred virtual Machines" section.
Part 2: Control Program (CP)
185
Interruption Handling
Input/output interrupts from completed I/O operations initiate various
completion routines and the scheduling of further I/O requests. The I/O
interrupt handling routine also gathers device sense information.
Program interrupts can occur in two states. If the CPU is in supervisor
state, the interrupt indicates a system failure in the CP nucleus and
causes the system to abnormally terminate. If the CPU is in problem
state, a virtual machine is executing.
CP takes control te perform any
required paging operations to satisfy the exception, or to simulate the
instruction. The fault is transparent to the virtual machine execution.
Any other program interrupt is a result of the virtual machine
processing and is reflected to the machine for handling.
When a machine check occurs, the CP Recovery Management Support (RMS)
gains control to save data associated with the failure fer the Field
Engineer. RMS analyzes the failure to determine the extent of damage.
Damage
taken:
assessment results
in
one of
the
following actions
•
System termination (with automatic restart)
•
system termination (CP disabled wait state)
•
Selective virtual user termination
•
selective virtual machine reset
•
Refreshing of
configuration
•
Refreshing of damaged information
removed from further systems use.
•
Error recording only for certain soft machine checks
damaged
information
with
with the
no
effect
on
defective storage
being
system
page
The system operator is informed of all actions taken by the RftS
routines.
When a machine check occurs during VM/370 startup (before the
system
is sufficiently
initialized to
permit
RftS to
operate
successfully), the CPU goes into a disabled wait state and places a
completion code of X'OOB' in the high-order bytes of the current PSW.
When an SVC interrupt occurs, the SVC interrupt routine is entered.
If
the machine is in problem mode, the type of interrupt (if it is other
186
IBft VM/370: System Programmer's Guide
than an SVC 76 or ADSTOP SVC) is reflected back to the pseudo-supervisor
(that is, the supervisor operating in the user's virtual machine).
Control is transferred to the appropriate interrupt handler for ADSTOP
SVCs and all SVC 76s.
~L
the machine
determined, and a
handler.
is in supervisor mode, the SVC interrupt code is
branch is taken to the appropriate SVC interrupt
If a timer interrupt occurs, CP processes it according to type. The
interval timer indicates time slice end for the running user. The clock
comparator indicates that a specified timer event occurred, such as
midnight, scheduled shutdown, or user event reached.
The external console interrupt invokes CP processing
the 3210 or 3215 to an alternate operator's console.
tc switch from
Part 2: Control Program (CP)
187
Functional Information
The functional diagraas
that follow describe the
prograa logic
associated with various control program functions. lot all CP functions
are described. These functional diagraas are aeant to describe the CP
functions about which you may want more detailed inforaaticn if you are
debugging, aodifying, or updating CP.
Figure 17 describes CP initialization process.
Figures 18 and 19 describe the
used by CP in its I/O control.
real and virtual I/O
control blocks
Figures 20, 21, and 22 show how CP handles SVC, external, and prograa
interrupts.
The CP paging function is described in Figure 23.
The CP spooling function
Figures 24 and 25.
(both virtual
and real)
is described
in
Figure 26 shows how virtual tracing is performed.
Figure 27 shows the steps involved in translating a virtual address
to a real address and gives an example of address translaticn.
The functional information contained in these diagrams is intended
for system programmers and IBft Field Engineering program support
representatives.
188
IBft Vft/370: System Programmer's Guide
I PL
IT OM""
()
~
H
I:'
PROCESS
'0
"'00'
INPUT---------------
.....
c+
.....
DMKCKP
For a warm start
RCHBLOK
u'II-
GI
....
.....
N
GI
checkpoint active file chains
>CJ
(j)
(")
'"o
,,"",m ,»"m '''' m."~.· ---y-"-----"
I
co
c+
.....
o
..,J
o
-----_._-
HOM""
I:'
OUTPUT-----
I
W
SEGTABLE
INPUT--------------
SEGPAGE
~MKSAV (DMKSAVRS entry POint)
ead copy of
D
"0'<0'
mOM""
I-----.:.=-~-..-
~
GI
t1
INPUT
DMKCPI
c+
'"
(")
~~t~~I~Z~e:ti:~:ge
IDW.D""I
c+
....
~
t1
0
I.Q
t1
GI
S
( ")
~
~
CO
1.0
and check TOO clock
Log on operator
Allocate Dump File
If warm start, perform that function'-.J----,..-------
0
I:'
t1
0
PAGT.~~B~L~E~----------
nucleu~
'CU"'j-[]
RCUBLOK
RCUBLOKs
t'Dc,eo'l
RDEVBLOKs
B
Go to Dispatcher
Wait for work
w
~
e
H
ttl
~
1-"
I.Q
j:l
H
It)
3:
<
CD
3:
"e
VJ
--.I
til
t<
Ul
MIt)
s
~
It)
~
....
H
"
0
Relationship of Real I/O Control Blocks - - - - - - - - ,
The real machine configuration is represented by
a set of related control blocks. These blocks are:
• in the VM/370 nucleus
• built from macros during system generation
• loaded at system IPL and initialized then for
operation.
There is one control block per channel, per control
unit, and per device.
The characteristics of VM/370 real I/O control are:
• Block multiplexing (BMPX) with RPS (Rotational Position
Sensing) is used .
• Multi·path scheduling is not used.
• All I/O operations are handled by VM/370
scheduling and interrupt handling.
DMKRIOCT (part of DMKRIO)
RCUBLOKs
n
n
0
t:I
It:!
H
0
I.Q
H
~
S
S
It)
H
Ul
MH
0
....
....
0
ttl
0
X'
RDEVBLOKs
DMKRIOCT - real channel table 1
11111~x
Ul
-negative value (FFFF)
~
indicates that no channel exists
- positive value is an index
to the RCHBLOK
.".
en
j:l
1-"
Q..
It)
RCHBLOK - real channel block 1
Channel identification
Scheduling Control
XXXX ) Control Unit
Index Table
XXXX
Control Unit identification
Scheduling Control
XXXX
XXXX
~--+----+----+----I
XXXX
XXXX
~-~'----7~------~
if negative (FFFF), no control
unit exists
if positive, that value is an
index to the RCUBLOK
1 See
IBM Virtual Machine Facility/370: Control Program (CP)
Program Logic publication, SY20 - 0880, for a complete description of CP control blocks.
if positive, that value is
an index to RDEVBLOK
) Device
Index
Table
RDEVBLOK
real device block 1
Device identification
Scheduling Control
Terminal Control
Spooling Control
Dedicated Control
Error Recovery
Allocation Control
Part of the RDEVBLOK pertains to functions that ar e
device independent; that part of the RDEVBLOK is used
in the same way for all devices. However, some of the
fields in the RDEVBLOK have mUltiple uses, depending
on the device type and function.
....H<
c+
~
I»
......
H
"no
Relationship of Virtual I/O Control Blocks - - , - - - - - - - - , - - - - -
The virtual machine configuration is represented by a set
of related control blocks. These blocks are:
• built by VM/370 at LOGIN from data in directory
• modified by user commands (for example, DETACH, LINK, DEFINE)
There is one control block per channel, per control unit, and per
device.
The characteristics of VM/370 virtual I/O control are:
• BMPX (block multiplexing) is supported
• RPS (rotational position sensing) is supported
• the virtual machine operating system performs scheduling
• VM/370 uses virtual I/O control blocks to
simulate real hardware interface
• virtual unit record devices use VM/370 Spooling
• virtual console is simulated on terminal
• minidisks simulate DASD
• dedicated devices are supported
VCUBLOKs
n
VDEVBLOKs
o
t:S
c+
H
o
......
tJ:t
......
o
n
VMCHTBL - virtual channel index table
~
Ul
VCHBLOK - virtual channel block 1
VDEVBLOK - virtual device block 1
VCUBLOK - virtual control unit block 1
Control unit identification
status
Channel identification
status
XXXX
XXXX
XXXX
XXX~
XXX X
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
Device idimtification
Status pending
Positioning
Terminal control
Spooling control
Device
Index
} Table
RDEVBLOK Pointer
n
Part of the VDEVBLtJK contains device ind','pendent
information and is us,ed identically in all VDEVBLOKs.
However, some fields of the VDEVBLOKs have multiple
uses, depending on the device type.
o
t:S
c+
H
o
if negative (FFFFI. no control
unit exists
tU
if positive, the value is an index
to the VCUBLOK
......
H
o
IQ
H
I»
Iii
....
....
\0
if negative (FFFFI. no device
exists
if positive, the value is an index
to the VDEVBLOK
~
the IBM Virtual Machine racility/370:
Control Program rCP) Program Logic publication, SY20 - 0880,
for a detailed description of the CP control blocks
1 See
"'IiI
.....
I
IQ
~
11
en
N
0
SVC Interrupt
1--------- Process--------......
..--INPUT
VI
<
n
I
GR 1
H
t:S
I I
GR 2
en
If PROBLEM MODE
FOR SVC 76
.--
c+
SVC
OLD
PSW
tIl
L--
~
't:I
I»
t:S
0.
.....
.....
0
•
And ADSTOP SVC, simulate 'ADSTOP' to
virtual machine
•
And an SVC 76, verify the parameters and
call DMKVER to build the error record."
And virtual machine is in e)(tended
mode and/or Page 0 is not in storage,
reflect interrupt to virtual machine
Otherwise, fetch Page 0, move CP PSW
to virtual SVCOPSW, and move SVCNPSW
to the CP PSW
If supervisor mode, run user·LPSW
•
v
•
VMBLOK
t:S
•
IQ
WI'
~>
v
[]
I
A (CALLED ROUTINE)
I
/
SVCOLD PSW
.....
.I
If SVC 8 (Link Request), _ _
.---INPUT------,~
PSA
V
SVC NEW PSW
If SVC 0 (Impossible condition or fatal error),
dump the machine
GR15
User Page
VMBLOK
I
c+
11
11
r--OUTPUT
pass control from one module to another
.....
E=J
v
I
If SVC 12 (Return Request),
return control to calling module
~
GR 1 3 '
I
1
RUNPSW
Caller's return
address and
V base regIster
SAVE AREA OF
MODULE CALLED
SAVE AREA OF CALLING
MODULE
I---'"
If SVC 16, release Save Area
_
If SVC 20, get next save area for
calling module
•
..,
If DMKPSA determines that the SVC 76
parameters are valid, it calls DMKVER to budd the
error record. If the parameters are not val id or d
DMKVER cannot build the errOr record, DMKPSA
reflects the SVC back to the virtual machIne. If the
error record is recorded, DMKVER gives control to
the dispatcher with the user's running status set to
return to the next sequential instruction followll1g
the SVC 76.
A new save area is acquired
and passed on. The caller's addressability
register (R 12), the save area address (R 13),
and the return address (SVCOPSW) are
saved in the new save area.
Control is returned to module issuing
SVC 16, rather than to calling module
as in SVC 12.
e
Return is to module issuing SVC 20.
External Interrupt
Process----------------------------------------~
OUTPUT - - - -.....
INPUT----------------------~
PSA (Prefix Storage Area)
If TOO clock comparator interrupt
• unchain from TOO clock comparator
• queue the re,lated TRQBLOK
GO TO
• place on dispatch queue
• set new clock comparator request . . . . . . . . . . . . . .~
DISPATCHEFI
If CPU timer interrupt
.........;..------• flag running user to be dropped from queue
If a Timer interrupt
VMBLOK
VMGPRS
VMFPRS
Timeelr:i:n~te:r:rL::IP:t~~~~~~~~~~=~~~~~~~~~=~>F;V~M~PSW
VMOSlf'AT
• if supervisor mode, ignore
• otherwise, save machine status:
VMBLOK
VMTERM
~
RDEVBLO K (for
operator)
If interrupt from the Console Interrupt Button (External)
• Set the disconnect flag in VMBLOK
• Halt any outstanding I/O
• Clear any outstanding console requests
• If the running user was not interrupted,
resume where left off by LPSW of External old PSW . . . . .~
• Otherwise
--_ _ _ _ _ _
GO TO
DISPATCHER
n
o
I:'
r+
11
o
~
tt:I
11
o
IQ
11
~
EI
•
External interrupt from control panel is used to disconnect
the system operator's terminal. The system operator may
reconnect at any other terminal via the LOGON command.
VMBLOK
VMOSTAT
X'lO'
VMTERM
X'OO'
1.0
-'=
"'Id
1-"
I
~
~
H
1-1
tx:I
3:
<
(I)
Program Interrupt
IV
IV
~-,----------.----- Process
3:
"
W
-J
0
INPUT-----------,
tU
H
0
Program Old PSW
~
CIl
'"<
Determine machine mode and cause of interrupt
H
III
a
Ul
~
(I)
H
I:'
a
~
(I)
't!
H
H
H
0
~
~
(I)
I:'
H
P-
Ul
G"l
------r------------.......
PSA
~
If invalid operation, go to DMKPRGHF routine . . . . . . . . . .,~
'"tj
H
III
a
a
If in supervisor mode, go to DMKDMPDK to take CP dump
GO TO
DMKPRGRF
'-------
::.t:
I»
If recognizable privileged instruction,
simulate it _ _ _ _ _ _ _'_ _ _ _ _ _ _ _ _ _ _ _---,,_ _ _ _ _ _ _-,......
.....
OUTPUT-------------------,
Virtual Storage
1-"
I:'
~
VMPSW
~
1-"
If privileged instruction is not recognized,
issue SVC 0 and dump CP --.::..--..:.-=:..---------~
P-
(I)
VMBLOK
•
If paging exception, call DMKPTRAN to
bring page with requested address
into real storage.
If program interrupt occurs in virtual
problem mode, reflect the
interrupt back to the virtual
machine _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
VMINST
D
SWPTABLE
OUTPUT-------------------,
User's Page 0
•
e.
This is the entry point
to reflect SVC interrupts
(when DMKPSASV could not
reflect it) and to reflect
privileged instructions that
cannot be simulated by
DMKPRVLG
Invalid operation code
is in GR O. The VMINST
field of the VMBLOK contains
the image of the privileged
instruction that caused the
interrupt
VMPSW
VMINST
•
Request For
Real Storage
INpUT------------------------------~
GPRl
GR 2 REQUEST
I
Virtual Address
~---------------~~--------------PROCESS------
------------>
Translate address
CORTABLE
SWPTABLE
YES
•~
Is requested page already in storage?
PAGTABLE
NO
Determine page selection
PAGCORE
real page
address
,•
r-
r - - - -__-Is page available from lists?
FREELIST
INPUT----~
FLUSHLIST
USER LIST
OUTPUT -.,--------_
YES.
/'
PAGII\~G
Release p a g e s . . . . . .
~~---~--.---L--"'~~
Allocate DASD space
' ..........
Schedule page I/O
Mark page free
PAGING
DEVICE
_.- .......
NO
_________
DEVICE
I
Lock - if requested
Form address
Return to requester • . . . . . . . . . . . . . . . . . . . GR 2
r-- Real Address
.~:
(')
o
=='
r+
11
o
~
~
11
o
\Q
11
I»
a
1.0
U1
_.
•
Bits defined for CORFLAG
•
Bits defined for SWPFLAG
SWPTRANS
EQU
X'SO'
Page in transit
SWPRECMP
EQU
X'40'
Page permanently assigned
SWPALLOC
EQU
SWPSHR
EQU
X'20'
X'10'
Page enqueued for allocation
Page shared
SWPREFl
EQU
X'OS'
1st half page referenced
SWPCHGl
EQU
X'04'
1st half page changed
EQU
EQU
X'02'
2nd half page referenced
X'Ol'
2nd half page changed
CORIOLCK
EQU
X'SO'
Page locked for I/O
CORCFLCK
EQU
X'40'
Page locked by console function
CORFLUSH
EQU
X'20'
Page is in flush list
CORFREE
EQU
X'10'
CORSHARE
EQU
X'OS'
Page is in free list
Page is shared
CORRSV
EQU
X'04'
Page is reserved
CORDISA
EQU
X'Ol'
Page disabled - not available
SWPREF2
SWPCHG2
I
~
0'1
....toll!
I.Q
c:
1-1
~
(t)
Il'
til
N
<:
~
til
"W
-..J
....
<:
0
11
til
~
~
~
SIO From Virtual
Machine
rt-
c:
____________ PROCESS ________________
~
OUTPUT--------------------~
DMKVSP
Ul
rt-
til
(t)
"1:j
EI
0
0
tt:I
~
....
Real Storage
INPUT
Free
Storage
Area
~
1-1
0
:::s
\Q
\Q
GR 2
1-1
Virtual CAW
~
EI
EI
(t)
1-1
If spool file not open,
create VSPLCTL
get virtual buffer
save data in VSPLCTL
VYORK
Ul
(j')
c:
....
If Printer, Punch, or Console •
get a work buffer
get virtual CCW
move logical record I[CCW and data) from
spool buffer to work buffer
move data to user's data area
post 'interrupt' pendiing and return to virtual machine
Q"
(t)
Virtual Storage
VDEVBLOK
VDEVSPL
VDEVCSW
•
If a Card Reader
get a work buffer
get virtual CCW
move logical record (CCW and data) from
spool buffer t() work buffer
move data to virtual data area
post 'interrupt' pending and return to virtual machine .
Virtual console spooling is the same as printer spooling except that:
• A skip to channel one CCW is inserted every 60 lines of output
• The operator's virtual console spool buffer is written for every 16 lines of output
• The Virtual spool buffer is written to the allocated spool device when the first CCW is
placed in the Virtual buffer. The buffer is kept in a pseudo closed state so that checkpoint
saves the buffer in the event of a system failure.
DMKDSPCH
User's virtual machine
page containing the Data Area
•
Interrupt From
Spool Device
INPUT FOR PUNCH/PRINTER
- - . - - PROCESS - - - - - - - - - - ,
1+J
, . . . - - - - - - OUTPUT FOR PUNCH/PRINTER . - - - - - . . ,
RDEVBLOK
RDEVBLOK
10BLOK
Find nonbusy unit record device
Find SFBLOK for that device type
RDEVSTAT
RDEVTYC
RDEVSPL .... ~
Create RSPLCTL block and chain it to RDEVBLOK
Remove SFBLOK from chain and chain it to RSPLCTL
SPUNK
Get virtual Duffer and read DASD page
Reconstruct CCWs in data page
Create 10BLOK and chain CCWs to 10BLOK
~_C.....;C.....;W....:.s_[I§
Data
CCWs
TIC
C=:J
OR
Data
Schedule I/O operation
When there is an interrupt from the
unit-record device, get next DASD
page -from chain
INPUT FOR READER
10BLOK
~
n
o
::s
r+
H
o
I-'
I't:l
H
o
\Q
H
~
S
1------------ OUTPUT FOR READER -------------i
Real Stor.lge
DASD Auxiliarv Storage
SPOOL BUFFER
....
\D
:Jl1LV-LUUL,
("loT '1 , , _ '1
March ..J......I
,
1975
Due to the algorithm used by the scheduler in determining
entry to the active queues, the value of STORAGE can exceed
1001.
The scheduler contention ratio, RATIO, is a smoothed measure
of the contention for real storage, and is defined as:
E+M
RATIO
M
M
is the number of users in queuel and queue2
E
is the number of users waiting to be allocated real
storage by the scheduler
and therefore temporQ~ily
resident in the scheduler's eligible lists.
Thus, RATIO is the ratio of active users to users being
serviced, and is 1.0 for optimum response.
Optimum response
occurs when enough real storage is available to accommodate
all active users,
assuming the CPU can
process their
commands. If E and M are both zero, the value of RATIO is set
to 1.0.
Given the value of RATIO and M, (Ql+Q2)
the eligible list can be computed as:
the number of users in
E = M (RATIO-l)
*
INDICATE USER
allows a user to determine the resources used and occupied by
his virtual machine, and the I/O events that have taken
place.
The following two line response is returned:
PAGES: RES-nnnn WS-nnnn READS=nnnnnn WRITES=nnnnnn DISK-nnnn DRUM-nnnn
VTIME=nnn:nn TTIME=nnn:nn SIO=nnnnnn RDR-nnnnnn PRT-nnnnnn PCH-nnnnnn
The first line of the response displays the data from the user's VMBLOR
that is relevant to his virtual machine's paging activity and resource
occupancy.
RES is the current number of the user's virtual storage pages
resident in real storage at the time the command is issued.
WS is the most recent system
set size.
estimate of the
user's working
READS is the total number of page reads for this user since he
logged on or since the last ACNT command was issued for his
virtual machine.
WRITES is the total number of page writes for this user since
he logged on or since the last ACNT command was issued for his
virtual machine.
DISK is the current number of virtual pages
system paging disk for this user.
allocated on the
DRUM is the current number of virtual pages
system paging drum for this user.
allocated on the
Part 2: Control Program
(CP)
210.3
GC'20-1807-3 Page Modified bV TNL GN20-2662, March
j
1,
1'1
The second line of the response gives the user
his
accumulated I/O activity counts since logon or since
command was issued for his virtual machine.
I':)
CPU usage and
the last ACNT
VTIME is the total virtual CPU time for the user.
TTIME is
user.
the total
virtual CPU and
SIO is the total number of
the user.
simulation time
for the
non-spooled I/O requests issued by
RDR is the total number of virtual cards read.
PRT is the total number of virtual lines printed.
PCH is the total nUIDber of virtual cards punched.
I THE CLASS E INDICATE COMMAND
The format of the class E INDICATE command is:
r
,
r
INDica te
ILOAD
I
IUSER
I
I
\Queues
I
, I
II
I userid II
L
J I
I
iI/O
I
IPAGing
I
r
I~!!~
IALL
, I
II
II
L
L
JJ
r
I~
I
I
INDICATE LOAD
-provides the same output as the INDICATE 1Q!~ option described
under "The Class G Indicate Command."
INDICATE USER *
reflects activity
of the system analyst's
own virtual
machine.
The output of this option is the same as that of the
INDICATE USER.! option described under "The Class G Indicate
Command."
INDICATE USER userid
allows the system analyst to determine the activity of other
virtual machines in terms of the resources used and occupied
and events that have taken place. Users with class E authority
can access data from the VMBLOK of any user currently logged
onto the system in their attempts to understand an overload or
poor performance situation.
The output of this option is the same as that of the INDICATE
USER.! option described under "The Class G Indicate Command".
210.4
IBM VM/370: system Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 3i, i975
INDICATE QUEUES
displays the active users, the queues they are in, the storage
~her are
occupying, and the status. th:yare.in.
The display
lndlcates those users currently domlnatlng maln storage. Users
waiting in eligible lists are included in the response because
they are contending for main storage and it is only by chance
that they were not occupying main storage at the time of the
command.
The response to the INDICATE QUEUES command is as follows:
userid1 aa bb ssslttt
userid2 •••
(up to 3 userids per line)
useridn is the user identification.
aa
is the eligible list or queue that the user cccupies.
bb
is one of the following status indicators:
RU
PG
IO
EX
PS
the user is currently running.
the user is not running because CP is attempting to
bring in a page from a paging device.
the user is in 1/0 wait because access to the device
is not available at the moment.
the user is waiting for the completion of an
instruction simulation.
the user is in an enabled wait state for high speed
1/0 devices.
waiting to be redispatched
!g!~:
In cases where a virtual machine may be in more
than one of the above
states,
only one state is
displayed.
The
state displayed is the
first one
encountered in the order of priority indicated above.
sss
ttt
is a hexadecimal number indicating the number of pages
resident in real storage
is a hexadecimal number indicating the working set size
INDICATE 1/0
provides information about conditions leading to possible I/O
contention within the system. The response gives the userids
of all the users in I/O wait state at that instant in time,
and the address of the real device to which the most recent
virtual SIO was mapped. Because the response indicates only
an instantaneous sample, use the command several times before
assuming a condition to be persistent.
If it is persistent,
run the SEEKS option of the MONITOR command to conduct a
thorough investigation of the suggested condition.
The response to the INDICATE 1/0 option is as follows:
userid1 cuu
userid2 cuu
•••
(up to 5 userids per line)
useridn
is the user identification
cuu
indicates the real device address.
Part 2: Control Program (CP)
210.5
GC20-1807-3 Page Modified by TNt GN20-2662, March 31, 1975
In the case where a virtual machine may have issued multiple
SIOs, the
response indicates
the real
device address
corresponding to the most recent one issued.
INDICATE PAGING WAIT
is provIded for installations that have 2305s as primary
paging devices and other direct access devices as secondary
paging device.
A full
primary device
and subsequent
allocation of paging space on the slower device may be
responsible for degradation in system performance.
Use the
INDICATE PAGING WAIT option when the INDICATE QUEUES option
shows that a significant proportion of the users in queue1 and
queue2 are persistently in page wait.
The response to the
command gives the userids of those users currently in page
wait and the numbers of page frames allocated on drum and on
disk.
The response to
follows:
the
INDICATE PAGING
userid1 nnn:mmm userid2 nnn:mmm •••
WAIT
option is
as
(up to 4 userids per line)
useridn
is the user identification.
nnn
is the hexadecimal number of pages allocated on drum
for these users.
mmm
is the hexadecimal number of pages allocated on disk
for these users.
!2!~:
Consider, for example, the following response:
usera 010:054
userb 127:000
If the two users were
to execute programs of similar
characteristics, then usera would be expected to experience
more
pagewait than
userb.
Also,
if the
level
of
multiprogramming were to be low during the execution of
usera's program, then more system page wait would occur than
during the execution of userb's program.
If users appear to have most of their pages allocated on disk,
it would be useful to know which users are occupying most of
the primary paging device space, and whether or not they are
still active.
(That is, a virtual machine that is running a
large operating system may have been allocated large amounts
of primary paging device space at IPL time but then may have
become inactive. Consequently, the machine is occupying a
critical resource that could be put to better use.
INDICATE PAGING ALL
displays the page residency data of all users of the system
(including the system nucleus and pageable routines).
The
response is identical to that of the INDICATE PAGING !!!!
option.
The following
appropriate:
response is
issued for the
NO USERS IN QUEUE
210.6
IBM VM/370: system Programmer's Guide
INDICATE QUEUES
option when
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
The following response
appropriate:
is
issued for
the
INDICATE
1/0 option
when
NO USERS IN I/O WAIT
The following response is
when appropriate:
issued for the
INDICATE PAGING
WAIT option
NO USERS IN PAGEWAIT
Part 2: Control Program (CP}
210.7
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
VM Monitor collects data in two ways:
1.
By handling interruptions caused
instructions.
2.
By using timer interruptions to
sampling routines.
by executing
give
control
MONITOR CALL
periodically
(MC)
to
MONITOR CALL instructions with appropriate classes and codes are
presently emtedded in strategic places throughout the main body of
VM/370 code (CP).
When a MONITOR CALL instruction executes, a program
interruption occurs if the particular class of MONITOR CALL is enabled.
The classes of MONITOR CALL that are enabled are determined by the mask
in control register 8. For the format and function of the MONITOR CALL
instruction, refer to the System/370 Principles of Operation manual,
Order No. GA22-7000.
The format of control register 8 is as follows:
I r
I I
I
I
I
I
I
I
I
I I xxxx xxxx xxxx xxxx 0123 4567 89AB CDEF
I I
I
I
I
I
I
I
I
I L
I x
indicates unassigned bits
O-F
(hexadecimal)
indicates the bit associated with each possible class of
the MONITOR CALL.
When a MONITOR CALL interruption occurs, the CP program interruption
handler
(DMKFRG)
transfers control to the VM Monitor interruption
handler, (DMKMON) where data collection takes place.
sixteen classes of separately enabled MONITOR CALL instructions are
possible, but only eight are implemented in the VM Monitor~
Monitor output consists of event data and sampled data. Event data
is obtained via MONITOR CALL instructions placed within the VM/370
code. Sampled data is collected following timer interruptions.
All
data is recorded on the output tape as though it were obtained through a
MONITOR CALL instruction. This simplifies the identification of the
ta pe records.
The following table indicates the
each Monitor class:
Monitor
Class
£!~~~
!~.!!!~
0
1
2
3
4
5
6
7
8
210.8
PERFORM
RESPONSE
SCHEDULE
Reserved
USER
INSTSIM
DASTAP
SEEKS
SYSPROF
type of collection
Collection
Mechanism
"TImer-requests
MC instructions
MC instructions
Timer requests
MC instructions
Timer requests
MC instructions
Collected via class 2
IBM VM/370: System Programmer's Guide
mechanism for
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Another function,
separate from the VM Monitor, is also handled by
the MONITOR command.
The MONITOR command can stop and start CP internal
trace table data collection, which is g21 initiated by MONITOR CALLs.
!21g: The
VM Monitor tape record format and the contents of
record are shown in Appendix B in this manual.
the tape
The MONITOR command:
;
e
I.
I
I
!.
I.
I
stops and starts CP internal trace table data collection.
Displays the status of the internal trace table and each implemented
class of VM Monitor data collection.
Enables one or more classes of
MONITOR CALL.
starts and stops data collection recording by VM Monitor onto tape:
Specifies what interval is to be used for timer driven data
collection.
I The format of the class A and E MONITOR command is:
-,
r-
MONitor
Display
ENable
PERForm
RESPonse
SCHedule
USER
INSTsim
DAStap
SEEKs
SYSprof
INTerval
nnnnn
1
,
r
I~~~I
IMINI
L
STArt
CPTRACE
STArt
TAPE
J
r
L
STOP
rOO}'
raddr IMODE 1600 I
6250 I
I
J
{ CPT RACE }
TAPE
lSelect one or more of the classes subject to the restrictions below.
L-___________________________
-----------------~
DISPLAY
displays the status of the internal trace table and the
implemented classes.
A separate line of output for the
internal trace table and each class of MONITOR CALL indicates
the class and its status (enabled or disabled).
Part 2: Control Program (CP)
210.9
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
ENABLE
PERForm
RESPonse
SCHedule
USER
INSTsim
DAStap
SEEKs
SYSprof
enables the
specified classes
of MONITOR
CALL.
Each
successful completion of this command creates a
new mask for
control register 8.
The function of each class is described
in the section "Implemented Classes."
The effect of the MONITOR ENABLE command depends on whether
data collection is active or inactive when the command is
issued. If data collection is active (MONITOR START TAPE has
been issued), the new mask is moved directly into control
register 8, replacing the previous mask, and the new mask
takes effect immediately. Collection then continues with the
classes just entered. If data collection is not active at the
time the command is issued, then the mask is saved until the
MONITOR START TAPE command is issued.
Restrictions exist on issuing the MONITOR ENABLE command while
the VM Monitor is collecting and recording data on tape.
Every MONITOR ENABLE command yields a
example, if PERFORM and USER classes
collected, and you enter MONITOR ENABLE
and USER classes are stopped and INSTSIM
new mask.
Thus, for
are currently being
INSTSIM, then PERFORM
is started.
Thp
DASTAP operand in the MONITOR ENABLE command must be
specified prior to the MONITOR START TAPE command.
DASTAP may
be disabled at any time by respecifying the MONITOR ENABLE
command with DASTAP absent from the class list.
The SYSPROF class cannot be activated unless
and SCHEDULE classes are also active.
both the DASTAP
If data collection is in progress when you issue a MONITOR
ENABLE command and an error occurs in the command line during
processing, no change is made to the monitoring status.
Unrecognizable keywords, conflicting
or missing operands
generate appropriately different error messages.
Due to the security exposure which potentially exists with
collecting terminal input and output data, the RESPONSE class
of data collection does not occur unless the system programmer
sets the TRACE (1) bit in the LOCAL COPY to 1 and reassembles
the CP module DMKMCC. If this is not done, the RESPONSE class
is considered an invalid operand of the MONITOR ENABLE
command.
r
INTERVAL
nnnnn
,
I~~£I
IMINI
L
J
specifies the time interval to be used for the three timer
driven data collection classes: PERFORM, USER, and DASTAP.
The value specified by nnnnn is the number of seconds or
minutes between data collections. If no interval is specified
on the MONITOR INTERVAL command, an error message occurs.
If
210.10
IBM VM/370: system Programmer's Guide
GC20-i807-3 Page Modified by TNL GN20-2662, March 31, 1975
you give an interval but enter neither SEC nor MIN,
the
default is SEC.
The maximum allowatle interval is 9 hours
(540 minutes or 32,400 seconds).
The minimum is 30 seconds.
If the MONITOR INTERVAL command is not issued,
the default
interval is 60 seconds. The MONITOR INTERVAL command can be
issued at any time; however, if data collection is already in
progress, the new interval does not take effect until the
current interval has elapsed.
The MONITOB interval is reset to ~ne
whenever any of the following occurs:
•
•
•
default of
60 seconds
the user issues MONITOR STOP
the
because of
an unrecoverable
I/O error
the end of tape is reached
!g!~:
The information regarding the INTERVAL operand of the
MONITOR command, contained in this publication,
supersedes
that found in the Y~LJ1Q: QE~£~!Q£~~ g~iQ~.
START CPTRACE
starts the tracing of events that occur on the real machine.
The events are recorded in the CP internal trace table in
chronological order.
When the end of the table is reached,
recording continues at the beginning of the table, overlaying
data previously recorded.
r
,
START TAPE raddr :MODE{l:gg}:
I
6250 I
L
J
starts the data collection by VM Monitor on to a tape.
Specify "raddr" as the real hexadecimal address of the tape
drive that you want to use.
It activates data collection for
those classes of MONITOR CALL previously specified in a
MCNITOR ENABLE command. The mask that was saved by the
MONITOR ENABLE command is moved into control register 8. The
data is collected in two buffer pages in real storage. These
pages are separate from the internal trace table pages.
As
each data page is filled, it is written onto the tape.
When the VM Monitor is started, CP
followed by a Set Mode command for
density.
issues a REWIND command
the reset value of tape
The user can request a different mode setting by specifying
the MODE option 1n the MONITOR START TAPE command.
Mode
values of 800, 1600, or 6250 BPI may be specified.
]2!~:
If a user specifies density mode that the tape cannot
handle, the control unit may not return an error conditon; in
this case the mode setting is ignored and the default control
unit setting is used.
STOP CPTRACE
terminates the tracing of events occurring on the real
Event recording ceases but the pages of storage
machine.
containing the CP internal trace table are not released.
Tracing can be restarted at any time by issuing MONITOR START
CPTRACE.
Part 2: Control Program (CP)
210.11
GC20-1807-3 Page Modified by TNL GN20-2662. March 31, 1975
STOP TAPE
stops data collection by VM Monitor on to tape.
A zero mask
is immediately stored in control register 8, thus disabling
MCNITOR CALL interruptions. The last partially filled page is
written out, two tape marks are written, and the tape is
rewound and unloaded.
The two buffer pages, which were
obtained at the time the MONITOR START TAPE command was
issued, are released.
The CPTRACE and TAPE operands of the MONITOR command
completely separate functions. Commands affecting the status of
function have no effect on the other.
!Q1~:
are
one
The following response occurs if you issue the MONITOR DISPLAY command:
!~X~Q~Q
~1~
PERFORM
RESPONSE
SCHEDULE
USER
INSTSIM
DASTAP
SEEKS
SYSPROF
CPTRACE
0
1
2
4
5
6
7
8
The following response occurs for
DISPLAY, that successfully execute:
~1A1~~
(ENABLED
or
DISABLED)
MONITOR commands,
except
MONITOR
COMMAND COMPLETE
I IMPLEMENTED CLASSES
The following MONITOR CALL classes correlate with the corresponding
classes in control register 8.
Refer to the System/370 ~£!~£!£!~§ Qf
Q£~~~!iQQ, Order No. GA22-7000 for details of the MC instruction and the
bits in control register 8.
Monitor
~!~§§
Zero
PERFORM
Samples system resource usage data by accessing
system
counters
of
interest
to
system
performance analysts.
One
RESPONSE
Collects data on terminal I/O.
simplifies
analyses of command usage, user and system
response times. It can relate user activity to
system performance. This class is invalid and
no data can be collected for it unless the
system programmer changes the LOCAL COPY file
and reassembles DMKMCC.
Two
SCHEDULE
Collects
data
about
scheduler
queue
manipulation.
Monitors flow of work through
the
system,
and indicates
the
resource
allocation strategies of the scheduler.
Three
210.12
Reserved
IBM VM/370: system Programmer's Guide
Page
ml.1T
..L. 11.J."
r'l.l')(\~_')CC,)
~
11 £
V
- L
U U L
,
u,~_t..
nUJ,.\.-ll
-') 1
..J
I ,
10"71:
1.:11-1
Four
USER
Periodically scans the chain of VMBLOKs in the
system, and extracts user resource utilization
and status data.
Five
INSTSIM
Records
every virtual
machine
privileged
instruction handled by the control program
(CP) •
Because
simulation
of
privileged
instructions is a major source of overhead,
this data may lead to methods of improving
performance.
If the VMA feature is active,
the number of
privileged instructions that are handled by the
control program is reduced for those virtual
machines that are runnino with the feature
acti va ted.
-
six
DASTAP
Periodically samples device I/O activity counts
(SIOs), for tape and DASD devices only.
It is possible that the number of DASD and tape
devices defined in DMKRIO exceeds 291
(the
maximum number of MONITOR DASTAP records that
fi t
in a
MONITOR
buffer) •
The following
algorithm
determines
which
devices
are
monitored:
Seven
SEEKS
1.
If the total number of DASD and tape
devices that are online is less than or
equal to 291, all online DASD and tape
devices are monitored.
2.
If the online DASD devices total less than
or equal to 291, all online DASD devices
are monitored.
3.
Otherwise,
the first
device are monitored.
291
online
DASD
Collects data for every I/O request to DASD
devices.
Reveals channel, control unit, or
device contention and arm movement interference
problems.
HIO
No
data is
collected
for
TIO or
data is
operations.
For
SIC operations,
collected when
the request
for the
I/O
operation is initially handled and again when
the request is satisfied.
This means that a
single SIO request could
result in two Monitor Calls. For example, if
the request gets queued because the device is
already busy, then a Monitor Call would be
issued as the request is queued.
Later, when
the device becomes free and is restarted, a
second Monitor Call is issued.
In general, the data collected is the same
except that in the first case there will be
non-zero
counts
associated
with
queued
requests.
Part 2: Control Program (CP)
210.13
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
If the request for I/O is satisfied when it is
initially handled,
without being queued v only
one Monitor Call results.
In both this case
and the second of the two data collections
mentioned above, the count of I/O requests
queued for the device is zero.
Eight
SYSPROF
Collects nata complimentary to the DASTAP and
SCHEDULE classes in order to provide a more
detailed
"profile" of
system
performance
through
a
closer
examination
of
DASD
utilization.
I VM MONITOR RESPONSE TO UNUSUAL TAPE CONDITIONS
When I/O to the tape is requested, the device may still be busy from the
previous request.
If this occurs, two data pages are full and data
collection must be temporarily suspended.
Control register 8 is saved
and then set to zero to disable MONITOR CALL program interruptions and
timer data collection. A running count is kept of the number of times
suspension occurs.
The current Monitor event is disregarded.
When the
current tape I/O operation ends, the next full data page is scheduled
for output.
MONITOR CALL interruptions are re-enabled (control register
8 is restored), a record containing the time of suspension, the time of
resumption and the suspension count is recorded and data collection
continues. The suspension count is reset to zero when the MONITOR STOP
TAPE is issued.
When an unrecoverable error occurs, DMKMON receives control and attempts
to write two tape marks, rewind and unload the tape.
The use of the
tape is discontinued and data collection stops.
The operator is
informed of the action taken.
Whether or not the write-tape-marks,
rewind and unload are successful, the tape drive is released.
When an end-of-tape condition occurs, DMKMON receives control.
A tape
mark is written on the tape and it is rewound and unloaded.
The VM
Monitor is stopped and the operator is informed of the action taken.
I VM MONITOR CONSIDERATIONS
The system programmer may want to set the TRACE(1) bit to 1 in the LOCAL
COPY file and reassemble DMKMCC to allow RESPONSE data (MONITOR class 1)
to be collected.
See the information about security exposure in
"MONITOR ENABLE Restrictions" in the MONITOR command description.
210.14
IBM VM/370: system Programmer's Guide
GC20-1807-3 Page Modified by TNL
f"~'')(\
Ul'~V
_')c
C ')
LUUL,
U~_~L
na.L.vu
I,
'") 1
J
MONITOR START CPTRACE is active after real system IPL
(manual
automatic).
The VM Monitor tape data collection is off after IPL.
1n...,c:
I :7 , .J
or
System shutdown implies a MONITOR STOP TAPE command.
Normal command
processing for the MONITOR STOP TAPE function is performed by the
system.
If the VM/370 system fails and data collection is active, an attempt is
made to write two tape marks, rewind and unload the tape. If the tape
drive fails to rewind and unload, be sure to write a tape mark before
rewinding and unloading the tape.
VM Monitor data collection is
terminated by the system failure.
A supported tape drive must be dedicated to the system for the duration
of the monitoring.
For accounting purposes, all I/O is charged to the
system.
I VM MONITOR DATA VOLUME AND OVERHEAD
Use of the VM Monitor requires that three pages be locked in storage for
the entire time the VM Monitor is active; this reduces by three the
number of page frames available for paging.
This significantly affects
the performance of the rest of the system when there is a limited number
of page frames available for paging.
PERFORM
This class of data collection is activated once every 60
seconds (or as defined by the MONITOR INTERVAL command), and
records system counters relevant to performance statistics.
It is, therefore, a very low overhead data collection option.
RESPONSE
This class collects terminal interaction data and, because of
the human factor,
has a very low rate of occurrence relative
to CPU speeds. Consequently, this class causes negligible
overhead and produces a low volume of data.
SCHEDULE
This class records the queue manipulation activity of the
scheduler and generates a record every time a user is added to
the eligible list, added to queue1
or queue2, or removed from
queue.
The recording overhead is very low.
Part 2: Control Program
(CP)
210.15
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
USER
This class of data collection is active once every 60 seconds
(or as defined by the MONITOR INTERVAL command). Data is
extracted from each user's VMBLOK,
including the system
VMBLOK. The overhead incurred is comparable with that of the
statistical data of the PERFORM class; however, it increases
with the number of users logged onto the system.
INSTSIM
This class of data collection can give rise to large volumes
of data because of the frequency of privileged instructions in
some virtual machines. This may incur significant overhead.
It should be activated for
short periods of time and
preferably, though not necessarily, when other classes of data
collection are inactive.
If the virtual Machine Assist
feature is active for the virtual machine, the data volume and
consequently the CP overhead may be reduced.
DASTAP
This class of data collection samples device activity counts
once every 60 seconds (or as defined by the MONITOR INTERVAL
command), and is a very low source of overhead, similar to the
PERFORM and USER classes.
SEEKS
This class of data collection can give rise to large volumes
of data because every start I/O request to DASD devices is
recorded via a MONITOR CALL.
SYSPROF
This class of data collection is complementary to the SCHEDULE
and DASTAP classes and results in a small amount of additional
overhead.
It obtains more refined data on DASD resource
usage.
For daily monitoring, to generate a data tape suitable for analyzing
utilization and performance trends, use the PERFORM class only.
If
performance bottlenecks are suspected, run the RESPONSE and SCHEDULE
classes to relate user activity to system scheduling decisions in terms
of demands on system resources.
If particular users are suspected of
dominating the system, or if I/O activity is suspected of being
concentrated on particular devices,
then run the USER and DASTAP
classes.
If the DASTAP class does not give enough information to
resolve possible I/O contention questions,
activate the SEEKS class for
a short period of time, for instance, ten minutes.
The SYSPROF class can be enabled along with SCHEDULE and DASTAP to
give an additional breakdown of I/O device activity as it relates to
queue manipulation by the scheduler. The INSTSIM class can be enabled
to determine which users are incurring high amounts of system overhead
due to instruction simulation.
I LOAD ENVIRONMENTS OF VM/370
Two distinct uses of VM/370 can be readily identified, and consequently
some differences in criteria for acceptable performance may occur. The
system may be required to time share multiple batch-type virtual
machines with interactive machines performing minor support roles; or,
the system may be primarily required to provide good interactive
time-sharing services in the foreground,
with a batch background
absorbing spare resources of real storage and CPU.
210.16
IBM VM/370: system Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662. March 31; 1975
First you must determine how many similar users can be run concurrently
on a given configuration before the throughput of individual users
becomes unacceptable.
After determining this, you can perform external observations of
turn-around time on benchmarks and specify a point beyond which the
addition of more users would be unacceptable. However, when that point
is reached, more sophisticated internal measurement is required to
determine the most scarce resource and how the bottleneck can be
relieved by additional hardware.
Several possible
conditions
different bottlenecks. They are:
can
be
identified
resulting
from
I •
I
I
I
Real storage is the bottleneck; levels of multiprogramming are low
compared with the number of contending users. Hence, each user is
dispatched so infrequently that running time or response time may
become intolerable.
I.
I
I
storage may be adequate to contain the working sets of contending
users, but the CPU is being shared among so many users that each is
receiving inadequate attention for good throughput.
I.
I
I
I
I
I
Real storage space may be adequate for the CPU, and a high speed drum
is used for paging; however, some virtual storage pages of some users
have spilled onto slower paging devices because the drum is full.
with low levels of multiprogramming, user page wait can become a
significant portion
of system
wait time.
Consequently, CPU
utilization falls and throughput deteriorates.
I.
I
I
I
I
storage, CPU, and paging resources are adequate, yet several users
are heavily I/O bound on the same disk, control unit, or channel. In
these circumstances, real storage may be fully committed because the
correct level of multiprogramming is selected, yet device contention
is forcing high I/O wait times and unacceptatle CPU utilization.
Estimates of typical working set sizes are needed to determine how
well an application may run in a multiprogramming environment on a given
virtual storage system. A measure of the application's CPU requirements
may be required for similar reasons.
Measurements may be required on
the type and density of privileged instructions a certain programming
system may execute, because, in the virtual machine environment,
privileged instruction execution may be a major source of overhead. If
the virtual machine environment is used for programming development,
where the
improvement in
programmer productivity
outweighs the
disadvantages of extra overheads, the above points may not be too
critical. However, if throughput and turnaround time are important,
then the converse is true, and the points need close evaluation before
allocating resources to a virtual machine operation.
High levels of multiprogramming and overcommitment of real storage
space leads to high paging rates.
High paging rates can indicate a
healthy condition; but, be concerned about page stealing and get
evidence that this rate is maintained at an acceptable level. A system
with a high rate of page stealing is probably thrashing.
Par~
2: Control Program (CP)
210.17
GC20-1807-3 Page Mcdified by TNL GN20-2662,
~arch
31,
1975
Most of the conditions for good performance, established for the
time-shared batch systems, apply equally well to mixed mode systems.
However,
two major factors make any determination more difficult to
make. First, get evidence to show that, in all circumstances, priority
is given to maintaining good interactive response, and that non-trivial
tasks take place truly in the background.
Second, background tasks, no
matter how large, inefficient, or demanding should not be allowed to
dominate the overall utilization of the time-sharing system. In other
words,
in mixed mode operation, get evidence that users with poor
characteristics are discriminated against for the sake of maintaining a
healthy system for the remaining users.
A number of other conditions are more obvious and straightforward.
You need to measure response and determine at what point it becomes
unacceptable and why.
Studies of time-sharing systems have shown that a
user's rate of working is closely correlated with the system response.
When the system responds quickly, the user is alert, ready for the next
interaction, and thought processes are uninterrupted.
When the system
response is poor, the user becomes sluggish.
For interactive environments, a need exists to analyze command
usage.
Average execution time of the truly interactive commands can
provide data for validation of the queue1 execution time.
210.18
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March
~1
.oJ
•
,
1975
Accounting Records
Accounting cards are punched and selected to pocket 2 of any class C
card punch when a user logs off of the system, detaches a dedicated
device or T-disk or lssues a Diagnose code x'4C' instruction.
(If the
real punch is a 2540, the accounting cards are put in pocket 3.) These
records should be kept for system accounting purposes. The information
on the accounting card is as follows (columns 1-28 contain character
data; all other data is in hexadecimal form, except as noted):
Column
-'=-89-16
17-28
Conten ts
UserIa:-Account number
Date and Time of Accounting (mmddyyhhmmss)
29-32
Number of seconds connected to VM/370 System
33-36
Milliseconds of CPU time used, including time for
VM/370 supervisor functions
Milliseconds of virtual CPU time used
Number of page reads
Number of page writes
Number of
virtual machine SIO
instructions for
nons pooled I/O
Number of spool cards to virtual punch
Number of spool lines
to virtual printer
(this
includes one line for each carriage control command)
Number of spool cards from virtual reader
Reserved
Accounting card identification code l (01 or Cl)
37-40
41-44
45-48
49-52
53-56
57-60
61-64
65-78
79-80
Accounting cards are punched and selected to pocket 2 of any class C
card punch when a previously dedicated device is released by a user via
DETACH, LOGOFF, or releasing from DIAL; or, by a user lssuing a Diagnose
code x'4C' instruction. A dedicated device is any device assigned to a
virtual machine for that machine's exclusive use. These include devices
dedicated by the ATTACH command, those being assigned at logon by
directory entries, or by a user establishing a connection (via DIAL)
with a system that has virtual 2702 or 2703 lines. The information on
1
The accounting card identification code is one of the following:
co
xl
x2
x3
~}~;~~
(' = C
User
User
User
User
formatted accounting card
virtual machine accounting card
dedicated device accounting card
temporary disk space accounting card.
if the card is initiated via CP command processing
if the card is initiated via a DIAGNOSE code x'4C'
Part 2: Control Program (CP)
211
GC20-1807-3 Page Mcdified by TNL GN20-2662,
~~rrh
11,
1Q7S
the accounting card is as follows
(columns 1-28 contain character data;
all other data is in hexadecimal form, except as noted):
f2!!!!!!!!
1- 8
9-16
17-28
29-32
33
34
35
36
37-38
39-78
79-80
f.2!!!~!!.!~
Userid
Account number
Date and Time of Accounting (mmddyyhhmmss)
Number of seconds connected to VM/370 system
Device class
Device type
Model (if any)
Feature (if any)
Number of cylinders of temporary disk space used (if
any). This informa tion appears only in a code 03 or
C3 accounting card.
Unused
Accounting card identification code.
(02, 03, C2, or
C3)
The device class, device type, model,
33-36 are shown in Figure 12.
and feature codes
in columns
A virtual machine user can initiate the punching of an accounting card
that contains up to 70 bytes of information of his own choosing.
To do
this, he issues a DIAGNOSE code x'4C'
instruction with the following
operands:
I •
I
I
The address of a data area in virtual storage containing the
information, in the actual format, that he wishes to have punched
into columns 9 through 78 of the card.
I •
A hexadecimal function code of x'10'
I •
The length of the data area in bytes
The information on the accounting card is as follows:
~2!!!!!!!!
1-8
9-79
79-80
contents
Useri"a:--
User formatted data
Accounting card identification, "CO"
A complete description of the DIAGNOSE code x'4C' instruction can be
found under "DIAGNOSE Instruction in a Virtual Machine" in this
section.
If a punch is started for two classes with NOSEP specified, accounting
cards are not uniquely separated from data decks.
If started with NOSEP
specified,
the operator is prompted when a user has a deck to be
punched.
The operator can thus remove any accounting cards before
starting the punch. After data is through punching, accounting cards may
be punched.
212
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
If the amount of free storage (available page frames) is relatively
small and the card punch is not periodically assigned to punch out CP's
accounting cards, it is possible for CP's accounting routine to
progressively use up a significant percentage of the available page
frames and cause a page thrashing condition to occur in VM/370.
This is
because the accounting routine creates and updates accounting records in
real storage, and does not free that storage space until the accounting
records are punched out on the real system card punch.
This situation
is further aggravated when the accounting option for a batch virtual
machine is in effect. due to the increased number of accounting records
generated.
To eliminate this problem, it is recommended that one punch pocket be
permanently dedicated to this accounting function, or if that is not
feasible, to punch out all the accumulated accounting records every 1 to
2 hours.
You may insert your own accounting procedures in the accounting
routines.
See the "CP Conventions" section for information on CP coding
conventions and loadlist requirements.
Operator responsibilities in
such cases should be defined by the installation making the additions.
When designing such accounting procedures, you should understand that:
1.
The accounting routines are designed to be expanded.
The entry
point provided in the accounting module for installation use is
called DMKACON.
If you want to perform additional accounting
functions, you should modify the following copy files:
ACCTON (account on) -- for action at logon time. This is provided
as a null file.
It can be expanded to provide additional functions
at logon time. The ACCTON routine can request the system to force
the user off by returning a nonzero value in SAVER2.
However, if
the
operator
is
automatically
logged
on
during
system
initialization, the nonzero return code has no effect.
!Q1~:
The ACCTON COpy file distributed with VM/370 contains the
basic logic required to enhance system security based on the 3277
Operator Identification Card Reader feature.
Additional checking
may be added to examine or validate the data read from the
identification card.
ACCTOFF (account off)
-- for action at logoff time. This section
contains the code that fills in the account card fields.
It does
not reset any internal data. This file exists in both DMKACO and
DMKCKP
(checkpoint). If the ACCTOFF copy file is changed, both
modules should be reassembled.
2.
CP has no provision for writing the accounting records to disk.
3.
In addition to CP accounting, your installation can use the
accounting routines to supply virtual machine operating system
accounting records.
This provides a means of job accounting and
operating system resource usage accounting.
4.
If no punch is generated in the VM/370 system, accounting records
are not queued for punching. The ACCTON and ACCTOFF copy files are
still called, however.
Part 2: Control Program (CP)
213
Generating Named Systems
By taking advantage of the SAV!SYS command, system resources are not
committed to perform an IPL each time a saved system is requested.
Instead, the named system is located and page tables are initialized
according to its system name table entry.
The named system is not
automatically loaded at IPL time; however, its pages are brought into
storage on demand as the virtual machine operating system executes.
In addition to saving time by avoiding an IPL, a saved system can
share segments of reenterable code, thus making more efficient use of
real storage. This technique is especially valuable when using CMS.
When adding, changing, or deleting, the DMKSNT module must be
reassembled.
The GENERATE EXEC procedure has a facility to reassemble
only the DMKSNT module.
See the description of the GENERATE EXEC
procedure in the !~LllQ: Rlg~ni~~ g~g §I§!~! §~!~!~!!Qn Guig~.
The procedure for generating a named system consists of two steps:
1.
Configuring and assembling the NAMESYS macro (DMKSNT).
2.
Loading the system
command.
to
be saved
and
then
invoking the
SAVESYS
When allocating DASD space for named systems, provide an extra page
for information purposes; do not overlay this area with subsequent named
systems.
The NAMESYS macro is assembled by the installation system programmer and
is used to describe the location of the saved system. Shared segments
may be specified, but they must consist of reenterable cede, with no
alteration of its storage space permitted.
A DMKSNT ASSEMBLE module supplied with the system contains a dummy
NAME TABLE.
Either edit or update this module to include the NAMESYS
macros describing your installation's named systems.
Note that this
module may contain a PUNCH SPB card, which is used by the loader to
force this module to a 4K boundary when the CP system is built (a 12-2-9
multipunch must be specified in column 1 of an SPB).
The format of the NAMESYS macro is:
label
NAMESYS
SYSSIZE=nnnK,SYSNAME=cccccc,VSYSRES=cccccc,
VSYSADR=ccu,SYSVOL=cccccc,SYSCYL=nnn,
SYSSTRT=(cc,p) ,SYSPGCT=nn,
SYSPGBM=(nn,nn,nn-nn, ••• ),
SYSHRSG=(n,n, ••• )
label
is any desired user label.
SYSSIZE
is the
system.
214
minimum storage size
K must be specified.
IBM VM/370: system Programmer's Guide
needed
to operate
the
saved
SYSNAME
is the name given the system to be used for identification by
SAVESYS and 1PL. The name selected must never be one that
could be interpreted as a hexadecimal device address
(for
example, 'A' or 'E').
VSYSRES
is the real volume serial number of the DASD volume containing
the virtual disk that is the system residence volume ~or the
system to be saved.
VSYSADR
is the virtual address of the virtual disk that is the system
residence volume for the system to be saved.
SYSVOL
is the volume serial number of the DASD designated to receive
the saved system. This must be a CP-owned volume.
SYSCYL
is the real starting cylinder of the virtual disk (specified
by VSYSRES and VSYSADR) that is the system residence volume
for the system to be saved.
SYSSTRT
designates the starting cylinder and page address on SYSVOL at
which this named system is to be saved. During the SAVESYS and
1PL processing, this will be used to make up the "cylinder
page and device" address for the DASD operations.
These
numbers are to be specified in decimal.
SYSPGCT
is the total number of pages to be saved.
SYSPGNM
are the numbers of the pages to be saved. Specification may
be done as groups of pages or as single pages. For example:
if pages 0, 4, and 10 through 13 are to be saved, use the
format: SYSPGHM (0,4,10-13).
SYSHRSG
are the segment numbers designated as shared. The pages in
these segments will be set up at 1PL time to be used by any
user loading by this name. All segments to be shared must be
reentrant.
For example, a DMKSNT module to create
follows:
DMKSNTBL CSECT
FSTNAME NAMESYS
a named CMS could be coded as
SYSS1ZE=384K,SYSNAME=CMS,VSYSRES=CPDSK1,
VSYSADR=190,SYSCYL=100,SYSVOL=CPDSK2,
SYSSTRT=(400,1) ,SYSPGCT=35,
SYSPGNM= (0-34) , SYSHRSG= (1)
x
X
X
END
The system to be saved must first be loaded by device address in the
traditional manner.
The system to be saved must have its execution
stopped before its page-format image can be saved. The point at which
the operating system is stopped should be determined by the installation
system programmer.
Then, the command "SAVESYS name" must be issued,
where name corresponds to the identification of the saved system. The
user must have a CP privilege class of E to issue the SAVESYS command.
Hext, you should 1PL the saved system. The virtual machine will attempt
to resume execution and immediately encounter a page fault.
The
required page is brought into storage and execution continues.
As
execution continues, subsequent page faults will bring the required
pages into storage.
Part 2: Control Program (CP)
215
A system should be saved as soon after IPL as possible.
All pages to be
saved must be resident at the time the SAVESYS command is issued. Also,
before issuing the SAVESYS command, be sure that the system is stopped.
CMS was designed to run under CP and it was also designed 50 that it
could easily be saved by CP. See "saving the CMS System" in "Part 3:
Conversational Monitor System (CMS)" of this publication.
I SPECIAL CONSIDERATIONS
FO~
SHARED SEGMENTS
When a saved system containing one or more shared segments is again
saved, a problem can occur if the following conditions are present:
1.
The previous system has been loaded by name before
was saved, and is still in use.
the new system
2.
The unshared segments contain at least one address pointing to data
in a shared segment that has moved as a result of a change.
3.
The new system has been loaded by name.
The problem is that when the new system is loaded, it will use the
old system's shared segaents if one or more users of the old system are
still logged on. Therefore, new versions of named systems containing
shared segments (for example, CMS) should not be saved as long as the
above conditions exist.
SAVING OS
Since OS varies with system, release,
and system generation options, it
is impossible to outline a detailed Frocedure to save OS. The following
considerations are only guidelines.
It is up to you to determine when
to save your installation's os.
The following steps should be performed:
1.
Make the os system residence volume read-only. Some modification to
OS is required.
Consider the following modifications to OS for a
saved OS system:
..
216
Uncatalog SYS1.DUMP -- if needed, CP dumps can be taken. If
your installation wants to have a shared OS system, SYS1.DUMP
must be cataloged on a scratch disk.
•
Modify the RDR SYS1.PROCLIB entry to allocate only a
amount of space for IEFDATA (5 cylinders are adequate).
•
Eliminate the
disk.
•
Eliminate LOGREC recording; CP does its own error recording.
•
If 2314s are used, eliminate alIOS standalone seeks, and turn
off all shared 2314 DASD bits (UCDTYP field, byte 2, bit 2).
writing location
of SYS1.PROCLIB
IBM VM/370: System Programmer's Guide
on the
small
system
For a 2314, if the first CCW in a channel program is a command
chained seek, CP executes a split seek before starting the
actual given CCW commands. This technique renders the OS
standalone seek redundant.
A shared DASD is a problem because
OS prefaces data transfer CCW command sequences with a release
command. As a result, CP does not do its split 2314 seek but
just executes the given CCW commands. Thus for a shared DASD,
since the CP split seek and the OS standalone seek both have
been eliminated, the actual 2314 CCW commands always tie up the
real channel for the duration of the seek (including arm
movement).
2.
Use the IBCDASDI program to initialize a virtual scratch disk.
3.
IPL OS in the usual manner and then save
job queue, the VTOC of the scratch disk,
in addition to the contents of storage
reload a saved OS system. The following
it can be saved. The job also causes a
when the saved OS system is started no
required.
consider using
moment:
the following
FOS
FASTOS
'SUPPORT FAST START OF SYSTEM UNDER VM370'
TITLE
CSECT
USING
B
ORG
STM
ST
ST
LR
SPACE
WTO
WTO
WTC
WTO
WTO
WTO
WTO
WTO
WTO
WTO
SPACE
job to help
it. You must save the os
and the working data set
in order t? successfully
job will sp1n OS so that
reader interrupt so that
operator intervention is
you save
OS at
the right
FASTOS,13
USE R13 AS BASE FOR FASTOS
72(,15)
BRANCH TO START OF PROGRAM
FASTOS+72
SAVE AREA
14,12,12 (13) SAVE ALL REGISTERS BUT R13
15,8(,13)
SAVE START ADDRESS IN CALLERS SAVE AREA
13,4(,15)
SAVE ADDRESS OF CALLERS SAVE AREA
13,15
SET BASE
'AFTER SPINNING IS TYPED - ENTER CP AND DISPLAY PSW'
'NEXT, STORE A NEW PSW USING ST PSW XXXXOOOO OOYYYYYY'
'WHERE XXXX is 0004,FOR OS, OR 040C FOR VS'
'AND YYYYYY IS ADDRESS IN DISPLAYED ORIG PSW +4'
'NEXT, BITER SAVESYS ZZZZZZZZ'
'WHERE ZZZZZZZZ IS A SAVESYS NAME IN DMKSNT'
'LAST, IPL CMS AND SAVE 1ST FEW CYL OF'
'SCRATCH PACK'
'SPINNING'
B
*
SPIN, GO INTO CP AND SET SUPR MODE
EJECT
*ENTRY TO SAVE OS PROGRAM AFTER IPL ZZZZZZZZ HAS BEEN GIVEN
SPACE
LA
1,=C'READY OOC'
SET UP TO READY C
LA
2,10
DC
X'83120008'
ISSUE DIAG COMMAND FOR READY C
SPACE
SR
15,15
NORMAL RETURN CODE
L
13,4(,13) GET CALLER'S SAVE AREA ADDRESS
RETURN ( 14, 12) , T, RC = (15) EXIT
SPACE
END
After the 'SPINNING' message types, issue the SAVESYS command. Then,
enter CMS and use the DASD Dump Restore program to copy the job queue,
VTOC of scratch disk, and working data set to a master scratch disk.
Part 2: Control Program (CP)
217
Several steps are
system. You must:
also
required to
restart or
activate
a saved
OS
1.
Build an identical configuration.
2.
Use the D1SD Dump Bestore program to copy the master scratch disk
to your working scratch disk. This ensures that the job queue,
VTOe, and working data set are identical to those of the saved OS
system.
3.
Load the job
reader.
4.
IPL the named system. The job run in step 3 of "Saving OS" will
cause an interrupt from the reader and allow OS to process the jobs
placed in the virtual reader without additional user action.
218
stream you
wish to
execute into
IBM VM/370: System Programmer's Guide
the virtual
card
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
VM/VS Handshaking
iM/iS Handshaking is a communication path between the VM/370 Control
Program and a virtual machine operating system (OS/VS1) that makes each
system control program aware of any capabilities or requirements of the
othpT_
VM/V~ H~nn~h~kinn ron~i~+~ OT·
- ------.-,.- -------_._---;] --------- --.
I •
I
Closing CP spool files when VS1
and output writer is completed
I •
Processing VS1 pseudo page faults
I.
I
Providing an optional nonpaging mode for VS1 when it is run under the
control of VM/370
I.
Providing miscellaneous enhancements for VS1 when it is run under the
control of VM/3JO
J
job output from its DSO, terminator,
The handshaking feature improves the operational characteristics of
VS1 with VM/370 and yet allows the same iSi operating system to run
without change in either (1)
a real machine or (2) a virtual machine
under the control of VM/370.
When the VM/VS Handshaking feature is
active, the operation of VSl with VM/370 more closely resembles the
standalone operation of VS1.
lhere is less need for virtual machine
operator intervention because VSl closes its CP spool files so they can
be processed by VM/370 when the job output from the VSl DSO, terminator,
and output writer is complete.
Also, one VSl task can be dispatched
while another is waiting for a page to be brought into real storage if
the pseudo page fault handling portion of handshaking is active.
with
nonpaging mode, duplicate paging can be eliminated.
Although handshaking is a system generation feature for VS1, it is
active only when VS1 is run under the control of VM/370; it is disabled
when that same VS1 operating system is run on a real machine. The VM/VS
Handshaking feature is not active unless:
I •
VSl is generated with the VM/370 option.
I.
I
VSl is run under the control of a version of VM/370 that supports the
feature (VM/370 supports handshaking with Release 2 PLC 13.)
The pseudo page fault portion of the handshaking feature is not active
unless it is set on.
It can be set on, and later set off, with the CP
SET PAGE X command line.
When a VS1 virtual machine with the handshaking feature is loaded,
its initialization routines determine whether the handshaking feature
should be enabled or not.
First, VSl checks to see if it is running
under the control of VM/370 by issuing an STIDP (Store Processor ID)
instruction. STIDP returns a version code; a version code of X'FF'
indicates VSl is running under VM/370.
If VSl finds a version code of
X'FF', it then issues a DIAGNOSE code X'OO' instruction to store the
VM/370 extended-identification code.
If an extended-identification code
is returned to VS1, VSl knows that VM/370 supports handshaking;
if
nothing is returned to VS1, VM/370 does not support handshaking. At
this point in the VS1 initialization process, VM/VS Handshaking support
is available.
If VSl is running in the nonpaging mode and if the
virtual machine operator issues the CP SET PAGEX ON command, full VM/VS
Handshaking support is available.
Pa rt 2: Control Program
(CP)
218.1
GC20~1807~3
Page Modified by TNL GN20-2662, March 31, 1975
When the handshaking feature is active,
VS1 closes the CP spool files
when the job output from the VS1 DSO, terminator, and output writer is
complete.
Once the spool files are closed, they are processed by VM/370
and sent to the real printer or punch.
With the VM/VS Handshaking
feature, virtual machine operator intervention is not required to close
CP spool files.
During its job output termination processing,
VS1 issues DIAGNOSE
code X'OS' instructions to pass the CP CLOSE command to VM/370 for each
CP spool file.
A page fault is a program interrupt that occurs when a page that is
marked "not in storage" is referred to by an instructicn within an
active page.
The virtual machine operating system referring to the page
is placed in a wait state while the page is brought into real storage.
without the handshaking feature,
the entire VS1 virtual machine is
placed in page wait by VM/370 until the needed page is available.
However, with the handshaking
feature, a multiprogramming
(or
multitasking) VS1 virtual machine can dispatch one task while waiting
for a page request to be answered for another task. VM/370 passes a
pseudo page fault (program interrupt X'14') to VS1.
When VS1 recognizes
the pseudo page fault,
it places only the task waiting for the page in
page wait and can dispatch any other VS1 task.
Thus, when VS1 uses
pseudo page faults, its execution under the control of VM/370 more
closely resembles its execution on a real machine.
When a page fault occurs for a VS1 virtual machine, VM/370 checks
that the pseudo page fault portion of handshaking is active and that the
VS1 virtual machine is in EC mode and enabled for I/O interrupts. Then,
VM/370 reflects the page faults to VS1 by:
I.
I
I.
I •
Storing the virtual machine address, that caused the page fault, at
location X'90', the translation exception address
Reflecting a program interrupt (interrupt code X'14') to VS1
Removing the VS1 virtual machine from page and execution wait
When VS1 recognizes program
associated task in wait state.
interrupt code X'14', it places
VS1 can then dispatch other tasks.
the
When the requested page is available in real storage, VM/370 reflects
the same program interrupt to VS1, except that the high order bit in the
translation exception address field is set on to indicate completion.
VS1 removes the task from page wait; the task is then eligible to be
dispatched.
When VS1 is
mode if:
I.
I
I.
run under the control
of VM/370, it executes
in nonpaging
Its virtual address space is equal to the size of the VM/370 virtual
machine
Its virtual machine size is a least one megabyte
21S.2
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
I.
The VM/VS Handshaking feature is available
When VS1 executes
in nonpaging mode, it
uses fewer privileqed
instructions
and
avoids
duplicate
paging.
The
VS1Nucleus
Initialization Program (NIP) fixes all VS1
pages to avoid the duplicate
paging.
Note, that the working set size may be larger for a VS1 virtual
machine in nonpaging mode than for one not in nonpaging mode.
When OS/VS1 is run in the VM/370 environment without the handshaking
feature, some duplication results. VS1 must perform certain functions
when it is run on a real machine; it continu~s to perform all those
functions in a VM/370 virtual machine even though VM/370 also provides
services.
However, with the handshaking feature, VS1 avoids many of the
instructions and procedures that are redundant or less efficient in the
VM/370 environment. For example, VS1 avoids:
I
I
I!
I
•
•
••
ISK (Insert storage Key) instructions and instead uses a key table
Seek separation for 2314 direct access devices
The ENABLE/DISABLE sequence in the VS1 I/O Supervisor (lOS)
T ,n\
TCH
(Test Channel)
instructions
preceding
SIO
(start
.L/ v J
instructions
Part 2: control Program
(CP)
218.3
OS/VS2 Uniprocessor Under VM/370
'M/370 simulates five System/370 instructions required by OS/VS2 Release
2 operating in uniprocessor .ode. These instructions included three
privileged instructions and two nonprivilegEd instructions.
The three
privileged instructions are:
.
CLEAR I/e (CLRIC)
INSERT PSW KEY (IPK)
SET PSW KEY PROft ADDRESS (SPKA)
The two nonprivileged instructions,
system/370 ftodels 135 and 145, are:
which
are
optional
on
the
COMPARE AID SWAP (CS)
COMPARE DOUBLE AND SWAP (CDS)
The compare instructions are executed normally, that is, CP does not
simulate them, when the machine is equipped with the appropriate
hardware feature.
However, V8/370 simulates the compare instructions
(CS and CDS) if OS/VS2 Release 2 is run under the control of V8/370 on a
System/370 machine without these instructions installed.
Part 2: Control Program (CP)
219
DOS Under VM/370
The following guidelines .ay be helpful if you wish to share a saved DOS
system between users. The guidelines that follow ought to he considered
when you are planning to share a DOS system.
If at all possible, generate DOS with a minimum
options that support multiprogramming.
supervisor without the
In general, a DOS system which is to run in a virtual machine should
have as few options as possible.
very often, options that improve
performance on a real machine have no effect (or possibly an adverse
effect)
in a virtual machine. For example, seek separation, which
improves performance on the real machine,
is redundant in a V"/370
virtual machine: CP itself issues a standalone seek for all disk I/O.
If you plan to share the saved DOS system among users, you should
specify Private Core Image Library support.
If you intend to share the DOS system among virtual machines, you must
provide a unique standard label cylinder for each such virtual DOS
user. The individual standard label cylinders are at the end of the
system residence volume (following the normal standard label cylinder).
Some modification to
label cylinders:
DOS is
necessary to
support unique
standard
•
The communication region in each DOS virtual machine must point to
the appropriate label cylinder for each user. The IPL communication
routines can be modified to do this.
•
$JOBCTLA updates the co.munication region pointer to the nor.al
standard label cylinder at the end of each job. This procedure
should be bypassed.
When users share a DOS system, you have several users writing to the
system residence disk since it contains a standard label cylinder for
each user. The system residence volume must be in "write multiple" mode
to support a shared DOS system. Then, each user can write on its own
label cylinder.
Bach user should have his own permanently assigned read/write private
core image library where he can catalog his own programs.
The
relocatable and source statement libraries can be on virtual disks as
well.
220
IB" VM/370: System Programmer's Guide
VM/370 Operating in a Virtual Machine Environment
You can update and test a VM/370 system in a virtual machine. This
procedure allows you to do all the time consuming work in processing for
other users.
After you are through testing, use the DASD Dump Restore (DDR)
....... ::iI::iLt:=w
---- ..... -- to tape.
restore l.ua. l.
program to dump the virtual \"1:'
virtual CP system to the real system disk and you are ready to execute
the new version of VM/370 with a minimum amount of real comFuter time.
I'I"IL _ _
·~Dt=ll,
~L_~
First, there must be a VM/370 directory entry for a VM/370 virtual
machine.
Assume TESTSYS is the userid for this virtual machine.
TESTSYS contains the options RBALTIMER and BCMODl, and would normally be
used to check a new CP nucleus before moving that nucleus to the floor
system.
It contains two MDISKs, 330 and 331. These disks would
normally be mirror images of the real SYSRES and SYSWORK volumes. They
would be formatted and allocated so that the real system could speol and
page on these disks. Any additional disks needed should be linked to
before issuing IPL for the virtual system.
A sample VM/370 directory entry for TESTSYS would be:
USER TESTSYS PASSWORD 512K
ACCOUNT NUMBER BIN11
OPTION BCMODB RBALTI8ER
CONSOLE 01F 3215
SPOOL C 2540 RBADER
SPOOL D 2540 PUNCH
SPOOL B 1403
LINK CMSSYS 190 190 R
MDISK 330 3330 1 15 SYSWRK WR RPASS WPASS
MDISK 331 3330 16 20 SYSWRK WB RPASS WFASS
This user ID has the options and configuration necessary to minimally
define a system that can IPL V8/370 in a virtual machine. The minimum
storage required is 240K, but in a virtual machine environment any
reasonable amount can be defined; in this example 512K is used. A 512K
virtual machine is required to do a virtual VM/370 system load.
The OPTION card specifies ECMODE and REALTIMER, which is required for
the virtual machine to operate in extended control mode.
The console
and spool device addresses must match the same addresses as the real
machine configuration, or if that is not used for the virtual system
operation, they must match whatever configuration is specified in the
DMKRIO module.
The LINK card is specified so that this virtual machine may operate
CMS, although special considerations have to be used for this function.
The minidisk cards for 330 and 331 define disks that are used for CP
system residence, paging, and spooling. Note that in this configuration
no other user disks are defined, nor are there any definitions for
teleprocessing lines or tape drives.
All additional devices required for testing in a virtual machine
environment can be specified in the virtual machine by the proper use of
the ATTACH, LINK, and DEFIlE commands.
Part 2: Control Program (CP)
221
If the virtual machine that can run CP is also going to be used to run
CMS, the configuration may be modified, once logged on.
The spooling
unit record equipment must have addresses that are recognized by CMS.
A LINK card can be specified for the CMS system residence or a link
can be made to the C8S system residence disk, and a link can also be
made if passwords are provided to other user's disks so that they can be
used as primary disks by the C8S system. It is possible, for instance,
under this one ID that can run V8/370 in a virtual machine, to link to
all the disks necessary to do a virtual system VMFLOAD or any other
similar function.
The V8/370 nucleus to be run in a virtual machine must be loaded onto
the corresponding minidisk that represents the virtual system residence
volume. Once this has been done, before IPL, the configuration of the
virtual machine should be carefully set up and verified. This involves
setting the console to the correct address, making sure that sufficient
unit record equipment is available at the proper addresses and attaching
or linking to enough disks so that a reasonable test can be made.
In setting up the virtual machine configuration, links can be made to
other user disks so that the V8/370 system can use these disks in its
virtual operation.
Be careful to ensure that links to other disks are
made with the correct addresses.
For instance, if the VM/370 system has 2314s defined as 130 to 137,
then links to user disks that are 2314s must be in this range. 3330 or
3340 links should be in the range of 330 to 337, for example, or
whatever is required to match the real machine configuration to
3330/3340 addresses. If a user disk is linked to as a 2314 address when
it is actually a 3330 or 3340 device, errors will be encountered when
trying to process that user disk.
It is probably not necessary to have a 2305 paging device in the
configuration unless the test specifically addresses that area.
If this
is required, and if the real configuration allows it, the user may
define temporary 2305 space fer a paging volume. Depending upon the
nature of virtual machine testing, one or more teleprocessing lines can
be defined so that users may DIAL into the VM/370 system in a virtual
machine.
In most cases, simple tests do not require teleprocessing
lines to be defined or enabled at the virtual machine level.
Most
testing can be performed by the operator's virtual machine from the
virtual console.
Before any of the CP disks can be used in a virtual machine environment,
they must be properly formatted and set up. This includes formatting
and allocating the disks, and creating a virtual directory and a virtual
nucleus. The virtual disks to be used for virtual system residence,
paging, and spooling must be formatted using the CP FORMAT program.
This program can be run in a virtual machine environment, but does not
operate under CMS.
To run the FORMAT program, make it available in the virtual machine's
spool card reader and IPL it from that reader.
Remember that it is a
virtual disk that is being formatted,
and hence the specification for
the number of cylinders should reflect the size of the virtual disk that
is being used.
222
IBM VM/370: System Programmer's Guide
In the sample directory for TESTSYS, virtual device 330 is only 15
cylinders; thus only 15 cylinders can be formatted.
The label written
on the virtual disk should match the label in the installation-owned
list if you are going to use the same DMKSYS module that the
installation is using. In other words, if your installation has two
volumes in the owned list (for instance, CPDSK1 and CPDSK3), then those
must be the labels that are placed on the minidisks that are going to be
used in a virtual machine.
Once the volumes are formatted, you must also allocate space on these
volumes. Space must be allocated to hold a virtual directory, to allow
for nucleus cylinders, warm start and error recording cylinders, and
temporary space for paging and spooling.
All space that is not
accessible to the virtual CP system because it is beyond the bounds of
the virtual disk must be assi.gned as permanent space or else the virtual
system attempts to access temporary space beyond the size of the virtual
disk and the real CP system reflects seek checks back to the virtual
system. The installation's allocation for permanent space to hold the
directory, CP nucleus, error recording area, and warm start cylinder
should be organized so that all these cylinders are in the first
available cylinders on the disk.
If the real installation system
residence volume is organized in this fashion, then the same DMKSYS and
DMKRIO modules can be used in a virtual machine configuration.
If, for example, the real configuration specifies that one of the
areas is beyond the range accessible by the virtual disk, then a special
DMKSYS module has to be generated. It is preferable that the same
installation modules are used when operating in a virtual machine
environment in order to ensure that the testing environment matches the
one to be used in the real machine configuration. The only exception to
this rule is the directory that appears on the virtual disk.
The
directory on the virtual disk cannot be the same as the real system
directory because none of the labels nor displacements for the user
disks match.
A special directory must be created to handle the virtual Vft/370
environment. The virtual directory need only specify a m1n1mum number
of users, sufficient to perform testing.
It is usually beneficial to
define an operator's virtual machine that is large enough and varied
enough to perform all necessary functions. This will allow most virtual
testing from one userid without requiring several userids to dial into
this system to accomplish a test.
The virtual directory that is to be placed on the virtual system
residence volume can be created by running CMS in the same virtual
machine. This is accomplished by setting up a CMS fil~ on one of the
virtual disks to which the user linked with the desired filename and the
filetype of DIRECT.
This file contains sufficient entries for testing
in the virtual machine environment. The DIRECT program that is invoked
under CMS will use this file to create the virtual system's directory.
Once you have verified (by using a QUERY VIRTUAL command) that the
virtual machine configuration matches the one that you wish to test, you
can perform a virtual IPL of the virtual disk containing the CP nucleus.
In this example it is disk 330. Remember that a terminal is handled
like a simulated virtual console. In this example a 2741 terminal is
used.
Each exclamation point (!) appearing in the sample terminal
output indicates the Attention key has been pressed.
The operation of
the Attention (ATTN) key on the terminal remains the same as it weuld
Part 2: Control Program (CP)
223
have been if running any other system, but the operation of the virtual
console is as though the device were an online console (3215) and not a
2741.
!gte: Attention handling varies with the type of terminal used. See
the !~Lll~: l~!~in~l ~§~!~§ Qyjg~ for a description of the terminals
supported by V"/370.
Proceed through the virtual machine IPL in the normal fashion,
responding where required.
You are not able to set the time-of-day
clock, so always reply "n6" to the change time-of-day-clock question.
Under most circumstances, it is advisable to perform a cold start unless
some specific function requiring a warm start is to be tested. Once the
IPL is successfully completed, one of the first things you should do is
specify that the dump go to the virtual printer.
It is sometimes
difficult to obtain a listing of a virtual machine dump once it has been
placed on the virtual spool disk.
In this example, SET DU"P OOE causes virtual machine dumps to go to
the CP spool printer.
This, of course, will be much faster than if on
the real machine they went to an online printer. Once you IPL the
virtual machine and logon the operator's virtual machine, you are free
to operate virtual operating systems under this userid or to enable any
virtual teleprocessing lines so that other users may dial into this
system, log on to V6/370 in a virtual machine, and perform whatever
actions they require.
ACCESSING DEVICES
Rote that once you IPL the virtual machine, the devices that were not
accessible to that machine at IPL time are considered offline.
It is
possible to attach more devices to this machine and have them placed
online, if required.
For instance, tape drives can be attached by the
real machine operator to the virtual machine configuration at the
required address that matches the configuration of the virtual CP
system. The same procedure can be used for teleprocessing lines, unit
record equipment, or other devices.
Remember that teleprocessing lines
(virtual 2701/2702/2703 for DIAL)
and spool unit record devices can be created using DEFINE. Before these
can be attached by the virtual CP operator to a virtual machine user in
that environment, they aust first be placed online at the virtual
machine level. Once they have been placed online they can be attached
and used by virtual machines in the virtual CP system.
Note also that
in the virtual machine environment there are two ways of displaying and
storing into real storage.
The user can use the virtual CP system and
perform DCP and STCP co.mands or, as a much faster approach, he can use
the real CP system and use the functions of display and store.
Remember
that display and store are operating on virtual storage, which is in
reality the real storage of the virtual CP system. Operating DCP and
STep at the virtual level appear to that machine to be operating on real
storage, when in fact it is virtual storage managed by the real CP
system. The virtual machine operating in the virtual CP system can, of
course, do its own display and store function, which displays and stores
into the third level virtual storage.
As was mentioned before, most testing can be accomplished if you IPL
and run tests from the operator's virtual machine without enabling any
virtual teleprocessing lines.
Note also that teleprocessing lines, if
required, can be attached directly to the virtual CP system for testing
in that environ.ent without using DIAL. Remember that disks that were
linked to before this system IPL appear to the virtual system as disks
224
IBM VM/370: Systea Programmer's Guide
with a zero cylinder relocation factor; therefore,
them via C~S in the operator's virtual machine, you
the virtual CP level to the operator so that he
though they were dedicated disks. In reality.they
but yeu will not normally access beyond your disk.
CP system will present I/O errors in the form of
virtual CP system, which will, in turn, reflect them
operating system.
in order to access
must attach them at
may access them as
are virtual disks,
If you do, the real
seek checks to the
back to the virtual
It is possible to use virtual disks in the virtual CP system; however,
their setup is complex and requires careful consideration to coordinate
it with the real directory of the real system. If the real directory of
the real system is changed, and a virtual disk is moved and the virtual
directory is not changed, serious operating errors can occur; therefore,
this practice is not advised unless a specific test of that function is
required.
SPOOLING CONSIDERATIONS
If the virtual machine performs any spooling operations, recognize that
the virtual CP system is also doing spooling operations unless it has
dedicated unit record equipment. This double spooling operation is not
a problem; however, certain operational peculiarities exist.
Por
instance, when the virtual system specifies that a printer is producing
output, the output is in fact being spooled. The user cannot easily
determine when this spooling operation is complete. One way 1S to
specify a DRAIN on the particular output device, and when the virtual CP
system reports that the device is drained, the output has indeed
stopped.
It is now necessary to specify a CLOSE for that device to the real CP
system to See the real spooled ou~put. also be aware that double
separators will occur.
Por instance, the separator page on virtual
printed output will include one page for the virtual CP system, and
another page for the separator of the virtual machine the virtual CP
system is running. The operation of virtual machines at this level is,
to say the leas~, complex. There is no easy way of describing how to do
all the functions.
It requires careful study and analysis, and at all
times an awareness of what level of virtual machine is operating, and
what function you are trying to perform. If you keep all these things
straight you will have no problem testing and operating virtual .achines
and systems themselves operating in a virtual machine environment.
The following sample terminal session is taken directly from a system
that was used to run a virtual CP system in a virtual machine
environment, and is annotated to point out some of the considerations
that have been previously outlined.
Part 2: Control Program (CP)
225
vm/370 online
Ijh359
<---- 8 bytes
MM/DD/II
>
MM/DD/II
HH:MM:SS
HH:MM:SS
or
VIRTCPU
TOTCPU
VIRTCPU
TOTCPU
Figure 29.
Formats of Pseudo Timer Information
Part 2: Control Program (CP)
237
The first eight-byte field is the date, in EBCDIC, in the fora
Month/Day-of-Month/Year. The next eight-byte field is the Time of Day
in Hours:"inutes:Seconds. The VIRTCPU and TOT CPU fields contain virtual
CPU and total CPU time used.
The units in which the CPU ti.es are
expressed and the length of the fields depend upon which of two methods
is used for interrogating the pseudo timer.
PSEUDO TIMER START I/O
The pseudo timer can be interrogated by issuing a START I/O to the
pseudo timer device, which is device type TIMER, and is usually at
device address OFF. No I/O interrupt is returned from the SIO. The
address in virtual storage where the timer information is to be placed
is specified in the data address portion of the CCW associated with the
SIO. This address must not cross a page boundary in the user's address
space.
If this method is used, the virtual CPU and the total CPU times
are expressed as fu11words in high resolution interval timer units. One
unit is 13 microseconds.
PSEUDO TI"ER DIAGNOSE
The pseudo timer can
operation code of C,
Virtual Machine."
If
times are expressed as
238
also be interrogated by issuing DIAGNOSE with an
as described under "DIAGNOSE Instruction in a
this method is used,
the virtual and total CPU
doub1ewords in microseconds.
IBM VM/370: system Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
DIAGNOSE Instruction in a Virtual Machine
The DIAGNOSE instruction cannot· be used in a virtual machine for its
normal function.
If a virtual machine attempts to execute a DIAGNOSE
instruction, a program interrupt returns control to CP.
Since a
DIAGNOSE instruction issued in a virtual machine results only ,n
returning control to CP, and
not in performing normal DIAGNOSE
functions, the instruction is used for communication between a virtual
machine and CP. The machine language format of DIAGNOSE is:
<------------r------I
83
4 bytes
I R1 I R2 I
------->
CODE
(There is no Assembler language mnemonic for X'83')
The operand storage addresses, passed to the DIAGNOSE interface in Rl
and R2, must be real addresses to the virtual machine issuing the
DIAGNOSE.
The Code is a two-byte hexadecimal value that CP uses to determine
what function to perform. The codes defined for the general VMj370 user
are described in this section. The code must be a multiple of 4.
Codes
X'OO' through X'FC' are reserved for IBM use, and codes X'100' through
X'lFC' are reserved for users.
Because DIAGNOSE operates differently in a virtual machine than in a
real machine, a program should determine that it is operating in a
virtual machine before 1ssu1ng a DIAGNOSE, and prevent execution of a
DIAGNOSE when in a real machine. The Store CPU ID (STIDP) instruction
provides a program with information about the CPU in which it is
executing, including the CPU version number.
If STIDP is issued from a
virtual machine the version number will be 'FF', in the first byte of
the CPUID field.
A virtual machine issuing a Diagnose instruction should run with
interrupts disabled.
This prevents
loss of
status information
pertaining to the Diagnose operation such as condition codes and sense
data.
Execution of DIAGNOSE code 0 allows a virtual machine to examine the
VMj370 extended-identification code.
For example, an OS/VSl virtual
machine issues a DIAGNOSE code 0 instruction to determine if the version
of VMj370 it is running with supports the VMjVS Handshaking feature. If
the extended-identification code is returned to VS1, VMj370 supports
handshaking; otherwise, it does not.
The register specified as Rl contains the doubleword aligned virtual
storage address where the VMj370 extended-identification cede is to be
stored. The R2 register contains the number of bytes to be stored.
If the VMj370 system currently running does not support the DIAGNOSE
code 0 instruction, no data is returned to the virtual machine. If it
does support the DIAGNOSE code 0 instruction, the following data is
returned to the virtual machine (at the location specified by Rl) :
Part 2: Control Program (CP)
239
GC20-1807-3 Page Modified by TNL GN20-2662, Harch 31, 1975
System
Name
"VH/370"
8 bytes, EBCDIC
version
Humber
The first byte is the
version number, the second
byte is the level, and the
third byte is the PLC (Program Level Change) number.
3 bytes, hexadecimal
Version
Code
VH/370 executes the STIDP
(Store CPU ID) instruction
to determine the version
code.
1 byte, hexadecimal
HCEL
VH/370 executes the STIDP
instruction to determine
the maximum length of the
HCEL (Machine Check Extended
Logout) area.
2 bytes, hexadecimal
Processor
Address
VM/370 executes the STAP
(store CPU Address) instruction
to determine the processor
address.
2 bytes, hexadecimal
Userid
The userid of the virtual
machine issuing the DIAGNOSE.
8 bytes, EBCDIC
If VH/370 is executing in a virtual machine, another 24 bytes, or less,
of extended identification data is appended to the first 24 bytes
described above.
Up to five nested levels of VH/370 virtual machines
are supported by this Diagnose instruction resulting in a maximum of 120
bytes of data that can be returned to the virtual machine that initially
issued the Diagnose instruction.
Upon return, R2 contains its original
that were stored.
No completion
unchanged.
code is
returned,
and
value less the number of bytes
the condition
code
remains
Execution of a DIAGNOSE Code 4 allows a user with command privilege
class C or E to examine real storage.
The register specified as R1
contains the virtual address of a list of CP
(real) addresses to be
exaained. The R2 register, which cannot be register 15, contains the
count of entries in the list.
R2+1 contains the virtual address of the
result field.
The result field contains the values retrieved from the
specified real locations.
The execution of DIAGHOSE with code 8 allows a program executing in
supervisor mode in a virtual machine to perform a CP command.
The
register specified as R1 contains the address, in virtual storage, of
the data area defining the CP command and parameters.
The R2 register
240
IBH VH/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
contains the length of the associated command input, which may be up to
132 characters. The following example illustrates how DIAGNOSE Code 8
would be issued to perform the CP command, QUERY, to determine the
number of input and output spool files:
LA
LA
DC
CMMD
CMMDL
6,CMMD
10,CMMDL
X'83',X'6A' ,XL2'0008'
DC
EQU
C'QUERY FILES'
*-CMMD
The output of the command is at the user's terminal.
A completion
code is returned to the user as a value in the register specified as R2.
In the example above it would be register 10. A comFletion code of 0
signifies normal completion. If there is an error, the completion code
is the binary value of the numeric portion of the error message. For
instance, the error message
DMKCFM045E userid NOT LOGGED ON
returns '045'
unchanged.
in
the
R2
register.
The
condition
code
remains
Execution of DIAGNOSE with Code C causes CP to store four doublewords of
time information in the user's virtual storage. The register specified
as R1 contains the address of the 32 byte area where the time
information is to be stored. The address must be a doubleword boundary.
The information returned is as shown in Figure 29.
The first eight bytes contain the Month/Day-of-Month/Year. The next
eight bytes contain the time of day in Hours:Minutes:Seconds. The last
16 bytes contain the virtual and total CPU time usea Dy the virtual
machine that issued the DIAGNOSE.
These times are expressed as
doubleword, unsigned integers, in microseconds. No completion code is
returned, and the condition code remains unchanged.
Pages of virtual storage can be released by issuing a DIAGNOSE with Code
10. When a page is released it is considered all zero.
The register
specified by R1 contains the address of the first page to be released,
and the R2 register contains the address of the last page to be
released.
Both addresses must be page boundaries.
A page boundary is a
storage address whose low order three digits, expressed in hexadecimal,
are zero. No completion code is returned, and the condition code
remains unchanged.
Part 2: Control Program
(CP)
240.1
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Execution of DIAGNOSE Code 14 causes DMKDRDER to perform input spool
file manipulation.
Depending on the value of the function subcode,
the
register specified as R1 contains a buffer address, a copy count, or a
240.2
IBM VM/370: System Programmer's Guide
spool file identifier. The R2 register, which cannot be register 15,
contains either the virtual address of a spool input card reader or, if
R2+1 contains X'OFFF', a spool file ID number.
R2+1 contains a
hexadecimal code indicating the file manipulation to be performed. The
codes are:
,g.Qg~
1.Y!!£!!2!!
Read next spool buffer (data record)
Read next print spool file block (SPBLOK)
Read next punch spool file block (SFBLOK)
Select a file for processing
Repeat active file ~~ times
Restart active file at beginning
Backspace one record
Retrieve subseOquent file descriptor
0000
0004
0008
OOOC
0010
0014
0018
OFFF
On return R2+1 may contain
returned condition code of 3.
Condition
Code
--'0---1
2
3
3
3
3
4
8
12
16
error
codes
which further
define
a
Error
Data-transfer successful
End of file
Pile not found
Device address invalid
Device type invalid
Device busy
Patal paging I/O error
Input/output operations to a direct access device of the type used by
CftS, can be performed from a virtual machine using DIAGNOSE with Code
18. No I/O, interrupts are returned by CP to the virtual machine; the
DIAGNOSE instruction is complete only when the Read or Write commands
associated with the DIAGNOSE are completed. The R1 register contains
the virtual device address of the direct access device. The R2 register
contains the address of a chain of CCWs. The CCW chain must be in a
standard format that CP expects when DIAGNOSE Code 18 is used, as shown
below. Register 15 must be loaded by the user with the number of reads
or writes in the CCW chain.
A typical
follows:
CCW string
to read or
write two
800-byte records
is as
SEEK,A,CC,6
SET SECTOR (needed only for 3330)
SRCB,A+2,CC,5
TIC,*-8,0,0
RD or WRT,DATA,CC+SILI,800
SEEK BEAD,B,CC,6 (omitted if BEAD number unchanged)
SET SECTOR (needed only for 3330)
SRCB,B+2,CC,5
TIC,*-8,0,0
RD or WRT,DATA+800,SILI,800
A
B
SEEK and SRCB arguments for first RD/WRT
SEEK and SRCH arguments for second RD/WRT
Part 2: Control Program (CP)
241
The Condition Codes and Completion Codes returned are as follows:
cc=O I/O complete with no errors
cc=1 Error condition. Register 15 contains one of
the following:
R15=1 Device not attached
R15=2 Device not 2319, 2314, or 3330
R15=3 Atteapt to write on a Read-only disk
R15=4 Cylinder number not in range of user's disk
R15=5 Virtual device is busy or has an interrupt pending
cc=2 Error condition. Register 15 contains one of
the following:
R15=5 Pointer to CCW string not doubleword aligned.
R15=6 SEEK/SEARCH arguments not within range of
user's storage
R15=7 READ/WRITE CCW is neither Read (06) nor Write (05)
R15=8 READ/WRITE Byte Count=O
R15=9 READ/WRITE Eyte Count greater than 2048
R15=10 READ/WRITE buffer not within user's storage
R15=11 The value in R15, at entry, was not a positive
number from 1 through 15; or, was not large
enough for the given CCW string.
R15=12 Cylinder number on seek head was not the same
number as on the first seek.
cc=3 Uncorrectable I/O error:
R15=13
CSW (8 bytes) returned to user
Sense bytes are available if user issues a SENSE command
Execution of DIAGNOSE Code 1C allows a user with privilege class F to
clear the I/C error recording data on disk.
The D~KIOEF~ routine
performs the clear operation. The register specified as R1 contains a
code value:
Function
Clear-and reformat all I/O error recording
Clear and reformat all machine check error recording
Clear and reformat all error recording (I/O and machine
check)
with DIAGNOSE Code 20, a virtual machine user can specify any valid CCW
chain to be performed on a tape or disk device.
No I/O interrupts are
reflected to the virtual machine; the DIAGNOSE instruction is complete
only when all I/O commands in the specified CCW chain are finished. The
register specified as R1 contains the virtual device address.
The R2
register contains the address of the CCW chain.
The eei string is processed V1a
full virtual I/O in a synchronous
are not permitted, however) to any
returns to the virtual machine only
242
IB~
D5KCCWTR through DMKGIOEX, providing
fashion (self-modifying CCW strings
virtual machine specified. Control
after completion of the operation or
VM/370: System Programmer's Guide
detection of a fatal error condition. EREP support is provided for tape
and DASD devices only; all other devices will present an error condition
in the PSW to the virtual user. Condition codes and error codes are
returned to the virtual system.
The Condition Codes and Completion Codes returned are as follows:
cc=O I/O complete with no errors
cc=l Error condition. Register 15 contains the following:.
R15=1 Device is either not attached or the virtual channel is
dedicated.
R15=5 Virtual device is busy or has an interrupt pending.
cc=2 Exception conditions. Register 15 contains one of the
following:
R15=2 unit Exception bit in device status byte=1
R15=3 Wrong Length Record detected.
cc=3 Error Condition:
R15=13 A permanent I/O error occurred or an unsupported
device was specified. The two low-order positions
of the user's R2 register contain the first two sense bytes.
CP maintains control blocks describing each virtual device and each real
device. DIAGNOSE Code 24 causes CP to return to the virtual machine
certain information from the virtual device block (VDEVBLOK) and the
real device block (RDEVBLOK) associated with a given virtual device
address. The R1 register from the caller contains a virtual device
address or a value of -1, indicating that the device is a virtual
console and its address is not known.
If the console is found, control
returns to the caller with the virtual device address in the low order 2
bytes of the R1 register.
The R2 register and the R2+1 register, on
return, contain the following one-byte fields:
R2
VDEVTiPe
VDEVTYPE
VDEVSTAT
VDEVFLAG
R2+1
RDEVT;YPC
RDEVTYPE
RDEVMDL
RDEVFTR
- or RDEVLLEN
The meanings of these fields are as follows:
R2
~~g!§!~!
VDEVTYPC
VDEVTYPE
VDEVSTAT
VDEVFLAG
Virtual Device Information
iirtuiI-devIce-type-clissVirtual device type
virtual device status
virtual device flags
R2+1
!~gi2!~I
RDEVTYPC
RDEVTYPE
RDEVMDL
RDEVFTR
RDEVLLEN
Real Device Information
ReiI-devlce-type-class-
Real device type
Real device model number
Real device feature code, for a device other than a
virtual console
Current device line length, for a virtual console
Part 2: Control Program (CP)
243
Note: If B2 is register 15,
returned to the caller.
only the virtual device
information is
A condition code of 3 indicates that the virtual device address
specified was invalid, or that the virtual device does not exist. A
condition code of 2 indicates the virtual device exists, but there is no
real device associated with it, and therefore no real device information
was provided. Spooling devices and Pseudo Timers are examples of such
devices.
A condition code of 0 indicates normal completion.
DIAGNOSE Code 28 allows a virtual machine to correctly execute some
channel programs modified after the Start I/O
(SIO) instruction is
issued and before the input/output operation is completed. The channel
command word (CCi) modifications allowed are:
•
A Transfer in Channel (TIC) CCi modified to a No Operation (NOP) CCi
•
1 TIC CCi modified to point to a new list of CCis
•
A NOP modified to a TIC CCi
ihen a virtual machine modifies a TIC CCi, it is modifying a virtual
channel program. CP has already translated that channel program and is
waiting to execute the real CCis. The DIAGNOSE instructicn, with Code
28, must be issued to inform CP of the change in the virtual channel
program, so CP can make the corresponding change to the real CCV before
it is executed. In addition, when a NOP CCW is modified to point to a
new list of CCis, CP translates the new CCWs.
To be sure that the DIAGNOSE instruction is recognized in time to
update the real CCW chain, the virtual machine issuing the DIAGNOSE
instruction should have a high favored execution value and a low
dispatching priority value. The CP SET command should be issued:
SET FAVORED xx
SET PRIOBITY nn
where xx has a high numeric value and nn has a low numeric value. The
virtual machine issuing the DIAGNOSE Code 28 must be in the supervisor
mode at the time it issues the DIAGNOSE instruction.
When DIAGNOSE Code 28 is issued, the R1 register contains the address
of the TIC or NOP CCW that was modified by the virtual machine. The B2
register contains the device address in bits 16 through 31.
Rl and R2
cannot be the same register. The addresses specified in the Rl
register, the new address in the modified TIC CCV, and the new CCV list
that the modified TIC CCi points to must all be addresses that appear
real to the virtual machine: CP knows these addresses are virtual, but
the virtual machine thinks they are real.
The condition codes (cc) and completion codes are as follows:
cc=O The real channel program was successfully
15 contains a zero.
modified; register
cc=l There was
probably an error
in issuing
the DIAGNOSE
instruction.
Register 15 (R15) contains one of the following
completion codes:
R15=1 The same register was specified for Bl and R2.
244
IBK VK/370: System Program.er's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
R15=2 The device specified by the R2 register was not found.
R15=3 The address specified by the Rl register was not within
the user's storage space.
R15=4 The address specified by the Rl register was not
doubleword aligned.
R15=5 A CCW string corresponding to the device
(R2)
and
address (Rl) specified was not found.
R15=6 The CCW at the address specified by the R1 register is
not a TIC or a NOP, or the CCW in the channel program is
not a TIC or a NOP.
R15=7 The new address in the modified TIC CCW is not within
the user's storage space.
R15=8 The new address in the
modified TIC CCW is not
doubleword aligned.
cc=2 The real channel program cannot
be modified because a channel
end or device end already occurred.
Register 15 contains a 9.
The virtual machine should restart the modified channel
program.
Execution of DIAGNOSE Code 2C allows a user with privileqe class C, E,
or F to find the location on disk of the error-recording area. The
register specified as Rl, on return contains the DASD location (in
VM/370 control program internal format)
of the first record of the
system I/O and machine check error recording area.
Execution of DIAGNOSE Code 30 allows a user with privilege class C, E,
or F to read one page of the system error recording area. The register
specified as Rl contains the DASD location (in VM/370 control program
internal format)
of the desired record.
The R2 register contains the
virtual address of a page-size buffer to receive the data. The DMKRPAGT
routine supplies the page of data.
The condition codes returned are:
Condition
__
fQg~
o
1
2
__ _
~~~~i~g
Successful read, data available
End of cylinder, no data
Invalid cylinder, outside recording area
A user with privilege class C or E can read the system spool file by
issuing a DIAGNOSE Code 34 instruction.
The register specified as Rl
contains the virtual address of a page-size buffer to receive the data.
The R2 register, which cannot be register 15, contains the virtual
address of the spool input card reader.
R2+1, on return, may contain
error codes:
Part 2: Control Program
(CP)
245
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Condition
__ fQgg __ _
o
R2+1
~££Q£_fQQg
1
2
3
4
3
3
3
8
12
16
~~!~!~g
Data transfer successful
End of file
File not found
Device address invalid
Device type invalid
Device busy
Fatal paging I/O error
The DMKDRDMP routine searches the system chain of spool input files
for the dump
file belonging to the user
issuing the DIAGNOSE
instruction.
The first (or next) record from the dump file is provided
to the virtual machine via DMKRPAGT and the condition code is set to
zero. The dump file is closed via VM/370 console function CLOSE.
Execution of DIAGNOSE Code 38 causes the routine DMKDRDSY to read the
system table into storage. The register specified as Rl contains the
address of the page buffer to contain the symbol table.
Execution of DIAGNOSE Code 3C allows a user to dynamically update the
VM/370 directory.
The register specified as Rl contains the first 4
bytes of the volume serial label. The first two bytes of R2 contain the
last 2 bytes of the volume serial label.
The routine DMKUDRDS
dynamically updates the directory.
This code can be issued only by a user with the account option (ACCT)
his directory.
in
Rl contains the virtual address of either a 24-byte parameter list
identifying the "charge to" user, or a variable length data area that is
to be punched into the accounting card. The interpretation of the
address is based on a hexadecimal code supplied in R2.
If the virtual
address represents a parameter list, it must be doubleword aligned; if
it represents a data area, the area must not cross a page boundary. If
Rl is interpreted as pointing to a parameter list and the value in Rl is
zeroes, the accounting card is punched with the identification of the
user issuing the DIAGNOSE instruction.
R2 contains a hexadecimal code interpreted by DMKHVC as follows:
Code
0000
0004
0008
OOOC
0010
!Qi~:
246
Rl ~g!~!§ !g:
a parameter list containing only a userid.
a parameter list containing a userid and account number.
a parameter list containing a userid and distribution
number.
a parameter list containing a userid, account number, and
distribution number.
a data area containing up to 70 bytes of user information to
be transferred to the accounting card slarting in column
9.
If R2 contains X'0010', R2 cannot be register 15.
IBM VM/370: System Programmer's Guide
March
GC20-1807-3 Page Modified by TNt
1975
R2+1 contains the length of the data area pointed to by Rl.
If Rl
points to a parameter list (R2 not equal to X'0010'), R2+1 is ignored.
DMKHVC checks the VMACCOUN flag in VMPSTAT to verify that the user
has the account option and if not, returns control to the user with a
condition code of one.
If R2 contains
checks:
a code
of
X'0010', DMKHVC
performs the
following
I.
I
If the address specified in R1 is negative or greater than the size
of the user's virtual storage, an addressing exception is generated.
I.
I
I
If the combination of the address in Rl
and the length in R2+1
indicates that the data area crosses a page boundary, a specification
exception is generated.
I.
I
If the value in R2+1 is zero,
negative
specification exception is generated.
or
greater than
70,
a
If both the virtual address and the length are valid, DMFREE is
called to obtain storage for an account buffer (ACNTBLOK) which is then
initialized to blanks. The userid of the user issuing the DIAGNOSE
instruction is placed in columns 1 through 8 and an accounting card
identification code of "CO" is placed in columns 79 and 80.
The user
data pointed to by the address in Rl is moved to the accounting card
starting at column 9 for a length equal to the value in R2+1. A call to
DMKACOQU queues the ACNTBLOK for real output.
If a real punch is
available, DMKACOPU is called to punch the card;
otherwise, the buffer
is stored in main storage until a
punch is free.
DMKHVC then returns
control to the user with a condition code of zero.
If R2 contains other than a X'0010' code, control is passed to DMKCPV
to generate the card.
DMKCPV passes control to DMKACO to complete the
"charge to" information;
either from the User
Accounting Block
(ACCTBLOK), if a pointer to it exists, or from the user's VMBLOK.
DMKCPV then punches the card and passes control back to DMKHVC to
release the storage for the ACCTBLOK, if one exists. DMKHVC then checks
the parameter list address for the following conditions:
I.
I
If zero,
zero.
I.
If invalid, an addressing exception is generated.
I.
I
If not aligned on a doubleword boundary, a specification exception is
generated.
control is returned
to the user
with a condition
code of
For a parameter list address that is non-zero and valid, the userid
in the parameter list is checked against the directory list and if not
found, control is returned to the user with a condition code of two. If
the function hexadecimal code is invalid, control is returned to the
user with a condition code of three.
If toth userid and function
hexadecimal code are valid, the User Accounting Block (ACCTBLOK)
is
built and the userid, account number,
and distribution number are moved
to the block from the parameter list or the User Machine Block belonging
to the userid in the parameter list.
Control is then passed to the user
with a condition code of zero.
Part 2: Control Program (CP)
246.1
(Privilege Class A, B, or C Only) DIAGNOSE Code 50 invokes the CP module
DeKSNC (1) to validate the parameter list and (2) write the page~format
image of the 3704/3705 control program to the appropriate system
volume.
When a 3704/3705 control program load module is created, the CMS
service program SAVENCP builds a communications controller list (CCPARM)
of control information. It passes this information to CP via a DIAGNOSE
Code X'0050'.
The register specified as R1 contains the virtual address of
parameter list (CCPARM). The R2 register is ignored on entry.
the
upon return, the R2 register contains the following error codes:
£~~~
044
171
178
179
435
]~~ni~g
'ncpname' was not found in system name table.
system volume specified not currently available.
Insufficient space reserved for program and system control
information.
System volume specified is not a Cp-owned volume.
Paging error while writing saved system.
Execution of DIAGNOSE Code 58 allows a virtual machine to display large
amounts of data on a 3270 in a very rapid fashion.
The interface can
display the entire 3270 screen with one write operation instead of 22
writes (one for each line in the output area of a 3270 screen).
The register specified as R1 contains the address of the console CCW
string. The R2 register contains (in bits 16-31) the device address of
the virtual console.
The format of the special display CCi is!
CCW
1'19' ,dataddr,flags,ctl,count
dataddr
is the beginning address of the data to be displayed.
flags
is the standard CCW flag field.
ctl
is a control byte that indicates the starting output display
line. If the high-order bit is on, the entire 3270 output
display area is erased before the new data is displayed. A
value of X'FF' clears the screen, but writes nothing.
count
is the number of bytes to be displayed.
bytes is 1760.
The maximum number of
When the DIAGNOSE is executed with a valid CCW string, a buffer
(whose length is the number of bytes specified by fQYn!) is built in
free storage. The data pointed to by g~!~~~! is loaded into the buffer.
Data chaining may be specified in the CCW to link noncontiguous data
areas; however, command chaining is an end of data indication for the
current buffer.
Part 2: Control Program (CP)
247
Using the starting output line (ctl) and the number of bytes of
output (count), CP checks that the data will fit on the screen. CP then
does the display. A zero condition code indicates the I/O operation
completed successfully; a nonzero condition code indicates an I/O error
occurred.
Execution of DIAGNOSE Code SC causes the editing of an
according to the user's setting of the EMSG function:
E!
contains the address of the message to te edited.
EI
contains the length of the message to be edited.
DMKHVC tests the VMMlEVEl field of the
with !! and El modified as follows:
VMBlOK and returns to the caller
Registers on Return
VMMlEVEl
VMMCODE
error message
V""TEXT
~.!
E.I
ON
ON
no change
01
OFF
no change
10 (length of
code)
OFF
ON
pointer to text
part of message
length of text
alone
OFF
OFF
N/A
no change
0
DIAGNOSE Code X'SC' does not write the message; it merely
rearranges the starting pointer and length. For CMS error aessages, a
console write is performed following the DIAGNOSE unless E.I is returned
with a value of O.
!Qi~:
248
IB" VM/370: System Programmer's Guide
CP Conventions
The following are coding conventions
used by CP modules.
This
information should prove helpful if you debug~ modify~ or update CP~
1.
FORMAT:
~Ql!!!!!
~Q!!!~'!!!§
1
10
16
31, 36, 41, etc.
2.
Labels.
Op Code
Operands
Comments (see Item 2)
COMMENT:
Approximately 75 percent of the source code contains comments.
sections of code performing distinct functions are separated from
each other by a co •• ent section.
3.
CONSTANTS:
Constants follow the executable code and precede the copy files
and/or macros that contain CSECTs or system equates. Constants are
defined in a section followed by a section containing initialized
working storage, followed by working storage.
Each of these
sections is identified by a com.ent.
Wherever possible for a
module that is greater than a page, constants and working storage
are within the same page in which they are referenced.
4.
No program modifies its own instructions during execution.
5.
No program uses its own unlabeled instructions as data.
6.
REGISTER USAGE:
For CP, in general
!t~gist~~
6
7
8
10
11
12
13
14
15
Us~
RCBBLOK, VCBBLOK
RCUBLOK, VCUBLOK
RDEVBLOK, VDEVBLOK
IOBLOK
VMBLOK
Base register for modules
called via SVC
SAVEAREI for modules
called via SVC
Return linkage for modules
called via BILR
Base address for modules
called via BILR
For virtual-to-Real address translation:
]~gist~!
1
2
Use
iIrtual address
Real address
Part 2: Control Program (CP)
249
7.
When describing an area of storage in mainline code, a copy file,
or a macro, DSECT is issued containing DS instructions.
8.
eeaningful naaes are used instead of self-defining terms, for
example 5,X'02',C'I' to represent a quantity (absolute address,
offset, length, register, etc.).
All labels, displaceaents, and
values are symbolic. All bits should be syabolic apd defined by
EQO. lor example:
veSTATUS
EQU
X'02'
To set a bit, use:
01
BYTE, BIT
Where BYTE = name of field, BIT is an EQU symbol.
TO reset a bit, use:
II
BYTE,255-BIT
To set mUltiple bits, use:
01
BYTE,BIT1+EIT2
etc.
All registers are referred to as:
RO, R1,
All lengths
V"BLOK is:
.. .,
R15 •
of fields or blocks
veBLOKSZ
EQU
are symbolic, that is,
length of
*-veBLOK
9.
Avoid absolute relative addressing in branches and data references,
(that is, location counter value (*)
or symbolic label plus or
minus a self-defining term used to form a displacement).
10.
When using a single operation to reference multiple values, specify
each value referenced, for example:
Le
CON1
CON2
CON3
R2,R4,COIT
DC
DC
DC
SET R2=COI1
SET R3=CON2
SET R4=COI3
F'1'
F'2'
F'3'
11.
Do no use PRINT NOGEN or PRINT OFF in source code.
12.
eODULE IAeES:
Control section Names and External References are as follows:
Control Section or eodule Name
The first three letters of the
code.
Example:
250
name are
DMK
IBe VM/370: System Programmer's Guide
the assigned
component
The next three letters of the ftodule Name identify
must be unique.
Example:
the module and
DSP
This three-letter,
TITLE card.
unique module
identifier is
the label
of the
Each entry point or external reference must be prefixed by the six
letter unique identifier of the module.
Example:
13.
DftKDSPCH
TITLE Card:
DSP TITLE 'DftKDSP Vft/370 DISPATCHER VERSION v LEVEL l'
14.
PTF Card Example:
CP/CftS:
PUNCH 'xxxxxxxx APPLIED'
Where xxxxxxxx = APAR Number Response
15.
EaROR ftESSAGES:
There should not be any insertions into the message at execution
time and the length of the message should be resolved by the
assembler.
If insertions must be made, the message must be
assembled as different DC statements, and the insert positions are
to be individually labeled.
16.
For all RX instructions use I,' to specify the
indexing is not being used, that is:
L
17.
base register when
R2,AB(,R4)
To determine if you are executing in a virtual machine or a real
machine, issue the Store CPU ID (STIDP) instruction.
If STIDP is
issued from a virtual machine, the version number (the first byte
of the CPUID field) returned will be X'FF'.
The CP load list EXEC contains a list of CP modules used by the VftFLOAD
procedures when punching the text decks that will make up the CP
system.
All modules following DftKCPE in· the list are pageable CP
.odules. Each 4K page in this area may contain one or more modules.
The module grouping is governed the order in which they appear in the
loadlist. An SPBI (Set Page Boundary) card is a loader control card
which forces the loader to start this module at the next higher 4K
boundary. An SPB card is required only for the first module following
DftKCPE. If more than one module is to be contained in a 4K page, only
the first can be assembled with an SPB card. The second and subsequent
modules for a multiple module 4K page must not contain SPB cards.
If changes are made to the loadlist, care must be taken to ensure
that any modules loaded together in the pageable area do not exceed the
4K limit.
Page boundary crossover is not allowed in the pageable CP
modules.
IA 12-2-9 multipunch must be in column 1 of an SPB card.
Part 2: Control Program (CP)
251
The position of two
following D!KCPE must
constants referring to
the last module in the
252
.odules in the loadlist is critical. All .odules
be reenterable and must not contain any address
anything in the pageable CP area. D!KCKP must be
loadlist.
IBft V8/310: System Programmer's Guide
How to Add a Console Function to CP
You can add your own command to your installation's VM/370. First, code
the module to handle the command processing. You should fellow the CP
coding convention outlined in an earlier section of this book.
Second, you must add an entry for your command in the CP DMKCFM
module.
DMKCFM has two entry points: one for logged on users and
another for non-logged on users.
If your command is for logged on
users, be sure its entry is beyond the label COMRBEG1.
TO place an entry for your command in
line with the following format:
the DMKC1M module,
insert a
r'--------------·--------------------------------------------------------------,
I [label] I COMND I commandname,class,min,entrypt[,RCL=1]
commandname is a one- to eight-character name.
class
is the command privilege class (up to four classes
allowed). 0 is coded for non-logged on user commands.
min
is the number
truncation.
entrypt
is the entry point of the
new command.
RCL=1
is specified only when class is "0".
of
characters
allowed
as
module you write to
the
are
minimum
process the
After you have inserted the above entry in the DMKCPM module, you
must reload DMKC1M as a resident module being sure it does not cross a
page boundary_ You must also load your own module which mayor may not
be a resident module.
Part 2: Control Program (CP)
253
Print BuHers and Forms Control
Buffer images are supplied for the UCS (Universal Character Set) buffer,
the UCSB (Universal Character Set Buffer), and the PCB (poras Control
Buffer). The V!/370 supplied buffer images are:
UCS - POR THE 1403 PRINTER
l~!~
AN
HI
PCAN
PCHI
QN
QIC
RN
II
TN
PI
SN
JJ~~!!!!!g
Normal AN arrangement
lormal HI arrangement
Preferred character set, AI
Preferred character set, HI
PL/I - 60 graphics
PL/I - 60 graphics
PORTRAN, COBOL commercial
High speed alphanumeric
Text printing 120 graphics
PL/I - 60 graphics
Text printing 84 graphics
UCSB - POR THE 3211 PRIITER
!!!§
All
Hll
Gll
P 11
Tll
PCB
-
!1~~!!!!!g
Standard COllmercial
Standard Scientific
ASCII
PLl
Text Printing
POR THE 3211 PRINTER
There is only one name provided for an FCB image.
!!!~
PCBl
!1~~!!!!!g
Space 6 lines/inch
Length of page 66 lines
Line
]~E!~§~!!1~~
1
3
5
7
9
11
13
15
Refer to the following
buffer images:
254
IB~
V~/370:
Channel
Skip
.§E~!!if!1!~!!
1
2
3
4
5
6
7
8
19
10
21
23
11
64
9
12
publications for the
System Programmer's Guide
exact contents
of the
If you find that the supplied buffer images do not meet your needs,
you can alter a buffer image or create a new buffer image. Be careful
not to violate the VM/370 coding conventions if you add a new buffer
image; buffer images must not cross page boundaries.
In order to add a new print buffer image to VM/370 you must:
a buffer
1.
Provide
load.
2.
Provide the exact image of the print chain.
3.
Provide a means to print the buffer
the LOADBUF command.
4.
Reload the changed CP modules.
Macros are available
relatively easy.
image na lie
and 12
byte header
for the
image if VER is
which make the process of
buffer
specified on
adding buffer images
UCS EUFFER IMAGES
The UCS buffer contains up to 240 characters and supports the 1403
printer. To add a new UCS buffer image, first code the ucs macro. This
creates a 12-byte header for the buffer load which is used by the CP
module DMKCSO. The format of the UCS macro is:
ucs
ucsname
I ucsname
is a one- to
buffer load.
four-character name
which is
assigned to
the
Next, supply the exact print image. The print image is supplied by
coding DCs in hexadecimal or character format. The print image may
consist of several DCs, the total length of the print image cannot
exceed 240 characters.
The UCSCCW macro must immediately follow the print image. This macro
creates a CCW string to print the buffer load image when VER is
specified by the operator on the LOADBUF command. The format of the
UCSCCW macro is:
ucsccw I ucsname[, (print 1, print2, ••• , print 12) ]
ucsname
is the same as the "ucsname" specified on the UCS macro.
Part 2: Control Program (CP)
255
[ (print 1, ••• , print 12) ]
is the line length (or number of characters to be printed by
the corresponding CCW)
for the verify operation.
Each count
specified must be between 1 and 132 (the length of the print
line on a 1403 printer) and the default line length is 48
characters. Op to 12 print fields may be specified.
However,
the total number of characters to bE printed may not exceed
240.
Finally, insert the macros just coded, OCS and OCSCCW, into the
DMKOCS module.
This module must be reloaded. D"KOCS is a pageable
module (with no executable code) that is called by DMKCSO. DMKOCS must
be on a page boundary and cannot exceed a full page in size.
1: You do not have to specify the line length for verification
of the buffer load.
Insert the following code in DMKOCS:
]~~!~!~
OCS
EX01
DC
5CL'1234567890A ••• Z1234567890*/'
UCSCCW EXOl
The buffer image
containing:
•
•
•
is
5 representations
of
a
48 character
string
The alphabetic characters
The numeric digits, twice
The special characters: * and /
since the line length for the print verification is not specified on the
OCSCCW macro, it defaults to 48 characters per line for 5 lines.
I!!!E!~ ~:
Insert the following code in DMKOCS:
OCS
NUM 1
DC
24CL'1234567890'
OCSCCW NUM1,(60,60,60,60)
The NO"l print buffer consists of 24 10-character entries.
DKKUCS is reloaded, the com.and
LOADBUF
OOE
UCS
10Kl
If, after
VEB
is specified, 4 lines of 60 characters (the 10-character string repeated
6 times) are printed to verify the buffer load).
I!!!E!~ J: ThE print image can
be specified in character or hexadecimal
notation, or a combination of the two.
The code in DMKOCS to support
the preferred character set, AI, is as follows:
OCS
DC
DC
DC
DC
DC
DC
DC
DC
UCSCCW
256
PCAN
C'1234567890,-PQB'$i/STOVWXYZ',X'9C'
C'.*1234567890,-JKL"NOABCDEFGHI+.*'
C'1234567890,-PQB&&$I/STOVWXYZ',X'9C'
C'.*1234567890,-JKLKBOABCDEFGHI+.*'
C'1234567890,-PQR'$i/STUVWXYZ',X'9C'
C'.*1234567890.-JKLMBOABCDEFGHI+.*'
C'1234567890,-PQR&&$I/STUVWXYZ',X'9C'
C'.*1234567890,-JKLMBOABCDEFGHI+.*'
PCAN,(60,60,60,60)
IBM V"/370: System Programmer's Guide
The DCs are coded in both character and hexadecimal notation. The
hexadecimal code for the lozenge (X'9C') follows the character notation
on 4 of the DCs.
The DCs, when taken in pairs, represent 60
characters. When print verification of a buffer load is requested, 4
lines of 60 characters are printed.
USCB BUFFER
I~AGES
The UCSB buffer contains up to 512 characters and supports the 3211
printer. To add a new UCB buffer image, first code the UCB macro. This
.acro creates a 12-byte header record for the buffer load which is used
by the CP module, DMKCSO. The format of the UCB macro is:
r-------------------------------------------------------------------------~
UCB
I
I ucbname
L,______________ •__________________________________________________________~
ucbname
is a one- to
buffer load.
four-character name
which is
assigned to
the
Next, supply the exact print image. The print image is supplied by
coding DCs in hexadecimal or character notation. The total length of
the print image cannot exceed 512 characters.
The format of the UCB buffer is:
~Q§i!iQ~
Contents
PrInt-train image.
433-447
Reserved for IBM use.
448-511
Associative field. See Figure 30 for an explanation
of the contents of this field. The associative
field is used to check (during print line buffer
(PLB) load1ng)
that each character loaded into the
PLB for printing also appears in the train i.age
field of the USCB and, therefore, is on the print
train. Any character loaded into the PLB without
its associated code in the train image field of the
USCB is unprintable, and causes a 'print data check'
to be set immediately. The associative field also
contains dualing control bits.
1-432
512
Reserved for IBK use.
Must be all zeros.
Kust be
z~ro.
Part 2: Control Program (CP)
257
HexaUCSB
Address decimal
00
448
01
449
02
450
03
451
04
452
453
05
06
454
07
455
456
08
457
09
OA
458
459
OB
460
OC
00
461
462
OE
463
OF
464
10
11
465
466
12
467
13
14
468
469
15
470
16
471
17
18
472
473
19
lA
474
18
475
476
1C
477
10
478
1E
479
IF
20
480
481
21
22
482
483
23
24
484
25
485
486
26
487
27
488
28
489
29
490
2A
491
2B
492
2C
20
493
494
2E
495
2F
30
496
497
31
498
32
499
33
500
34
501
35
502
36
37
503
504
38
505
39
506
3A
507
38
508
3C
509
3D
3E
510
3F
I 511
Bit 0
Graphic & Control
Symbols EBCDIC
NUL
PF
HT
LC
DEL
Hexadecimal
40
41
42
43
44
45
46
47
Bit 1
Graphic & Control
Symbols EBCDIC
SP
48
CU2
49
4A
4B
4C
40
4E
4F
50
51
52
53
54
55
56
57
58
59
5A
5B
5C
50
5E
5F
60
/
BYP
LF
E08
PRE
61
62
63
64
65
66
67
CU1
RES
NL
BS
IL
CC
e
<(
+
I
&
!
$
*
)
;
-,
68
69
SM
CU3
6A
6B
6C
60
6E
6F
70
71
%
-
>
?
72
PN
RS
UC
EOT
73
74
75
76
77
78
79
7A
7B
7C
70
7E
7F
84
#
@
=
Figure 30. UCSB Associative Field Chart
258
Hexadecimal
80
81
82
83
84
85
86
87
88
89
8A
8B
8C
80
8E
8F
90
91
92
93
94
95
96
97
98
99
9A
9B
9C
90
9E
9F
AO
A1
A2
A3
A4
A5
A6
A7
A8
A9
AA
AB
AC
AD
AE
AF
BO
B1
B2
B3
IBM VK/370: system Programmer's Guide
B5
B6
87
B8
B9
BA
BB
BC
BO
BE
BF
Bit 2
Graphic & Control HexaSymbols EBCDIC decimal
CO
C1
a
b
C2
c
C3
d
C4
e
C5
C6
C7
C8
C9
CA
CB
CC
CO
CE
CF
DO
01
02
03
04
05
06
07
08
09
OA
DB
DC
DO
DE
OF
EO
E1
E2
E3
E4
E5
E6
E7
E8
E9
EA
E8
EC
ED
EE
EF
FO
F1
F2
F3
F4
F5
F6
F7
F8
F9
FA
FB
FC
FO
FE
FF
f
9
h
i
{
~
(
+
j
k
I
m
n
0
p
q
r
}
lJ
)
±
•
0-
s
t
u
v
w
x
y
z
L
r[
~
•
0
1
2
3
4
5
6
7
8
9
.J
""1
1
-!
Bit 3
Graphic & Control
Symbols EBCDIC
A
B
C
0
E
F
G
H
I
J1
y
J
K
L
M
N
0
P
Q
R
S
T
U
V
W
X
Y
Z
rl
0
1
2
3
4
5
6
7
8
9
The UCBCCW macro must immediately follow the print image. This macro
creates a CCW string to print the buffer load image when the operator
specifies VER on the LOADBUF command.
The format of the UCBCCW macro
is:
,
I
I UCBCCW I ucbnalle[, (print 1, print2, ••• print 12) ]
l
ucbname
is the same nalle specified on the corresponding UCB macro
[ (print i, ••• ,print i2j j
specifies the line length of each line (up to 12) printed to
verify the buffer load. The line length must be between 1 and
150
~he length
of a print line on a 3211 printe~.
The
default specification for verification is 48 characters per
line for 9 lines.
The total number of characters to be
printed must not exceed the size of the print train image, 432
characters.
Finally, insert the two macros just coded, UCB and UCBCCW, into the
DMKUCB module. This module must be reloaded before the new buffer image
can be used. DMKUCB is a pageable module (with no executable code) that
is called by DMKCSO.
DMKUCB must be on a page boundary and cannot
exceed a full page in size.
The code for the All UCB buffer is as follows:
UCB
DC
All STANDARD COMMERCIAL 48 GRAPHICS 3211
All
9C'l<.+IHGFEDCBA*$-RPQONMLKJI,&&ZYXWVUTS/~'098765432'
X'OOOOOO' 433-435
DC
X'000000000000000000000000101010'
DC
X'101010101010100040404240004010'
DC
X' 101010101010101000404041000040'
DC
X'401010101010101010004040000000'
DC
X'101010101010101010100040404448'
DC
X'OOOO' 511-512
UCBCCW All,(48,48,48,48,48,48,48,48,48)
EJECT
DC
436-450
451-465
466-480
481-495
496-510
Note that the DC specification contains 49 characters and the UCBCCW
macro specifies 48 characters. The ampersand, &, has to be coded twice
in order to be accepted by the assembler.
The single quote, " must
also be specified twice in order to be accepted.
It would have been acceptable to code the UCBCCW as:
UCBCCW All
since the default is what was coded.
Part 2: Control Program (CP)
259
It is possible to have a foras control buffer with both a virtual and
real 3211 printer. 1 virtual 3211 file can be printed on a real 1403;
in fact,
one way to provide forms control for a 1403 is to define it
virtually as a 3211.
There is an
FCB macro is:
FCB
FCB .acro to support
forms control.
The for.at
of the
I fcbname,space,length, (line, channel ••• ) ,index
fcbname is the name of the forms control buffer.
to four alphameric characters.
"fcbname"
can be one
space
is the number of lines/inch. Valid specifications are 6 or 8.
This operand may be o.itted, the default is 6 lines/inch. When
the space operand is omitted, a comma must be coded. Spacing
has no .eaning for a virtual printer.
length
is the
180).
number of print
lines per page
or carriage tape
(1 to
(line,channel ••• )
shows which print line (line) prints in each channel (1 to 12).
The entries can be specified in any order.
index
is an index value (from 1 to 31). "index" specifies the print
position which is to be the first printed position.
(The
"index" specification can be
overridden with the LOADBUF
command).
One standard FCB image is supplied, FCB1. You will find FCBl in the
module DftKFCB. DftKFCB is a pageable module which is called by DftKCSO.
It aust start on a page boundary and cannot exceed a full page in size.
As long as you follow these conventions, you can add additional forms
control buffer images to DMKFCB.
!2te: The GEIERATE EXEC procedure has a facility to reassemble only the
DftKFCB module.
See the description of the GENERATE EXEC procedure in
the !11L37Q: R!!!!!!ing !nd ~I§te!! Ge~~io!! ~.!!id~.
~!!!12!~
1:
If you wanted your printer to print:
•
•
•
•
•
•
8 lines/inch
60 lines/page
,
print line 3 in channel 1
print line 60 in channel 9
print line 40 in channel 12
print position 10 the first print position
you would code the FCB macro (with a name, SPEC) as:
FCB SPEC,8,60, (3,1,40,12,60,9) ,10
260
IBft VM/370: System Programmer's Guide
If you want another forms control buffer, called LONG, to be exactly
the same as SPEC (except that only 6 lines print per inch) you could
code either of the following:
FCB LONG,6,60, (3,1,40,12,60,9) ,10
FCB LONG,,60, (3,1,40,12,60,9) ,10
].!~.!!!.EJ:~ ~:
You could have your special forms control buffer (SPEC) loaded for
either a virtual or real 3211 printer.
The LOADVFCB command is for the
virtual 3211 and the LOltBUF command is for the real 3211. If INDEX is
not specified on these commands, no indexing is done.
If INDEX is
specified without a value, the value coded in the FCB macro is used and
if INDEX is specified with a value, the specified value overrides the
value coded in the FCB macro.
If you specify INDEX for the virtual 3211 printer and
real 3211 printer,
the output is indexed the sum
specifications minus 1. For example, the command
again for the
of the two
LOADVFCB OOF FCB SPEC INDEX
indexes the virtual print file 10 positions because 10 was specified in
the FCB macro for the SPEC forms control buffer. When this file is sent
to the real printer, the command
LOADBUF OOE FCB SPEC INDEX 20
indexes the file an additional 20 positions. The value specified on the
command line (20) overrides the value 1n the FCB macro (10). The output
will start printing in print position 29 (10+20-1=29).
Part 2: Control Program (CP)
261
Part 3: Conversational Monitor System (CMS)
Part 3 contains the following inforaation:
•
Introduction to CftS
•
Interrupt Handling
•
Functional Information (How CftS works)
Register usage
DftSBUC structure
storage structure
Free storage management
SVC handling
•
How To Add a Command or EXEC Procedure to CftS
•
os Macro simulation
•
Saving the CftS system
•
Batch Monitor
•
Auxiliary Directories
Part 3: Conversational Monitor System (CMS)
263
Introduction to eMS
The Conversational Monitor System (CMS), the major subsystem of VM/370,
provides a comprehensive set of conversational facilities to the user.
Several copies of CMS may run under CP, thus providing several users
with their own time sharing system.
CMS is designed specifically for
the VM/370 virtual machine environment.
Each copy of CMS supports a single user. This means that the storage
area contains only the data pertaining to that user. Likewise, each CMS
user has his own machine configuration and his own files. Debugging is
simpler because the files and storage area are protected from other
users.
Programs can be debugged from the terminal. The terminal is used as
a printer to examine limited amounts of data.
After examining program
data, the terminal user can enter commands on the terminal which will
alter the program.
This is the most common method used to debug
programs that run in CMS.
CMS, operating with the VM/370 Control Program, is a time sharing
system suitable for problem solving, program development, and general
work.
It includes several
programming language processors, file
manipulation commands, utilities, and debugging aids. Additionally, CMS
provides facilities to simplify the operation of other operating systems
in a virtual machine environment when controlled from a remote terminal.
For example, CMS capabilities are used to create and modify job streams,
and to analyze virtual printer output.
Part of the CMS environment is related to the virtual machine
environment created by CP. Each user is completely isolated from the
activities of all other users, and each machine in which CMS executes
has virtual storage available to it and managed for it. The CP commands
are recognized by CMS. For example, the commands allow messages to be
sent to the operator or to other users, and virtual devices to be
dynamically detached from the virtual machine configuration.
The CMS command language offers terminal users a wide range of
functions.
It supports a variety of programming languages, service
functions, file manipulation, program execution control, and general
system control. The CMS commands that are useful in debugging are
discussed in the "Debugging with CMS" section of "Part 1: Debugging with
VM/370." For detailed information on all other CMS commands, refer to
the !11LJ.IQ: £Q.!!.!~nd !!~'!!.9'y~.9~ Gu!de £.2£ Q~.!!~al Us~!:§.
Figure 34 describes CMS command processing.
Part 3: Conversational Monitor System (CMS)
265
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1Y75
The Conversational Monitor system interfaces with virtual disks, tapes,
and unit record equipment.
The CMS residence device is kept as a
read-only, shared, system disk.
Permanent user files may be accessed
from up to nine active disks. Logical access to those virtual disk~ is
controlled by CftS, while CP facilities manage the device sharing and
virtual-to-real mapping.
User files in CMS are identified with three designators. The first
is filename.
The second is a filetype designator which may imply
specific file characteristics to the CftS file management routines. The
third is a filemode designator which describes the location and access
mode of the file.
The compilers available under CMS default to particular input
filetypes,
such as ASSEftBLE, but the file manipulation and listing
commands do not.
Files of a particular filetype form a logical data
library for a user;
for example, the collection of all COBOL source
files, or of all object (TEXT) decks, or of all EXEC procedures. This
allows selective handling of specific groups of files with minimum input
by the user.
User files can be created directly from the terminal with the CMS
EDIT facility.
EDIT provides extensive context editing services. File
characteristics such as record length and format, tab locations, and
serialization options can be specified.
The system includes standard
definitions for certain filetypes.
CMS automatically allocates compiler work files at the beginning of
command execution on whichever active disk has the greatest amount of
available space, and deallocates them at completion.
Compiler object
decks and listing files are normally allocated on the same disk as the
input source file or on the primary read/write disk, and are identified
by combining the input filename with the filetypes TEXT and LISTING.
These disk locations may be overridden by the user.
The size of a single user file is limited to one virtual disk. The
file management system limits the number of files on anyone virtual
disk to 3400.
All CMS disk files are written as 800-byte records,
chained together by a specific file entry that is stored in a table
called the Master File Directory; a separate Master File Directory is
kept for,
and on, each virtual disk.
The data records may be
discontiguous, and are allocated and deallocated automatically.
A
subset of the Master File Directory (called the User File Directory) is
made resident in virtual storage when the disk directory is made
available to CMS; it is updated on the virtual disk at least once per
command if the status of any file on that disk has been changed.
virtual disks may be shared by CMS users; the facility is provided by
VM/370 to all virtual machines, although a user interface is directly
available in CMS commands.
specific files may be spooled between
virtual machines to accomplish file transfer between users. Commands
allow such file manipulations as writing from an entire disk or from a
specific disk file to a tape, printer, punch, or the terminal. Other
commands write from a tape or virtual card reader to disk, rename files,
copy files, and erase files.
Special macro libraries and text or
program libraries are provided by CMS, and special commands are provided
to update and use them.
CMS files can be written onto and restored from
unlabeled tapes via CMS commands.
Caution:
results.
266
Multiple write
access
under
CMS can
IBM VM/370: System Programmer's Guide
produce
unpredictable
GC20~1807~3
Page Modified by TNL GN20=2662, March
~1
J
I ,
1975
Problem programs which execute in CMS can create files on unlabeled
tape in any record and block size; the record format can be fixed,
variable, or undefined.
Figure 31 describes the CMS file system.
Part 3: Conversational Monitor System (CMS)
266.1
~
....
DMSNUC Area of Storage
I.Q
Free Storage
Disk Storage
C
H
(1)
W
n
tJr
AFT
DMSNUC
tn
....
"'II
.....
(1)
tn
loci
en
t+
(1)
EI
AFT
continued
AFTS
to
I»
H
ADTSECT
t+
w
n
0
t:S
>
>
<
<
When issuing a variable length GBTMAIN, six and a half pages are
reserved for CMS usage; this is a design value. A user who needs
additional reserved pages (for example, for larger directories) should
free up some of the variable GETftAIN storage from the high end.
DMSFREE FREE STORAGE nANAGEnENT
The DftSFRBE macro allocates CftS free storage.
macro is:
r
[label]
DftSFREE
The format of the DMSFREE
,
DWORDS={ n } l,ftIN={ n }'
(0)
I
( 1) I
.J
L
r
r
"r
r
"
I
I I I,ERR=lladdrl I
I ! II
I NUCLEUSII I
L
L
.J.J
L
.J.J
I,TYPE=IUS!~
L
I, AREA= I LOW II
I
IBIGBII
r
r"
I ,TYPCALL=I~!£ I I
I
I BALRII
r
r"
L
L.J.J
L
L.J.J
Part 3: Conversational Monitor System (CMS)
279
label
is any valid assembler language label.
DWORDS={ n }
(0)
is the number of doublewords of free storage requested.
DWORDS=n specifies the number of doublewords directly and
DVORDS=(O) indicates that register 0 contains the number
of doublewords requested.
MIN={ n }
indicates a variable request for free storage. If the
exact nuaber of doublewords indicated by the DWORDS
operand is not available,
then the largest block of
storage that is greater than or equal to the minimum is
returned.
MIN=n
specifies the
minimum number
of
doublewords of free storage
directly while MIN=(1)
indicates that the minimum is in register 1.
(1)
r
,
TYPE=IY~!~
I indicates the type of CMS storage with which this request
INUCLEUSI for free storage is filled: USER or NUCLEUS.
~
L
r
,
is the return address if any error occurs.
"laddr" is
any address that can be referred to in an LA
(load
address) instruction.
The error return is taken if there
is a macro coding error or if there is not enough free
storage available to fill the request.
If
is specified
for the return address, the error return is the same as a
normal return.
ERR=lladdrl
*
I
L
I
~
*
r
,
AREA=ILOW I
indicates the area of CMS free storage from which this
request for free storage is filled. LOW indicates the
low storage area between DMSNUC and the transient program
area.
HIGH indicates the area of storage between the
user program area and the CMS loader tables.
If AREA is
not specified, storage is allocated wherever it is
available.
IHIGHI
~
L
r
,
TYPCALL=I~!~
I indicates how control is passed to DMSFREE. Since DMSFREE
IBALRI is a nucleus-resident routine, other nucleus-resident
L
~ routines can
branch directly to it
(TYPCALL=BALR) while
routines that are not nucleus-resident must use linkage
SVC (TYPCALL=SYC).
The pointers FREEUPPR and FREELOWE in NUCON indicate the amount of
storage which DMSFREE has allocated from the high portion of the user
program area.
These pointers are initialized to the beginning of the
Loader Tables.
The pointer FREELOVE is the "low-e~tend" pointer of DMSFREE storage
in the user program area.
As storage is allocated from the user program
area to satisfy DMSFREE requests,
this pointer will be adjusted
downward.
Such adjustments are always in multiples of 4K bytes, so that
this pointer is always on a 4K boundary.
As the allocated storage is
released, this pointer is adjusted upward.
The pointer FREELOWE
can never be lower
than MAINHIGH, the
"high-extend" pointer for GETMAIN storage.
If a DMSFREE request cannot
be satisfied without extending FREELOWE below MAINHIGH, then DMSFREE
will take an error exit, indicating that insufficient storage is
available to satisfy the request. Figure 33 shows the relationship of
these storage areas.
280
IBM VM/370: System Programmer's Guide
The FREETAB free storage table is kept in free storage, usually in
low-storage, just below the Master lile Directory for the System Disk
(S-disk). However, the FREETAB may be located at the top of the user
program area~
This table contains one byte for each page of virtual
storage. Each such byte contains a code indicating the use of that page
of virtual storage. The codes in this table are as follows:
Code
US ERCODE-1x I 01 1 )
The page is assigned to user storage.
IUCCODE (X I 02 I)
The page is assigned to nucleus storage.
TRNCODE (X I 03 1 )
The page is part of the Transient Program Area.
USARCODE (X I 041)
The page is part of the User Program Area.
SYSCODE (X I 05 1 )
The page is none of the above. The page is assigned
to systell storage, system code, or the Loader
Tables.
J1~!!i!!g
other DMSFREE storage pointers are maintained in the DftSFRT CSECT, in
BUCON. The four chain header blocks are the most important fields in
DftSFRT. The four chains of unallocated elements are:
•
•
•
•
The
The
The
The
low-storage nucleus chain
low-storage user chain
high-storage nucleus chain
high-storage user chain
For each of these chains of unallocated elements, there is
block consisting of four words, with the follo~ing format:
i
0(0)
i
a control
i
POINTER -- pointer to the first
free element on the chain, or
zero, if the chain is empty.
-------I
1
1-------
NUft -- the number of elements on
II
III \
.... , .... I
1---1
MAX -- a value equal to or greater
8 (8)
than the size of the largest
element.
1
I
FLAGS- 1 SKEY
1 TCODl -I Unused
12 (C) Flag
IStorage IFREETAB I
byte
1 key
1 code 1
I
.L
I
POINTER
points to the first element on this chain of free elements.
If there are no elements on this free chain, then the POINTER
field contains all zeros.
NUM
contains the number of elements on this chain of free
elements. If there are no elements on this free chain, then
this field contains all zeros.
ftAX
is used to avoid searches which will fail.
It contains a
number not exceeding the size, in bytes, of the largest
element on the free chain. Thus, a search for an element of a
Part 3: Conversational Monitor System (eMS)
281
given size will not be made if that size exceeds the "AX
field. However, this number may actually be larger than the
size of the largest free element on the chain.
FLAGS
The following flags are used:
FLCll (XISO') -- Clean-up flag. This flag is set if the chain
must be updated.
This will be necessary in the following
circumstances:
•
If one of the two high-storage chains contains a 4K page
which is pointed to by FREELOVE, then that page can be
removed from the chain, and FREELOVE c~n be increased.
•
All completely unallocated 4K pages are kept on the user
chain, by convention.
Thus, if on~ of the nucleus chains
(low-storage or high-storage) contains a full page, then
this page must be transferred to the corresponding user
chain.
FLCLB (XI401)
destroyed.
-- Destroyed flag.
FLHC (XI201) -- High-storage chain.
and user high-storage chains.
set
if the chain
has been
Set for both the nucleus
FLBU (X'10') -- Nucleus chain. set for
and high-storage nucle~s chains.
both the low-storage
FLPA (X'OS') -- Page available. This flag is set if there is
a full 4K page available on the chain. This flag may be set
even if there is no such page available.
SKEY
contains the one-byte storage key
assi9ned to storage on this
ch~in.
TeODE
contains the one-byte
chain.
FREETAE table code for
storage on this
When DMSFRBE with TYPB=USER (the default) is called, one or more of the
following steps are taken in an attempt to satisfy the request.
As soon
as one of the following steps succeeds, then user free storage
allocation processing terminates.
1.
Search
size.
2.
Search the
size.
3.
Extend high-storage user storage downward into
Area, modifying FREELOVE in the process.
4.
For a variable request, put all available storage in the User
Program Area onto the high-storage user chain, and then allocate
the largest block available on either the high-storage user chain
or the low-storage user chain. The allocated block will not be
satisfactory unless it is larger than the minimum requested size.
282
the low-storage
user chain
high-storage user
for
a block
of the
required
chain for
a block
of the
required
IB" V!/370: System Programmerls Guide
the User
Program
When DMSFREE with TYPE=BUCLKUS is called, the following steps are taken
in an attempt to satisfy the request, until one succeeds:
1.
Search the
size.
low-storage nucleus chain for
a block of
2.
Get free pages from the low-storage user chain, if
available, and put the. on the low-storage nucleus chain.
3.
Search the high-storage
size.
4.
Get free pages from the high-storage user chain, if they
available, and put them on the high-storage nucleus chain.
S.
Extend high-storage nucleus storage downward
Area, modifying FREELOWE in the process.
6.
For variable requests, put all available pages from the user chains
and the User Program Area onto the nucleus chains, and allocate the
largest block available on either the low-storage nucleus chains,
or the high-storage nucleus chains.
nucleus chain for a block
the required
DMSFRET
are
of the required
are
into the User Program
The DMSFRET macro releases free storage previously allocated
DMSFREE macro. The format of the DMSFRET macro is:
[label]
any
with the
DWORDS= { n }' LOC={laddr }
(0)
(1)
r
..
"r
.."
L
L
.J.J
L.J.J
!#ERR=lladdr!! I.TYPCALL=!§!£ !!
I
I * II I
IBALR II
label
L
is any valid assembler language label.
DWORDS={ n }
is the number of doublewords of storage to be released.
DWORDS=n specifies the number of doublewords directly and
DWORDS=(O) indicates that register 0 contains the number
of doublewords being released.
LOC={laddr }
is the address of the block of storage being released.
"laddr" is any address that can be referred to in an LA
(load address) instruction.
LOC=laddr specifies the
address directly while LOC=(1) indicates the address is
in register 1.
(0 )
(1 )
Part 3: Conversational Menitor System (CMS)
283
r
,
is the return address if an error occurs.
"laddr" is any
address that can be referred to by an LA (Load Address)
instruction. The error return is taken if there is a
macro coding error or if there is a problem returning the
storage.
If
is specified, the error return address is
the same as the nor.al return address.
EBR=lladdrl
I
I
L
*
J
*
r
,
TYPCALL=I§!~
I indicates how control is passed to DMSFRET. Since DMSFRET
IBALRI is a nucleus-resident routine, other nucleus-resident
L
J
routines can branch directly to it
(TYPCALL=BALR) while
routines that are not nucleus-resident must use SYC
linkage (TYPCALL=SYC).
When DMSFRET is called, the block being released is placed on the
appropriate chain.
At that point, the final update operation is
performed, if necessary, to advance FREELOVE, or to move pages from the
nucleus chain to the corresponding user chain.
similar update operations will be
calls to DMSPREE, as well.
performed, when
necessary, after
RELEASING ALLOCATED STORAGE
Storage allocated by the GETMAIN macro
any of the following ways:
instruction may be
released in
1.
A specific block of such storage may
FREE!!IN macro instruction.
be released by means
2.
The STRINIT macro instruction releases
any previous GETMAIN requests.
3.
Almost all CMS commands issue a STRINIT macro instruction. Thus,
executing almost any CMS command will cause all GET MAIN storage to
be released.
all storage
of the
allocated by
Storage allocated by the DMSFREE macro instruction may be released in
any of the following ways:
1.
A specific block of such storage may
DMSPRET macro instruction.
be released by means
of the
2.
Whenever any user routine or CMS com.and abnormally terminates (so
that the routine DMSABN is entered), and the ABEND recovery
facility of the system is invoked, all DMSPREE storage with
TYPE=USER is released automatically.
Except in the case of ABEND recovery, storage allocated by the
DMSPRE! macro is never released automatically by the system.
Thus,
storage allocated by means of this macro instruction should always be
released explicitly by .eans of the DMSFRET macro instruction.
DMSPREE SERYICE ROUTINES
The DMSPRES macro instruction is used by the system
free storage .anagement services.
284
IBM YM/370: System Programmer's Guide
to request certain
The format of the DMSlRES macro is:
DMSlRES
IllT1
r
r"
IllT2
I,TYPCAtL=I~!~ II
CHECK
I
IBALR II
L
L
~~
CKOI
CKOll
UREC
L-__________________________________________________________________________
CAtOC
~
[label]
.!l!~:
label
is any valid assembler language label.
IllT1
invokes the first free storage initialization routine, so
that free storage requests can be made to access the
system disk.
Before this routine is invoked, no free
storage requests may be made. After this routine has
been invoked, free storage requests may be made, but
these are subject to the following restraints until the
second free storage management initialization routine has
been invoked:
•
All requests for USER type storage
requests for IUCLEUS type storage.
are changed
to
•
Error checking is limited before initialization is
complete. In particular, it is sometimes possible to
release a block which was never allocated.
•
All requests that are satisfied in high storage must
be of a temporary nature, since all storage allocated
1n high storage is released when the second free
storage initialization routine is invoked.
When CP's saved system facility is used, the CMS system
is saved at the point just after the A-Disk has been made
accessible.
It is necessary for DMSlRE to be used before
the size of virtual storage is known, since the saved
system can be used on any size virtual machine. Thus,
the first initialization routine initializes DMSFRE so
that limited functions can be requested, while the second
initialization
routine performs
the
initialization
necessary to allow the full functions of DMSFRE to be
exercised.
IHIT2
invokes the second initialization routine. This routine
is invoked after the size of virtual storage is known,
and it performs initialization necessary to allow all the
functions
of
DMSFRE
to
be
used.
The
second
initialization routine performs the following steps:
•
Releases all storage
high-storage area.
which has been allocated
in the
•
Allocates the FREETAB free storage table. This table
contains one byte for each 4K Fage of virtual storage,
and so cannot be allocated until the size of virtual
storage is known.
Part 3: Conversational Monitor system (CMS)
285
•
The FREETAB table is initialized,
protection keys are initialized.
and all
storage
•
All completely unallocated 4K pages on the low-storage
nucleus free storage chain are removed to the user
chain. Any other necessary operations are performed.
CHECK
invokes a routine which checks all free storage chains
for consistency and correctness. Thus, it checks to see
whether any free storage pointers have been destroyed.
This option can
be used at any
time for system
debugging.
CKON
turns on a flag which causes the CHECK routine to be
invoked each time a call is made to DftSFREE or DftSFRET.
This can be useful for debugging purposes (for example,
when you wish to identify the routine destroying free
storage management pointers). Care should be taken when
using this option, since the CHECK routine is coded to be
thorough rather than efficient. Thus, after the CKON
option has been invoked, each call to DftSFREE or DftSFRET
will take much longer to be completed than before.
CKOFF
turns off the
option.
UREC
is used by DftSABN during
release all user storage.
CALOC
is used by DftSABN after the ABEND recovery process has
been completed. It invokes a routine which returns, in
register 0, the number of doublewords of free storage
which have been allocated. This number is used by DHSABN
to determine whether ABEND recovery has been successful.
flag
which was
turned
on
by the
the ABEND recovery
CKON
process to
ERROR CODES FROH DHSFRES, DftSFREE, AND DftSFRET
A nonzero return code upon return
indicates that the request could not
this return code, indicating which
codes apply to the DftSFRES, DftSFREE,
from DftSFRES, DftSFREE, or DftSFRET
be satisfied. Register 15 contains
error has occurred.
The following
and DftSFRET macros.
Error
(DMSFREE) Insufficient storage space is available to satisfy
the request for free storage.
In the case of a variable
request, even the minimum request could not be satisfied.
2
3
(DHSFREE or DHSFRET) User storage pointers destroyed.
(DMSFREE, DftSFRET,
destroyed.
or
DMSFRES)
Nucleus
storage
pointers
(DHSFREE) An invalid size was requested. This error exit is
taken if the requested size is not greater than zero. In the
case of variable requests, this error exit is taken if the
m~n~mu.
request
is greater
than the
maximum request.
(However, the latter error is not detected if DftSFREE is able
to satisfy the maximum request.)
5
286
(DHSFBET) An invalid size was passed to the
This error exit is taken if the specified
positive.
IBft Vft/370: System programmer's Guide
DMSFRET macro.
length is not
6
(DMSFRET) The block of storage which is being released was
never allocated by DMSFREE. Such an error is detected if one
of the following errors is found:
The block does
not lie entirely
low-storage free storage area or the
between FREELOiE and FREEUPPR.
either the
User Program Area
•
The block crosses a page boundary which separates a page
allocated for USER storage from a page allocated for
NUCLEUS type storage.
•
The block overlaps
storage chain.
another block
already
the block being
on
the
free
7
(DMSFRET) The address given for
not doubleword aligned.
released is
8
(DMSFRES) An invalid request code was passed to the DMSFRES
routine.
since all request codes are gen~rated by the DMSFRES
macro, this error code should never appear.
9
(DMSFREE, DMSFRET, or DMSFRES)
Unexpected and
error in the free storage management routine.
unexplained
CMS HANDLING CF PSi KEYS
The purpose of the CMS Nucleus protection scheme is to protect the CMS
nucleus from inadvertent destruction by a user progra.. iithout it, it
would be possible, for example, for a FORTRAN user who accidentally
assigns an incorrectly subscripted array element to destroy nucleus
code, wipe out a crucial table or constant area, or even destroy an
entire disk by destroying the contents of the Master File Directory.
In general, user programs and disk-resident CMS commands run with a
PSi key of X'E', while nucleus code runs with PSi key of X'O'.
There QL~,
however, ~um~ exceptions
to this
rule.
certain
disk-resident CMS commands run with a PSi key of X'O', since they have a
constant need to modify nucleus pointers and storage. The nucleus
routines called by the GET, PUT, READ,
and iRITE macros run with a user
PSi key of X'E', to increase efficiency.
Two macros are available to any routine that wishes to change its PSi
key for some special purpose. These are the DMSKEY macro and the DMSEXS
macro.
The DMSKEY macro may be used to change the PSi key to the user value
or the nucleus value. The DMSKEY NUCLEUS option causes the current PSi
key to be placed in a stack, and a value of a to be placed in the PSi
key. The DMSKEY USER option causes the current PSi key to be placed in
a stack, and a value of X'E' to be placed in the PSi key. The DMSKEY
RESET option causes the top value in the DMSKEY stack to be removed and
re-inserted into the PSi.
It is a requirement of the CMS system that when a routine terminates,
the DMSKEY stack must be empty.
This means that a routine should
execute a DMSKEY RESET option for each DMSKEY NUCLEUS option and each
DMSKEY USER option executed by the routine.
Part 3: Conversational Monitor System (CMS)
287
The DMSKEY key stack has a current maximum depth of seven for each
routine.
In this context, a "routine" is anything invoked by an SVC
call.
The DMSKEY LASTUSER option causes the current PSi key to be placed in
the stack, and a new key inserted into the PSi, determined as follows:
the SVC system save area stack is searched in reverse order
(top to
bottom) for the first save area corresponding to a user routine. The
PSi key which was in effect in that routine is then taken for the new
PSi key. (If no user routine is found in the search, then LASTUSER has
the same effect as USER.)
This option is used by OS .acro simulation
routines when they wish to enter a user-supplied exit routine; the exit
routine is entered with the PSi key of the last user routine on the SVC
system save area stack.
The NOSTACK option of DMSKEY may be used with NUCLEUS, USER, or
LASTUSER (as in, for example, DMSKEY NUCLEUS,NOSTACK) if the current key
is not to be placed on the DMSKEY stack. If this option is used, then
no corresponding DMSKEY RESET should be issued.
The DMSEXS ("execute in system mode")
macro instruction is useful in
situations where a routine is running with a user protect key, but
wishes to execute a single instruction which, for example, sets a bit in
the NUCON area. The single instruction may be specified as the argument
to the DMSEXS macro, and that instruction will be executed with a system
PSi key.
Whenever possible, CMS commands run with a user protect key. This
protects the CMS nucleus in cases where there is an error in the system
command which would otherwise destroy the nucleus.
If the command must
execute a single instruction or small group of instructions which modify
nucleus storage, then the DMSKEY or DMSEXS macros are used, so that the
system PSi key will be used for as short a period of time as possible~
CMS SVC HANDLING
DMSITS (INTSVC)
is the CMS system SVC
operation of DMSITS is as follows:
handling routine.
The general
1.
The SVC new PSi
(low-storage location X'60')
contains, in the
address field, the address of DMSITS1.
The DMSITS module will be
entered whenever a supervisor call is executed.
2.
DMSITS allocates a system and user save area.
The
is used as a register save area
(or work area)
routine.
3.
The called routine is called (via a LPSi or BALR) •
4.
Upon return from the called routine, the save areas are released.
5.
Control is returned to
made the SVC call).
the caller
(the routine
user save area
by the called
which originally
SVC TYPES AND LINKAGE CONVENTIONS
SVC conventions are important to any discussion of CMS because the
system is driven by SVCs (supervisor calls). SVCs 202 and 203 are the
most common CMS SVCs.
288
IBM VM/370: System Progra.mer's Guide
SVC 202 is used both for
calling routines written
modules).
calling nucleus resident routines, and for
as commands (fer example~ disk resident
A typical coding sequence for an SVC 202 call is the following:
LA
SVC
DC
R1,PLIST
202
AL4(BRRADD)
Whenever SVC 202 is called, register 1 must point to a parameter list
(PLIST). The format of this parameter list depends upon the actual
routine or command being called, but the SVC handler will examine the
first eight bytes of this parameter list to find the name of the routine
or command being called.
The "DC AL4 (address)" instruction following the SVC 202 is optional,
and may be omitted if the programmer does not expect any errors to occur
in the routine or command being called. If included, an error return is
made to the address specified in the DC. DMSITS determines whether this
DC was inserted by examining the byte following the SVC call inline. A
nonzero byte indicates an instruction, a zero value indicates that "DC
AL4(address) " follows.
SVC 203 is called by CMS macros to perform various internal system
functions. It is used to define SVC calls for which no parameter list
is provided. For example, DMSFREB parameters are passed in registers 0
and 1.
A typical calling sequence for an SVC 203 call is as follows:
SVC
DC
203
H'code'
The halfword decimal code following the SVC 203 indicates the
specific routine being called. DMSITS examines this halfword code,
taking the absolute value of the code by an LPR instruction. The first
byte of the result is ignored, and the second byte of the resulting
halfword is used as an index to a branch table.
The address of the
correct routine is loaded, and control is transferred to it.
It is possible for the address in the SVC 203 index table to be
zero. In this case, the index entry will contain an 8-byte routine or
command name, which will be handled in the same way as the 8-byte name
passed in the parameter list to an SVC 202.
The programmer indicates an error return by the sign of the halfword
code. If an error return is desired, then the code is negative. If the
code is positive, then no error return is made.
The sign of the
half word code has no effect on determining the routine which is to be
called, since DMSITS takes the absolute value of the code to determine
the routine called.
Since only the second byte of the absolute value of the code is
examined by DMSITS, seven bits (bits 1-7) are available as flags or for
other uses.
Thus, for example, DMSFRBB uses these seven bits to
indicate such things as conditional requests and variable requests.
Part 3: Conversational Monitor system (CMS)
289
When an SVC 203 is invoked, DMSITS stores the halfword code into the
NUCON location CODE203, so that the called routine can examine the seven
bits made available to it.
All calls made by means of SVC 203 should be made by macros, with the
macro expansion computing and specifying the correct halfword code.
The programmer may use the HNDSiC macro to specify the address of a
routine which will handle any SVC call other than for SVC 202 and SiC
203.
In this case, the linkage conventions
user-specified SiC-handling routine.
CMS supports selected SVC calls generated
the effect of these macro calls.
are
as
required
by as macros,
by
the
by simulating
The proper linkages will be set up by the as macro generations.
DMSITS does not recognize a "normal" or "error" return from an as macro
simulation SVC call.
There are several types of invalid SiC calls recognized by DMSITS.
1.
Invalid SiC number. If the SVC number does not fit into any of the
four classes described above, then it is not handled by DMSITS. An
appropriate error message is displayed at the terminal, and control
is returned directly to the caller.
2.
Invalid routine name in SVC 202 parameter list. If the routine
named in the SVC 202 parameter list is invalid or cannot be found,
DMSITS handles the situation in the same way it handles an error
return from a legitimate SiC routine.
The error code is -3.
3.
Invalid SiC 203 code. If an invalid code follows SiC 203 inline,
then an error message is displayed, and the ABEND routine is called
to terminate execution.
SEARCH HIERARCHY FOR SiC 202
When a program issues SiC 202, passing a routine or command name in the
parameter list, then DMSITS must be searched for the specified routine
or command.
(In the case of SVC 203 with a zero in the table entry for
the specified index, the same logic must be applied.)
The search algorithm is as follows:
290
IBM VM/370: System Programmer's Guide
1.
First, a check is made to see if there is a routine with the
specified name currently occupying the system Transient Area.
If
this is the case, then control is transferred there.
2.
Second, the system function name table is searched, to see if a
command by this name is nucleus-resident. If successful, control
goes to the specified nucleus routine.
3.
Next, a search is made for a disk file with the specified name as
the filename, and MODULE as the filetype.
The search is made in
the standard disk search order.
If this search is successful, then
--~
~n~
specified module is loaded (via the LOAD MOD comaand), auu
control passes to the storage location now occupied by the
command.
4.
If all searches so far have failed, then DMSINA (ABBREV) is called,
to see if the specified routine name is a valid system abbreviation
for a system command or function.
user-defined abbreviations and
synonyms are also checked. If this search is successful, then
steps 2 through 4 are repeated with the full function name.
5.
If all searches fail, then an error code of -3 is issued.
When a command is entered from the terminal, DMSINT processes the
command line, and calls the scan routine to convert it into a parameter
list consisting of eight-byte entries.
The following search is
performed:
1.
DMSINT searches for a disk file whose filename is the command name,
and whose filetype is EXEC.
If this search is successful, EXEC is
invoked to process the EXEC file.
If not found, the command name is considered to be an abbreviation
and the appropriate tables are examined. If found, the abbreviation
is replaced by its full equivalent and the search for an EXEC file
is repeated
a
2.
If there is no EXEC file,
DMSINT executes SVC 202, passing the
scanned parameter list, with the command name in the first eight
bytes. DMSITS will perform the search described for SVC 202 in an
effort to execute the command.
3.
If DMSITS returns-to DMSINT with a return code of -3, indicating
that the search was unsuccessful, then DMSINT uses the CP DIAGNOSE
facility to attempt to execute the command as a CP command.
4.
If all these searches fail, then
UNKNOWN CP/CMS COMMAND.
DMSINT displays the error message
See Figure 34 for a description of this search for a command name.
USER AND TRANSIENT PROGRAM AREAS
Two areas can hold programs which are loaded from disk. These are
called the User Program Area and the Transient Program Area.
(See
Figure 33 for a description of CMS storage usage.)
Part 3: Conversational Monitor System (CMS)
291
The User Progra. Area starts at location X'20000' and extends upward
to the Loader Tables.
Generally, all user programs and certain system
commands (such as EDIT, and COPYFILE)
run in the User Program Area.
Since only one program can be running in the User Program Area at any
one time, it is impossible (without unpredictable results) for one
program running in the User Program Area to invoke, by means of SVC 202,
a module which is also intended to be run in the User Program Area.
The Transient Program Area is two pages long, running from location
X'EOOO' to location X'PllF'.
It provides an area for system com.ands
which may also be invoked from the User Program Area by means of an SVC
202 call.
The Transient Program Area is also used to handle certain OS macro
simulation SVC calls.
If DMSITS cannot find the address of a sUFPorted
OS SVC handling routine, then it loads the file DMSSVT MODULE into the
transient area, and lets that routine handle the SVC.
A program running in the Transient Program Area may not invoke
another program intended to run
in the Transient Program area,
including OS macro simulation SVC calls which are handled by DMSSVT.
For example, a program running in the Transient Program Area may not
invoke the RENAME command. In addition, it may not invoke the OS macro
iTO, which generates an SVC 35, which is handled by DMSSVT.
292
IBM VM/370: System Programmer's Guide
C_r----"
No
Expand Line by
inserting the
command name
EXEC to:
EXEC name
Pass control to the
routine (in the nucleus,
transient area, or
user area) to execute
the command
Display
UNKNOWN
CP/CMS
COMMAND
Ves
Notes:
1. If the terminal line was actually from an EXEC file, or if the
command SET IMPEX OFF has been executed, implied EXEC
is not in effect.
2. A -3 return code indicates SVC 202 processing did not find
the command.
3. If the terminal line was actually from an EXEC file, or if the
command SET IMPEX OFF has been executed, implied CP
is not in effect.
Figure 34.
CMS Command (and Request) Processing
Part 3: Conversational Monitor System (CMS)
293
DMSITS starts programs running in the User Program Area enabled for
all interrupts but starts programs running in the Transient Program Area
disabled for all interrupts. The individual program may have to use the
SSM (Set System Mask) instruction to change the current status of its
system mask.
CALLED ROUTINE START-UP TABLE
Figures 35 and 36 show how
called routine is entered.
the PSi and
registers are set up
when the
--,
r-
I "Called" Type
I
ISVC 202 or 203
I - Nucleus
I resident
I
ISVC 202 or 203
I - Transient
I area MODULE
I
ISVC 202 or 203
I - User area
I
I User-handled
1
lOS - Nucleus
I resident
I
lOS - in DMSSVT
Figure 35.
System Mask
storage Key
Problem Bit
Disabled
System
Off
Disabled
User
Off
Enabled
User
Off
Enabled
User
Off
Disabled
System
Off
Disabled
System
Off
PSi Fields When Called Routine Starts
I Registers RegisterslRegister Register Register Register
15
12
13
14
2 - 11 I
I o- 1
1
1
SVC 2021Same as
Address
Unpredic-IAddress User
Return
or 2031 caller
save
address of
table
I of
to
called
area
I
I called
routine
DMSITS
I
I routine
1---I
Other ISame as
Same as I Address User
Same as
Return
address caller
save
caller I of
I caller
area
to
I
I caller
DMSITS
I
I
Type
Figure 36.
294
Register Contents When Called Routine Starts
IBM VM/370: System Programmer's Guide
RETURNING TO THE CALLING ROUTINE
ihen the called routine finishes processing, control is returned
DftSITS, which in turn returns control to the calling routine.
The return
is accomplished by loading
vas
at
saved
the
time
D~SITS
vas
the original SVC old
first
entered)~
after
to
PSi (which
possibly
modifying the address field.
The address field modification depends
upon the type of SVC call, and on whether the called routine indicated
an error return.
For SVC 202 and 203, the called routine indicates a normal return by
placing a zero in register 15, and an error return by placing a nonzero
code in register 15. If the called routine indicates a normal return,
then DftSITS makes a normal return to the calling routine. If the called
routine indicates an error return, DftSITS passes the error return to the
calling routine, if one was specified, and atnormally terminates if none
was specified.
For an SVC 202 not followed by "DC AL4 (address)", a normal return is
made to the instruction following the SVC instruction, and an error
return tauses an ABEID. For an SVC 202 followed by "DC AL4(address)", a
normal return is made to the instruction following the DC, and an error
return is made to the address specified in the DC. In either case,
register 15 contains the return code passed tack by the called routine.
For an SVC 203 with a positive halfword code, a normal return is made
to the instruction following the halfword code, and an error return
causes an ABEND. For an SVC 203 with a negative halfword code, both
normal and error returns are made to the instruction following the
halfword code. In any case, register 15 contains the return code passed
back by the called routine.
For OS macro simulation SVC calls, and for user-handled SVC calls, no
error return is recognized by DftSITS.
As a result, D~SITS always
returns to the calling routine by loading the SVC old PSi which was
saved when D~SITS was first entered.
Upon entry to DftSITS, all registers are saved as they were when the SVC
instruction was first executed. Upon exiting from D~SITS, all registers
are restored from the area in which they were saved at entry.
The exception to this is register 15 in the case of SVC 202 and 203.
Upon return to the calling routine, register 15 always contains the
value which was in register 15 when the called routine returned to
D~SITS after it had completed processing.
If the called routine
storage protect key of
Save Area.
has system status, so that it runs with a PSi
0, then it may store new values into the System
Part 3: Conversational
~onitor
System
(C~S)
295
If the called routine wishes to modify the location to which control
is to be returned, it .ust .odify the following fields:
•
For SVC 202 and 203, it must modify the IUMRET and ERRET (normal and
error return address) fields.
•
For other SVCs, it must modify the
addr~ss
field of OLDPSW.
To modify the registers that are to be returned to the calling routine,
the fields EGPR1, EGPR2, ••• , EGPR15 must be modified.
If this action is taken by the called routine, then the SVCTRACE
facility may print misleading information, since SVCTRACE assumes that
these fields are exactly as they were when DMSITS was first entered.
Whenever an SVC call is made, DMSITS allocates two save areas for that
particular SVC call.
Save areas are allocated as needed. For each SVC
call, a system and user save area are needed.
When the SVC called routine returns, the save areas are not released,
but are kept for the next SVC. At the completion of each command, all
SVC save areas allocated by that command are released.
The system Save Area is used by DMSITS to save the value of the SVC
old PSi at the time of the SVC call, the calling routine's registers at
the time of the call, and any other necessary control information.
Since SVC calls can be nested, there can be several of these save areas
at one time.
The system Save Area is allocated in protected free
storage.
The User Save Area contains 12 doublewords (24 words), allocated in
unprotected free storage.
DMSITS does not use this area at all, but
si.ply passes a pointer to this area (via register 13.)
The called
routine can use this area as a temporary work area, or as a register
save area. There is one User Save Area for each System Save Area. The
field USAVEPTR in the System Save Area points to the User Save Area.
The exact for.at of the System Save
£B~~~§!!io~!J ~BnitQ~ ~~~!!!
(~A~)
Area can be found in the VM,37~:
199if. The most important
f~Qg~!!
fields, and their uses, are as follows:
CALLER
(Fullword) The address
in this call.
CALLEE
(Doubleword) Eight-byte symbolic name of the called routine.
For OS and user-handled SVC calls, this field contains a
character string of the form SVC nnn, where nnn is the SVC
number in decimal.
CODE
(Balfword) For SVC 203, this field contains the halfword code
following the SVC instruction line.
OLDPSW
(Doubleword)
entered.
IRMRET
(Fullword) The address of the calling routine to which control
is to be passed in the case of a normal return from the called
routine.
296
The SVC
of the SVC instruction
old PSW
IBM VM/370: System Programmer's Guide
at
the time
which resulted
that DMSITS
was
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
ERRET
(Fullword) The address of the calling routine to which control
is to be passed in the case of an error return from the called
routine.
EGPRS
(16 Fullwords, separately labeled EGPRO, EGPR1, EGPR2, EGPR3,
••• ,
EGPR15)
The entry registers.
The contents of the
general registers at entry to DMSITS are stored in these
fields.
EFPRS
(4 Doublewords, separately labeled EFPRO, EFPR2, EFPR4, EFPR6)
en~Ly
floating-point registers. The contents of the
floating-point registers at entry to DMSITS are stored in
these fields.
~ne
SSAVENXT
{Full word}
The address of the next System Save Area in the
chain. This points to the System Save Area which is being
used, or will be used, for any SVC call nested in relation to
the current one.
SSAVEPRV
(Fullword)
The address of the previous system Save
the chain.
This points to the System Save Area for
call in relation to which the current call is nested.
USAVEPTR
(Fullword)
Area in
the SVC
Pointer to the User Save Area for this SVC call.
CMS has an interface that allows it to display large amounts of data in
a very rapid fashion.
This interface for display terminals is much
faster and has less overhead than the normal write because it displays
up to 1760 characters in one operation, instead of issuing 22 individual
writes of 80 characters each (that is one write per line on a display
terminal). Data that is displayed in the screen output area with this
interface is not placed in the console spool file.
The DISPW macro allows you to use this display terminal interface.
It generates a calling sequence for the CMS display terminal interface
module, DMSGIO.
DMSGIO creates a channel program and issues a DIAGNOSE
The format of the eMS DISPW
instruction
macro is:
,.-----I
I [label]
I
I
I
r
DISPW
,
r
,
bufad I,LINE=nl
I,BYTES=bbbbl
ILb!!~::.Q1
I L !!!1:§.§::11'§QI
L
.J
L
[ERASE=YES]
.J
[CANCEL=YES]
L-
where:
label
is an optional macro statement label.
bufad
is the address of a buffer containing the
written to the display terminal.
r
,
ILINE=nl
ILINE=OI
L
.J
is the
number of
the
line,
display terminal
that
is
to
number 0 is the default.
o
be
to
data to
23, on
written.
Part 3: Conversational Monitor System (CMS)
be
the
Line
297
GC20-1807-3 Paqe Modified bV TNL GN20-2662, March 31, 1975
r
,
I BY TES=bbbb I
1!!.!1~~=lI§QI
L
is the
on the
number of bytes
display terminal.
(0 to 1760)
to be written
1760 bytes is the default.
.I
[ERASE=YES]
specifies that the display screen is to be erased before
the current data is written.
The screen is erased
regardless of the line or
number of bytes to be
displayed. Specifying ERASE=YES causes the screen to go
into "MORE" status.
[CANCEL=YES]
causes the CANCEL operation to
area is erased.
298
IBM VM/370: System Programmer's Guide
be performed:
the output
How to Add a Command or EXEC Procedure to CMS
You can create a module or EXEC procedure which executes in the user
area and resides on disk. To execute such a comsand or EXEC procedure,
you only have to enter the filename from the terminal.
However, be
aware of the C~S search order for terminal input. Once a match is
found, the search stops. The search order is:
1.
EXEC file on any currently accessed disk.
2.
Valid
disk.
3.
Nucleus resident or transient area command.
4.
Command on any currently accessed disk.
s.
Valid abbreviation
area command.
6.
Valid abbreviation for disk resident command.
abbreviation for
an
EXEC file
or synonym
on
any currently
for nucleus
resident or
accessed
transient
For example, if you create an EXEC file with the same name as a disk
resident command, the CftS search will always find the EXEC file first.
Thus, the disk resident command will never get executed.
C~S has a fUnction table containing
the names of C~S functions. C~S
reserves the following names, all entries in the CftS FUNCTAB (found in
DftSFNC), for its own use:
ATTN
CARDPH
CARDRD
C~STI~E
CONREAD
CONWAIT
CP
DEBUG
DESBUF
DftSCIOSI
DftSERR
D~SLADAD
D~SPIOCC
D~SPIOSI
ERASE
EXEC
FIllS
GEN~OD
INCLUDE
LOAD
LOADftOD
POINT
PRIIiTIO
PRINTR
RDBUF
RETURN
START
STATE
STATEW
SUBSET
SVCFREE
SVCFR!T
TAPEIO
TRAP
TYPLIN
WAIT
WAITRD
WRBUF
Part 3: Conversational Monitor System (CftS)
299
OS Macro Simulation Under eMS
When a language processor or a user-written program is executing in the
C"S environment and using os-type functions,
it is not executing as
code.
Instead, C"S provides routines that simulate the as functions
required to support as language processors and their generated object
code.
C"S functionally simulates the as macros in a way that presents
equivalent results to programs executing under C"S. The as macros are
supported only to the extent stated in the publicaticns for the
supported language processors, and then only to the extent necessary to
successfully satisfy the specific
requirement of the supervisory
function.
The restrictions for COBOL and PL/I program execution listed in
"Executing a Program that Uses as "acros" in the !ALl1.Q: Pla]]ing ~]g
~I~~~! §~~g!g~!2] ~y!gg
exist because of the limited siaulation by CftS
of the as macros.
Figure 37 shows the as macro functions that
completely simulated, as defined by SVC number.
are
partially
or
The disk format and data base organization of C"S are different from
those of as. A CMS file produced by an as program running under C"S and
written on a CftS disk, has a different format than that of an OS data
set produced by the same as program running under as and written on an
as disk. The data is exactly the same, but its format is different.
(An
as disk is one that has been formatted by an as program, such as
IBCDASDI.)
Because DOS macros are not simulated by CMS, DOS programs cannot run
under C"S. Therefore, DOS files cannot be written on a C"S or as disk.
I HANDLING FILES THAT RESIDE ON C"S DISKS
C"S can read, write, or update any as data that resides on a CMS disk.
CMS simulates the following access methods so that as data organized by
these access methods can reside on C"S disks:
direct
identifying a record by a key
position within the data set.
or
by
partitioned
seeking a named member within the data set.
sequential
accessing a record in a sequence relative
or following items in the data set.
its
relative
to preceding
Refer to Figure 37 and the "Simulation Notes", then read
Method Support" to see how CMS handles these access methods.
"Access
since CftS does not simulate the indexed sequential access method
(ISAM), no as program which uses ISAft can execute under C"S. Therefore,
no program can write an indexed sequential data set on a C"S disk.
300
IBK VM/370: System Programmer's Guide
I HANDLING FILES THAT RESIDE ON OS OR DOS DISKS
CftS can read, but not write or update, OS sequential and partitioned
data sets that reside on OS disks. The OS macros simulated by CftS read
~ne
OS data. uS1ng ~ne same simu~a~ed os macros, efts can read DOS
sequential files that reside on DOS disks. No DOS macros are simulated,
but the OS macros handle the DOS data as if it were OS data. Thus a DOS
file can he used as input to an OS program running under CftS.
CMS cannot write or update any OS data set that resides on an OS
disk. Such a data set can be written or updated only by an OS program
running in a real virtual OS machine. The same restriction applies to
DOS files that reside on DOS disks.
For more information, see "Reading OS
this section.
Data Sets and DOS
Files", in
Part 3: Conversational Menitor System (CMS)
301
r--------------·----------------------------------------------------------~
svc
ftacro
li!!~
RU!B~!:
XDApl
WAIT
POST
GETftAIR
FREEftAIR
GETPOOL
FREEPOOL
LINK
XCTL
00
01
02
04
05
06
07
LOAD
DELETE
GETftAIN/
FREEftAIR
TIft El
ABEND
SPIEl
08
09
BLDL/FINDI
18
OPEN
CLOSE
STOWI
OPENJ
TCLOSE
DEVTYPEI
20
21
22
23
10
11
13
14
19
24
TRKBAL
WTO/WTORI
EXTRACTI
IDENTIFy1
A'ITACH I
CHApl
T'IIftERI
STlftERI
DEQI
SNApl
ENQI
FREEDBUF
STAE
25
3S
40
41
42
44
46
47
48
S1
S6
S7
60
DETACHI
CHKPTI
RDJFCBI
62
63
64
SYNADI
BSPI
GET/PUT
READ/WRITE
NOTE/POINT
CBECK
TGET/TPUT
TCLEARQ
STAX
RETURN
68
69
93
94
96
Function
Read or-write-direct access volumes
Wait for an I/O completion
Post the I/O completion
Conditionally acquire user storage
Release user-acquired storage
Simulate as SVC 10
Simulate as SVC 10
Link control to another phase
Delete, then link control to another
load phase
Read a phase into storage
Delete a loaded phase
ftanipulate user free storage
Get the time of day
Terminate processing
Allow processing program to
handle program interrupts
ftanipulate simulated partitioned
data files
Activate a data file
Deactivate a data file
ftanipulate partitioned directories
Activate a data file
Temporarily deactivate a data file
Obtain device-type physical
characteristics
NOP
communicate with the terminal
Effective NOP
Add entry to loader table
Effective LINK
Effective NOP
Access or cancel timer
Set timer
Effective NOP
Dump specified areas of storage
Effective HOP
Release a free storage buffer
Allow processing program to
decipher ABEND conditions
Effective NOP
Effective NOP
Obtain information from FILEDEF
command
Handle data set error conditions
Backup a record on a tape or disk
Access system-blocked data
Access system-record data
ftanage data set positioning
Verify READ/WRITl completion
Read or write a terminal line
Clear terminal input queue
Create an attention exit block
Return from a linked or
attached routine
ISimulated in the transient routine "DftSSVT".
routines reside in the nucleus.
Figure 37.
302
Simulated OS Supervisor Calls
IBft Vft/370: System Programmer's Guide
Other simulation
SIMULATION NOTES
Because CMS has its own file system and is a single-user system
operating in a virtual machine with virtual storage, there are certain
restrictions for the simulated OS function in CMS. For example, HIARCHY
options and options that are used only by OS multitasking systems are
ignored by CMS.
Listed below are descriptions of all the OS macro functions that are
simulated by CMS as seen by the programmer.
Implementation and program
results that differ from those given in Q~LVS Da!! ~!~~~~~! fta£!~
Instructions and CSLVS Su£ervisor Services and !acrc Instructions are
stated:--HIARCHY options-and those used--only-by os-iultitasking-systems
are ignored by efts. validity checking is not performed within the
simulation routines. The entry point name in LINK, XCTL, and LOAD (SVC
6, 7, 8) must be a member name or alias in a TXTLlB directory uuless the
COMPSWT is set to on. If the COMPSWT is on, SVC 6, 7, and a must
specify a MODULE name. This switch is turned on and off by using the
COMPSWT macro. See the !~Ll1Q: ~Q~~~!~ 1!~Y!E~ ~Y~~~ !~ g~ne~gl Us~~§
for descriptions of all CftS user macros.
Q!!!~!~B~E-~~-I~le~entat!~B
The TYPE option must be R or W; the V, I, and K
options are not supported. The BLKREF-ADDR must point
to an item number acquired by a NOTE macro. Other
options associated with V, I, or K are not supported.
WAIT-SVCl
All options of WAIT are supported. The
waits for the completion bit to be
specified ECBs.
POST-SVC2
All options of POST are supported.
POST sets a
completion code and a completion bit in the specified
ECB.
GETMAIN-SVC4
All the options of GETMAIN
gets blocks of free storage.
are supported.
GETMAIN
FREEMAIN-SVCS
All the options of FREEMAIN are supported.
frees blocks of storage acquired by GETMAIN.
FREEftAIN
WAIT routine
set in the
I LINK-SVC6
The DCB and HIARCHY options are ignored by CftS.
All
other options of LINK are supported. LINK loads the
specified program into storage
(if necessary)
and
passes control to the specified entry point.
XCTL-SVC7
The DCB and HIARCHY options are ignored by CftS.
All
other options of XCTL are supported. XCTL loads the
specified program into storage
(if necessary)
and
passes control to the specified entry point.
LOAD-svca
The DCB and HIARCHY options are ignored by CMS. All
other options of LOAD are supported. LOAD loads the
specified program into storage
(if necessary)
and
returns the address of the specified entry point in
register zero. However, if the specified entry point
is not in core when SVC a is issued, and the
subroutine contains VCONs which cannot be resolved
within that TXTLIB member, CMS will attempt to resolve
these references, and may return another entry point
address. To insure a correct address in register zero,
the user should bring such subroutines into core
either by the CMS LOAD/INCLUDE commands or by a VCON
in the user program.
Part 3: Conversational Monitor System (CMS)
303
Macro-SVC No.
GETPC0 Lj----FREEPOOL
~~1!~f~g£~§_~]_!!]1~!~n!~!i2n
All the options of GETPOOL and FREEPOOL are supported.
GETPOOL constructs a buffer pool and stores the
address of a buffer pool control block in the DCB.
FREEPOOL frees a buffer pool constructed by GETPOOL.
DELETE-SVC9
All the options of DELETE are supported.
DELETE
decreases the use count by one and if the result is
zero frees the corresponding virtual storage. Code 4
is returned in register 15 if the phase is not found.
GETMAIN/
FRFEMAINSVC10
All the options of GETMAIN and FREEMAIN are supported.
Subpool specifications are ignored.
TIME-SVC11
All the options of TIME except MIC are supported.
TIME returns the time of day to the calling program.
ABEND-SVC13
The completion code parameter is supported. The DUMP
parameter is not.
If a STAF request is outstanding,
control is given to the proper STAE routine.
If a
STAE routine is not outstanding, a message indicating
an ABEND has occurred is printed on the terminal along
with the completion code.
SPIE-SVC14
All the options of SPIE are supported.
The SPIE
routine specifies interruption
exit routines and
program interruption types that will cause the exit
routine to receive control.
BLDL-SVC18
BLDL is an effective NOP for LINKLIBs and JOBLIBs.
For MACLIBs, item numbers are filled in the TTR field
of the BLDL list; the K, Z, and user data fields, as
described in Q~L!~ ~~!~ ~~n~g~!~~! ~~£Q !~!!ycti2~'
are set to zeros. The 'alias' bit of the C field is
supported, and the remaining bits in the C field are
set to zero.
FIND-SVC18
All the options of FIND are supported.
FIND sets the
read/write pointer to the item number of the specified
member.
STOW-SVC21
All the options of STOW are supported.
The 'alias'
bit is supported, but the user data field is not
stored in the MACLIB directory since CMS MACLIBs do
not contain user data fields.
OPEN/OPENJSVC19/22
All the options of OPEN and OPENJ are supported except
for the DISP and RDBACK options which are ignored.
OPEN creates a CMSCB (if necessary), completes the
DCB, and merges necessary fields of the DCB and
CMSCB.
CLOSE/TCLOSESVC20/23
All the options of CLOSE and TCLOSE are supported
except for the DISP option, which is ignored. The DCB
is restored to its condition before OPEN.
If the
device type is disk, the file is closed. If the
device type is tape, the REREAD option is treated as a
REWIND.
DEVTYPE-SVC24
All the options of DEVTYPE are supported.
DEVTYPE
moves
device
characteristic information
for
a
specified data set into a specified user area.
304
IBM VM/370: System Programmer's Guide
ftacro-SVC 10.
WTO/iTOi=sVC35
Diffe~~~~~!~_I.ple~~1~1!~B
All options of WTO and WTOR are supported except those
options concerned with multiple console support. WTO
displays a aessage at the operator's ccnsole. iTOR
displays a .essage at the operator's console, waits
for a reply, moves the reply to the specit~ed area,
sets a co.pletion bit in the specified ECB, and
returns.
EXTBACT-SVC40
The EXTRACT routine in CftS is essentially a NOP. The
user provided answer area is set to zeros and control
is returned to the user with a return code of 4 in
register 15.
IDENTIFY-SVC41
The IDENTIFY routine in CftS
the load request chain for
address.
ATTACH-SVC42
All the options of ATTACH are supported in CftS as in
OS PCP.
The following options are ignored by CftS:
DCB, LPftOn, DPftOD, HIARCHY, GSPV, GSPL, SHSPV, SHSPL,
SZEBO, PURGE, ASYNCH, and TASKLIB.
ATTACH passes
control to the routine specified, fills in an ECB
co.pletion bit if an ECB is specified, passes control
to an exit routine if one is specified, and returns
control to the instruction following the ATTACH.
adds a RPQUEST block to
the requested name and
Since CftS is not a multitasking system, a phase
requested by the ATTACH .acro must return to CftS.
CHAP-SVC44
The CHAP routine in CftS is
to the user.
TTlftER-SVC46
All the options of TTlftER are supported.
STlftER-SVC47
All options of STIftER are supported except for TASK
and WAIT. The TASK option is treated as if the REAL
option had been specified, and the WAIT option is
treated as a NOP; it returns control to the user.
DEQ-SVC48
The DEQ routine
to the user.
SNAP-SVC51
All the options of SNAP are supported except for the
DCB, SDATA, and PDATA options, which are ignored. SlAP
always dumps output to the printer. The dump contains
the PSW, the registers, and the storage specified.
ENQ-SVC56
The EIQ routine
to the user.
FRElDBUF-SVC57
All the options of FREEDBUF are supported. FREEDBUF
returns a buffer to the buffer pool assigned to the
specified DCB.
STAE-SVC60
All the options of STAE are supported except for the
XCTL option, which is set to XCTL=YES; the PURGE
option, which is set to HALT; and the ASYICH option,
which is set to NO.
STAE creates, overlays, or
cancels a STAE control block as requested. STAE retry
is not supported.
DETACH-SVC62
The DETACH routine in
control to the user.
a NOP.
in CftS is a NOP.
in CftS is a NOP.
CftS
is
It returns control
It returns control
It returns control
a NOP.
It
returns
Part 3: Conversational ftonitor System (CftS)
305
ftacro-SVC No.
ciiiPT-SVC63--
~iii~~~gf~2_i]_!!]le!gB!~!!2B
RDJFCB-SVC64
All the options of RDJFCB are supported.
RDJFCB
causes a Job File Control Block (JFCB) to be read from
a CftS Control Block (CftSCB) into real storage for each
data control block specified. CftSCBs are created by
FILEDEF commands.
SYNADAF-SVC68
All the options of SYNADAF are supported.
SYNADAF
analyzes an I/O error and creates an error message in
a work buffer.
SYNADRLS-SVC68
All the options of SYNADRLS are supported. SYNADRLS
frees the work area acquired by SYNAD and deletes the
work area from the save area chain.
BSP-SVC69
All the options of BSP are supported.
the item pointer by one block.
TGET/TPUTSVC93
TGET and TPUT operate as if EDIT and WAIT were coded.
TGET reads a terminal line. TPUT writes a terminal
line.
TCLEARQ-SVC94
TCLEARQ in CftS clears the input
returns control to the user.
STAX-SVC96
Updates a queue of CftTAXEs
attention exit level.
NOTE
All the options of NOTE are supported. NOTE returns
the item number of the last block read or written.
POINT
All the options of POINT are supported. POINT causes
the control program to start processing the next read
or write operation at the specified item number. The
TTR field in the block address is used as an item
number.
CHECK
All the options of CHECK are supported.
the
I/O operation
for
errors and
conditions.
DCB
The following fields of a DCB may be specified,
relative to the particular access method indicated:
Q.E~!:~.!!.9
BFALN
BLKSIZE
BUFCB
BUFL
BUFNO
DDNAftE
DSORG
EODAD
EXLST
KEYLEN
LlftCT
LRECL
ftACRF
OPTCD
RECFM
SYNAD
NCP
306
The CHKPT routine is a NOP.
user.
BDA!1
F,D
n (number)
a (address)
n
n
s (symbol)
DA
a
n
n
R,W
A,E,F,R
F,V,U
a
It returns centrol to the
BSP decrements
terminal queue
each of which
defines an
CHECK tests
exceptional
J1g!!1
J12!~
22111
n
R,W
It
n
R,W, P
G,P,L,ft
F,V,U
a
n
F,V,B,S,A,ft,U
a
n
F,V,B,U,A,ft,S
a
F,D
n
a
n
n
s
PO
a
a
F,D
n
a
n
n
s
PS
a
a
n
IBft Vft/370: System programmer's Guide
and
F,D
n
a
n
n
s
PS
a
a
ACCESS METHOD SUPPORT
The manipulation of data is governed by an access method. To facilitate
the execution of OS Code under eMS; the processing program must see data
as as would present it.
Por instance, when the processors expect an
access method to acquire input source cards sequentially, CMS invokes
specially written routines that simulate the OS sequential access method
and pass data to the processors in the format that the OS access methods
would have produced. Therefore, data appears in storage as if it had
been manipulated using an OS access method.
For example, block
descriptor words (BDi), buffer pool management, and v~riable records are
updated in storage as if an OS access method had processed the data.
The actual writing to and reading from the I/O device is handled by CMS
file management.
The essential work of the Volume Table of contents (VTOC) and the
Data set Control Block (DSCB) is done in CMS by a Master Pile Directory
(MFD) which updates the disk contents, and a File Status Table (PST)
(one for each data file). All disks are: formatted in physical blocks
of 800 bytes.
CMS continues to update the OS format, within its own format, on the
auxiliary device, for files whose filemode number is 4. That is, the
block and record descriptor words (BDi and RDi) are written along with
the data. If a data set consists of blocked records, the data is
written to, and read from, the I/O device in physical blocks, rather
than logical records. CMS also simulates the specific methods of
manipulating data sets.
To accomplish this simulation, CMS
for the following access methods:
supports certain essential macros
• BDAM
(direct) -- identifying a record by
position within the data set.
• BPAM
(partitioned) -- seeking a named member within data set.
• SAM
(sequential) -- accessing a record
n~o~o~;nn
r~~~~u~u~
np
V~
~~"n~~~~
~v~~v.~"~
a key or by its relative
in a sequence relative to
~~~~~~~
~~~v~u~.
CMS also updates those portions of the OS control blocks that are
needed by the OS simulation routines to support a program during
execution.
Most of the simulated supervisory OS
the following two CMS control blocks:
control blocks are contained in
CMSCVT
simulates the Communication Vector Table.
the address of the CVT control section.
Location 16 contains
CMSCB
is allocated from system free storage whenever a FILEDEF command
or an OPEN (SVC19) is issued for a data set. The CMS Control
Block consists of a File Control Block (FCB) for the data file,
and partial simulation of the Job File Control Elock (JPCB),
Input/Output Block (lOB), and Data Extent Block (DEB).
The Data Control Block (DCB) and the Data Event Control Block (DECE)
are used by the access method simulation routines of CMS.
Part 3: Conversational Monitor System (CMS)
307
The GET and PUT .acros are not supported for use with spanned
records.
READ and WRITE are supported for spanned records, provided the
file.ode number is 4, and the data set is Physical sequential (BSAM)
format.
GET (OSAM)
All the OSAM options of GET are supported.
Substitute mode is
handled the sa.e as .ove mode. If the DCBRECPM is PB, the file.ode
number is 4, and the last block is a short block, an EOP indicator
(X'61PPPP61')
must be present in the last blo~k after the last
record.
GET (OISAM)
OISAM is not supported in CMS.
PUT (OS AM)
All the QSAM options of PUT are supported.
Substitute mode is
handled the same as .ove mode. If the DCBRECPM is PB, the file.ode
number is 4, and the last block is a short block, an BOP indicator is
written in the last block after the last record.
PUT (QISAM)
OISAM is not supported in CMS.
PUTX
PUTX support is provided only for
with simple buffering.
data sets opened
for QSAM-UPDATE
READ/WRITE (BISAM)
BISAM is not supported in CMS.
READ/WRITE (BSAM and BPAM)
All the ESAM and BPAM options of READ and WRITB are supported except
for the SE option (read backwards).
READ (Offset Read of Keyed EDAM dataset)
This type of READ is not supported
spanned records.
because
READ/WRITE (BDAM)
All the EDAM and BSAM
(create)
options
supported except for the Rand RU options.
it is
of
only used
READ and
WRITB
for
are
The four methods of accessing EDAM records are:
1.
2.
3.
4.
Relative Block R~~
Relative Track TTR
Relative Track and Key TI!ey
Actual Address MBECCBBR
The restrictions on those methods are as follows:
•
Only the EDAM identifiers underlined above can be used to
records, since CMS files have a two-byte record identifier.
•
CMS BDAM files are always created with 255 records cn the first
logical track, and 256 records
on all other logical tracks,
regardless of the block size.
If BDAM methods 2, 3, or 4 are used
and the RECPM is U or V, the BDAM user must either write 255 records
308
IBM VM/310: System Programmer's Guide
refer to
on the first track and 256 records on every track thereafter, or he
must not update the track indicator until a NO SPACE FOUND message is
returned on a write. For method 3 (WRITE ADD), this message occurs
when no more dummy records can be found on a WRITE request. For
methods 2 and 4i this will not occur i and the track indicator viII be
updated only when the record indicator reaches 256 and overflows into
the track indicator.
•
Two files of the same filetype, which both use keys, cannot be open
at the same time. If a program that is updating keys dces not close
the file it is updating for some reason, such as a system failure or
another IPL operation, the original keys for files that are not fixed
format are saved in a temporary file with the same filetype and a
filename of $KEYSAVE. To finish the update, run the program again.
•
Once a file is created using keys, additions to the file must not be
made without using keys and specifying the original length.
•
The number of records in the data set extent must be specified using
the FILEDEF command. The default size is 50 records.
•
The minimum LRECL for a CMS BDAM file with keys is eight bytes.
READING OS DATA SETS AND DOS FILES
CMS users can read, but not write or update, OS sequential and
partitioned data sets that reside on OS disks. The CMS MOVEFILE command
can be used to manipulate those data sets, and the OS QSAM, BPAM, and
BSAM macros can be executed under CMS to read them.
The CMS MOVEFILE command and the same OS macros can also be used to
manipulate and read DOS sequential files that reside on DOS disks. No
DOS macros are simulated; the OS macros handle the DOS data as if it
were OS dat a.
The following os Release 20.0 BSAM, BPAM, and QSAM wacros can
with CMS to read OS data sets and DOS files:
BLDL
BSP
CHECK
CLOSE
DEQ
DEVTYPE
ENQ
FIND
GET
NOTE
POINT
FOST
_
Ut::l
.. _ _ _ .!I
U:::it::lU
RDJFCB
READ
SYNADAF
SYNADRLS
WAIT
CMS supports the following disk formats
sequential and partitioned access methods:
•
•
•
•
L
for
the
OS
and
OS/VS
split cylinders
user labels
track overflow
alternate tracks
As in OS, the CMS support of the BSP macro produces a return code of
4 when attempting to backspace over a tape mark or when a beginning of
an extent is found on an OS data set or a DOS file. If the data set or
file contains split cylinders, an attempt to tacks pace within an extent
resulting in a cylinder switch, also produces a return code of 4.
Part 3: Conversational Monitor System (CMS)
309
Before CMS can read an OS data set or DOS file that resides on a non-CMS
disk, you must issue the CMS ACCESS command to make the disk on which it
resides available to CMS.
The format of the ACCESS command is:
ACCESS cuu moder/ext]
You must not specify options or file identification when accessing an OS
or DOS disk.
you then
issue the
FILEDEF command to
assign a
CMS file
identification to the OS data set or DOS file so that CMS can read it.
The format of the FILEDEF command used for this purpose is:
r-------------------------------------------------------------------------,
,
r
r
r
FILEDEF
{dd;:me}
"
I DISK fn ft I fmll IDSN ?
I
I
IA111 IDSN q1 [q2···]1
L
L
.J.J
L
.J
r
r
"
L
L
.J.J
DISK Ifn
ft
Ifm II
IFILE ggJ}~'!!!~ IAjl1
DUMMY
r
~~1~1ed ~E!i9~:
,
IMEMBER membernamel
ICONCAT
I
L
.J
If you are issuing a FILEDEF for a DOS file, note that the OS program
that will use the DOS file .ust have a DCB for it. For "ddname" in the
FILEDEF command line, use the ddname in that DCB. with the DSN operand,
enter the file-id of the DOS file.
Sometimes, CMS issues the FILEDEF command for you. Although the CMS
MOVEFILE command, the supported CMS program product interfaces, and the
CMS OPEN routine each issue a default FILEDEF, you should issue the
FILEDEF command yourself to be sure the appropriate file is defined.
After you have issued the ACCESS and FILEDEF commands for an OS
sequential or partitioned data set or DOS sequential file, CMS commands
(such as ASSEMBLE and STATE) can refer to the OS data set or DOS file
just as if it were a CMS file.
Several other CMS commands can be used with OS data sets and DOS
files that do not reside on CMS disks. See the VMLll~: ~Qm!~g b~~g~~g~
Q~!g~ !Q!
§~~~!~1 Q§~!§ for a
complete description of the CMS ACCESS,
FILEDEF, LISTDS, MOVEFILE, QUERY, RELEASE, and STATE commands.
For restrictions on reading OS data sets and DOS files under eMS, see
the "VM/370 Restrictions" in "Part 1. Debugging with VM/370".
310
IBM VM/370: System Programmer's Guide
THE FILEDEF CCMMAHD
The CMS FILEDEF command allows you to specify
file characteristics to be used by a program
conjunction vith the OS simulation scheme,
functions of the Data Definition JCL statement.
FILEDEF
functions.
filedef
may be used
For example:
filel
disk
only
proga
with
data
programs
the I/O device and the
at execution time. In
FILEDEF simulates the
using
OS
macros
and
al
After issuing this command, your program referring to FILEl would access
PROGA DATA on Jour A-disk.
If you wished to supply data from
issue the command:
your terminal for FILE1, you could
filedef filel terminal
and enter the data for your program without recompiling.
fi tapein tap2 (recfm fb lrecl 50 block 100 9track den 800)
After issuing this command, programs referring to TAPEIH will access a
tape at virtual address 182.
(Each tape unit in the CMS environment has
a symbolic name associated with it.) The tape must have been previously
attached to the virtual machine by the VM/370 operator.
The AUXPROC option can only be used by a program call to FILEDEF and not
from the terminal. The CMS language interface programs use this feature
for special I/O handling of certain (utility) data sets.
The AUXPROC option, followed by a fullword address of an auxiliary
processing routine, allows that routine to receive control from DftSSEB
before any device I/O is performed. At the completion of its processing,
the auxiliary routine returns control to DMSSEB signalling whether I/O
has been performed or not. If not, DMSSEB performs the appropriate
device I/O.
GPR15 is used by the auxiliary processing routine to inform to DMSSEB
of the action that has been or should be taken with the data block as
follows:
GPR15=0
Ho I/O performed by AUXPROC routine; DMSSEB will perform I/O.
GPR15(0
I/O performed by AUXPROC routine
DMSSEB will take error action.
GPR15)O
I/O performed by AUXPROC routine with residual count in GPR15;
DMSSEB returns normally.
and error
was encountered.
Part 3: Conversational Monitor System (CMS)
311
Saving the eMS System
Only named systems can be saved. The BAMESYS macro must be used to name
a system. A discussion on creating a named system is found under
"Generating Bamed System" in "Part 2: Control Program (CP)".
The DMKSBT module must have been configured (by coding the BAMESYS
macro) when CP was generated. The DMKSNT module contains the system
name, size of the system, and its real disk location. The CMS system
aay be saved by entering the command 'SAVESYS name' as the first command
after the IPL command (that is,
after the CMS version identification is
displayed),
where 'name' is the name to be assigned to the saved
system.
The CMS S, D, and Y disks (and, optionally, the A disk)
should be
mounted and attached to the virtual machine creating the saved system
before the SAVESYS command is issued.
This ensures that the CMS file
directory is saved correctly.
The status of the saved system proceeds, upon a subsequent IPL, as if
an IPL of a specific device had occurred, with the single exception that
the file directory for the system disk is part of the nucleus.
There are several coding restrictions that must
is to run as a Saved system.
he imposed on CMS if it
The first and most obvious one is that CMS may never modify
segment 1. The shared segment runs with a real storage key of 0,
although the virtual storage key equals F.
A less obvious, but just as important, restriction, is that CMS may
never modify, with a single machine instruction (except MVCL), a section
of storage which crosses the boundary between two pages with different
storage keys.
This restriction applies not only to SS instructions,
such as MVC and ZAP, but also to RS instructions, such as STM, and to RX
instructions, such as ST and STD, which may have nonaligned addresses on
the System/370.
It also applies to I/O instructions. If the key specified in the CCW
is zero, then the data area for input may not cross the boundary between
two pages with different storage keys.
It is not advisable to use the CMS DEBUG command or the CP commands
to debug a named system with shared pages because it is impossible to:
•
•
store into shared pages.
Address stop in shared pages.
IPL a CMS system with no shared pages and then
tools while executing.
use the VM/370 debug
If you intend to modify a shared eMS system, be sure that all code
that 1S to he shared resides in the shared segment, CMS Nucleus
(X'10000'-X'20000').
To make room for additional code in the CMS
Nucleus, you may have to move some of the existing code.
You can use
the USERSECT area of DMSNUC to contain nonshared instructions.
312
IBM VM/370: System Programmer's Guide
eMS Batch Facility
The CftS Batch Facility is a Vft/370 programming facility that runs under
the CftS subsystem.
It allows Vft/370 users to run their jobs in batch
mode by sending jobs either fro. their virtual machines or through the
real (system) card reader to a virtual machine dedicated to running
batch jobs. The Batch Facility then executes these jobs, freeing user
machines for other uses.
If both CftS Batch Facility and the Remote spooling Communications
subsystem (RSCS) are running under the same Vft/370 system,
job input
streams can be transmitted to the Batch Facility from remote stations
via communication lines. Also, the output of the batch processing can be
transmitted back to the remote station. For additional information, see
"Remot~
Job Entry to CftS Batch" in the !1!Ll1Q: .!!~~2~ .§2QQ!!!!g
~2~!~i~~ti~!§ ~!bSI§!~!
(R~£~)
Us~£~ Q~!de.
The Batch Facility virtual machine is generated and controlled on a
userid dedicated to execution of jobs in tatch mode.
The system
operator generates the "batch machine" by loading (via IPL) the CftS
subsystem, and then issuing the CftSBATCB command.
The CftSBATCB module
loads the DftSBTP TEXT S2 file which is the actual Batch processor.
After each job is executed, the Batch Facility will IPL itself, thereby
providing a continuously running batch machine.
The Batch Processor
will IPL itself by using the PARft option of the CP IPL command, followed
by a character string which CftS recognizes as peculiar to a batch
virtual machine performing its IPL. Jobs are sent to the batch
.achine's virtual card reader from users' terminals and executed
sequentially.
When there are no jobs waiting for execution, the Batch
Facility remains in a wait state ready to execute a user job. See the
!1!L.J1.Q: Q.E~~!!.Q~..!.§ §!i,g~ for more information about controlling the
ba tch machine.
The Batch Facility is particularly useful for compute-bound jobs such
as assemblies and compilations and for execution of large user programs,
since interactive users can continue working at their terminals while
their time=consu.ing jobs are run in another virtual machine.
The System Programmer controls the Batch Facility virtual machine
environment by resetting the Batch Facility machine's system limits, by
writing routines that handle special installation input to the Batch
Facility, and by writing EXEC procedures that make the Batch Facility
facility easier to use.
Each job running under the Batch Facility is limited by default to the
maximum value of 32,767 seconds of virtual CPU time, 32,767 punched
cards output, and 32,767 printed lines of output.
You can reset these
limits by modifying the BATLIftIT ftACRO file,
which is found in the
CftSLIB macro library, and reassembling DftSBTP.
The Batch Facility can handle user-specified control language and
special installation Batch Facility /JOB control cards. These handling
Part 3: Conversa tional ftoni tor System (CftS)
313
mechanisms are built into the system in the form of user exits from
Batch; you are responsible for generating two routines to make use of
them. These routines must be named BATEXITl and BATEXIT2, respectively,
and must have a filetype of TEXT and a filemode number of 2, if placed
on the system disk or an extension of the system disk.
(See the !ftL37Q:
~Q!!~n~ 1~ngy~g~ ~Y!~~ !Q£ ~~n~~!! ~~I§ for infor,ation on how to write
and use Batch Facility control cards.)
The routines you write are
responsible for saving registers, including general register 12, which
saves address ability for the Batch Facility. These routines
(if aade
available on the system disk) are included with the Batch Facility each
time it is loaded.
BATEXIT1: PROCESSING USER-SPECIFIED CONTROL LANGUAGE
BATEXITl is an entry point provided so that users may write their own
routine to check non-CftS control sta~ements.
For example, it could be
written to scan for the OS job control language needed to compile, link
edit, and execute a FORTRAN job. BATEIITl receives control after each
read from the Batch Facility virtual card reader is issued.
General
register 1 contains the address of the Batch Facility Read Buffer, which
contains the card image to be executed by the Batch Facility. This
enables BATEXITl to scan each card it receives as input for the type of
control information you specify.
If, after the card is processed by BATEIIT1, general register 15
contains a nonzero return code, the Batch Facility flushes the card and
reads the next card.
If a zero is returned in general register 15, the
Batch Facility cQntinues processing by passing the card to CftS for
execution.
BATEXIT2: PROCESSING THE BATCH FACILITY /JOB CONTROL CARD
BATEXIT2 is an entry point provided so that users can code their own
routine to use the /JOB card for additional information.
BATEXIT2
receives control before the VK/370 routine used to process the Batch
Facility /JOB card begins its processing,
but after CftS has scanned the
/JOB card and built the parameter list. When BATEIIT2 is processing,
general register 1 points to the CftS parameter list buffer. This buffer
is a series of a-byte entries, one for each item on the /JOB card.
If
the return code found in general register 15 resulting from BATEXIT2
procesing of this card is nonzero, an error message is generated and the
job is flushed. If general register 15 contains a zero, normal checking
is done for a valid userid and the existence of an account number.
Finally, execution of this job begins.
You can control
the Batch Facility
procedures. For example, you can use:
virtual
machine
using
EXEC
•
An EXEC to produce the proper sequence of CP/CftS
who do not know CftS com.ands and controls.
•
An EXEC to provide the sequence of commands needed to execute the
most common jobs (assemblies and compilations)
in a particular
installation.
314
IBK Vft/370: System Programmer's Guide
commands for users
For information on how to use the EXEC facility to control the Batch
Facility virtual machine, see the !ALJIQ: ~!~~ y§~~!§ GU~g~.
After each job, the Batch Facility will IPL itself, destroying all
nucleus data and work areas. All disks linked to during the previous
job are detached.
At the beginning of each job, the Batch Facility work disk is
accessed and then immediately erased, preventing the current user job
from accessing files that might remain from the previous job. Because
of this, execution of the PROFILE EXEC is disabled for the Batch
Facility machine.
YoU may, however, create an EXEC procedure called
BATPROF EXEC and store it on any system disk to be used instead of the
ordinary PROFILE EXEC.
The Batch Facility will then execute this EXEC
at initialization time.
Part 3: Conversational Monitor System (CMS)
315
Auxiliary Directories
When a disk is accessed, each module that fits the description specified
on the ACCESS command is included in the resident directory.
An
auxiliary directory is
an extension of the
resident directory,
containing the name and location of certain CftS modules that are not
included in the resident directory. These modules, if added to the
resident directory,
would significantly increase its
size, thus
increasing the search time and storage requirements.
An auxiliary
directory can reference modules that reside on the system (S) disk; or,
if the proper linkage is provided, reference modules that reside on any
other read-only CftS disk. To take advantage of the saving in search
time and storage, modules that are referenced via an auxiliary directory
should not also be in the resident directory. The disk on which these
.odules reside should be accessed in a way that excludes these modules.
To add an auxiliary directory to CftS, the system programmer must
generate the directory, initialize it,
and establish the proper
linkage.
Only when all three tasks are completed, can a module
deicribed in an auxiliary directory be properly located.
GENERATION OF THE AUXILIARY DIRECTORY
An auxiliary directory TEXT deck is generated by assembling a set of
DftSFST macros, one for each module name. The format of the DftSFST macro
is:
,
I
DftSFST
modulename
[,aliasname]
I
.odulename
is the name of the module whose File
information is to be copied.
status Table
aliasname
is another name by which the module is to be known.
(FSi)
INITIALIZING THE AUXILIARY DIRECTORY
After the auxiliary directory is generated via the DftSFST macro, it must
be initialized. The CftS GENDIRT command initializes the auxiliary
directory with the name and location of the modules to reside in an
auxiliary directory. By using the GENDIRT co.mand, the file entries for
a given module are loaded only when the module is invoked. The format
of the GENDIRT command is:
316
IBft Vft/370: System Programmer's Guide
GENDIRT
directoryname
[targetmode]
wh~I~:
directoryname
is the entry point of the auxiliary directory.
targetmode
is the mode letter of the disk containing the modules
referenced in the auxiliary directory. The letter is the
mode of the disk containing the aOdules at execution
time, not the mode of the disk at the initialization of
the directory.
The default value for targetmode is S,
the system disk.
It is your responsibility to determine
the usefulness of this operand at your installation and
to
inform users
of
programs utilizing
auxiliary
directories of the proper accesses.
ESTABLISHING THE PROPER LIIKAGE
The CMS module, DMSLAD, entry point DMSLADAD, must be called by a user
program or interface to initialize the directory search order.
The
subroutine, DMSLADAD, must be called via an SVC 202 with register 1
pointing to the apropriate PLIST.
The disk containing the modules
listed in the auxiliary directory must be accessed as the mode
specified, or implied, with the G!IDIRT command before the call is
issued.
If it is not, the user will receive messages indicating either
'file not found' or 'error reading file'.
The coding necessary for the call is:
LA
SVC
DC
R1,PLIST
202
AL4(error return)
This call must De eXecuted Defore the call to any
be located via an auxiliary directory.
module that
is
to
The PLIST should be:
PLIST
DS
DC
DC
DC
OF
CLS'DMSLADAD'
v (directoryname)
F'O'
The auxiliary directory is copied to nucleus free storage.
The
Active Disk Table (ADT)
for the targetmode expressed or implied with
GENDIRT is found and its file directory address chain (ADTFDA)
is
modified to include the nucleus copy of the auxiliary directory.
A
flag, ADTPSTM, in ADTFLG2 is set to indicate that the directory chain
has been modified.
The address of the nucleus copy of the auxiliary directory is saved
in the third word of the input parameter list and the high order byte of
the third word is set to X'80' to indicate that the directory search
chain was modified and that the next call to DMSLADAD is a clear
request.
Part 3: Conversational Monitor System (CMS)
317
To reset the directory search chain, a second call is made to
O"SLADAO using the modified PLIST.
D"SLADAD removes the nucleus copy of
the auxiliary directory from the chain and frees it. DMSLADAD does not,
however, restore the caller's PLIST to it initial state.
An error handling routine should be coded to handle non-zero return
codes in register 15.
When register 15 contains 1 and the condition
code is set to 2, the disk specified by the targetmode operand of the
GENOIRT command was not accessed as that mode.
When register 15 contains 2 and the condition code is set to 2, the
disk specified by the target mode operand of the GENOIRT command has not
previously had its file directory chains modified, therefore a call to
D"SLADAD to restore the chain is invalid.
Consider an application called PAYROLL consisting of several modules.
It is possible to put these modules in an auxiliary directory rather
than in
the resident directory.
It is further possible to put the
auxiliary directory on a disk other than the system disk.
In this
example, the auxiliary directory will be placed on the Y disk.
First, generate the auxiliary directory TEXT
application using the D"SFST macro:
PAYDIRT
DIRTBEG
DIRTEND
START
DC
DC
EQU
DMSFST
DftSFST
DMSFST
D"SFST
DMSFST
DftSFST
DMSFST
D"SFST
DMSFST
D"SFST
DMSFST
DC
EQU
END
deck for
the payroll
o
F'40' LENGTH OF FST ENTRY
A (DIRTEND-DIRTBEG) SIZE OF DIRECTORY
*
PAYROLL1
PAYROLL2
PAYROLL3
PAYFICA
PAYFEDTX
PAYSTATE
PAYCITY
PAYCREDU
PAYOVERT
PAYSICK
PAYSHIFT
2A(0) POINTER TO NEXT FST BLOCK
*
In this example, the payroll control program
(PAYROLL), the payroll
auxiliary directory (PAYDIRT), and all the payroll modules reside on the
194 disk.
In the payroll control module (PAYROLL), the subroutine D"SLADAD must
be called to establish the linkage to the auxiliary directory. This
call must be executed before any call is made to a payroll module that
is in the PAYDIRT auxiliary directory.
318
IB" V"/370: System Programmer's Guide
PLIST
LA
SVC
DC
R1, PLIST
202
AL4(ERRTN)
DS
OP
CLS'DMSLADAD'
V (PAYDIRT)
P'O'
DC
DC
DC
Next, all payroll modules must have their absolute core-image files
generated and the payroll auxiliary directory must be initialized. In
the example, the payroll control module (PAYROLL) is given a mode number
of 2 while the other payroll modules are given a mode number of 1. When
the PAYROLL program is finally executed, only the files on the 194 disk
with a mode number of 2 will be accessed. This means only the PAYROLL
control program (which includes the payroll auxiliary directory) will be
referenced from the resident directory.
All the other payroll modules,
because they have mode numbers of 1, will be referenced via the payroll
auxilary directory.
The following sequence
of commands will create
the absolute
core-image files for the payroll modules and initialize the payroll
auxiliary directory.
ACCESS 194 A
LOAD PAYROLL PAYDIRT
(now the auxiliary directory is included in the
GENMOD PAYROLL
payroll control module, but it is not yet
initialized.)
LOAD MOD PAYROLL
INCLUDE PAYROLL1
(this sequence of three commands is repeated for
GENMOD PAYRCLL1
each payroll module called by PAYROLL.)
LOADMOD PAYROLL
INCLUDE PAY SHIFT
GENMOD PAYSHIFT
LOAD50D PAYROLL
GENDIRT PAYDIRT Y
GENMOD PAYROLL MODULE A2
When it is time to execute the PAYROLL program the 194 disk must be
accessed as the Y disk (the same mode letter as specified on the GENDIRT
command). Also, the 194 disk is accessed in a way that includes the
PAYROLL control program in the resident directory but not the other
payroll modules. This is done by specifying a mode number of 2 on the
ACCESS command.
ACCESS 194 Y/S
**
Y2
NOw, a request for a payroll module, such
successfully fulfilled.
The auxiliary directory
PAYOVERT will be found on the Y disk.
as PAYOVERT, can be
will be searched and
Note: A disk referred to by an auxiliary directory must be accessed as a
read-only disk.
Part 3: Conversational Monitor System (CMS)
319
Assembler Virtual Storage Requirements
The minimum size virtual machine required by the assembler is 256K
bytes.
However, better performance is generally achieved if the
assembler is run in 320K bytes of virtual storage.
This size is
recoamended for medium and large assemblies.
If more virtual storage is allocated to the assembler, the size of
buffers and work space can be increased.
The amount of storage
allocated to buffers and work space determines assembler speed and
capacity. Generally, as more storage is allocated to work space, larger
and aore complex macro definitions can be handled.
You can control the buffer sizes for the asseabler utility data sets
(SYSUT1, SYSUT2, and SYSUT3) and the size of the work space used during
macro processing, by specifying the BUlSIZI assembler option.
Of the
storage given, the assembler first allocates storage for the ASSEMBLE
and CMSLIB buffers according to the specifications in the DD statements
supplied by the FILEDEF for the data sets. It then allocates storage
for the modules of the assembler.
The remainder of the virtual machine
is allocated to
utility data set buffers
and macro generation
dictionaries according to the BUlSIZE option specified:
BUlSIZE (STD): 37 percent is allocated to buffers, and 63 percent to
work space.
This is the default chosen, if you do not
specify any BUFSIZE option.
BUFSIZE(MIN):
Each utility data set is allocated a single 790-byte
buffer.
The remaining storage is allocated to work
space. This allows relatively complex macro definitions
to be processed in a given virtual machine size, but the
speed of the assembly is substantially reduced.
An overlay structure can be created in CMS
although CMS has no overlay supervision.
in
See the !AL.J70: ~.Q!!!.!!g l!!.!!g'y~~ 2'y!g!! !Q!
descriptions of all the CMS commands mentioned.
two different
Q!!!!!t~!
y~!:§
ways,
for
PRESTRUCTURED OVERLAY
1 prestructured overlay
program is created using the LOAD, INCLUDE and
GENMOD commands. Each overlay phase or segment is a nonrelocatable
core-image module, created by GENMOD. The phases may be brought into
storage with the LOIDMOD command.
320
IBM VM/370: System Programmer's Guide
A (Root Phase)
~------------------_I(-------------Location
xxxxxx
I
I
IC
III
au
I
I
I
Figure 38.
-------1 (.----Location
rei
ID
yyyyyy
I
IE
I
An overlay structure
The overlay structure shown in Figure 38 could be prestructured using
the following sequence of commands (Programs A, B, C, D, and E are the
names of TEXT files; the overlay phases will be named Root, Second,
Third, etc.):
LOAD
GENftOD
GENftOD
LOADftOD
INCLUDE
GEliftOD
GEliftOD
LOADftOD
INCLUDE
GENftOD
AB
ROOT
SECOND
ROOT
C D
THIRD
FOURTH
THIRD
E
FIlTH
(FROft A TO B STR)
(FROft B)
(FROft C TO D)
(FROft D)
(FROft E)
The programmer need not know the storage address where each phase
begins.
A TEXT file can be made to load at the proper address by
reloading earlier phases.
In the foregoing example, the command
sequences, "LOADftOD ROOT/IRCLUDE C D" and "LOADftOD THIRD/INCLUDE E,"
cause TEXT files C, D, and E to load at the proper addresses.
If the root phase contains address constants to the other phases, one
copy of the root must be kept in storage while each of the other phases
is brought in by LOAD or INCLUDE without an intervening GENftOD. The
root phase is then processed by GENftOD after all address constants have
been satisfied.
In this case, the programmer must know the address
where nonroot phases begin (in Figure 38, locations xxxxxx and yyyyyy).
The following sequence of commands could be used:
LOAD
GENftOD
INCLUDE
GENftOD
GENftOD
INCLUDE
GENftOD
LOAD
INCLUDE
INCLUDE
GENftOD
AB
SECORD
C D
THIRD
FOURTH
E
FIFTH
AB
C D
E
ROOT
(FROft B)
(ORIGIN xxxxxx)
(PROft C TO D)
(FROft D)
(ORIGIN IYYYYY)
(FROft E)
(ORIGIN xxx xxx)
(ORIGIN yyyyyy)
(FROft A TO C STR)
Part 3: Conversational ftonitor System (CftS)
321
The ORIGIN option of the INCLUDE command is used to cause the
included file to overlay a previously loaded file. The address at which
a phase begins must be a doubleword boundary. For example, if the root
phase were X'2BD' bytes long, starting at virtual storage location
X'20000', then location xxxxxx would be the next doubleword boundary, or
X'202CO'.
The STR option, which is specified in the GENMOD of the root phase,
specifies that whenever that module is brought into storage with the
LOADMOD command, the storage Initialization routine should be invoked.
This routine initializes user free storage pointers.
At execution time of the prestructed overlay program, each phase is
brought into storage with the LOADMOD command. The phases can call
LOADMOD. The OS macros LINK, LOAD, and XCTL normally invoke the INCLUDE
command, which loads TEXT files. These macros will invoke LOADMOD if a
switch, called COMPSWT, in the CMS Nucleus Constant area, NUCON, is
turned on.
with COMPSWT set, overlay phases that use LINK, LOAD,
be prestructured MODULE files.
and XCTL must
DYNAMIC LOAD eVERLAY
The dynamic load method of using an overlay structure is to have all the
phases in the form of relocatable object code in TEXT files or members
of a TEXT library, filetype TXTLIB. The os macros, LINK, LeAD, and XCTL
may then be used to pass control from one phase to another. The XCTL
macro causes the calling program to be overlayed by the called program
except when it is issued from the root phase. When issued from the root
phase, CMS treats XCTL as a LINK, adding the new code at the end of the
root phase.
The COMPSWT flag in OSSFLAGS must be off when the dynamic load method
is used.
322
IBM VM/370: System Programmer's Guide
Part 4: IBM 3704 and 3705 Communications Controllers
Part 4 describes the procedures a system programmer must follow to load,
test and run a 3704/3705 control program with Vft/370.
Part 4 includes
the following information:
•
•
•
Introduction
trMJ"l,()
.u,~.v
c::.,nn,..r+
~wr~v~~
,..~
~4
+'-0
~u~
"l,()IIJ"l,()~
v'V~'J'VJ
Loading the 3704/3705 Control Program
Testing the 3704/3705 Control Program
Part 4: IBft 3704 and 3705 Communications Controllers
323
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Introduction to the IBM 3704 and 3705 Communications Controllers
The IBM 3704
units. One of
storage:
and 3705 Communications Controllers are programmable
three programs can be generated to execute in 3704/3705
1•
The
Net work Control
Program
(HCP)
performs
ma ny of
the
teleprocessing line control and line servicing functions previously
performed by the central processing unit.
2.
The Emulation program (EP) permits existing teleprocessing systems,
including VM/370, that use the IBM 2701, 2702, or 2703 Transmission
Control units or the Integrated Communications Adapter (ICA) of the
System/370 Model 135, to run without change on the 3704/3705.
3.
The Partitioned Emulation Program (PEP)
allows the 3704/3705 to be
divided so that both the NCP and EP can execute in one 3704/3705.
In this publication, the term "3704/3705 control program is used to
refer to any of the three types of control programs: NCP, EP, or PEP.
VM/370 supports both the:
•
•
IBM 3704 Communications Controller, Models A1-A4
IBM 3705 Communications Controller, Models A1-D8
when attached to an IBM System/370 Model 135, 145, 155 II, 158, 165 II,
or 168.
Four terminals are supported: 1050, 2741, CPT-TWX 33/35, and
3270. You can generate any of three kinds of 3704/3705 control programs
(NCP, EP, or PEP) to run under VM/370. The 3704/3705 must use emulation
mode for the 3270 Information Display Systems.
The minimum amount of 3704/3705 storage required for a NCP or PEP
control program is 48K and the minimum required by an EP control program
is 16K.
The IBM 3704/3705 Communications Controllers can support:
•
•
•
•
•
•
Up to 352 low-speed start-stop lines
Up to 60 medium-speed synchronous lines
Line speeds from 45.2 baud to 50.0K baud
Modem capability within the 3704/3705
Limited-distance "hard-wire" capability.
16K to 240K internal storage
VM/370 supports all three versions of the 3704/3705 control programs:
•
•
•
Emulation Program (EP)
Network Control Program (NCP)
Partitioned Emulation Program (PEP)
VM/370's support of the 3704/3705 does not include:
•
Remote 3704/3705 Communications Controllers
Part 4: IBM 3704 and 3705 Communications Controllers
325
GC20-1807-3 Page Modified by TNL GN20-2662; March 31, 1975
I.
I
Bisynchronous terminals if attached to
mode.
lines in other than emulation
EMULATION PROGRAM (EP) WITH VM/370
The EP 3704/3705 control program under VM/370:
•
•
•
•
Emulates
Attaches
supports
supports
2701, 2702, and 2703 operations
to a System/370 byte-multiplexer channel
up to 255 start-stop lines
up to 50 medium-speed sychronous lines
This support is equivalent to that provided in Release
However, Release 2 of VM/370 provides additional support:
1 of VM/370.
•
Service programs and special CMS commands allow you
generate the EP control program in a CMS virtual machine.
•
The CP NETWORK command allows you to load or dump the 3704/3705 and
provides for automatic dumping and reloading if a fatal error
occurs.
NETWORK CONTROL PROGRAM
to
easily
(NCP) WITH VM/370
The NCP 3704/3705 control program under VM/370 provides:
•
A device-independent EBCDIC interface
•
Communications line control handling
•
Attachment to a
selector channel
•
Block and character checking
•
Block and message buffering
•
Assembly and disassembly of multiple-block transmissions
•
Line error recovery procedures
•
Checkpoint/restart switching to a back-up processor
•
User-written message processor routines
However, when an
of VM/370:
System/370
byte-multiplexer, block-multiplier,
NCP 3704/3705 control program is
or
under the control
•
The CP DIAL command is not supported.
•
The CP TERMINAL APL ON or APL OFF command line is not supported.
If
you issue the TERMINAL APL ON command at a terminal that is connected
to VM/370 on a 3704/3705 line in NCP mode, you will not be able to
execute your program and may have to IPL again to continue.
•
(the Control Program)
NCP resources cannot be shared between VM/370
and the virtual machines.
A virtual 3704/3705 or 2701/2702/2703 is
not supported.
326
IBM VM/370: system Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
•
Special sign-on procedures are required (1)
if you have the Multiple
Terminal Access feature generated for your NCP control program and
(2)
if you have a 2741 terminal on an NCP-mode line.
These
procedures are described 1D "step 11.
Logging un Through the
3704/3705 Control Program" of the "Generating and Loading the
3704/3705 Control Program" section.
A VM/370 nucleus that supports the NCP version of the 3704/3705
control program is smaller than one that supports the EP or PEP
versions.
Each line in NCP mode requires 48 bytes of free storage while
each line in ewulator mode requires 80 bytes of nucleus storage.
PARTITIONED EMULATION PROGRAM (PEP) WITH VM/370
The PEP 3704/3705 control program under VM/370:
•
Combines the 2701/2702/2703 Emulation Program and the Network Control
Program
•
Allows for the concurrent use of NCP and emulator interfaces
•
Provides for programmable switching
emulator mode
of lines
between NCP
mode and
If you execute a PEP control program under the control of VM/370, you
should know that:
•
The CP DIAL command is supported for lines generated as emulator
lines and lines generated to vary between emulator mode and NCP
mode.
If the DIAL command is issued for a line that may be varied
(and,
if that line is currently in NCP mode), that line is
automatically varied to emulator mode.
•
The TERMINAL APL ON or APL OFF command
lines currently in emulator mode.
•
Only 3704/3705 lines in emulator mode may be dedicated.
The VM/370 system that will run
generated with:
line is supported
the 3704/3705 control program
•
An RDEVICE macro describing the 3704/3705.
•
One or more entries for the 3704/3705 control program
Name Table (DMKSNT).
•
Space reserved on a CP-owned
3704/3705 control program.
volume for
only for
must be
in the system
a page-format copy
of the
A detailed discussion on coding the RDEVICE macro, creating an entry
in the system name table, and reserving DASD space for the 3704/3705
control program image can be found in the !~Lll~: g!~nning ~ng ~I21~!
g~~~!~1iQn ~~ig~·
Part 4: IBM 3704 and 3705 Communications Controllers
327
Loading the 3704/3705 Control Program
There are several commands and EXEC procedures to generate and load the
3704/370S control program. These commands and EXEC procedures run in a
CMS virtual machine. The commands are a part of the VM/370 system and
are distributed with it.
A special version of the IBM 3704/370S Network Control Program
support Package for OS/VS, Order No. S744-EA1, is available from PID for
use under VM/370. This version of the 3704/370S package contains two
CMS EXEC procedures for generating and loading the 3704/370S control
programs that are ~Q! available in the standard OS/VS 3704/370S support
package, Order No. S744-AN1.
A step-by-step procedure for generating the 3704/370S control program
can be found in the !~L~lQ: E!~~~!~g ~~g §I2!~! ~~~~!~!l2~§ Guig~. Each
EXEC procedure and command is described as it is used. The action
required at each step is first summarized and then explained in detail.
If the SAVE operand on the GEN370S command was specified during system
generation, the SAVENCP command is automatically executed for you.
If
you did not specify SAVE on the GEN370S command, you must issue the
SAVENCP command yourself.
Note: The VM/310 command privilege class A,
the-SAVENCP command.
S, or C is required to use
THE SAVENCP COMMAND
Use the CMS SAVENCP command to read a 3704/37C5 control program load
module created by the LKED command, and to load it into virtual storage
in the CMS user area.
Once the load has been performed, SAVENCP scans
the control program image and extracts the control information required
by CP. The control information is accumulated in one or more 4096-byte
pages in the CKS user area. When all of the necessary control
information has been extracted, SAVENCP builds the Communications
Controllers Parameter List
(CCPARK) and issues the DIAGNOSE X'SO'
instruction to create the page-format copy of the control program on a
CP-owned volume. The format of the SAVENCP command is:
328
IBK VM/370: System Programmer's Guide
r-----------------------------------------------------------------------~
SAVENCP
fname
[
(options •• [) ]]
.QE!!Q!l§:
r
L
ENTRY ...
co . . . " ' " ...
~lrI1!!I
[
BAftE
fna.!~
~_...,v
[ LIBE
fname
ncpnallel
,
J
]
librarynalle I I!l!]!!! ]
is the filename of the LOADLIB file where the 3704/3705
control program load module resides; unless LIBE is specified,
in which case, it specifies the mellber name of the illage
within the LOADLIB. This name is used as the 'ncpnaae' for
the DIAGIOSE instruction, unless the IAftE option is also
specified.
ENTRY sYllbol
is the external symbol of the entry point in the 3704/3705
control program load module.
The default, CXFINIT, is the
entry point of the standard NCP or PEP control programs. (The
standard entry for the Eaulation prograll is CYASTART.) If the
SAVE option of the GEN3705 command is specified, this symbol
is set in the output EXEC file according to the Stage 2 input
file.
BAftE ncpnalle
is the 'ncpnalle' to be used when the DIAGNOSE parameter list
is built.
The ncpname specified IIUSt match an entry in the
systea nalle table. These entries are created with the IAftEICP
macro when Yft/370 is generated.
LIBE librarynaae
is
~De
filename of
LOADLIB, which
'fname' •
a
load
module library
contains the control
file,
program image
filetype
as member
EXECUTION OF THE SAVEICP PROGRAft
The DIAGNOSE X'50' instruction invokes the CP aodule DftKSIC to:
•
Interpret the parameter list (CCPARft) built by SAVEICP.
•
Check the paralleter specifications against
3704/3705 control program.
•
write the page-format image
appropriate CP-owned volume.
of
the
the NAftENCP aacro for the
control
program
onto
the
The paraaeter list for the DIAGNOSE instruction must start on a
4096-byte boundary. See the Yft/l1Q: ~~I!!£!! jQY!!!l~ Rrogr~ 1Q3~~ for
a description of the CCPARft control block.
Part 4: IBft 3704 and 3705 Communications Controllers
329
When the DIAGBOS! X'50' instruction is executed, the module D~KSBC
searches the DMKSBT module for a NAMENCP macro of the same 'ncpname' as
the one in the CCPAR~ parameter list.
The values specified in the
parameter list are compared to those specified in the BAMENCP macro.
If
any parameters conflict, an error message is displayed at the terminal.
If no error conditions are detected, DftKSNC starts to transfer the
control program image from CMS virtual storage to the CP-owned volume
specified in the NAMENCP macro. Successful completion of this process
completes the generation of a 3704/3705 control program for Vft/370 use.
The 3704/3705 control program is automatically loaded each time the
VM/370 system is loaded, if the CPBAft! operand was specified on the
RDEVICE macro when VM/370 was generated and if the 3704/3705 is online.
If the CPBA~E operand was not coded, you must issue the CP BETWORK LOAD
command line to load a 3704/3705 control program into the 3704/3705
Communications controllers' storage.
THE NETWORK LOAD COMMAND LINE
Use the NETWORK LOAD command to initiate the loading of an NCP, PEP, or
EP control program into a 3704/3705 Communications Controller.
The
format of the BETWORK LOAD command line is:
NETwork
LOAD raddr ncpname
LOAD
initiates the control program load operation.
raddr
is the real address of the 3704/3705 to be loaded.
ncpname
is the name, defined by a
control program image to
specified by 'raddr'.
NAftENCP macro, of the
be
loaded into the
3704/3705
3704/3705
EXECUTION OF THE BETWORK LOAD COMMAND
The NETWORK LOAD command accesses the control program image using the
information in DMKSBT created by the BAMENCP macro. If the 3704/3705
specified in the co.mand is not in an "IPL Required" state at the time
the command is issued, the message:
DMKNET461R CTLR raddr IPL NOT REQUIRED; ENTER "YES" TO CONTINUE:
appears at the terminal.
If the reply to the message is other than
"YES", the command terminates without loading the 3704/3705. Otherwise,
the loader bootstrap routines are written to the 3704/3705 and loading
starts. Vft/370 does not run the "bring-up" test routines as a part of
the load process. If these tests are to be made they must be run from a
virtual machine with the 3704/3705 dedicated.
330
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
When the load of the control program image is complete, the command
processor verifies that the 3704/3705 configuration described by the
control program can be serviced by the VM/370 CP control blocks in
storage. In the case of CPTYPE=NCP (or PEP), this involves creating (or
refreshing) the control list associated with the 3704/3705 RDEVBLOK.
The information necessary to do this is contained in the system pages at
the beginning of the control program image on secondary storage.
SPECIAL CONSIDERATIONS FOR LOADING THE EP 3704/3705 CONTROL PROGRAM
If a 3704/3705 Emulation Program is automatically reloaded after a
3704/3705 failure, the system may loop after the restart. The message
DMKRNH463! CTLR raddr UNIT CHECK; RESTART IN PROGRESS
and two responses
CTLR raddr DUMP COMPLETE
CTLR raddr ncpname LOAD COMPLETE
indicate that the 3704/3705 has been reloaded. If the system loops
after tbe second response, you must reset all emulator lines from the
3704/3705 control panel.
If the automatic dump feature is not enabled, one of the messages
DMKRNH462I CTLR raddr UNIT CHECK; IPL REQUIRED
DMKRNH464I CTLR 'raddr' CC=3; DEPRESS 370X "LOAD" BUTTON
indicates a 3704/3705 abnormal termination.
The 3704/3705 Emulation
Program must be reloaded via the NETWORK LOAD command. If the system
loops when an attempt is made to enable the lines, you must reset all
emulator lines from the 3704/3705 control panel.
The IBM 3704 and 3705 Communications Controllers QE~~~!2f~ ~B1Q~
describes-the-procedure-for-resetting--emulator-lines-from the 3704/3705
control panel in its "Generating Channel End/Device End with Emulator
Program" section.
SPECIAL CONSIDERATIONS
PROGRAMS
FOR LOADING
THE NCP
AND PEP
3704/3705 CONTROL
While the 3704/3705 Emulation Program may be loaded at any time, special
care must be taken when loading a Network Control Program or Partitioned
Emulation program. The NETWORK LOAD command should not be used to load
either an NCP or PEP except at VM/370 system IPL time, unless that same
3704/3705 control program was active just prior to the load (that is,
unless it
is reloaded immediately).
A VM/370
system abnormal
termination (code PTR007) may result if the 3704/3705 is loaded, for the
first time, during normal operation with an NCP or PEP program.
However, if an NCP or PEP 3704/3705 control program must be loaded
during system operation, all resources must first be freed.
If there are active resources, the resources must be disabled and the
NETWORK SHUTDOWN command must be issued before the operator can
successfully issue the NETWORK LOAD command.
Part 4: IEM 3704 and 3705 communications Controllers
331
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Because a 3704/3705 can support emulator-mode lines, NCP-mode lines, and
lines that can be varied to either mode, and can also suppcrt a variety
of terminals,
the procedure for logging on is sometimes complicated.
Use the following procedure to log on to VM/370.
TURN THE POWER ON
First, turn the power on for your terminal and wait 15 to 30 seconds.
CHECK FOR AN ONLINE MESSAGE
Second, look for an online message at your terminal.
If one of the following messages appears at your terminal
vm/370 online
xxxxxx xxxxxx
or
xxxxxx xxxxxx
vm/370 online
your terminal is a 2741 connected to VM/370 via a 2701/2702/2703 line or
via a 3704/3705 line in emulation mode.
You can then proceed with the
normal logon procedure for your type of terminal, as described in
!~L1IQ: !~~~i~~l Us~£~§ ~~i£g·
If the messsage
vm/370 online
appears at your terminal, it is a
2741 connected to VM/370 via a
3704/3705 line in NCP mode without the Multiple Terminal Access feature,
or it is a 1050, or CPT-TWX (Model 33/35) terminal in EP mode.
You can
proceed with the normal logon procedure for your terminal type.
This
procedure is described in the !~L1IQ: 1~~~iD~1 Q2~~~§ QYi~~·
If you receive a message at your terminal in the form
xxxxxx xxxxxx
where the XiS indicate that the message is unintelligible, your terminal
is most likely connected to a 3704/3705 line in NCP mode that is defined
for a different terminal type.
For example, you may have an EBCD
terminal on a line defined for Correspondence terminals.
Use the m (at
sign) character to determine what kind of terminal you are using.
If
the m character is an uppercase 2,
your terminal is a Correspondence
2741; otherwise, it is an EBCD 2741.
If a 2741 terminal is connected to VM/370 via a 3704/3705 line in NCP
mode, you must press the Return key before the "vm/370 online" message
will appear at the terminal.
If a terminal is connected to VM/370 via a
3704/3705 line in NCP mode, and with the Multiple Terminal Access (MTA)
feature, the "vm/370 online" message does not appear at the terminal
and, after approximately 15 seconds, the terminal locks and unlocks.
You must perform a special sign-on procedure tefore continuing with the
normal logon procedure.
332
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
The sign-on procedures for the terminals supported for use with the
3704/3705 under the control of VM/370 are summarized in the following
paragraphs.
If you have any further difficulties accessing VM/370
throuah a 3704/3705. see the VM/370~
Terminal User's Guide and the 3704
and 3705 Gener~tion'andUtiiitI;s-~~lg~-for-complete-descrIptions of-the
procedures-summarized-here:------
SPECIAL SIGN-ON PROCEDURES FOR LINES IN NCP MODE WITH MTA FEATURE
Three sign-on procedures are described: the 2741, 1050, and TWX sign-on
procedures for terminals on lines with thp MT! feature.
Once the
sign-on procedure is completed, the message
vm/370 online
should appear at your terminal.
logon procedure described in the
You
can then proceed with
!~L]l~:
the normal
!er~lB~l Q~~!~~ ~~lg~.
1.
Dial the telephone number of the
communicating with the controller.
2.
When the keyboard unlocks, enter
3.
Press the Return key.
MTA
line
to
be
used
for
I".
If the "vm/370 online" message appears at your terminal, you have signed
on successfully and may proceed with the normal logon. If no message
appears at your terminal but your terminal unlocks, press the Return key
in an attempt to get the "vm/370 online" message.
However, if the type
element moves back and forth,
the sign-on procedure was unsuccessful;
you must repeat steps 2 and 3 of the sign-on procedure.
1.
Dial the telephone number of the
communicating with the controller.
MTA
2.
When the Proceed light comes on, enter
I".
3.
Press the Return key.
4.
Enter EOB.
line
to
be
used
for
If the "vm/370 online" message appears at your terminal, you have signed
on successfully and may proceed with the normal logon. If no message
appears at your terminal but your terminal unlocks, press the Return key
in an attempt to get the "vm/370 online" message.
However, if the type
element moves back and forth,
the sign-on procedure was unsuccessful;
you must repeat steps 2, 3, and 4 of the sign-on procedure.
Part 4: IBM 3704 and 3705 Communications Controllers
333
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
1.
Dial the telephone number of the
communicating with the controller.
2.
Press the WRU (Where Are You)
audible data tone begins.
MTA
line
to
be
key within three seconds
used
for
after the
If the typing mechanism does not "jump" within a few seconds, you have
signed on successfully and may proceed with the normal logon.
If the
typing mechanism does jump, the sign-on procedure was unsuccessful;
press the WRU key again or repeat both steps of the sign-on procedure.
LOGGING ON AFTER AN NCP CONTROL PROGRAM HAS ABNORMALLY TERMINATED
If an NCP 3704/3705 control program
(with the automatic dump and reload
options previously set) abnormally terminates but VM/370 continues to
run, VM/370:
1.
Disconnects all the 3704/3705 users
2.
Dumps the contents of 3704/3705 storage
3.
Reloads the 3704/3705 control program
4.
Enables the lines again
At this point, each user must log on again.
Any user that does not log
on within 15 minutes is logged off the system.
If necessary, it is possible to apply Program Temporary Fixes (PTFs)
directly to the 3704/3705 load library using the VM/370 ZAP Service
Program.
I THE ZAP SERVICE PROGRAM
ZAP is a CMS command that modifies or dumps MODULE, LOADLIB, or TITLIB
files.
It is for use by system support personnel only.
Input control records control ZAP processing.
They can be submitted
either from the terminal or from a disk file.
Using the VER and REP
control records, you can verify and replace data or instructions in a
control section
(CSECT). Using the DUMP control record, you can dump
all or part of a CSECT, or an entire member of a LOADLIB or TITLIB file,
or an entire module of a MODULE file.
The format of the ZAP command is:
334
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March .J......I , 1975
r---------------------------------------------.-----------------------------,
,
'{ MODULE }
,ZAP , LOADLIB [libname 1
! \. TXTLIB ;
,,,
,
I
,,,
•••
libname 3
][
,
,
(option ••• [) ]]
options:
r
, r
,
'I~~~
"PRINT ,
IINPUT filename, I NOPRINT I
,I
L
J L
J
--------'
L
MODULE
LOADLIB
TITLIB
jnd'cates the type of file that is to be modified or dumFed.
libname
is the library name containing the member to be modified or
dumped.
You can specify one to three library names.
The
libname is valid only for LOADLIB and TITLIB files.
r
IJHH1
,
I RR!!I ,
I NOPRINT I
L
J
indicates that input to the ZAP service program is
submitted through the terminal. If you specify TERM, the
prompting message ENTER: is issued, and you can then
enter input control records up to 80 characters long.
If you specify PRINT with TERM, all output prints on the
printer, but
only error
messages display
at the
terminal.
If you specify NOPRINT with TERM, nothing prints on the
printer. All output except control records displays at
the terminal.
r
INPUT filename
,
!PRJ!l !
,NOPRINTI
L
J
specifies
filename.
must be a
accessible
that input is submitted from a disk file,
This file must have a filetype of ZAP, and
fixed 80-byte sequential file residing on any
device.
If you specify PRINT with INPUT filename, all output
produced by the ZAP service program prints on the
printer. In addition, commands and control records in
error and error messages display at the terminal.
If you specify NOPRINT with
prints on the printer. All
terminal.
INPUT filename,
output displays
nothing
at the
Part 4: IEM 3704 and 3705 Communications Controllers
335
GC20-1807-3 Page Modified by TNL GN20-2662. March 31. 1975
The following
combinations:
IOPTIONS
I
I
I
IINPUT
I
I
I
I
I
ITERM
I
,I
table shows
the
resulting
output of
valid
option
NOPRINT
PRINT
Commands and control
records in error and
error messages on the
terminal. Everything
to printer.
Everything on the
terminal. Nothing
on the printer.
Only error messages on
the terminal.
Everything on the
printer.
Everything except
control records
on the terminal.
Nothing on the
printer.
I ZAP INPUT CONTROL RECORDS
Seven types of ZAP control records
VERIFY, REP, comment, and END.
exist:
NAME,
DUMP, BASE,
VER or
ZAP control records are free form and need not start in position one
of the record but the ZAP program can accept only 80 characters of data
for each control record.
Separate all information by one or more
blanks.
All address fields including disp (displacement) fields in VER
and REP control records must contain an even number of hexadecimal
digits, to a maximum of six digits (OD, 02C8, 014318).
Data fields in
VER and REP control records must also contain an even number of
hexadecimal digits, but are not limited to six digits.
If you wish, you
example,
83256482 or
opera tion.
may separate the data anywhere by commas
(for
8325,6482). The commas have no effect on the
The program sets the NOGO switch on if a control record is found to
be in error.
A file cannot be modified once the NOGO switch is turned
on. The next valid NAME record turns the NOGO switch off.
This means
that if the control record is the NAME record, all succeeding records
are ignored until the next NAME, DUMP, or END record.
For any other
error, only REP control records that follow are ignored.
The DUMP control record resets the NOGO switch off. The DUMP control
record must not immediately precede a BASE, VER, or REP control record.
A NAME control record must precede the BASE, VER, and REP control
records (if any) that follow a DUMP control record.
The DUMP control record allows you to dump a portion or all of a
specified control section, or the complete member or module. The format
of the output of the dump is hexadecimal with an EBCDIC translation of
the hexadecimal data.
The DUMP control record is optional.
record is:
336
IBM VM/370: System Programmer's Guide
The format of the DUMP control
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
r-------------------------
I
I
r
IDUMP {membernamet Icsectname [startaddress [endaddress]]
lmodulenamef IALL
I
L
I
I
,
I
I
~
L
membername
is the name of the member to be dumped, or the member
that contains the CSECT(s}
to be dumped. This member
must be found in one of the libraries specified in the
ZAP command line.
However, if the library is a CMS
TXTtlB, its directory does not contain member names.
Therefore, the program ignores the member name (although
you must specify it), and the program searches for the
csectname (which you must specify).
modulename
is the name of the module to be dumped, or the module
that contains the CSECT(s) to be dumped.
If you specify
a module that has no loader table, the program dumps the
entire module.
csectname
is the name of the control secticn that is to be dumped.
If you do not specify csectname, the program dumps only
the first CSECT.
The csectname is required for CMS TXTLIBs, optional for
OS TXTLIEs, LOADLIBs,
and
MODULE files.
(See the
discussion of csectname under "Name control Record.")
You must not specify csectname
the NOMAP option.
for a module created with
ALL
specifies to the program to dump all CSECTs within the
specified member or module.
You can specify ALL for
MODULE files, LOADLIBs, and OS TEXTLIBs, but not for CMS
TXTLIBS. If you wish to dump all the CSECTs in a member
of a CMS TXTLIB, you must issue a separate DUMP control
record for each CSECT.
startaddress
is the location within the specified CSECT where the dump
is to begin. This must be two, four, or six hexadecimal
digits.
The start address is the displacement from the beginning
of the CSECT.
For example, if you wish to start dumping
at address 08 in a CSECT that begins at location 400, you
specify start address or 08, not 0408.
endaddress
is the last address to be dumped.
This must be two,
four, or six hexadecimal digits.
If you specify no
address, the program dumps the rest of the CSECT.
Note
that start and end addresses apply only when you specify
a csectname.
If the file to be dumped contains undefined areas (such
as a DS in a TXTLIB member), the hexadeGimal portion of
the
dump contains
blanks
to
indicate that
the
corresponding positions are undefined.
Part 4: IBM 3704 and 3705 Communications Controllers
336.1
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
The NAME control record specifies the member or module and CSECT that
contain the data to be verified or replaced by the ZAP operation. The
format of the NAME control record is:
r
I
I
I
I
NAME
membername } [csectname]
{ modulename
L
membername }
{ modulename
is the member or module that you want to be searched for the
desired CSECT.
csectname
is the name of the desired control section.
You must
specify csectname if the CSECT you wish to modify is in a
CMS TITLIB
(that is, TITLIB created by the TITLIB command
from CMS TEIT decks that do not have a NAME card following
the END card).
The directory of a CMS TITLIB contains only CSECT names and
no member names.
The CSECT name specified in the NAME
record is compared with CSECT names in the directory. If a
CSECT match is found and no member name match is found, the
member selected is the one that contains the CSECT name.
The csectname is optional if the CSECT you wish to modify 1S
a LOADLIB or an OS TITLIB (that is, a TITLIB created by the
TITLIB command from CMS TEIT decks that have a NAME card
after the END card). The dictionaries of the specified
libraries are searched for the member name and the member is
then searched for the CSECT name,
if you specified one. If
you do not specify csectname for a LOADLIB or an OS TITLIB,
the program uses the first control section.
The csectname is optional for a MODULE file.
The module
named in the NAME control record is located and, if you
specified csectname, the first record is read to determine
the number of records in the module and the availability of
a loader table, which the program can then search for the
csectname.
If you do not specify csectname, the program uses the
beginning location of the module.
You are not allowed to
specify csectname if the module was created with the NOMAP
option.
The NAME control record must precede the EASE, VER, and REP
control records.
If it does not, the program sets the NOGO
switch on.
The BASE control record adjusts displacement values for subsequent VER
or REP control records for a CSECT whose starting address is not
336.2
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
location zero
record is:
in an assembly listing.
The format of the
BASE control
r-----------------------------------------
I
I
I
address
BASE
'-------
address
is the starting address of the CSECT.
two, four, or six hexadecimal digits.
The
-..::11..::11----
d.UU!"~::>::>
must be
For example, for a CSECT starting at location 400, you would
specify the BASE 0400 in the BASE control record. If a
subsequent VER card requests verification of location 0408,
the BASE of 0400 is subtracted from 0408, and the program
verifies lecation 08 in the CSECT. This example applies if
you specify TITLIB,
LOADLIB, or MODULE and the module map is
present.
However, if no module map is present for a MODULE file (that
is, the module was generated with the NOMAP option), then all
operations are performed as if the BASE address is location O.
For example, if you specify a BASE of 400 and the address you
wish to inspect or modify is 408, then you must specify 08 and
not 408 in REP and VER control records.
The address in this
case is from the start of the module.
If you do not specify
csectname in the NAME control record, you cannot specify any
BASE value other than 00.
The BASE control record is optional.
See the discussion under
"VER or VERIFY Control Record."
If specified, the BASE
control record must follow the NAME record, but it need not
follow the NAME record immediately.
For example,
you could
have the following sequence of control records: NAME,
VER,
REP, BASE, VER, REP.
The VER control record requests verification of instructions or data
within a CSECT.
If the verification fails, the program does not perform
a subsequent REP operation until it encounters another NAME control
record.
The VER control record is
follow a single NAME record.
optional.
More
than one VER
record can
The format of the VER control record is:
r-
I
I
I
I
------------------------------- ------------,I
VERIFY}
{ VER
disp
data
'------_.
Part 4: IBM 3704 and 3705 Communications Controllers
I
I
I
336.3
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
disp
is the hexadecimal displacement of the data to be inspected
from the start of the CSECT, if you did not submit a BASE
control record for this CSECT.
If you did submit a BASE
control record, then disp is the actual location of the data.
The disp must be two, tour, or six hexadecimal digits. This
displacement does not have to be aligned on a fullword
boundary. If this displacement value is outside the limits of
the CSECT specified by the preceding NAME control record, the
VERIFY control record is rejected.
data
is the data against which the data in the CSECT is to be
compared. This must be an even number of hexadecimal digits.
For example, if the location you wish to verify is 3CC, and
the CSECT begins at location 2BO, you can either issue:
BASE 02BO
VER 03CC data
or you can omit the BASE control record, subtract the CSECT
start address from the address of the data, and issue:
VER 011C data
This also applies
record.
to the
disp
operand of
the REP
control
The REP control record modifies instructions or data at the specified
location within the CSECT that you specified in a preceding NAME control
record. The data specified in the REP control record replaces the data
at the CSECT location specified by the disp operand. This replacement
is on a "one-for-one" basis; that is, one byte of data defined in the
control record replaces one byte of data at the location that you
specified.
If the replacement fails, the program does not perform
additional REP operations until it encounters another NAME control
record.
The REP control record is
follow a single NAME record.
336.4
optional.
More
IBM VM/370: System Programmer's Guide
than one REP
record can
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
The format of the REP control record is:
,
I
I
II
REP
disp
I
I
!
data
L _____________
-J
disp
is the hexadecimal displacement of the data to be replaced
from the start of the CSECT, if you did not submit a BASE
control record for this CSECT.
If you did submit a BASE
control record r then disp is the actual location of the data.
The disp must be two, four, or six hexadecimal digits. This
displacement need not address a fullword boundary.
If this
displacement value is outside the limits of the CSECT being
modified, the program does
not perform the replacement
operation.
data
is the data that is to replace the data in the
must be an even number of hexadecimal digits.
~Q!g:
Although you do not have to
aata, you should do so to make sure
you expect it to be.
CSECT.
This
verify a location before replacing
that the data being changed is what
The ZAP program ignores comment control records. If the PRINT option is
in effect, the program prints the comments.
The format of a comment
record is:
r----------
I
I
*
comment
You must follow the asterisk with at least one tlank.
The END control record ends ZAP processing.
The END record is required
and must be the last control record.
The format of the END control
record is:
r----------
I
I END
IL-__________
Part 4: IBM 3704 and 3705 Communications Controllers
336.5
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
I SPECIAL CONSIDERATIONS FOR USING THE ZAP SERVICE PROGRAM
Before you use the ZAP command against MODULE files, you can
MODMAP command to determine whether a module map exists and
contains.
use the
what it
When a ZAP input file has more than one pair of VER and REP control
records and a VER control record (other than the first) fails, you must
remove the records prior to the failing record and correct the error
before you 1ssue the ZAP command again. Otherwise, the file being
modified returns to its original status.
If you issue REP control record against a file that contains an
undefined area (for example, a Define storage area) within the REP data
field and do not issue a VER control record prior to the REP control
record, the bytes prior to the undefined area, if any, are modified and
all the bytes after the undefined area are not modified.
The program
prints warning message DMSZAP248W.
336.6
IBM VM/370: System Programmer's Guide
Testing the 3704/3705 Control Program
After you have generated a 3704/3705 control program, loaded it, and
logged on, you aay want to test the 3704/3705 control program. Several
CP commands are provided to control the operation, check the status, and
dump the contents of the 3704/3705. The NETWORK command loads and dumps
any 3704/3705 control program.
It also controls the operation of NCP
and PEP 3704/3705 control programs, while the existing CP commands
(ENABLE, DISABLE, QUERY, DISPLAY, VARY,
and BALT)
provide similar
support for EP 3704/3705 control programs. The NCPDUMP command formats
and prints a dump of 3704/3705 storage.
ijse these commands to test the
3704/3705 control program.
The CP NETWORK command loads, dumps, and controls the operation
3704/3705 control program in the VM/370 environment. NETWORK:
•
Causes 3704/3705 dump operations
•
Initiates 3704/3705 load operations
•
Enables or disables terminal resources
•
Varies resources on or offline
•
Alters the
resource
operating mode
of a
Partitioned Emulation
of a
Program line
= Halts a particular resource
•
Ceases all 3704/3705 operations
•
Queries and displays 3704/3705 resource status and storage
•
Traces line activity to and from a 3704/3705 resource
BOW TO USE THE NETWORK COMMAND
When using the NETWORK command to control the operation of the 3704/3705
Network Control Program (ICP), or the NCP portion of the Partitioned
Emulation Program (PEP), the operator must be aware of the different
classes of resources which are defined at generation time for the
3704/3705 control program.
When operating with a 2701/2702/2703 or an Emulation Program (EP),
there is only a single reference for each logon device, and that is the
physical subchannel address for the telecommunications line.
When
operating with the NCP, the line is a separate entity, and the actual
logon device is the terminal, which is also separately addressable. For
Part 4: IBM 3704 and 3705 Communications Controllers
337
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
a simple leased line configuration, there is one resource 10 for each
line, and one resource ID for each terminal (one terminal per line),
alternating in numeric value.
The majority of the NETWORK command operations are performed for
terminal resources.
For example, NETWORK ENABLE, DISABLE, QUERY, HALT,
VARY ONLINE,
and VARY OFFLINE all operate for terminals.
The NETWORK
QUERY command line can be used to display the status of a line resource,
but only when the 'NETWORK QUERY resource' command format is used. The
possible states of a line resource are:
•
•
•
OFFLINE (that is, inactive)
ACTIVE
EP-MODE (PEP only)
While the NETWORK VARY ONLINE and VARY OFFLINE command lines may be used
for a line resource, they are primarily intended for use with terminal
resources, because the state of the line changes automatically if the
terminal is enabled or disabled. Also, NETWORK VARY EP and VARY NCP are
valid only for line resources, and in this case the terminal resources
change state when the line changes state.
The only way to tell which resources are lines and which are
terminals is to examine the output from the first stage of the 3704/3705
control program generation.
The installation system programmer
(or
whoever performs the 3704/3705 control program generation), should
prepare a cross-reference list of resource IDs and their characteristics
(such as, line or terminal, type of line, location, and so on) for the
operations personnel.
In summary, use
NETWORK
NETWORK
NETWORK
NETWORK
NETWORK
NETWORK
ENABLE
DISABLE
QUERY ACTIVE
QUERY FREE
QUERY OFFLINE
QUERY ALL
for terminals only.
Use
NETWORK VARY EP
NETWORK VARY NCP
NETWORK TRACE resource
for lines only.
NETWORK
NETWORK
NETWORK
NETWORK
And, use
QUERY resource
HALT
VARY ONLINE
VARY OFFLINE
for lines or terminals.
The format of the class A NETWORK command is:
---,
r
I NETWORK
I
I
I
I
338
HALT resource
r
,
SHUTDOWN Iraddrl
I !11 I
L
J
IBM VM/370: System Programmer's Guide
I
I
I
I
I
GC20-1807-3
HALT resource
r
by
March 31, i975
attempts to terminate any active channel prcgram on the
specified resource
(line or terminall _ "resource" 1S a
4-digit hexadecimal identity of a 3704/3705 resource.
The last three digits are the actual NCP resource ID.
The first digit is a device sequence number associated
with a particular 3704/3705. This device sequence number
designates the relative position of the device in the
DMKRIO module:
the first 3704/3705 listed has a device
sequence number 0, the second listed has a device
sequence number 1, and so on.
,
SHUTDOWN Iraddrl
I !11 I
ceases all telecommunications on 3704/3705 Communications
Controllers. "raddr" is the real address of a 3704/3705.
When "raddr" is specified, telecommunications are stopped
on only the specified 3704/3705.
When ALL is specified,
telecommunications are stopped on all 3704/3705s.
No attempt is made to preserve line status or messages in
the 3704/3705.
Any virtual machines that depend on a
3704/3705 for which the SHUTDOWN command is issued are
placed in a disconnected state.
The normal response is:
DEVICE HALTED
This response indicates that VM/370 has
halt the device.
attempted to reset
status and
The normal response is:
COMMAND COMPLETE
Part 4: IBM 3704 and 3705 Communications Controllers
339
GC20-1807-3 Page Mooified by TNL GN20-2662, March 31, 1975
The format of the class A and B NETWORK command is:
r-
NE'IWORK
LeAD raddr ncpname
DUMP raddr
r
,
I!~~~~I
10FF I
IAUTO I
.J
L
r
ENable
,
1!11
1
Iresource [resource ••• ]1
L
J
r
,
DISAble IALL
I
Iresource [resource ••• ]1
L
.J
,
r
1!~l!Y~
Query
I
I
I
I
1OFF line
IFREe
IALL
Iresource [resource ••• ]1
.J
L
r
r
"
Display raddr hexloc 1 I{ -} I hexloc 2 I
I : I]!!]
I
L
I
r
VARY
l
I{ •
I
.J
,
11 bytecount I
I
I]!!]
L
L
I
I
I
I
I
I I
.J
.J
resource [resource ••• ]
ONline )
OFFline)
EP
NCP
r
POLLdlay nnnn
,
I
Iraddrl
1!11
L
L-. _ _ _ __
.J
LOAD raddr ncpname
loads an NCP,
PEP, or EP 3704/3705 control program.
"raddr" is the real address of the 3704/3705 to be
loaded.
"ncpname" is the name, previously defined by a
NAftENCP macro and saved on a CP volume, of the 3704/3705
control program image to be loaded into the 3704/3705
specified by "raddr".
DUftP raddr
r
,
I!~~~]I
10FF I
IAUTO I
L
.J
dumps the contents of 3704/3705 storage for NCP, PEP, or
EP 3704/3705 control programs.
"raddr" is the real
address of the 3704/3705 to be dumFed.
IMMED specifies that the 3704/3705 is to be dumped
immediately.
See the "NETWORK Dump Operations" section
340
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by
in
the
!~LJ1Q:
information.
Q~~I~!QI~§
,.,.,')(\_')!t:!t:')
Ul1LV-LUUL,
March
for
"l1
oJ
I,
1975
additional
OFF specifies that the 3704!170S is not to be dumped
automatically if the 3704/3705 control program abnormally
terminates.
AUTO specifies the automatic dumping and reloading of the
3704/3705 if the 3704/3705 control program abnormally
terminates.
r
,
ENABLE IALL
I
,resource [resource ••• ]1
L
J
activates 3704/3705 resources (terminals only) and remote
3270 resources for use by VM/37C. ALL enables all the
available
resources.
Resources
may
be
enabled
selectively
by specifying
the 4-digit
hexadecimal
identity of the terminal resource to be enabled.
The
last three digits are the actual KCP resource ID. The
first digit is a device sequence number associated with a
particular 3704/3705.
This device
sequence number
designates the relative position of the device in the
DMKRIO module: the first 3704/3705 listed has a device
sequence number 0, the second listed has a device
sequence number 1, and so on.
The resource specified must be a terminal device and
formats the display station screen for remote 3270
terminals. The NETWORK ENABLE command first ensures that
the associated line resource is activated, and then
enables the terminal device.
Response from the enabled
terminal devices causes the "vm/370 online" message to
appear on the terminal.
r
,
DISABLE 1!11
I
,resource [resource ••• ],
L
J
disables 3704/3705 resources (terminals only) and remote
3270 resources.
ALL disables all 3704/3705 terminals.
To disable selective resources, specify the 4-digit,
hexadecimal identity of the terminal resources to be
disabled.
The last three digits are the actual NCP
resource ID. The first digit is a device sequence number
associated with a particular 3704/3705.
This device
sequence number designates the relative position of the
device in the DMKRIO module: the first 3704/3705 listed
has a device sequence number 0, the second listed has a
device sequence number 1, and so on.
If any of the resources specified on the NETWORK DISABLE
command are in use at the time the command is issued,
they are not immediately disabled. However, as scon as
the resource becomes free (usually after a LOGOFF command
is issued), the resource is automatically disabled.
Part 4: IEM 3704 and 3705 Communications Controllers
341
GC20-160,-3
Pdy~
MoJified Ll TNL GN20-2662, MarcL ......
J
I ,
,
r
QUERY 1!£1!!1
IOFFLINE
IFREE
IALL
Iresource [resource •••
1
1
1
1
]1
.J
L
displays the status of 3704/3705 resources (lines
terminals) and remote 3270 resources.
or
ACTIVE displays only the resources (terminals, display
and printer staticlls)
that are active (those being used
by VM/370 users).
OFFLINE displays only resources (terminals, display and
pr inter stations)
tha t a r e not available to VM/370
users.
FREE displays only resources
(terminals, display
printer stations) that are not offline and also
currently in use.
and
not
ALL displays all the resources
(terminals only)
of all
the 3704/3705s and all the resources (display and printer
stations) of all the 3271/3275 control units.
"resource" displays
only the
resources
(lines
or
terminals)
whose 4-digit,
hexadecimal identity
is
specified.
The last three digits are the actual NCP
resource ID. The first digit is a device sequence number
associated with a particular 3704/3705.
This device
sequence number designates the relative position of the
device in the DMKRIO module: the first 3704/3705 listed
has device sequence number 0, the second listed has
device sequence number 1, and so on.
r
"
}I
hexloc21
1
1 : I]ND
1
1
r
DISPLAY raddr hexloc1 1{1
L
1
r
I
.J
,
1
1{. }1bytecount 1 1
1
L
I~!~
L
I I
.J
.J
displays the contents of 3704/3705 storage. The data is
displayed in
full words.
No EBCDIC
translation is
provided.
"raddr" is the real address of the 3704/3705 whose
storage is to be displayed.
"hexlocl" specifies the
hexadecimal address of the start of the display and must
be specified. To display more than one fullword, -, : or
• must be specified.
"hexloc2" specifies the hexadecimal
location of
the end of the
display.
"bytecount"
specifies the number of bytes to be displayed.
END
indicates that the display will continue until the end of
storage is reached and is the default if "hexloc2" or
"bytecount" are not specified.
342
IBM VM/370: System Programmer's Guide
GC20-1807~3
Page Modified by TNL GN20-2662, March 31, 1975
\
VARY
\
ONLINE
resource [resource ••• ]
OFFLINE (
):~p (
\
)
varies the status of specified
3704/3705 resources or
changes the operational mode of a PEP 3704/3705 control
program.
ONLINE places a resource
(line or terminal)
online;
OFFLINE places
a resource
(line cr terminal)
offline.
EP changes the operational mode of the PEP
3704/3705 resource
(line only)
to emulation mode.
NCP
changes
the
resource
(line only) to NCP mode.
operational
mode
of
the
PEP
3704/3705
"resource" is a 4-digit hexadecimal identity.
The last
three digits are the actual resource ID~
The first digit
is a device sequence number associated with a particular
3704/3705. This device sequence number designates the
relative position of the device in the DMKRIO module: the
first 3704/3705 listed has a device sequence number 0,
the second listed has a device sequence number 1, and so
on.
POLLDLAY
r
,
nnnn IALL
1
jraddrj
L
.J
changes the duration of the polling delay interval for
the bisync line to the value of nnnn.
The address of the
bisync line is raddr and nnnn is the decimal number in
tenths of a second (not to exceed 9999)
for the polling
delay interval.
If ALL is specified, the polling delay
interval is set for all the 3270 remote lines.
The polling delay interval that
generation is two seconds.
is
defined at
system
!Q!~:
The polling delay interval is that period of time
from the time a bisync line receives a negative response
from a general polling sequence until the polling delay
interval expires, or a message is sent to the station on
the bisync line.
The polling delay interval minimizes unproductive polling
and CPU meter time.
In general,
if no data or other
communications is being received from the stations on the
bisync line,
the polling delay interval is started and
control is given to the dispatcher.
Part 4: IBM 3704 and 3705 Communications Controllers
342.1
!~!l!QBK I!Q!~
CTLR raddr ncpname LOAD CO"PLETE
The 3704/3705 'raddr'
program 'ncpname'.
was successfully
loaded
with the
control
!~!]QBK ~JHH~
CTLR raddr DUMP COMPLETE
The 3704/3705 'raddr' was successfully dumped.
The normal response is:
The normal response is:
DEVICE HALTED
!~!j.Q!L~ .2.!!I~.!
DEV
DEV
DEV
DEV
rid
rid
rid
rid
LOGON AS userid
DISABLE
ENABLED
OFFLINE
LINE rid ACTIVE
LINE rid EP-"ODE raddr
LINE rid OFFLINE
DEV ridl ENABLED, DEV rid2 ENABLED, DEV rid3 ENABLED, •••
... ..:
1
.L..L.U I
DEV rid2 DISABLE, DEV rid3 DISABLE, •••
DEV ridl OFFLINE, DEV rid2 OFFLINE, DEV rid3 OFFLINE, •••
DEV
~
n'T~"''"''"r.I
JJ..L~alJJ...D,
LOGON
indicates that the resource is in use as
machine operator console, by 'userid'.
DISABLE
indicates that the resource is
available for access to V"/370.
ENABLED
indicates that the resource is
to V"/370.
ACTIVE
indicates that the line resource is online and has been
activated. Terminals on the line mayor may not be in
use.
EP-MODE
indicates that the line resource is a PEP line currently
in emulation mode at real address 'raddr'.
OFFLINE
indicates that
for use.
rid
is the real resource identifier.
online
a
but
virtual
is
not
available for user access
the resource is inactive
and unavailable
Part 4: IB" 3704 and 3705 Communications Controllers
343
userid
is the user identifier.
raddr
is the real device address.
The for.at of the class F NETWORK command is:
NETwork
TRICE {BTU raddr}
resource
L-________________________________________________________________________
_
END
TRACE BTU raddr
formats (in hexadecimal) each BTU (~asic Iransmission ~nit)
sent to the specified 3704/3705,
and each one received 1n
response. The trace output is spooled to a virtual printer on
the virtual machine of the user issuing the command. Each BTU
is tiae-stamped at the time when it is traced, and the trace
record consists of the 14-byte BTU header plus the first 4
bytes of the BTU data area.
"raddr" is the real address of the 3704/3705 to be traced.
TRACE resource
activates the BCP line trace facility for the specified
resource (lines only). This facility provides a response BTU
to the host whenever I/O activity for the specified resource
exists. These responses are formatted in a manner similar to
the BTU trace output, and they are likewise spooled to a
virtual printer.
"resource" is a 4-digit hexadecimal identifier of a specific
telecom.unication line. The last three digits are the actual
resource ID. The first digit is a device sequence number
associated with a particular 3704/3705. This device sequence
number designates the relative position of this device in the
DMKRIO module. The first listed 3704/3705 would be designated
as 0, the second 3704/3705 listed in the DMKRIO module would
be designated as 1, and so on.
TRICE END terminates the trace operation.
Note: NETWORK TRICE can be
3704/3705 at anyone time.
set active
for
only
a single
physical
TRACE STIRTED
is the response given to the BTU and the resource operand.
COMMIBD COMPLETE
is the response given to the END operand (trace termination).
344
IBM VM/370: System Programmer's Guide
BCPDUftP is a CftS com.and that processes CP spool reader files created by
3704/3705 dump operations.
The NCPDUftP command:
•
•
•
•
creates the CMS NCPDUMP file from the spool file.
Formats the dump.
Prints the dump.
Erases the eMS BCPDUftF file (if specified) after printing it.
Although NCPDUftP is a CMS command, its effective use is restricted to
a specific user identified by the SYSDUftP operand of the SYSOPER macro
in DMKSYS. The operation of NCPDUftP is similar to VMFDUMP operations.
A general description of the NCPDU~P operation follows the command
description.
The NCPDUMP command has the following format:
NCPDUMP
r
[DUftPxx] I
I
I
L
r
,
IERASE
I
INOFORM I
IMNEMONICI
L
~
,
I
I
I
~
DUMPxx
is the filename of the CMS file containing a 3704/3705 control
program dump. This dump was created by a previously invoked
NCPDUftP command with the ERASE option not specified.
ERASE
erases the current dump file or
file (DU ftPxx) •
NOFORft
suppresses the formatting of the control block.
MNEftONIC
includes the 3705 Assembler mnemonic
printed output.
a previously created CMS dump
This command is also described in the VM/370:
operation codes
in the
Oper~!~!§ §yi~~.
USING THE NCPDUftP COMftAND
The NETWORK command invoked with the DUMPxx operand produces CP files.
These CP files contain the 3704/3705 storage dump and are spooled reader
input assigned to a system-designated user.
The CMS NCPDUftP command
invoked by this user formats (optionally) and prints the contents of
these files.
A CftS file, with a filename DUMPxx, and a filetype of NCPDUftP, is
created and the original spooled dump reader file (created when the
NETWORK DUftP com.and was issued) is deleted. If ERASE was specified on
the NCPDUftP command line, the CftS dump file is also erased; otherwise,
it is saved.
Part 4: IBft 3704 and 3705 Communications Controllers
345
A maximum of ten dumped spooled files can be processed and saved, and
later recalled if necessary, by the system assignment of the xx suffix
to the CftS-created DUftPxx filename. 'xx' is a decimal number from 00 to
09, depending on any existing files of similar name. For example, if
the files 'DUftPOO BCPDUftP' and 'DUftP01 BCPDUftP' already exist, the new
file is called 'DUftP02 NCPDUftP'. The file thus created is retained for
later use unless the ERISE option is specified, in which case the file
is erased immediately following the dump printing.
346
IBM VM/370: system Programmer's Guide
Part 5: Remote Spooling Communications Subsystem (RSCS)
Part 5 contains the following inforaa tion:
•
Introduction to Rses
•
structure of Rses virtual storage
•
•
Functional inforaation
Logging I/O activity
Part 5: Reaote Spooling eoa.unications Subsystem (RSeS)
347
Introduction to RSCS
The Remote Spooling Communications subsystem (RSeS), a component of
Vft/370, provides telecommunication facilities for the transmission of
bulk files between Vft/370 users and remote stations. Rses is a single
purpose operating system for a virtual machine, dedicated to the
management of files spooled to it by Vft/370 users or transmitted to it
by remote stations via communication lines. Remote stations can submit
files to a Vft/370 user or efts Batch facility for processing and receive
printer and punch output in return. Vft/370 users can submit job streams
to a remote HASP- or ASP-type batch processor. Remote stations can send
printer and punch files to other remote stations.
Under RSeS, all remote locations as well as the local Rses virtual
machine are assigned a one- to eight-character alphameric location
identification. The transmission path between the Rses virtual machine
and any single remote station is defined as a link. A link has certain
attributes that make up a link definition and these attributes are
assigned at system generation time or dynamically via the Rses DElINE
command.
A link definition consists
of a linkid (the location
identifier of the remote station), the type of remote station, the line
address to be used or transmission, the class of files to be processed,
and other information unique to the link. Rses maintains a table of link
definitions (link table) in the module DftTSYS. A maximum of 64 links may
be defined of which any 16 may be active at anyone time.
! remote station, in
the context of RSCS, ~s QUI ter.inal or system on
the other end of the link from the Rses virtual machine.
The Rses
virtual machine is also referred to as the local Rses station. Rses
supports two general types of I/O configurations used as remote
stations.
Nonprogram.able remote terminals, such as the
configurations where the line protocol necessary for
remote stations is provided by the hardware. These
by the Nonprogrammable Terminal (NPT) line driver of
IBft 2780, are I/O
them to function as
devices are managed
Rses.
Programmable remote
stations, such as
the IBft
system/3 and
System/360, are IBft processing systems with attached binary synchronous
communications adapters. These systems must be programmed to provide a
ftULTI-LEAVIIG line protocol necessary for their devices to function as
remote stations. For a detailed description of ftULTI-LEAVING, see
"Appendix B: ~ULTI-LEAVING." This programming support is provided by a
Remote Terminal Processor (RTP) program generated according to HASP
workstation
protocol
and
tailored
to
the
system's
hardware
configuration. certain programmable remote stations like the System/3
can only be programmed to function as remote terminals. Others, like the
System/360 and System/370, can function either as remote terminals or as
host batch systems using Rses as a remote job entry workstation. Both
of these types of remote stations are managed by the spool ~ULTI-LEAVING
(SftL) line driver of Rses.
Part 5: Remote Spooling communications Subsystem (RSeS)
349
Rses uses the VM/370 spool system to interface with V"/370 users.
When a user generates a file to be transmitted to a remote location
by RSeS, he aust coaply with two require.ents. The file must be spooled
to the Rses virtual machine and the spool file tag associated with the
file must contain, as the first entry, the linkid (location identifier)
of the remote station to which the file is being transmitted.
When a remote station transmits a card file to RSeS, the file must be
preceded by an ID card containing the userid of the virtual machine that
is to receive the file. Rses punches the file on a virtual punch and
spools it to the appropriate virtual machine. If the userid is that of
the Rses virtual machine and the ID card also contained valid tag data,
Rses will retrieve the file from the VM/370 spool system and forward it
to the remote station designated by the linkid in the tag data.
The RSeS command language provides the
with the following capabilities:
Rses virtual
machine operator
I.
I
Manipulate the status, transmission priority,
files owned by the Rses virtual machine.
class
I.
I
Initialize, suspend or
terminals or stations.
of
I.
Reposition or restart files currently being transmitted.
I •
I
Send or forward
stations.
I •
Query file, link or system information.
I.
Monitor link activity for any remote location.
terminate transmission
messages
and commands
to
remote
and order
files to
of
remote
terminals
and
A summary of the RSeS commands is shown in Figure 39; for a full
Remote Spooling
description and
format, refer to
"Appendix A:
Communications Subsystem
Commands" in the VM/370: Re~~e ~E~~~~~~
Communications SubsjL~t~~ l~SS~l g~~~~ Q~i_de.
------
350
IBM VM/370: Syste. Prograaaer's Guide
Command
lame
Function
BACKS PAC
Restart Qr reposition in a backward direction the file
currently being transmitted.
CHAIGE
Alters one or more attributes of a file owned by RSCS.
CMD
Control certain functions performed by a remote system,
or control the logging of I/O activity on a specified
link.
DEFINE
Temporarily add a new link definition to the RSCS link
table or temporarily redefine an existing link.
DELETE
Temporarily delete a link definition from the RSCS link
table.
DISCONN
place RSCS in disconnect mode and optionally direct
output to another virtual machine.
DRAIN
Deactivate an active communication link.
FLUSH
Discontinue processing the current file on the specified
link.
FREE
Resume transmission on a communication link previously
in HOLD status.
FWDSPACE
Reposition in a forward direction the file currently
being transmitted.
HOLD
Suspend file transmission on an active link without
deactivating the line.
MSG
Send a message to a local or remote station.
ORDER
Reorder files enqueued on a specific link.
PURGE
Remove all or specified files from a
QUERY
Request system information for a link, a file, or for the
system in general.
START
Activate a specified communication link.
TRACE
Monitor line activity on a specified link.
Figure 39. RSCS Command Summary
A subset of the RSCS commands is available to the remote station
operators. In general, the remote operator can issue only these commands
that offset his specific link. The commands are punched, one per card,
and entered at the remote card reader. Commands from remote stations are
only accepted before the ID card of an input card file or after the file
has been completely processed (end-of-file generated).
Part 5: Remote spooling Communications Subsystem (RSCS)
351
I Structure of RSCS Virtual Storage
RSCS virtual storage is made up of fixed address storage areas,
supervisor service routines, syste.
service .odules, line driver
modules, and available free storage for active tasks.
Figure 40 shows
how RSCS storage is allocated.
Or,---------------------------------,
Df!TVEC
1
10000
1
2701-------------------------------Df!TfUP
1
Df!TREX
Df!TCf!X
1---------------------------------Df!TEXT
1
Df!Tf!GI
Df!TSVC
Df!TCRE
Df!TIOf!
Df!TCOf!
Df!TCRQ
Df!Tf!SG
Df!TSYS
Df!TDSP
Note 1
Df!TINI (Note 2)
Df!TilT
Free Storage
Df!TPST
Df!TASK
Df!TSTO
/
/
Df!TASY
/
/
/
/
Df!TSIG
Df!TGIV
/
Df!T1KE
1000
Supervisor Queue Extension
2000
/
/
/
/
/
/
/,
/
/
/
/
/
/
/
Free Storage
(allocatable)
Note 1: The Df!TSYS module can vary in
when the RSCS system was generated.
following the end of Df!TSYS.
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
700001
1
740001
1
780001
1
7COOOI
1
7DOOOI
t
80000'
Third Line Driver
Second Line Driver
First Line Driver
Df!TLlX
Df!T1IS
I
size depending on the number of macros specified
Free storage starts on the first page boundary
Bote 2: The Df!TINI module is loaded at the beginning of the free storage area.
initialization, the storage it occupied is freed and becomes part of free storage.
Figure 40. RSCS Storage Allocation
352
IBft Vft/310: System Programmer's Guide
After
The first 4K bytes of storage contain hardware
constants, control areas. and supervisor service
and supervisor-defined
routines~
DftTVEC - The first 512 bytes of DftTVEC are defined by System/370
architecture and contain hardware-defined constants.
This area is
initialized by the DftTIRI routine at initial program load time.
The rest of DKTVEC, 112 bytes, contains supervisor-defined addresses
and constants used for dispatching, storage mapping, queue management,
and task management.
DftTftAP - The supervisor storage area contains the main
the first extent of the supervisor queue.
storage map and
The main storage map is a table comprising one byte for each page in
accessible main storage. Each byte displacement in the table implies an
associated main storage number.
The supervisor queue is a chain of 16 byte elements, formatted during
initialization, maintained by the DKTORQ routine, and containing the
status information for all system tasks running or waiting to be
dispatched. The length of this chain is such that-the service routines
that follow are located at the end of the page of storage.
supervisor service Routines - the rest of the supervisor contains
The
service routines that provide services to other system tasks.
thirteen routines and their functions are:
DftTEXT
DftTSVC
DftTIOft
DKTORO
DftTDSP
DKTWAT
DftTPST
DKTASK
DHTSTO
DKTASY
DKTSIG
DKTGIV
DftTAKB
-
Handle external interruptions
Handle SVC interruptions
Handle I/O interrupts and requests
Manage the supervisor status queue
Dispatch eligible tasks
Suspend task execution
Signal completion of an event
create and delete system service tasks
Reserve and release main storage ~Qy~~
Provide asynchronous task-to-task exits
Interrup~ a task, immediately, for an ALERT request
Enqueue a GIVE request element for another task
Process a GIVB request element
The supervisor queue extension is a chain of 16 byte elements
provide an extension to the supervisor queue located in DKTftAP.
that
This area of free storage is managed by the DKTSTO module. System tasks
reserve and release virtual storage
in full page increaents as
required.
Part 5: Remote Spooling Communications Subsystem (RSCS)
353
The system
control task
consists of
five
non-executable modules. Their functions are:
executable
and
two
DftTREX - Handle console I/O; process request elements for service
routines; terminate system service and line driver tasks.
DftTCRE - start a line driver task and create the DftTIXS and DMTLIX tasks
during initialization.
DftTCftX - Handle all console functions.
DftTftGX - Build and forward message request elements.
DftTCOft - Perform miscellaneous system service functions.
DftTftSG - Table of message texts and codes.
DftTSYS - Link table, file tag storage
switched line port table.
area, tag
queue pointers,
and
This area of free storage is also managed by DftTSTO. In addition to
providing storage for system tasks, it is used for line driver storage.
For each active link that is initialized by DftTCRB, a copy of a DftTSftL
or DftTNPT line driver is brought into virtual storage~ Line driver
storage is assigned downward from X'7COOO', in four-page increments.
Free storage for system tasks is assigned upwards from the page boundary
following DftTSYS, in one-page increments.
The DftTLAX module allocates a line port to a link when its line driver
task is started. If a line address has been previously assigned in the
link definition or is specified in the START command, D"TLAX verifies
that the line is for a valid device type and is not already in use. If
a line address has not been previously assigned and is not specified in
the START command, DMTLAX scans the table of switchable line ports for
an available line and assigns it to the link's line driver task. If a
line is not available or is incorrectly specified, an error message is
issued to the RSCS operator.
The DftTAXS module accepts files from the Vft/370 spool system and
maintains the queues of main storage file tag slots; executes the ORDER,
CHANGB, and PURGB commands; and opens and closes input and output V"/370
spool files.
354
IBM Vft/370: System Programmer's Guide
Functional Information
The RSCS virtual machine performs certain basic functions as it manages
the transmission of files between the host VM/370 and remote locations.
These functions include:
•
•
•
•
•
•
Virtual storage management
File management
Task-to-task communication
RSCS co •• and processing
RSCS message handling
Interruption handling
The RSCS supervisor controls virtual storage in blocks of either 4096
bytes (page size) or in 16 byte queue elements. Tasks running under the
supervisor obtain their working storage area in page size blocks and
then allocate variable size blocks as their functions require.
I PAGE ALLOCATION
Page allocation is performed by the supervisor service routine, DMTSTO.
A storage allocation map, 256 bytes in length, is located in the
supervisor area and is pointed to by MAINMAP in the DMTVEC data area.
Each byte represents a page of virtual storage and contains X'OO' if the
page is free. MAINSIZE, also in DMTVEC, contains the total number of
pages defined for the particular RSCS virtual machine.
When a task requires a page of storage, it first searches the storage
allocation map for a free page (X'OO').
The page number is placed in
register 1 and a call to DMTSTO reserves the page. DMTSTO replaces the
storage map byte with the one-byte TASKID assigned to the calling task
by the supervisor. To release storage, a task has only to clear the
appropriate bytes in the storage map.
QUEUE ELEMENT MANAGEMENT
with the exception of a few words of low address storage used by the
dispatcher, the rest of the supervisor status information is stored in
chains of 16-byte queue elements managed by DMTQRQ. The first extent of
these queues is in the supervisor and occupies the area between the main
storage allocation map and DMTEXT. A supervisor queue extension area,
one page in length, is located at X'1000'. Queue elements are dequeued
from the free element queue pointed to by FREEQ in DMTVEC and enqueued
on one of the active queues (TASKQ, MPXIOQ, SELIOQ, IOEXTQ, EXTQ, ALERTQ
or GIVEQ). When the queue element is released, it is returned to the
free element queue.
Part 5: Remote Spooling Communications Subsystem (RSCS)
355
RSCS uses the V~/370 spool file system to interface with V~/370 users.
A user who generates a file intended for transmission to a reaote
location must spool the file to the RSCS virtual machine via the CP
SPOOL com.and.
In addition, he must also enter the identification of
the remote location into the spool file tag area via the CP TAG
command.
A remote station submitting a file to RSCS for transmission to
another remote location must meet the same requirements as a V~/370
user. The ID card that precedes the input card file being transmitted
to RSCS must include the userid of the RSCS virtual machine and a tag
field containing the location identifier of the remote station that is
to receive the file.
A remote station submitting a file destined for a
only specify that user's use rid on the ID card.
V~/370
user need
When the BSCS virtual machine is initially logged on, one of the
first tasks that is started is the Spool File Access task, D~TAXS. Two
main functions of D~TAXS are: to provide access to the VM/370 spool file
system, and to manage the queues of tag slots used by RSCS to control
the status and flow of files through the system.
TAG SLOT QUEUES
The D~TAXS task in RSCS manages a file tag storage area pointed to by
TTAGQ in D~TVEC. This area is made up of a fixed number of tag slots,
each containing iOa bytes. The total nuaber of slots is determined, at
the time RSCS is generated, by the value specified in the GEBTAGQ macro.
The number of slots reserved for each link is part of the link
definition stored in the RSCS link table. The contents of each file tag
include file attributes from the
file's SFBLOK and transmission
destination and priority from the associated spool file tag.
File tags are chained on one of four types of queues:
I.
I
I
The active input queue, pointed to by TAGACIN in TAGAREA, contains
the tags for those files that are currently being processed for
transmission to remote locations.
I •
I
I
The active output queue, pointed to by TAGACOUT in TAGAREA, contains
the tags for those files that are currently being received from
remote locations.
I •
I
I
I
An inactive file queue exists for each link that has one or more
files waiting to be transmitted.
Each link's file tag queue is
pointed to by the LPOINTER field in the corresponding link table
entry.
I.
I
The free slot queue, pointed to by TAGAFREE in TAGAREA, is made up of
all the slots not currently on any of the other tag slot queues.
SPOOL PILE ACCESS
The Spool File Access task, DMTAXS, uses the "retrieve subsequent file
descriptor" option of the CP DIAGNOSE X'014' command to access the spool
356
IBft VM/370: System program.er's Guide
file block (SFBLOK) and spool file tag for each of the files enqueued on
the RSCS virtual reader.
Using the location identifier in
the spool file tag,
DftT1IS
interrogates the link table entry for the specified link to determine if
a tag slot is available. If so, a tag is built, using information in
the SFBLOK and spool file tag, and then enqueued on the link's chain of
inactive files pointed to by LPOINTER in the link table entry.
If a tag
slot is not available, the file is placed in a pending status and the
link table entry count of pending files
(LPENDING) is incremented by
one.
Pending files are added to the inactive file queues as slots
become available.
When a line driver task is started for a link via the RSCS START
command, the highest priority file on that link's inactive queue
(LPOINTER) is dequeued and placed in the system's active input queue
(TAGACIN). The file's tag and first spool buffer are then passed to the
line driver task for transmission.
Any additional spool buffers for
that file are directly obtained by the line driver task.
RSCS
provides two methods of
requests, and ALERT requests.
task-to-task communications:
GIVE/TAKE
GIVE/TAKE requests are issued by lower priority tasks, such as line
drivers, to request a service from a higher priority task, such as a
supervisor service routine. The requesting task builds a request table
containing the name of the task that is to perform the service, along
with pointers to a request buffer containing the data required for the
service.
If appropriate, a pointer to a response buffer is also
supplied.
This information is passed to the DftTGIV module.
DftTGIV
builds a GIVE element that points to the requestor's request table and
chains it on the GIVE element queue for execution.
Service tasks pass control to DftTAKE whenever they coaplete the
execution of a particular service.
DftTAKE locates the GIVE element for
the service that was just completed: passes any response data back to
the requestor via the response buffer, locates the next GIVE element for
that service task, and passes the corresponding request table data to
the service task for execution.
ALERT requests are issued by high priority tasks for services to be
performed by a lower priority task.
These requests are not queued; the
lower priority task is executed as soon as it is received.
ALERT
requests are handled by the DftTSIG module.
The primary command processor in RSCS is the DftTCMX module of the system
control task.
DMTCMI receives commands either as a result of a ccnsole
read started by the DftTREI module in response to attention interruption
from the RSCS operator console, or through a GIVE request pointer to a
command element, provided by an active line driver task.
The DEFINE, DELETE, DISCONN, QUERY and START commands are processed
entirely by the system control task, as they may involve the referencing
and updating of the system status tables (DMTSYS).
Part 5: Remote Spooling Communications Subsystem (RSCS)
357
For the CHANGE, PURGE and ORDER commands, DMTCMX builds a formatted
table called a command element and passes it, via an ALERT request, to
the £MTAXS task for execution.
The BACKSP1C, CMD, DRAIN, FLUSB, FREE, Pi£SPACE, BOLD, MSG, and TRACE
commands are passed to the line driver task for the associated active
link via a command element and ALERT request.
Messages can occur in response to a command or
of a system malfunction.
~pontaneously
as a result
The task that originates the message passes the message number and
the variable portion of the message text to the message handler, DMTMGX.
DMTMGX obtains the fixed portion of the message text and routing
information from the DMTMSG module and issues the message to the
appropriate operator.
Messages can be addressed to the local RSCS operator, remote station
operator, local VM/370 virtual machine, VM/370 system operator, or
combinations of these.
Messages directed to the VM/370 system operator or VM/370 user are
issued via the CP MSG command using the Virtual Console Function of the
Diagnose interface. Messages for the local RSCS operator are enqueued
for output by DMTREX.
Messages for the remote station operator are
presented to the line drivers for the associated links via an RSCS MSG
command element and ALERT request.
Three types of interruptions are handled
routines:
external
interruptions,
SVC
interruptions.
by the supervisor service
interruptions,
and
I/O
I EXTERNAL INTERRUPTIONS
External interruptions are handled by the DMTEXT module.
Each bit of
the external interruption code (bytes 16-31 of the external old PSi in
low storage)
is inspected. ihen a bit is set to one, a scan of the
external exit request queue is made to locate the first requested exit
for the bit that was set.
If one is found, the exit is taken;
otherwise, processing continues until the entire interruption code has
been inspected.
I SVC INTERRUPTIONS
The DMTSVC module receives control directly on an SVC interruption.
RSCS uses the SVC interruption to "freeze" the execution of a task while
it is waiting for the results of some service that it has requested of
another task.
The left half of the SVC old PSi is moved to the left
half of the resume PSi in the task's save area; the right half is loaded
358
IBM VM/370: System Programmer's Guide
with the contents of register 14 (resume PSi address).
The register
contents at interruption time are also stored in the task's save area.
D"TSVC returns control to the caller by setting register 14 to the
address of the task element of the "frozen" task and loading a PSi with
all mask bits set off (except machine eheekj and execution address as
stored in the SVc old PSi.
I/O IBTERRUPTIOBS
I/O interruptions are handled by the D"TIO" module at entry point
D"TIC"IN. D"TIOft first searches for an active I/O request element on
the appropriate queue (ftPXIOQ or SELIOQ).
If one is found, the I/O
request table is updated to reflect the new status. If this is net the
final interruption, control is immediately returned to the dispatcher.
If the I/O has completed without unit check, ,the synch lock in the I/O
table is posted; and, if there is no further I/O enqueued for that
subchannel, control is passed to the dispatcher. If I/O is enqueued for
that subchannel, it is started.
If the I/O has completed, but there was a unit check and automatic
sense was requested, the sense channel program is built in a new element
and the new element is chained to the request element. The sense
operation is started and if not completed immediately, control is passed
to the dispatcher.
If an active I/O request element was not found, the asynchronous I/O
exit queue (IOBXITO) is scanned for a matching device address. If found,
the asynchronous exit is taken.
If neither an active I/O request element nor an asynchronous exit
request element is found, the interrupt is ignored and control is passed
to the dispatcher.
Part 5: Remote Spooling communications subsystem (RSCS)
359
I Logging I/O Activity
The RSCS component of V"/370 contains a facility for logging all I/O
activity on a particular teleprocessing link. This logging feature can
be utilized if a problem arises where tracing I/O activity on a line
becomes a necessity.
The RSCS operator can turn the feature on and off by issuing the RSCS
C"D command with the LOG or BOLOG operand.
The format of the CftD
command, when used to control logging, is as follows:
CftD
linkid { LOG
}
BOLOG
linkid
is the location identifier for the link on which logging is to
be perforlled.
LOG
is the keyword that starts the logging of I/O activity.
BOLOG
is the keyword that stops the logging of I/O activity.
The logging output is a printer spool file containing a one-line
record for each I/O transaction
on the teleprocessing line.
A
transaction is defined as any read or write of a teleprocessing buffer.
When logging is turned off, the output is automatically spooled to a
printer. The distribution code on the printer output is the linkid that
was specified in the CftD cOllmand.
The output log record is printed in hexadecimal notation except for
the rightmost field which is an alphabetic character.
The contents of the log record are as follows:
21 bytes
The first 21 bytes of the teleprocessing buffer, including BSC
bytes, ftULTI-LE1VIBG bytes (for SftL only), and enough initial
bytes of data to fill the field.
7 bytes
For read I/O: the last seven bytes of the CSW.
For SftL write I/O: The first seven bytes of the S"L buffer
header that is used internally by S"L but
not transmitted.
For BPT write I/O: Bot applicable.
3 bytes
The first three bytes
transaction.
3 bytes
The first three sense bytes, if any.
1 byte
"R" for read I/O; "W" for write I/O.
of the
RSCS I/O
synch lock
The fields of the record are separated by blanks.
sa.ples of read and write log records for SftL:
360
IBft Vft/3JO: System Programmer's Guide
for this
The following are
1070808FCFOOC161SCD2C9C7DSD6DS404040404040 0346!80EOOPDE6 800000 020000 R
- - - - - - - - - - - - - - - ---
BSC and ftULTILEAVING Bytes
........
----......
-----....."...
--- '-v-'"
Data
t
'-v-"
~
'-v-"
t
Addr
Count Synch Sense Read
Status
Lock Bytes
Bytes
---........
--~~
TP Buffer
~
--~~
-
----------CSW
1070808FCPOOC161SCE2C9C7DSD6DS404040404040 00037338000602 000000 000000 i
....
BSC and ftULTILEAVING Bytes
~~----
--- ------------
Data
....
--~~~---TP Buffer
SftL Internal
Buffer
'-v-'"
Synch
Lock
'-v-'"
t
Sense Write
Bytes
--~~
Part 5: Remote Spooling Communications Subsystea (RSCS)
361
Appendix A: System/370 Information
The control registers are used to maintain and manipulate centrol
information that resides outside the PSi. There are sixteen 32-bit
registers for control purposes. The control registers are not part ef
addressable storage.
At the time the registers are loaded, the information is not checked
for exceptions, such as invalid segment-size or page-size code or an
address designating an unavailable or a protected locaticn.
The
validity of the information is checked and the errors, if any, indicated
at the time the information is used.
Figure 41 is a summary of the control register allocation and Figure
42 lists the facility associated with each control register.
Figure 43 is a description of the EC (Extended Control) PSi.
<--------------------------o
32 bits
SYSTEM CONTROL ITRANSL. CONTROLI
SEGM-TBL LENGTHI
----------------------------->
EXTERNAL-INTERRUPTION MASKS
SEGMENT-TAELE-ORIGIN-ADDRESS
CHANNEL MASKS
2
3
4
5
6
7
MONITOR MASKS
8
9 PER EVENT MASKSI
PER GR ALTERATION MASKS
10
PER STARTING ADDRESS
11
PER ENDING ADDRESS
12
13
14
ERROR-RECOVERY CONTROL & MASKSI
15
Figure 41.
MCEL ADDRESS
Control Register Allocation
Appendix A: System/370 Information
363
Name of Pield
WordlBits
o
0 IBlock-Multiplexing Mode
1 155M Suppression
8-9 IPage Size 1
o I 101 Reserved
o 111-12lSegment size 1
o I 20lClock Comparator Mask
o I
211CPU Tiaer Mask
o I 241Interval Timer Mask
o I 251Interrupt Key Mask
o I
261External Signal Mask
o
o
1
1
0-7 ISegment Table Length
8-25lSegment Table Address
I
2
Initial Value
IBlock-Multiplexing Control
IExtended Control
IDynamic Addr. Translation
IDynamic Addr. Translation
IDynamic Addr. Translation
IClock Comparator
I CPU Timer
IExternal Interruption
IExternal Interruption
IExternal Interruption
IDynamic Addr. Translation
IDynamic Addr. Translaticn
I
0-31lChannel Masks
1
o
10
o
00
1
o
1
1
o
ISet by CP. Value
varies with the type
of virtual machine.
PPPPPPPP
11/0 Interruptions
8 I 16-31 I Monitor Masks
I
I
I Monitoring
I
IValue depends on
I virtual machine.
9 I 0-7 IPER2 Event Masks
9 116-311PER GR Alteration Masks
IProgram-Event Recording
IProgram-Event Recording
IValue depends on
I virtual machine.
IProgram-Event Recording
IValue depends on
I virtual machine.
10
8-311PER starting Address
I
11
I
8-311PER Ending Address
I
14
14
14
14
14
14
14
14
14
15
o
1
2
4
5
6
7
8
9
IProgram-Event Recording
I
ICheck-Stop Control
I Machine-Check
ISynchronous MCEL3 Control
IMachine-Check
11/0 Extended Logout Control I Channel-Check
IRecovery Report Mask
I Machine-Check
IDegradation Report Mask
I Machine-Check
IExternal Damage Report Mask I Machine-Check
IWarning Mask
I Machine-Check
I Asynchronous MCEL Control
IMachine-Check
IAsynchronous Pixed Log Ctrl.IMachine-Check
8-28IMCEL Address
I Value depends on
I virtual machine.
Handling
Handling
Handling
Handling
Handling
Handling
Handling
Handling
Handling
Value depends on
machine check
handler for the
virtual machine.
IMachine-Check Handling
~xpla.!!~!io.!!:
IThe fields not listed are unassigned.
IThe initial value of unassigned register positions is unpredictable.
I
11
I
12
13
The initial value varies depending on whether virtual storage is supported in the
virtual machine.
PER means program-event recording.
MCEL means machine-check extended logout.
I
Pigure 42.
364
Control Register Assignments
IBM VM/370: System Programmer's Guide
I
ISystem Mask
I
I
o
I Key I EftWP I
I
I
I
7 8
11 12
cc
o
15 16 17 18
I Program I
I Mask
I
19 20
o
23 24
3i
r-----------------------------------------------------------------------,
I 0
Instruction Address
I
32
33
63
The fields of the PSW are:
o
1
2-4
5
6
7
8-11
12
13
14
15
16-17
18-19
20-23
24-32
33-63
Figure 43.
Must be zero.
PER (Program Event Recording) enabled.
Must be zero.
Address translation.
Summary I/O mask.
Summary extension.
The protection key determines if information can be stored
or fetched from a particular location.
Extended control mode.
The machine check flag is set to 1 whenever a machine check
occurs.
The wait state flag is set to 1 when the CPU is in the wait
state.
The problem state flag is set to 1 when the CPU is
operating in the problem rather than the supervisor
state.
Must be zero.
The condition code reflects the result of a previous
arithmetic, logical, or I/O operation.
The program mask indicates whether or not various program
exceptions are allowed to cause program interrupts.
Must be zero.
The instruction address gives the location of the next
instruction to be executed for program interrupts or of
the instruction last executed for external interrupts.
The Extended Control PSi (Program Status Word)
Appendix A: System/370 Information
365
Appendix B: MULTI-LEAVING
MULTI-LEAVING
is a
term that
describes a
computer-to-computer
communication technique developed for use by the HASP system and used by
the RSCS component of VM/370. MULTI-LEAVING can be defined as the fully
synchronized,
pseudo-simultaneous, bidirectional
transmission of a
variable number of data streams between two or more computers using
binary synchronous communications facilities.
The following sections outline the specifications of a ccmprehensive,
MULTI-LEAVING communications system (as is used in HASP/ASP). While the
VM/370 support for programmable BSC remote stations is completely
consistent with the MULTI-LEAVING design, it does not use certain of the
features provided in MULTI-LEAVING:
•
The transmission of record types other than
console, and control is not supported.
•
The only
control.
•
Only SCB count units of 1 are used.
•
No support is included for column binary cards.
general control
record type used
print, punch,
is the
input,
terminal sign-on
The basic element for multileaved transmission is the character string.
One or more character strings are formed from the smallest external
element of transmission, the physical record. These physical records
are input to MULTI-LEAVING and may be any of the classic record types
(card images,
printed lines, tape records, etc.). For efficiency in
transmission, each of these data records is reduced to a series of
character strings of two basic types:
1.
A variable-length nonidentical series of characters.
2.
A variable number of identical characters.
An eight-bit control field, termed a String control Byte
(SCB),
precedes each character string to identify the type and length of the
string. Thus, a string of nonidentical characters (as in 1 above) is
represented by an SCB followed by the nonduplicate characters. A string
of consecutive, duplicate, non blank characters (as in 2 above)
can be
represented by an SCB and a single character (the SCB indicates the
duplication count, and the character following indicates the character
to be duplicated). In the case of an all-blank character string, only an
SCB is required to indicate both the type and the number of blank
characters.
A data record to be transmitted is segmented into the
optimum number of character strings
(to take full advantage of the
identical character compression) by the transmitting program. A special
SCB is used to indicate the grouping of character strings that compose
the original
physical record.
The
receiving program
can then
reconstruct the original record for processing.
Appendix B: MULTI-LEAVING
367
r----------------------------------------------------------------------------,
control
Characters
DLE
STX
BCB
FCS
FCS
RCB
SRCB
SCB
DATA
SCB
DATA
SCB
RCB
SRCB
SCB
DATA
SCB
RCB
OCE
ETB
Figure 44.
Usage
BSC Leader (SOH if no transparency feature)
BSC Start-of Text
Block Control Byte
Function Control Sequence
Function Control Sequence
Record Control Byte for record 1
Sub-Record Control Byte for record
String Control Byte for record 1
Character String
string Control Byte for record
Character string
Terminating SCB for record 1
RCB for record 2
SRCB for record 2
SCB for record 2
Character string
Terminating SCB for record 2
Transmission Block terminator
BSC Leader (SIN if no transparency feature)
BSC Ending Sequence
A Typical MULTI-LEAVING Transmission Block
In order to allow multiple physical records of various types to be
grouped together in a single transmission block (see Figure 44), an
additional eight-bit control field precedes the group of character
strings representing the original physical record. This field,
the
Record Control Byte
(RCB), identifies the general type and function of
the physical record (input stream, print stream, data set, etc.). A
particular RCB type has been designated to allow the passage of control
information between
the various systems.
Also, to
provide for
simultaneous transmission of similar functions
(that is, multiple input
streams, etc.), a stream identification code is included in the RCB. A
second eight-bit control field, the Sub-Record Control Byte (SRCB), is
also included immediately following the RCB.
This field is used to
supply additional information concerning the record to the rece1v1ng
program.
For example, in the transmission of data to be printed, the
SRCB can be used for carriage control information.
For actual MULTI-LEAVING transmission, a variable number of records
may be combined into a variable block size, as indicated previously
(that is, RCB,SRCB,SCB1,SCB2, ••• ,SCBn, RCB,SRCB,SCB1, ••• ,etc.). The
MULTI-LEAVING design provides for two
(or more) computers to exchange
transmission blocks, containing multiple data streams as described
above,
in an interleaved fashion.
To allow optimum use of this
capability, however, a system must have the capability to control the
flow of a particular data stream while continuing normal transmission of
all others. This requirement becomes obvious if one considers the case
of the simultaneous transmission of two data streams to a system for
immediate transcription to physical I/O devices of different speeds
(such as two print streams). To provide for the metering of the flow of
individual data streams, a Function Control Sequence (FCS)
is added to
each transmission block.
The FCS is a sequence of bits, each of which
represents a particular transmission stream.
The receiver of several
data streams can temporarily stop the transmission of a particular
stream by setting the corresponding FCS bit off in the next transmission
to the sender of that stream. The stream can subsequently be resumed by
setting the bit on.
368
IBM VM/370: System Programmer's Guide
Pinally, for error detection and correction purposes, a Elock Control
Byte (BCB) is added as the first character of each block transmitted.
The BCB, in additional to control information, contains a hexadeciaal
block sequence count. This count is aaintained and verified by both the
sending and receiving systems to exercise a positive control over lost
or duplicated transmission blocks.
In addition to the normal binary synchronous text control characters
(STX, ETB, etc.) ftULTI-LEAVIIG uses two of the BSC control characters,
ACKO and NAK. lCKO is used as a "filler" by all systems to maintain
communications when data is not available for transmission. N1K is used
as the only
negative response and indicates
that the previous
transmission was not successfully received.
This section describes the bit-by-bit definitions of the various
ftULTI-LEAVIIG control fields and includes notes concerning their use.
lppendix B: MULTI-LE1VING
369
RECORD CONTROL BYTE (RCB)
-------
OIIITTTT
o
7
M§~E~:
To identify each record type within a transmission block
OIIITTTT
--or--
00000000
o
1110000
III
000
001
010
011
100
101
111
o
lon-EOT RCB
III is control information:
Reserved
Request to initiate a function
transmission (prototype RCB for
function in SRCB )
Permission to initiate a function
Transmission (RCB for function
contained in SRCB )
Reserved
Reserved
Available for location modification
General control record (Type
indicated in SRCB)
--or-1
IIITTTT
TTTT
370
End of transmission block
0001
0010
0011
0100
0101
0110
0111
1000-1100
1101-1111
Non-EOT RCB
III is used to identify streams
of multiple identical functions
(such as multiple print streams
to a multiple printer terminal).
TTTT is the record type identifier.
Operator message display request
Operator command
Normal input record
Print record
Punch record
Data set record
Terminal message routing request
Reserved
Available to user
IBK VK/370: System Programmer's Guide
SUB-RECORD CONTROL BYTE (SRCB)
To provide supplemental information about a record
Y§~E~:
~!i~:
The contents of this control block depend upon the
record type. Several types are shown below •
•• CHAR ••
7
o
~§~g~:
To identify the type of generalized control record
~!!§:
CHARACTER
A
B
C
D
E
F
G
H
I-R
S-Z
Initial terminal sign-on
,inal terminal sign-off
Print initialization record
Punch initialization record
Input initialization record
Data set transmission
initialization
System configuration status
Diagnostic control record
Reserved
Available to user
OMCCCCCC
o
7
~§~E~:
o
M
To provide carriage control information for print records
1
o
1
CCCCCC
000000
000011
01NINN
1000 II
111HHN
Normal carriage control
Reserved
Suppress space
Space nn lines after print
Skip to channel nnnn after print
Space immediate nn spaces
Skip i.mediate to channel nnnn
Appendix B: MULTI-LEAVING
371
-----OfU!BBBSS
o
Y2~~:
7
To provide additional information for punch records
1
00
01
10
11
B
o
BR
SS
00
II
1
SCB count units = 1
SCB count units = 2
SCB count units = 4
Reserved
EBCDIC card image
Column binary card image
Reserved
stacker select information
OftftBRBBR
o
7
us~~~:
To provide additional information for input records
~!i2:
o
1
00
01
10
11
0
1
0000
ftM
B
RRRR
SCB count units = 1
SCB count units = 2
SCB count units = 4
Reserved
EBCDIC card image
Column binary image
Reserved
OTTTTTTT
o
Y2~g~:
7
To indicate the destination of a terminal message
Bit§:
372
o
1
TTTTTTT
0000000
IIIIIII
Broadcase to all remote systems
Remote system number (1-99) or
remote system group (100-127)
IBft VM/370: System Programmer's Guide
STRING CONTROL BYTE (SCB)
OKLJJJJJ
o
7
~§~g~:
Control field for data character strings
~i!§:
OKLJJJJJ
--or-OKLJJJJJ
--or-o
00000000
End of record
10000000
Record is continued in next
transmission block
1
Non-EOR SCB
Duplicate character string
Duplicate character is blank
Duplicate character is nonblank
and follows seB
Duplicate count
o
o
K
L
1
NNNNN
JJJJJ
--or--
o
1
1
K
LJJJJJ
NNNNN
Non-EOR SCB
Nonduplicate character string
Character string length
Note: Count units are normally 1 but may be in any other units.
the units used may be indicated at function control sign-on
or dynamically in the SRCB.
BLOCK CONTRCL BYTE (BCB)
oxxxccce
o
~§~3~:
~ii2:
o
xxx
CCCC
7
transmission block status and sequence count
1
000
001
010
011
100
101
110
111
NNNN
Reserved
Bypass sequence count validation
Reset expected block sequence count
to ecec
Reserved
Reserved
Available to user
Available to user
Reserved
Module 16 block sequence count
Appendix B: MULTI-LEAVING
373
FUNCTION CONTROL SEQUENCE (FCS)
---------------OSRRABCDORRRWXYZ
o
Us~~~:
7 8
15
To control the flow of individual function streams
O ••• 0
S
1 ••• 1
o
1
RR ••• RRR
ABCD
WXYZ
00 ••• 000
NNBN
NNNN
Normal processing
Suspend all stream transmission
(wait-a-bit)
Reserved
print or input stream identification
punch stream identifiers
Note: These function stream identifiers are oriented only to the
recipient. Presence of a bit indicated that function
transmission is to be continued; its absence indicates that
function transmission is to be suspended.
374
IBM VM/370: System Programmer's Guide
GC20-1807-3 Page Modified by TNL GN20-2662, March 31, 1975
Appendix C: VM Monitor Tape Format and Content
Each time a monitor call interrupt occurs, VM Monitor receives control
and collects data appropriate for the particular class and code of
MONITOR CALL.
(Or, for USER, PERFORM or DASTAP classes, VM Monitor
gets control at periodic intervals to collect data.)
The data is
formatted into records which are collected sequentially in the order
that each interrupt occurred. The tape data format is standard Variable
Blocked
(VB)
format.
Data is written at the default tape drive
density.
The formats and contents of all the kinds of data records for
the currently implemented classes and codes of MONITOR CALL are listed
below.
All values described
otherwise noted.
I
in
the
following
records
are
binary
unless
lIndicates that the field is EBCDIC.
2Indicates that the field is in special timer format described below.
3See CP PLM for field format definition.
Every data record is preceded by the following 12 byte header:
Total bytes ~n record
Zeros (standard V format record)
MONITOR CALL class number
MONITOR CALL code number
Time of Day
Number
Of
DSECT
Variable
].Y!~'§
!!!.!!~
')
MUUD1U"C''7
u
LJ &'1,U Ll.&.;l'- tJ
L.
2
1
2
MNHCLASS
MNHCODE
MNHTOD
5
!2!~:
Time of day occupies 2 full words in storage, with the right hand
12 bits zeros. The right hand 2 bytes and the leftmost byte are ignored
giving 16 microsecond accuracy instead of 1 microsecond.
The first 4 bytes of this
record-length field.
header
are
the standard
variable-format
Appendix B: MULTI-LEAVING
374.1
GC20-1807-3 Page Modified by TNL GN20-2662, Mdrch 3i,
Monitor
Code
97
98
99
Data
Item
Tape header record
CPU serial/model number
Software version number 1
Date of data collection session 1
Time of data collection session 1
USERID of monitor controller 1
CR8 mask of enabled classes
Tape trailer record
USERID of user shutting down monitorl
Tape write suspension record
TOD at suspension 2
Count of write suspensions
1~75
DSECT
Variable
Name
Number
of
Bytes
CP
Variable
Name
8
4
CPUID
DMKCPEID
tod clock
tod clock
VMUSER
DMKPRGC8
MN097CPU
MN097LEV
MN097DAT
MN097TIM
MN097UID
MN097CR8
8
VMUSER
MN098UID
8
8
8
8
MN099TOD
MN099CNT
5
4
Class Zero - PERFORM
Monitor
Code
00
374.2
Data
Item
Interval statistics
Total system idle time 3
Total system page wait 3
Total system time I/O wait 3
Total system problem time 3
Total paging start I/O's
Total page I/O requests
Current page frames on free list
Pages being written, due for free list
Total pages flushed, but reclaimed
Number of reserved pages
Number of shared system pages
Total number of times free list empty
Total number of calls to DMKPTRFR
Total pages stolen from in Q users
Number of pages examined in stealing pages
Number of pages swapped from the flush
list
Number of full scans done in stealing
pages
Total real external interrupts
Total calls to DMKPRVLG
Total calls to DMKVIOEX
Total calls to CCWTRANS from DMKVIO
Total Virt Interval Timer Ints reflected
Total Virt CPU Timer Ints reflected
IBM VM/370: System Programmer's Guide
Number
of
Bytes
CP
Variable
Name
DSECT
Variable
Name
8
8
8
8
4
4
4
4
4
4
4
4
4
4
4
IDLEWAIT
PAGEWAIT
IONTWAIT
PROBTIME
DMKPAGPS
DMKPAGCC
DMKPTRFN
DMKPTRSW
DMKPTRPR
DMKPTRRC
DMKPTRSC
DMKPTRFO
DMKPTRFC
DMKPTRSS
DMKPTRFF
MNOOOWID
MNOOOWPG
MNOOOWIO
MNOOOPRB
MNOOOPSI
MNOOOCPA
MNOOONFL
MNOOOPSN
MNOOOPRC
MNOOORPC
MNOOOSPC
MNOOOFLF
MNOOOCPT
MNOOOSS
MNOOOPFF
4
DMKPTRRF
MNOOOPRF
4
4
4
4
4
4
4
DMKPTRC S
DMKPSANX
DMKPRVCT
DMKVIOCT
DMKVIOCW
DMKDSPIT
DMKDSPPT
MNOOOPCS
MNOOONXR
MNOOOCPR
MNOOOCVI
MNOOOCCW
MNOOOITI
MNOOOPTI
~~20-1807-3
Page Modified by TNL GN20-2662, March 31,
Data
Item
Monitor
Code
Total
Total
Total
Total
Total
Total
Total
Total
Virt Clock Comparator Ints reflected
virtual SVC interrupts simulated
virtual program interrupts handled
I/O interrupts handled
calls to dispatch (main)
fast reflects in dispatch
dispatches for new PSi's
calls to schedule
COUll
of virtual machine SSK'& simulated
Count of virtual macnine SKiS simu:~ted
Count of virtual machine S3M's simulated
Count of virtual machine LPSW's sim~lated
Cndnt
CO~Lt
of
virtuaJ machine f3iagnose in.st
of ~irtual machine SIO's simulated
count of virtual machine SIOF's simulated
Count of virtual machine TIO·s simulated
Count of virtual machine CLElO's simulated
Count of virtual machine HIO's simulated
Count of virtual machine HDV's simulated
Count of virtual machine TeH's simulated
Count of virtual machine STNSM's simulated
Count of virtual machine STOSM's simulated
Count of virtual machine LRA's simulated
Count of virtual machine STIDP's simulated
Count of virtual machine STIDC's simulated
Count of virtual machine SCK's simulated
Count of virtual machine SCKC's simulated
Count of virtual machine STCKC's simulated
Count of virtual machine SPT's simulated
Count of virtual machine STPT's simulated
Count of virtual machine SPKA's simulated
Count of virtual machine IPK's simulated
Count of virtual machine PTLB's simulated
Count of virtual machine RRB's simulated
Count of virtual machine STCTL's simulated
Count of virtual machine LCTL's simulated
Count of virtual machine CS's simulated
Count of virtual machine CDS's simulated
Count of virt machine diagnose disk I/O's
Number of users dialed to virtual machines
Number of users logged on
Number of page reads
Number of page writes
Number of system pagable pages
Sum of working sets of in-Q users
Number of users in interactive queue (Q1)
No. of users in compute bound queue (Q2)
Number of users eligible to enter Q1
Number of users eligible to enter Q2
Monitor sampling interval (seconds)
Count of cylinders allocated on primary
paging device
Cylinder capacity of primary paging device
1975
Number
of
Bytes
CP
Variable
Name
DSECT
Variable
Name
4
4
4
4
DMKDSPCK
PSASVCCT
DMKPRGCT
DMKIOSCT
DMKDSPCC
DMKDSPAC
MNOOOCKI
MNOOOCSV
MNOOOCPG
MNOOOCIO
MNOOOCDS
MNOOOCDA
MNOOOCDB
MNOOOCSC
MNOOOEK
4
4
4
4
4
4
4
4
4
4
4
4
DMKDSPRC
DMKSCHCT
DMKPRVEK
DMKPI:'(VIK
DMK P Ify f'13
i
'0'
• :::I
·tC
: -i
.;r
• iii'
:r
·3'
YOUR COMMENTS PLEASE . ..
• III
This manual is one of a series which serves as a reference source for
systems analysts, programmers, and operators of I BM systems. Your
comments on the back of this form will be carefully reviewed by the
persons responsible for writing and publishing this material. All comments and suggestions become the property of IBM.
Please note:
Requests for copies of publications and for assistance in
utilizing your IBM system should be directed to your IBM representative
or to the IBM sales office serving your locality.
FOLD
FOLD
FIRST CLASS
PERMIT NO. 172
BURLINGTON, MASS.
BUSINESS REPLY MAIL
NO POSTAGE STAMP NECESSARY IF MAILED IN U.S.A.
.co
POSTAGE WI LL BE PAID BY
.~
.<
· ...,
IBM CORPORATION
.-+
.~
VM/370 PUBLICATIONS
Ql
24 NEW ENGLAND EXECUTIVE PARK
·. ~
BURLINGTON, MASS. 01803
.(")
(")
."
Ql
:~
• -..J
· .,
·0
'Cf)
:~
."tI
:0
•
•
(Q
VI'
......•.........................................................•..•..•......•...•........................................'G)
c
FOLD
FOLD
c.:
:
: CD
.~
::::I
.-+
.CD
.0.
:::::1
·c
:(1)
:?>
G)
International Bu.lne.. Machine. Corporation
Data Proce••lng Dlvl.lon
1133 We.tche.ter Avenue, White Plalnl, New York 10804
(U.S.A. only)
IBM World Trade Corporation
821 United Natlonl Plaza, New York, New York 10017
(International)
n
N
·9
..a
OQ
o
'w"
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : No XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Producer : Adobe Acrobat 9.13 Paper Capture Plug-in Modify Date : 2009:09:09 19:03:24-07:00 Create Date : 2009:09:09 19:03:24-07:00 Metadata Date : 2009:09:09 19:03:24-07:00 Format : application/pdf Document ID : uuid:89d8448d-ba26-4a7f-9889-b520e2c52dda Instance ID : uuid:888d55c4-499c-4799-9f66-85a815a3cf5d Page Layout : SinglePage Page Mode : UseOutlines Page Count : 437EXIF Metadata provided by EXIF.tools