SC23 0358 1_VM_XA_SP_CP_Command_Reference_Rel_2_Nov88 1 VM XA SP CP Command Reference Rel 2 Nov88
SC23-0358-1_VM_XA_SP_CP_Command_Reference_Rel_2_Nov88 SC23-0358-1_VM_XA_SP_CP_Command_Reference_Rel_2_Nov88
User Manual: SC23-0358-1_VM_XA_SP_CP_Command_Reference_Rel_2_Nov88
Open the PDF directly: View PDF 
.
Page Count: 802
| Download | |
| Open PDF In Browser | View PDF |
----- --- -- -------------_.-
Vi rtual Machi ne/Extended Architecture ™
System Product
CP Command, Reference
VM/Xp\M SP Release 2
SC23-0358-1
Second Edition (November 1988)
This is a major revision of, and obsoletes, SC23-0358-0. Technical changes throughout this manual are
indicated by vertical bars to the left of the changed material.
This edition applies to Release 2 of the Virtual Machine/Extended Architecture System Product (VM/XA SP)
Licensed Program 5664-308. Changes are made periodically to the information herein; before using this
publication in connection with the operation of IBM systems, consult the latest IBM System/370, 30xx, 4300,
and 9370 Processors Bibliography, GC20-000l, for the editions that are applicable and current.
References in this publication to IBM products, programs, or services do not imply that IBM intends to
make these available in all countries in which IBM operates. Any reference to an IBM licensed program in
this publication is not intended to state or imply that only IBM's licensed program may be used. Any
functionally equivalent program may be used instead.
Publications are not stocked at the address given below. Requests for IBM publications should be made to
your IBM representative or to the IBM branch office serving your locality.
A form for readers' comments is provided at the back of this publication. If the form has been removed,
comments may be addressed to International Business Machines, Department 52Q/MS 458, Neighborhood
Road, Kingston, N.Y. 12401. IBM may use or distribute whatever information you supply in any way it
believes appropriate without incurring any obligation to you.
Virtual Machine/Extended Architecture and VM/XA are trademarks of the International Business Machines
Corporation (IBM).
© Copyright International Business Machines Corporation 1988
Preface
Purpose
This publication describes the command formats, syntax rules, operands, and options
for the Virtual Machine/Extended Architecture System Product (VM/XA SP) control
program (CP) commands.
Audience
This manual is for anyone who uses CP commands.
Related Publications
Please refer to the Bibliography at the back of this publication.
Preface
iii
Contents
Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
............................
Using VM/XA SP CP Commands
VM/XA SP CP Command Structure . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Command Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Command Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Enter Comments in the CP Command Language . . . . . . . . . . . . .
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Truncations and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . .
Notational Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Privilege Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
1
1
2
2
3
3
3
3
5
8
Chapter 2. VM/XA SP CP Commands . . . . . . . . . . . . . . . . . . . . . . . .
* (ASTERISK COMMAND) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#CP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ATTACH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ATTN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AUTOLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BACKSPACE/BACKWARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BEGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHANGE: Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CLOSE: Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COMMANDS .................................~......
COUPLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CPFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CPT RAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ' . . . .
CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEDICATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE
..........................................
DEFINE CONSOLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE CHANNEL-TO-CHANNEL ADAPTER . . . . . . . . . . . . . . . . .
DEFINE GRAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE MDISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE (spooling device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE (temporary disk) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D EFINE (virtual device) . . . . . . . . , . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFSEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFSYS
.........................................
DETACH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETACH CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETACH (real device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETACH VIRTUAL (devices) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETACH VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETACH XSTORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
DIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
95
101
105
107
108
112
116
118
120
Contents
V
11
17
18
20
21
30
31
35
37
39
41
48
49
58
60
62
63
70
71
73
75
77
78
80
81
82
83
87
89
91
93
DISABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISCONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISPLAY GUEST STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISPLAY HOST STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISPLAY PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISPLAY PROGRAM STATUS WORDS . . . . . . . . . . . . . . . . . . . . .
DISPLAY REGISTERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISPLAY SCHIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISPLAY VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DRAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
DUMP GUEST STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DUMP HOST STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DUMP PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DUMP PROGRAM STATUS WORDS . . . . . . . . . . . . . . . . . . . . . .
DUMP REGISTERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DUMP SCHIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DUMP VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ECHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ENABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXTERNAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FORCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FORWARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FREE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FREE LOGON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FREE PRINTER/PUNCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HALT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HOLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . '. . ..
HOLD LOGON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HOLD PRINTER/PUNCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INDICATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INDICATE I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INDICATE LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INDICATE PAGING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INDICATE QUEUES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INDICATE USER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INDICATE VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOADBUF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOADVFCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOCATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOGOFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOGON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MESSAGE ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MESSAGE (user) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MONITOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MONITOR EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MONITOR SAMPLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MONITOR START/STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
MSGNOH . . . . . . . . . . . . . . . . . . . . . . . . . . . '.' . . . . . . . . . . .
NOTREADY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vi
VM/XA SP2 CP Command Reference
122
124
126
130
135
139
140
141
144
146
150
156
161
166
170
171
173
176
178
182
183
184
186
188
190
192
193
194
196
198
199
200
202
204
205
209
211
213
218
219
223
228
233
236
238
241
244
248
250
251
253
256
262
267
269
270
ORDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PURGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PURGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PURGE IMG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PURGE NLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PURGE NSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PURGE TRFILES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PURGE UCR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY ABEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY ACCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY ALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CACHE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CHPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CMDLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY COMMANDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CPLANGLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CPLANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CPLEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CPT RACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CPTRAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY CPUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY DASD RESERVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY (real device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY FILES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY FRAMES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY HOLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY IMG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY IOASSIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY LINKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY LOGICAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY LOGMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY MAXSPOOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY MAXUSERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY MITIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY MONDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
QUERY MONITOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY NAMES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY NLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY NSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY PATHS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY PER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY PFnn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY PROCESSORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY QUICKDSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY READER/PRINTER/PUNCH . . . . . . . . . . . . . . . . . . . . . .
QUERY RECORDING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY SCREEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY SDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY SECUSER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY SHARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERY SRM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
271
275
276
278
281
283
285
287
289
290
297
298
299
301
305
307
308
310
311
312
313
316
317
318
320
335
337
340
343
345
347
348
349
350
351
352
353
355
356
364
366
368
375
377
378
379
381
382
383
390
392
393
394
396
401
402
Contents
vii
QUERY (real) STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
QUERY SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
QUERY TAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
QUERY TDISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
QUERY TERMINAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
QUERY TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 413
QUERY TRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
QUERY TRFILES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
QUERY TRSAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 420
QUERY TRSOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
QUERY UCR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
QUERY USERID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
QUERY USERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
QUERY VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
QUERY VIRTUAL ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
QUERY VIRTUAL CONSOLE . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
QUERY VIRTUAL CPUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
QUERY VIRTUAL CTCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
QUERY VIRTUAL DASD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
QUERY VIRTUAL DEVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
QUERY VIRTUAL GRAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
QUERY VIRTUAL PRINTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
QUERY VIRTUAL PUNCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
QUERY VIRTUAL READER . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
QUERY VIRTUAL STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
QUERY VIRTUAL TAPES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
QUERY VIRTUAL UR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
QUERY VIRTUAL VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
QUERY VIRTUAL XSTORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
QUERYV=R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
QUERY XSTORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
READY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
RECORDING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
REDEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
RESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
RETAIN XSTORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
REWIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
SAVESEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
SAVESYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
SCREEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
SEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
SET ABEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
SET ACCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
SET AUTOPOLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
SET CACHE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
SET CCWTRAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
SET CMDLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
SET CONCEAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
SET CPCONIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
SET CPLANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 508
SET CPTRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
SET CPUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
SET DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
viii
VM/XA SP2 CP Command Reference
SET EMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET IMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET IOASSIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
SET LINEDIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET LOGMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
SET MACHINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET MAXUSERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET MIH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET MITIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET (error recording) MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET MONDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET NOPDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET NOTRANS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET PAGEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET PFnn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET PFnn COpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET PFnn RETRIEVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET PFnn TAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET QUICKDSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET RESERVED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET RUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET SHARE . . . . . . . . . . .; . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET SHARED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET SMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET SRM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET SVC76 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET VMCONIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET WNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHUTDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SLEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . '. . ..
SPOOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPOOL READERjPRINTERjPUNCHjCONSOLE . . . . . . . . . . . . . . ..
SPOOLING: Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ',' . .,
SPTAPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,....
SPTAPE CANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPTAPE DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPTAPE LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPTAPE SCAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPTAPE STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
START: Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STORE GUEST STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STORE HOST STORAGE
..............................
STORE PSWjCAWjCSW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STORE REGISTERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STORE STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STORE VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
522
523
524
525
526
528
529
530
531
534
535
536
537
538
539
540
542
545
547
549
550
552
553
554
555
557
558
559
564
565
566
567
568
569
571
572
574
577
579
586
594
595
598
601
602
603
604
612
613
615
617
619
620
621
622
625
ix
TAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL APL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL ASCIITBL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL ATTN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
TERMINAL BREAKIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL BRKKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL CHARDEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL CONMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL CNTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL ESCAPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL HI LIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL LINEDEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL LINEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL LINE SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL PROMPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL SCROLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL TABCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TERMINAL TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE: Common Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE: Command Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE APPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . " . . . . . .
TRACE BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE CLEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE COUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE EXTERNAL/PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE GOTO/CALL/RETURN . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE GPRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE INSTRUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
TRACE MCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE mnemonicl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE mnemonic2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE RIO/RSCH/SIO/SIOF/SSCH . . . . . . . . . . . . . . . . . . . . . . . .
TRACE STORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE SVC/DIAGNOSE/MC . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE TPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRACE TRAP . . . . . . . . . . . . . . . . . . . . : . . . . . . . . . . . . . . . . .
TRANSFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRSAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRSOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRSOURCE DISABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRSOURCE DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRSOURCE DROP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRSOURCE ENABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRSOURCE ID (Definition Operands) . . . . . . . . . . . . . . . . . . . . . . .
UNDEDICATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UNLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
" VARY PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
X
VMjXA SP2 CP Command Reference
627
630
633
634
635
636
637
639
640
642
643
644
645
646
647
648
649
650
651
652
653
654
659
663
672
673
674
676
677
678
679
680
682
684
686
688
689
691
693
695
697
699
700
702
704
710
715
718
719
720
721
722
731
732
734
737
743
745
749
751
VARY VECTOR . . . . . . .
VMDUMP . . . . . . . . . . .
WARNING . . . . . .
XAUTOLOG . . . . . . . . . .
.
757
Summary of Changes . . . . . . .
Second Edition . . . . . . . . . . .
759
759
Appendix A. Restricted Userids
Glossary
763
...
Bibliography . . . . . . . . . . . . . .
VM/XA System Product Microfiche
VM/XA System Product Publications
769
769
769
Index
773
.................. .
Contents
xi
Chapter 1. Introduction
The Virtual Machine/Extended Architecture™ System Product (VMjXATM SP) is a
flexible operating system that will help your installation to gain the benefits of the
IBM System/370 Extended Architecture (370-XA). This means the removal of
storage constraints and an enhancement to your use of IBM's largest 370-XA
processors. With VM/XA SP, you also get a high-capacity interactive
environment-CM8-that supports System/370 and 370-XA programs.
Environments
VMjXA SP uses two command languages which correspond to the two environments
it creates. You should:
• Use the control program (CP) command language if:
You are a VM/XA SP system operator and you want to control the
resources of the real machine located in your computer room.
You are a virtual machine user and you want to control your virtual
machine's configuration and environment.
• Use a virtual machine command language if:
You are communicating with the operating system you loaded into your
virtual machine.
To perform production or test work, load your virtual machine with one of
the operating systems supported by the VM/XA SP system. Your virtual
machine command language is the command language of the operating
system you load. This command language is described in the library that
documents that particular operating system.
To perform service, installation, and maintenance tasks, along with editing and
text creation, communicating with others, and problem solving, load your
virtual machine with the conversational monitor system (CMS). CMS is a
single user, conversational operating system. It runs under CP in a
System/370 mode or a 370-XA virtual machine. The VM/XA SP CMS
Command Reference describes the CMS commands used to install and to
service VM/XA SP.
Using VM/XA SP CP Commands
You can use CP commands whenever:
• Your virtual machine is in the control program (CP) command environment.
Your virtual machine is in the CP environment when you log on to VM/XA SP
and "CP READ" is displayed in the lower right-hand corner of the screen.
Virtual Machine/Extended Architecture and VM/XA are trademarks of the International Business Machines
Corporation (IBM).
Chapter 1. Introduction
1
• You press the break key while in full-screen mode before entering a command.
(The break key may be PAl, the VMjXA SP default break key, or another key
that you have defined as the break key using the TERMINAL BRKKEY
command. Also, the break key may be totally disabled by some application
programs or when in the protected application environment.)
• You are in a virtual machine command environment, not running in full-screen
mode, and issue the #CP command (and # is your logicallinend character).
• You are in the CMS virtual machine environment and issue the CP command.
• You are in the CMS virtual machine environment and have the 1MPCP function
set ON.
To determine your current command environment, look at the status area in the
lower right-hand comer of your display screen. "CP READ" indicates the CP
environment and "VM READ" indicates the virtual machine environment. If you're
running CMS in your virtual machine, "VM READ" indicates the CMS
environment. When "RUNNING" appears in the status area, enter a null input line
to determine your environment. (To enter a null line, press the enter key but do not
enter any data.) When you enter the null line, the status area displays either "CP
READ" or "VM READ." Also, if you're in a read state in either the CP command
environment (with RUN set OFF) or the CMS command environment and you enter
a null line, the system responds with the name of your command environment ("CP"
or "CMS") in the system output area.
You enter CP commands using any combination of uppercase and lowercase letters.
When you have typed the command and its operands, press the enter key to execute
the command.
You can also issue CP commands from CMS EXEC procedures. VMjXA SP Real
System Operation and the VMjXA SP System Product Interpreter User's Guide
contain information about issuing CP commands from CMS EXEC procedures.
VM/XA SP CP Command Structure
A VMjXA SP command line consists of a command name, usually followed by one
or more positional operands. The general form for the CP command line is:
I
command name
I
operands ...
You must use one or more blanks to separate each entry in the command line unless
otherwise indicated.
The Command Name
The command name is an alphanumeric symbol, not more than twelve characters
long. For example, you can enter:
DISCONNECT.
as a command.
In general, command names are verbs that describe the function that you want the
system to perform. For example, if,you want to attach a real device to your virtual
machine configuration, you would issue the ATTACH command.
2
VMjXA SP2 CP Command Reference
The Command Operands
Command operands are keywords and positional symbols, usually no longer than
eight alphanumeric characters.
You use operands to specify the information on which the system will operate when
it performs the command function. For example, you use the TERMINAL operand
in conjunction with the CP QUERY command to find out what terminal options are
in effect for your virtual machine.
Some commands require no operands; others require several. You can find a
description of each command with all of its operand requirements in
Chapter 2, "VM/XA SP CP Commands."
Unless otherwise indicated, you must enter the operands that you select in the order
in which they appear in the command formats in Chapter 2, "VM/XA SP CP
Commands. "
How to Enter Comments in the CP Command Language
You can use the CP * command to annotate your display screen and console spool
file. Within this console spool file will be your input to the system and the system's
responses back to you. Refer to the description of the CP * command in
Chapter 2, "VM/XA SP CP Commands" for complete details.
Character Sets
You can enter VM/XA SP CP commands using a combination of characters from six
different character sets. The contents of each of these sets is summarized in Table 1.
Table 1. Character Set Summary
Symbols
Character Set
Names
Separator
Blank
National
Dollar Sign
Pound Sign
At Sign
$
#
Alphabetic
Uppercase
Lowercase
A-Z
a-z
Numeric
Numeric
0-9
Alphanumeric
National
Alphabetic
Numeric
$,#, @
A - Z, a - z
0-9
Special
@
All other
characters
Using Truncations and Abbreviations
To make entering commands on the keyboard more convenient, VM/XA SP allows
you to enter many commands and operands in a shortened form. This shortened
form can be either a truncation or an abbreviation.
'
Chapter 1. Introduction
3
You truncate a command or operand name by dropping one- or more letters from
the end of the name. The format box for each command in Chapter 2, "VMjXA
SP CP Commands" shows the truncations that you can use for each command and
its operands. If a letter appears in uppercase in the format box, you must enter it
when you issue the command from your display; if a letter is in lowercase, you may,
if you wish, omit it when you issue the command.
For example, the format box for the QUERY command shows the command as:
Query
This means that you can enter the QUERY command in any of the following forms:
query
quer
que
qu
q
The minimum acceptable truncation is Q, but CP will accept any of the above forms
of the command.
Abbreviations are also shorter forms of commands and operands, but unlike
truncations, are not formed by simply dropping letters from the name of the
command.
The format boxes in Chapter 2, "VMjXA SP CP Commands" show acceptable
abbreviations for command names below the full name of the command.
Abbreviations for operands are listed in the description of the operands following the
format box.
For example, the format box for the MESSAGE command shows:
Message
Msg
This means that you can:
• Truncate the command to a minimum of "M"
• Use the abbreviation "MSG"
• Truncate the abbreviation to "MS" or "M".
Thus, CP will accept all of the following forms of the MESSAGE command:
message
messag
messa
mess
mes
me
m
4
OR
VM/XA SP2. CP Command Reference
msg
ms
m
Notational Conventions
The command format descriptions in Chapter 2, "VM/XA SP CP Commands" use
the following notation to define command syntax:
• Truncations and Abbreviations of Commands
Where truncation of a command name or operand is permitted, the shortest
acceptable version of the command is indicated in uppercase letters. (Of course,
you can enter the command from your display using any combination of
uppercase and lowercase letters.) If no truncation is permitted (that is, the entire
command name or option is in uppercase letters), you must enter the entire
command name or operand.
Abbreviations are shown below the full command name in the format box, and
abbreviations for operands are shown in the description of the operands that
follows the format box.
• Do not enter the following symbols when you are entering CP commands.
These symbols are used to define command formats and are not part of the CP
commands they describe:
Character
Symbol
Definition Usage
Underscore
-
Default
Braces
{}
Must select one operand
Brackets
[]
Optionally select operand
Ellipsis
...
Repeat operand
• Always enter uppercase letters and words, and the following symbols when
specified in the format box:
Character
Symbol
Asterisk
*
Comma
,
Hyphen
-
Equal sign
=
Parenthesis
()
Period
Colon
• Lowercase letters, words, and symbols serve two purposes in the command
format box.
Lowercase letters in a command or operand name indicate that you do not have
to enter that letter when entering the command or operand from your display.
(See "Using Truncations and Abbreviations" above for more information.)
Other lowercase words and symbols that appear in the format box represent
variable information. You must supply the specific information that VM/XA SP
system will need to perform the command function. For example, "hexloc"
Chapter 1. Introduction
5
indicates that the system needs a hexadecimal storage location in order to
process the command. You would substitute the appropriate value when you
enter the command.
Table 2 includes "variable" names that are commonly used in
Chapter 2, "VM/XA SP CP Commands" to express command syntax:
Table 2 (Page 1 of 2). Variable Names Commonly Used to Express
Command Syntax
Variable
Definition
cpuaddr
A virtual processor address, in hexadecimal.
hexloc
A one- to eight-digit hexadecimal number
that represents a location in storage. If your
virtual machine is operating in System/370
mode, storage locations can range from 0
through FFFFFF. For 370-XA mode virtual
machines, the maximum value is 7FFFFFFF.
Of course, when you substitute a value for
hexloc, it can never be larger than the size of
the real or virtual machine storage that it
refers to.
6
ldev
An "L" followed by a one- to four-digit
hexadecimal number that represents a logical
device number. Note that Ll, L01, LOO1,
and LOOO 1 all represent the same logical
device number.
ldev-Idev
A range of logical device numbers. The
second logical device number must be greater
than or equal to the first. F or example,
L2AO-L2A2 refers to the logical device
numbers L2AO, L2AI, and L2A2.
luname
A 1- to 8-character logical unit name that
identifies an SNA/CCS terminal or printer.
It is the name from the VTAM definition of
the device as an SNA logical unit.
rdev
A one- to four-digit hexadecimal number that
represents a real device number. This is the
hardware configured physical device number.
rdev-rdev
A range of real device numbers. The second
device number must be greater than or equal
to the first. For example, 2AO-2A2 refers to
real device numbers 2AO, 2Al, and 2A2.
spoolid
The spool file identification number tjlat CP
assigns to each spool file created on the
system.
userid
The one- to eight-character name that
identifies the user to the VM/XA SP system.
This is essentially the name by which the
system knows you.
VMjXA SP2 CP Command Reference
Table 2 (Page 2 of 2). Variable Names Commonly Used to Express
Command Syntax
Variable
Definition
vdev
A one- to four-digit hexadecimal number that
represents a virtual device number.
vdev-vdev
A range of virtual device numbers. The
second device number must be greater than
or equal to the first. For example, lDO-ID2
refers to virtual device numbers IDO, IDl,
and lD2.
• Choices are represented in the command format boxes by stacking.
For example, the representation:
A
B
C
indicates that you have three choices: A, B, or C.
• An underscore indicates a default. If you select an underscored choice, you need
not specify it when you enter the command.
For example, the representation:
A
~
C
indicates that you may select A, or B, or C. If you select B, you need not
specify it when you enter the command. If you do not enter A, or B, or C, the
system will assume that B was your choice.
• When a list of choices is enclosed by braces, you must select one of the choices
when you enter the command.
For example, the representation:
indicates that you must specify one of A, or B, or C.
• When a list of choices is enclosed by brackets, you may select one of the choices
when you enter the command; your selection is optional.
For example, the representation:
UJ
indicates that you may enter A, or B, or C, or you may omit the field.
Chapter 1. Introduction
7
• An ellipsis ( ... ) indicates that you can repeat the preceding item or group of
items more than once in succession.
For example, the representation:
{spoolidl ••• }
indicates that you can enter more than one spoolid.
Privilege Classes
The set of CP commands that you can use depends upon the privilege class or classes
that have been assigned to you.
VMjXA SP CP commands are divided into eight groups, each represented by a
privilege class. The privilege class indicates the type of user from whom the
commands will be accepted.
In general, the system programmer who creates your system directory will assign you
one or more privilege classes as part of your entry in the directory.
Privilege classes are denoted by the letters A through Z, the numbers I through 6, or
the word "Any." These classes, and the type of user who can use the commands
belonging to the privilege class set, are summarized in Table 3. Classes I through Z
and numbers I through 6 are reserved for redefinition through user class restructure
(UCR) by each installation for its own use.
Users who have been assigned the password NOLOG have no privilege class and can
only receive spooled output as punched cards or printed forms. For more
information about NOLOG users, see VMjXA SP Installation and Service.
Table 3 (Page 1 of 2). Privilege Classes
Class
User and Function
A
System Operator: The class A user controls the VMjXA
SP system. The system operator is responsible for the
availability of the VMjXA SP system and its resources.
In addition, the system operator controls system
accounting, broadcast messages, virtual machine
performance options, and other options that affect the
overall performance of VMjXA SP.
Note: The class A user who is automatically logged on
during CP initialization is designated as the
primary system opera tor.
8
B
System Resource Operator: The class B user controls all
the real resources of the VMjXA SP system, except those
controlled by the system operator and the spooling
operator.
C
System Programmer: The class C user updates certain
functions of the VMjXA SP system.
D
Spooling Operator: The class D user controls spool files
and the system's real reader, printer, and punch
equipment allocated to spooling use.
VMjXA SP2 CP Command Reference
Table 3 (Page 2 of 2). Privilege Classes
Class
User and Function
E
System Analyst: The class E user examines and saves
system operation data in specified VMjXA SP storage
areas.
F
Service Representative: The class F user obtains, and
examines in detail, data about input and output devices
connected to the VMjXA SP system.
G
General User: The class G user controls functions
associated with a particular virtual machine.
Any
Commands belonging to class "Any" are available to any
user, regardless of his privilege class. These commands
are primarily those used to gain access to or relinquish
access from the VMjXA SP system.
H
Reserved for IBM use.
1- Z
I-6
Classes I through Z are reserved for redefinition through
user class restructure (UCR) by each installation for its
own use.
Chapter 1. Introduction
9
Chapter 2. VM/XA SP CP Commands
This section contains format descriptions for all of the VMjXA SP CP commands.
These command formats are listed in alphabetical order except for the * and #CP
commands, which appear first.
Each of the command formats is presented in the following order:
• Command name: identifies the name of the command. This appears on the top
of the page for easy reference.
• Privilege class: indicates which users can issue the command, unless user class
restructure (UCR) is in use.
• Description of function: explains how you can use the command.
• Syntax diagram: lists the syntax of the command with all the possible operands
that you can use.
• Operand description: describes the function of each operand and any values that
you can include in the operand.
• Usage Notes: describe special uses of the command and general considerations
that you should be aware of before you issue the command.
• Responses: describe the CP command responses that you may receive on your
display device. Responses are normal operation output and provide information
about the execution and effect of the command. Unlike system messages,
command responses are not prefixed with an identification and are not
contained in the VMjXA SP System Messages and Codes Reference.
Note, however, that execution of commands may produce system messages for
abnormal situations. Refer to the VMjXA SP System Messages and Codes
Reference for complete information about these messages and suggested actions
that you can take.
• Migration Notes: describe for both VMjSP HPO users and VMjXA System
Facility users what specific changes they may expect to see from their systems to
VMjXA SP. For more information, both general and specific, these users
should refer to the VMjXA SP Conversion Notebook.
Chapter 2. VMjXA SP CP Commands
11
To help you see at a glance which commands are discussed in this book, the
following table lists each command alphabetically, shows its privilege classes, and
gives a brief description of what the command accomplishes.
Command Summary
Table 4 (Page 1 of 5). List of CP Commands and Their Privilege Classes
CP
Command
IBM-Defined
Privilege
Class
Command Description
*
Any
Display a comment on the virtual operator's console.
#CP
Any
Enter CP commands when the virtual machine command
environment is in effect and/or switch from the virtual machine
command environment to the CP command environment.
ACNT
A
Create accounting cards for one or more logged-on users and
reset accounting data.
ATTACH
B
Allocate a real or logical device to a virtual machine.
Allocate a direct access device for CP control (CP-owned
volume).
Allocate a partition of Expanded Storage to a virtual machine.
ATTN
G
Signal one attention interruption from a virtual operator's
console.
AUTOLOG
A,B
Automatically log on a virtual machine to operate with its virtual
operator's console disconnected.
BACKSPACE
(BACKWARD)
D
Reposition the output of a real spooling device.
BEGIN
G
Resume execution of the virtual machine at a specific virtual
storage location or at the address in the current PSW on all or
selected virtual CPU s.
CHANGE
D,G
Alter one or more external attributes of a closed spool file.
Alter the user hold status of an active output spool file.
CLOSE
G
Terminate spooling operations on a virtual card reader, card
punch, printer, or console.
COMMANDS
Any
Display the commands and diagnose codes which you are
authorized to use.
COUPLE
G
Connect two virtual machines via virtual channel-to-channel
adapter.
CP
Any
Treated as a null command if entered when the CP command
environment is in effect in a virtual machine.
CPFORMAT
G
Format, allocate, and/or label a direct access storage volume for
CP use.
CPT RAP
N.A.
VM/XA SP does not support CPTRAP. See the TRSOURCE,
TRSAVE, and SET CPTRACE commands.
CPU
G
Select the virtual CPU on which CP commands will be executed
or on which console function reads will be issued.
12
VMjXA SP2 CP Command Reference
Table 4 (Page 2 of 5). List of CP Commands and Their Privilege Classes
CP
Command
IBM-Defined
Privilege
Class
DEDICATE
A
Dedicate a real processor to a virtual CPU belonging to the
virtual = real virtual machine.
DEFINE
A,G
Reconfigure a virtual machine.
Define a minidisk on a system volume for recovery purposes.
DEFSEG
E
Define a skeleton system data file for a saved segment.
DEFSYS
E
Define a skeleton system data file for a named saved system.
DETACH
B,G
Remove a real or logical device from a virtual machine.
Remove a direct access storage device from CPo
Remove Expanded Storage from a virtual machine.
Remove a virtual CPU, virtual Vector Facility, or virtual device
from a virtual machine.
DIAL
Any
Connect a display to a virtual communication line of a
multiple-access virtual machine.
DISABLE
A,B,F
Prevent displays and VTAM service machines from accessing
VM/XA SP.
DISCONNECT
Any
Disconnect the virtual operator's console from a virtual machine.
DISPLAY
C,E,G
Display real storage on the virtual operator's console.
Display the contents of specified virtual storage areas, certain
registers, and/or certain control words on the virtual operator's
console.
DRAIN
D
Halt operations on specified real spooling devices after
processing of the current spool file is complete.
DUMP
C,E,G
Dump real storage to a spooled virtual printer.
Dump to a spooled virtual printer the contents of specified
virtual storage areas, certain registers, and/or certain control
words on the virtual operator's console.
ECHO
G
Test display hardware.
ENABLE
A,B,F
Allow displays and VTAM service machines to access VM/XA
SP.
EXTERNAL
G
Simulate an external interruption for a virtual machine and
return control to that virtual machine.
FLUSH
D
Immediately terminate transcription by a specified real unit
record device of the current output spool file.
FORCE
A
Cause the logoff of a specified user.
FORWARD
D
Reposition the current spool file on a real printer or card punch.
FREE
B,D
Remove spool files belonging to a specified user from system
hold status.
Remove a specified user from logon hold status.
HALT
A
Terminate the active channel program on the specified real
device.
Command Description
Chapter 2. VM/XA SP CP Commands
13
Table 4 (Page 3 of 5). List of CP Commands and Their Privilege Classes
CP
Command
IBM-Defined
Privilege
Class
HOLD
B,D
Place the spool files of a specified user in system hold status.
Prevent a specified user from logging on.
INDICATE
B,C,E,G
Display on the virtual operator's console the use of and
contention for the resources of the real machine.
IPL
G
Simulate initial program load for a virtual machine.
LINK
G
Provide access for a virtual machine to a minidisk that is owned
by another virtual machine.
LOADBUF
D
Load a real UCS or FCB buffer with a specified image.
LOADVFCB
G
Establish a virtual forms control buffer for a spooled virtual
printer.
LOCATE
C,E
Display the address of CP modules and certain CP control
blocks on the virtual operator's console.
LOCK
A
Bring pages into real storage and permanently lock them.
LOGOFF
LOGOUT
Any
Disable access to CP and terminate the existence of a virtual
machine.
LOGON
LOGIN
Any
Provide access to CP and establish the existence of a virtual
machine.
MESSAGE
A,B,Any
Send messages from user to user.
MONITOR
A,E
Initiate and terminate data collection and recording for
performance measurement.
MSGNOH
B
Send a message without the standard message header.
NOT READY
G
Simulate "not ready" for the specified virtual spooling device.
ORDER
D,G
Rearrange closed spool files in a specific order.
PER
G
See the TRACE command.
PURGE
A,B,C,D,E,G
Remove closed spool files and system data files from the system.
QUERY
Any
Request information about the configuration or status of a
virtual machine or the real machine.
READY
G
Simulate a device-end interruption for the specified virtual
device.
RECORDING
A,B,C,E,F
Change the processing parameters for CP accounting and error
recording facilities.
REDEFINE
G
Change the virtual device number of any existing virtual device
in a virtual machine configuration.
REPEAT
D
Repeat printing or punching of the current spool output file.
REQUEST
G
Signal one attention interruption from a virtual operator's
console.
14
VM/XA SP2 CP Command Reference
Command Description
Table
4
(Page
4
of 5). List of CP Commands and Their Privilege Classes
,
CP
Command
IBM-Defined
Privilege
Class
RESET
B,G
Release a real direct access storage device that holds a reserve.
Clear and reset all pending interruptions for a specified virtual
device and reset all error conditions.
RETAIN
B
Reserve Expanded Storage for CP use.
REWIND
G
Perform an operation equivalent to rewinding and readying a
tape drive.
SAVESEG
E
Save a saved segment in a previously defined system data file.
SAVESYS
E
Save a named saved system in a previously defined system data
file.
SCREEN
G
Change either the color definition, the highlighting definition, or
both definitions for a virtual machine console.
SEND
G
Enter console input to a disconnected virtual machine for which
you provide secondary console services.
SET
A,B,C,E,F,G
Establish system parameters.
Control various functions within a virtual machine.
SHUTDOWN
A
Checkpoint the system for a warm start and terminate real
machine operations.
SLEEP
Any
Place the virtual machine in a dormant state for a specified
period of time.
SMSG
G
Send a special message to a virtual machine programmed to
accept and process the message.
SPACE
D
Force single spacing on a real printer that is being used for
spooling.
SPOOL
G
Change spooling control options or transfer spool output files to
another virtual machine.
SPTAPE
D,E
Save on tape spool files and system data files and restore to the
system previously saved spool files and system data files.
START
D
Start a real spooling device after it has been drained or change
the processing options currently in effect for the device.
STOP
G
Place all virtual CPUs in a virtual machine in soft-stop or place
selected virtual CPU s in hard-stop.
STORE
C,G
Alter specified real storage locations.
Alter specified virtual storage locations, registers, and/or control
words or perform the STORE .STATUS function.
SYSTEM
G
Simulate for a virtual machine the following hardware functions:
CLEAR STORAGE, RESET, RESTART, and STORE
STATUS.
TAG
G
Assign tag data to a spooled virtual unit record output device,
insert tag data in the tag field of a spool output file, or display
the tag information assigned to a spooled output device or a
spool output file.
Command Description
Chapter 2. VMjXA SP CP Commands
15
Table 4 (Page 5 of 5). List of CP Commands and Their Privilege Classes
CP
Command
IBM-Defined
Privilege
Class
TERMINAL
G
Redefine the virtual operator's console I/O processing, message
handling, and attention interruption handling.
TRACE
G
Monitor events that occur in the virtual machine, including
instruction execution, storage alteration, register alteration, and
I/O activity.
TRANSFER
D,G
Send spool files to or retrieve previously transferred spool files
from the specified user's reader, printer, or punch queue.
TRSAVE
A,C
Control the saving of traces on tape or DASD.
TRSOURCE
C
Define and control I/O, data, and guest tracing.
UNDEDICATE
A
Remove sole use of a real processor from a virtual CPU
belonging to the virtual = real virtual machine.
UNLOCK
A
Unlock previously locked pages or release the pages in the V = R
or RI0370 area.
VARY
B
Mark available or unavailable for use a real device, real channel
path, real processor, or real Vector Facility.
VMDUMP
G
Dump to a spooled virtual reader all or selected pages of a
virtual machine's virtual storage.
WARNING
A,B,C
Send a high-priority message to a specified user or to all users.
XAUTOLOG
A,B,G
Automatically log on a virtual machine to operate with its virtual
operator's console disconnected.
16
VM/XA SP2 CP Command Reference
Command Description
* (ASTERISK COMMAND)
* (ASTERISK COMMAND)
Privilege Class: Any
Use the asterisk command (*) to annotate your console sheet or your display screen.
[any comment]
Usage Notes
1. CP treats any statement that you prefix with an asterisk as a comment line.
Thus, all of the following are comments:
*
* any comment
*any comment
*** any comment
2. If you have invoked the console spooling function for your virtual machine, the
commentary that you write will also appear in your console spool file.
Responses
None.
Migration Notes
VMISP HPO: VMjXA SP does not require a blank after the
* command.
Chapter 2. VMjXA SP CP Commands
17
#CP
#CP
Privilege Class: Any
Use the #CP command to execute one or more CP commands if you are not in a
full-screen environment. After the CP command or commands have been executed
your virtual machine will continue execution.
I HCP
[command line ••• ]
where:
command line
is the name and operands for the CP command or commands you want to issue.
You must precede the first command line with at least one blank. If you are
specifying multiple CP commands, separate them with your logical line end
symbol (see Usage Note 2).
Usage Notes
1. The #CP command is r handy method to reduce the number of operations you
must perform when you want to issue a CP command from a virtual machine
command environment. For example, you can display the number of files you
have on your virtual machine system by issuing the command:
HCP QUERY FILES
This is equivalent to performing the following sequence of operations:
a. Pressing the PAl key to enter the CP command environment
b. Entering the QUERY FILES command
c. Entering the CP BEGIN command.
2. The pound sign (#) shown in the preceding format represents the logical line end
symbol currently in effect for your virtual machine. If you have redefined the
logical line end symbol, you must substitute your line end symbol for the pound
sign.
3. Before you issue the #CP command, be sure that:
• Your virtual machine is operating with the CP SET LINEDIT function set
ON. This is the default.
• The first three characters you enter in the command line are #CP (uppercase
or lowercase); the "#" represents the currently defined logical line end
symbol.
• At least one blank separates the #CP from any command line.
• Your virtual machine issued a READ for at least four bytes of data.
4. You can enter multiple command lines as operands of the #CP command
provided that:
• Your virtual machine's console READ is for at least the number of bytes
required to enter the entire line.
• You separate all the command lines that you want to execute with the
current logical line end symbol.
5. If you enter #CP without operands, your virtual machine enters the CP
environment. You may then enter any number of CP commands. (If you have
SET RUN ON, you may issue only one command.) To return to virtual
machine operation, enter the CP BEGIN command.
18
VM/XA SP2 CP Command Reference
#CP
If you enter #CP during a virtual machine read (that is, when "VM READ"
appears in the lower right corner), CP terminates your virtual machine's console
read by returning a unit exception for the virtual console. The operating system
that is running in your virtual machine then reissues the console READ to allow
you to key in the appropriate response to a previous message from that
machine's operating system.
6. The #CP command has no meaning if:
• You are running an operating system in your virtual machine that has a
virtual console defined as a 3270
• You are using DIAGNOSE Code X 158
3270 VIRTUAL CONSOLE
INTERFACE, CCW operation codes 29 or 2A.
I
-
7. See Table 5 for a summary of system responses to various #CP commands.
Table 5. System Responses to Various #CP Commands
Command
System Action
#CP
Your virtual machine enters the
CP environment.
#CP QUERY FILES
The QUERY FILES command
is executed.
#CP QUERY FILES#QUERY USERS
Two separate QUERY
commands are executed.
#CP data entered
You enter the CP environment
and CP interprets the "data
entered" as a CP command,
which mayor may not be a
valid command.
Responses
If you enter #CP without a command line, you receive this response:
CP
and the status area of your display device will indicate "CP READ." If you enter
#CP with a command line, you receive the responses that correspond to the
individual CP commands you entered.
Chapter 2. VM/XA SP CP Commands . 19
ACNT
ACNT
Privilege Class: A
Use the ACNT command to create accounting records for logged-on users and to
reset accumulated accounting data.
ACNT
useridl [userid2 ••. userid10]
SYSTEM
{ ALL
}
where:
useridl [userid2••. useridl01
is the list of users for whom accounting records are to be created. You can
specify up to 10 userids on the command input line.
SYSTEM
is used to account for all time not charged to a specific user.
ALL
specifies that accounting records are to be created for all logged-on users, and
for SYSTEM.
Usage Notes
1. When you issue the ACNT command, an accounting record is created for each
user that you specify on the command line, including accounting records for any
dedicated devices or T-disks. The record indicates the amount of time that user's
virtual machine has used since the last ACNT command was issued for the user,
or since the user logged on.
Vector time is a subset of CPU time; that is, using a second of vector CPU time
results in incrementing both the CPU time and the Vector Facility time counts.
This applies to both virtual (guest) and total time. The reason for this is that
using the VF implies using the CPU; all VF usage arises from executing
instructions on that CPU.
2. CP processes the list of userids in the same order that you entered them on the
command line. If any userid in the list is invalid, accounting records are created
only for those userids that precede the invalid one.
3. To provide an ACNT command syntax that is compatible with VMjSP, VMjXA
SP accepts CLOSE as an option following ALL or ACNT (for example, ACNT
ALL CLOSE or ACNT CLOSE). However, this option does not change the
operation of the ACNT command in VMjXA SP.
Responses
None.
Migration Notes
VM/SP HPO:
1. VMjXA SP accepts but ignores CLOSE if specified.
2. VMjXA SP does not send a response to the user indicating accumulated
accounting data.
3. VMjXA SP supports an additional operand: SYSTEM.
20
VM/XA SP2· CP Command Reference
ATTACH
ATTACH
Privilege Class: B
Use the ATTACH command to logically connect:
• A real or logical device to a virtual machine for that virtual machine's exclusive
use
• A DASD device to CP
• A partition of real Expanded Storage to a virtual machine for that virtual
machine's exclusive use.
ATTach
{rdev} [TO] { ~seri d} [[AS] vdev]
[R [fa]
TWITH]
NOASSIGN]
SYSCTL
DEVCTL
NOCTL
{l dev} [TO] {~Seri d} [[AS] vdev] [R [/0]]
{rdev} [TO] SYSTEM
[[AS] volid]
} [TO] {~serid} [R[jO]]
rdev ••.
{ rdev-rdev
l dev ..•
::: } [TO]
ldev-ldev
{
rdev ldev
{~serid} [R[jO]]
[[WITH]
NOASSIGN]
SYSCTL
DEVCTL
NOCTL
rdev ..• ) [TO] SYSTEM
{ rdev-rdev
f
where:
rdev
rdev •••
rdev-rdev •..
specifies a real device number, a list of real device numbers or a range. of real
device numbers to be attached to the specified user or to the CP system. Specify
a real device number as four hexadecimal digits, noting that leading zeros may
be omitted. The maximum number of devices allowed in a range is 256.
If you are not specifying a virtual device number or volume label for the real
device that you are attaching, the virtual device number defaults to the real
device number. You may combine device numbers, lists of device numbers, and
ranges of device numbers on a single command line.
If you are specifying a virtual device number for the device, you can specify only
one real device number when you issue the ATTACH command.
Chapter 2. VM/XA SP CP Commands
21
ATTACH
Idev
Idev •••
Idev-ldev ..•
specifies a logical device number, a list of logical device numbers or a range of
logical device numbers to be attached to the specified user. Specify a logical
device number as an "L" followed by up to four hexadecimal digits, noting that
leading zeros may be omitted.
If you are not specifying a virtual device number for the logical device that you
are attaching, the virtual device number defaults to the logical device number.
You may combine device numbers, lists of device numbers, and ranges of device
numbers on a single command line.
If you are specifying a virtual device number or volume label for the device, you
can specify only one logical device number when you issue the ATTACH
command.
rdev Idev .••
specifies a list of both real and logical device numbers.
TOJuSerid
[ TO: *
is the userid of the virtual machine that is to receive the device or devices or
Expanded Storage. That virtual machine must be currently logged on to the
system. If you are attaching either a device or Expanded Storage to your own
virtual machine, you can specify your userid as an asterisk (*).
You must use TO when:
• You specify a userid with 3 numbers or less in a range of addresses or
multiple device addresses
• You specify a userid that could also be a valid hexadecimal device address
(for example, CE)
• You specify a userid as "to" or "t."
(AS) vdev
is the virtual device number to be assigned to the device.
Note: If your virtual machine is operating in System/370 mode, vdev is the
System/370 virtual device address (channel, control unit, and device) and
may consist of up to four digits. If your virtual machine is operating in
370-XA mode, vdev specifies the virtual device number. It is assigned to
an available virtual subchannel number, which may consist of up to four
digits. If the device is attached to the preferred guest, then an effort is
made to assign the real subchannel number as the virtual subchannel
number.
R(/O)
is optionally used for DASD and tape devices that are attached to a user. This
allows the system operator to apply read-only protection to a user's disk or tape.
CP ignores the RIO operand for any device number that does not correspond to
a TAPE or DASD device.
(WITH) NOASSIGN
specifies that the tape device that is to be attached to the user is not to be
assigned to the user's system.
CP ignores the NOASSIGN operand for any real tape device that does not
support the ASSIGN/NOASSIGN CCWs.
22
VMjXA SP2 CP Command Reference
ATTACH
Warning: CP does not REWIND/UNLOAD when the tape is detached.
WITH] SYSCTL
,WITH DEVCTL
[
WITH NOCTL
determine the CCWs, and options within CCWs, that are accepted by this
device.
SYSCTL means that the device accepts CCWs that have a direct global effect on
subsystem resources and functions, not just CCWs that are related to the device.
For example, subsystem storage may be turned on or off. SYSCTL is the
default for V = R and V = F machines.
DEVCTL means that the device accepts CCWs that have an effect on resources
and functions directly related to the device. For example, caching may be
turned on or off for the device. DEVCTL is the default for the V = V
(nonpreferred) guest.
NOCTL means that the device accepts no CCWs that can exercise control of
subsystem resources or functions, regardless of whether they directly relate to the
device. For example, subsystem storage may not be turned on or off and
caching may not be turned on or off for the device.
(TO) SYSTEM
specifies that the DASD device is to be made available to CP for accessing users'
virtual disks and/or for paging, spooling and temporary disk functions.
(AS) volid
is the volume label of the volume on the device being attached. The volume
label on the device will be verified and must be unique when compared to all
other volumes attached to the system.
XSTORE
XSTORAGE
indicates that Expanded Storage is to be attached to the specified user.
XSTORE[TO],' {userid}
XSTORE TO {*}
specifies the userid of the virtual machine that is to receive the real Expanded
Storage. The virtual machine must be currently logged on to the system. The
userid of SYSTEM is not valid. * specifies the use rid of the virtual machine that
issues the ATTACH XSTORE command.
nnnnnnnnM
specifies the size of real Expanded Storage that is to be assigned to the virtual
machine. If the Expanded Storage exceeds the maximum available for guest
virtual machine use, then the maximum contiguous Expanded Storage is
assigned.
ALL
specifies that all of Expanded Storage that has not been reserved for CP use with
the RETAIN XSTORE command is attached to the user's virtual machine for
exclusive use. This is the default.
Usage Notes
1. If you are attaching a device with logical addresses, both the real device number
and the virtual device number you specify must be the base address.
2. When you attach a device to a 3880 Model 11 or 21 with SYSCTL or DEVCTL
specified, the base address and the paging addresses are processed. If you
specify NOCTL, only the base address is attached.
Chapter 2. VMjXA SP CP Commands
23
ATTACH
3. If you mount and ready a device that contains virtual minidisks after you have
loaded VM/XA SP onto the system, you must ATTACH that device to the
system if you want to use it. If you log on after the device has been attached,
you will gain access to the disk as provided by your entry in the system
directory. If you were logged on before the volume was attached to the system,
you must use the CP LINK command to gain access to the virtual disks.
4. All the device numbers you specify will be processed even if errors are
encountered when attempting to attach the devices. Thus, if you issue the
following command:
attach 10S-10F user1 r
and real devices lOA and lOD are not ready and online, the following devices
would be successfully attached:
10S, 109, 10B, 10C, 10E, 10F
Messages tell you which devices were successfully attached. Error messages
identify the devices that were not attached.
5. Attaching a cache device to a userid while any other cache is in use by a system
results in an error message.
6. You can use the system directory DEDICATE statement to attach real devices
to their virtual machine. Then, when they have successfully logged on to the
system, the devices (if online and available) are automatically attached to their
virtual machine. This method can save them the trouble of issuing multiple
ATTACH commands for the devices.
7. The ATTACH XSTORE command allows a class B operator to assign
Expanded Storage to a guest virtual machine without authorization in the user
directory. The command size parameter allows the operator to attach any size
up to the maximum Expanded Storage allowed for guest use on the system,
regardless of the user directory limit. The maximum allowed for a guest virtual
machine is the total XSTORE less what is retained by the system. For more
information, see the RETAIN command.
The size parameter must be in units of 1 megabyte. The size of the Expanded
Storage feature dedicated to the guest is displayed on the response to the
originator of the command as well as to the owner of the Expanded Storage.
When the user issues QUERY XSTORE, the dedicated Expanded Storage for a
user appears as an Expanded Storage feature equal· to the size provided in the
ATTACH XSTORE command. The actual size of Expanded Storage depends
on whether any non-configured Expanded Storage exists within the user's
Expanded Storage partition.
8. The system directory XSTORE statement directs CP to attach Expanded Storage
to a virtual machine during logon. When logon is complete, Expanded Storage
(if available) is automatically attached to the user's virtual machine.
9. When running on a partitioned processor, the amount of Expanded Storage
attached to a user may appear larger than the amount requested. For example,
a 3090-400E with 128 megabytes of XSTORE may be partitioned with 64
megabytes of XSTORE on each side. In this example, the lower block addresses
are on one side, the 'A' side, and the higher block addresses are on the other
side, the 'B' side. With CP running on the 'B' side, attaching 4 megabytes of
XSTORE to a user results in CP responding with 4 megabytes attached.
However, the guest operating system sees 68 megabytes attached with 64
megabytes not configured.
24
VM/XA SP2 CP Command Reference
ATTACH
10. Issuing the ATTACH XSTORE command at initialization suspends virtual
machine execution until XSTORE initialization completes. To avoid this, you
can (a) wait until XSTORE initialization completes to issue ATTACH XSTORE
or (b) issue ATTACH XSTORE from a disconnected virtual machine that has
been automatically logged on.
II. SYSCTLjDEVCTLjNOCTL apply only to DASD on a cached control unit. If
one of these operands is specified for a noncached DASD, the device is attached
and a response is issued stating that the operand was ignored.
12. If you attempt to use DEVCTL or NOCTL to attach cached DASD to a V=R
or V=F guest, the DASD is attached with SYSCTL and a response is issued
stating that an attach is forced to be SYSCTL for a preferred virtual machine.
This is necessary because a V = R or V = F guest may run with the start
interpretive execution assist or without CCW translation (see the SETCCW
command), and thus bypass CP's enforcement of the level of control.
13. Specifying a level of control (NOCTL, DEVCTL, or SYSCTL) for a DASD
device attached to a cache storage control unit authorizes CP to accept
particular control CCWs. Table 6 shows you the additional control CCWs CP
accepts for a level of control. The DEVCTL column shows the CCWs CP
accepts in addition to those it accepts for the NOCTL level of control. The
SYSCTL column shows the CCWs CP accepts in addition to those it accepts for
the DEVCTL and NOCTL levels of control.
Table 6. 3880 Control Levels
3880
Model
Additional Control CCWs
Accepted for DEVCTL
Additional Control CCWs
Accepted for SYSCTL
3880-11
Discard block (not all blocks) Set paging
parameters
Discard block (all blocks)
3880-13
Set subsystem mode (device option)
Set subsystem mode (subsystem option) Set
high performance storage limits
3880-21
Set subsystem mode (device option)
Discard block (not all blocks) Set paging
parameters
Set subsystem mode (subsystem option)
Discard block (all blocks)
3880-23
Set subsystem mode (device option)
Set subsystem mode (subsystem option)
14. Note that the ATTACH command does not execute synchronously when you
are attaching real devices to another userid. That is, you (the issuer of the
command) may receive control BEFORE all processing has been completed on
behalf of the other user. Any later attempt you make to use that device before it
becomes attached may yield unexpected results.
For example, suppose the following command sequence exists in a CMS EXEC
procedure:
CP DETACH 250 USERA
CP ATTACH 250 SYSTEM
CP will begin to ATTACH device 250 to the system before the DETACH
command completes. USERA has not completed all processing when the
DETACH is issued. Since the device is still attached to USERA, you receive an
error message for the ATTACH command.
Chapter 2. VM/XA SP CP Commands
25
ATTACH
Thus, if you intend to issue commands using the same real device owned by
another user, do not string the commands together (using the logical line end
character) and do not issue the commands one right after the other in a CMS
EXEC.
15. You cannot be certain that the device has been attached until you receive the
appropriate response from the system. If after a reasonable amount of time you
haven't received the expected response, issue the QUERY command to
determine the status of the device. Attachment may be pending (see Usage Note
14) or may have been unsuccessful. Note that if you issued the command from
the CMS environment and received a return code of 0, you cannot assume that
the device has been attached. A return code of 0 indicates only that your
request has been accepted.
Response 1
The following responses go to the receiver of the device:
type rdev ATTACHED TO userid vdev [RIO] [WITH SYSCTl.]
,WITH DEVCTl
WITH NOCTl
informs the user that the device has been attached to his or her virtual machine. If
more than one device number was entered, a response is be displayed for each device
attached.
DASDvdev vdev vdev vdev ATTACHED [RIO] [WITH SYSCTl]
WITH DEVCTl
occurs when attaching a DASD on a 3880 Model 11 or 21 subsystem. Notice that
WITH NOCTL has been deleted. Only the base address gets attached if NOCTL is
specified on the ATTACH command.
Note: In the above and all following ATTACH responses, "type" is one of the
following:
Type
Meaning
DASD
TAPE
RDR
PRT
PUN
GRAF
CTCA
CTLR
MSC
DEV
Direct access storage device
Magnetic tape
Card reader
Printer
Card punch
Display device
Channel-to-channel adapter
3704 or 3705 Communications Controller
Mass Storage Controller
Any other device
Response 2
Depending on the command format the class B user issued, this response indicates
the device(s) attached to a specified user's virtual machine (and, if appropriate, the
virtual device number access mode and the level of control for the device) or
indicates that the device has been attached to the CP system. You receive this
response for each device that is attached.
26
VM/XA SP2 CP Command Reference
ATTACH
The following responses go to the originator of the ATTACH command:
type {rdev} ATTACHED TO userid vdev
ldev
[RjO]
- or -
DASD rdev ATTACHED TO userid vdev [RjO] [WITH SYSCTl]
WITH DEVCTl.
WITH NOCTl .
- or -
type rdev ATTACHED TO SYSTEM volid
- or -
DASD rdev rdev rdev rdev ATTACHED TO SYSTEM volid
occurs when attaching a DASD on a 3880 Model 11 or 21 subsystem to VM/XA SP.
- or DASD rdev rdev rdev rdev ATTACHED TO userid vdev vdev vdev vdev [RjO] [WITH SYSCTl]
WITH DEVCTl
occurs when attaching a DASD on a 3880 Model 11 or 21 subsystem. Note that
WITH NOCTL has been deleted. Only the base address gets attached if NOCTL is
specified on the ATTACH command.
Response 3
The responses in this category are the responses which can be sent to the primary
system operator (if this operator did not issue the command) indicating that the
device has been attached either to the specified user's machine (at virtual device
number vdev) or to the CP system. The "originator" field designates the userid of
the user who issued the command.
The following responses go to the system operator:
type {rdev} ATTACHED TO userid vdev BY originator [RjO]
{ldev}
- or -
DASD rdev ATTACHED TO userid vdev BY originator [RjO].,[.WITH SYSCTl]
WITH DEVCTl
WITH NOCTl ,
-AND -
type rdev ATTACHED TO SYSTEM volid BY originator
Chapter 2. VMjXA SP CP Commands
27
ATTACH
- or -
DASD rdev rdev rdev rdev ATTACHED TO SYSTEM volid BY originator
occurs when attaching a DASD on a 3880 Model 11 or 21 subsystem to VMjSP.
DASD rdev rdev rdev ATTACHED TO userid vdev vdev vdev BY originator [RIO] [.WITH SYSCTL]
WITH DEVCTL
i
occurs when attaching a DASD on a 3880 Model 11 or 21 Subsystem. WITH
NOCTL has been deleted. Only the base address gets attached if NOCTL is
specified on the ATTACH command.
Response 4
ctlevel IGNORED - INVALID FOR rdev
informs the originator of the command that control options have been specified for a
noncached DASD.
where:
ctlevel
is the level of control: SYSCTL, DEVCTL, or NOCTL.
rdev
is the real device number.
Response 5
ctlevel IGNORED - SYSCTL REQUIRED FOR PREFERRED VIRTUAL MACHINE
informs the originator of the command that invalid control options have been
specified for a cached DASD being attached to a preferred virtual machine.
where:
ctlevel
is the level of control: DEVCTL or NOCTL
Note: For Responses 6, 7, and 8:
The owner of Expanded Storage, the user who issued the command (if
different from the owner), and the primary system operator (if different from
the user who issued the command), each receives responses indicating that the
ATTACH was successful.
Response 6
[XSTORE MIGRATION STARTED, MAY TAKE SEVERAL MINUTES TO COMPLETE]
XSTORE CLEARING STARTED
XSTORE ATTACHED, SIZE=nnnnnnnnM
informs the guest that Expanded Storage has been attached to the virtual machine.
Line 1 is issued when migration of pages from Expanded Storage to DASD is
necessary, for example, when CP has already used some of the area to be attached to
the guest.
28
VM/XA SP2 CP Command Reference
ATTACH
Response 7
XSTORE ATTACHED TO userid
informs the Class B user who issued the ATTACH XSTORE command that
Expanded Storage has been attached to the specified virtual machine.
Response 8
XSTORE ATTACHED TO userid BY originator
is the response sent to the primary system operator (if not the person issuing the
command) indicating that Expanded Storage has been attached to the specified
user's virtual machine. The word "originator" designates the userid of the issuer of
the command.
Migration Notes
VMISP HPO
1. VM/XA SP supports neither the 3330V nor the CHANNEL operands.
2. In VM/XA SP if a person issues an ATTACH command on behalf of another
user, the attachment does not take place immediately (it is asynchronous). The
attachment occurs just prior to the user being dispatched.
3. VM/XA SP supports an additional operand: XSTORE.
4. VM/XA SP supports the attachment of logical devices.
5. VM/XA SP limits the maximum number of devices allowed.
6. VM/XA SP does not accept' A' for' AS'.
7. VM/XA SP accepts rdev * R/O, where rdev is a tape device to allow users to put
in a check simulating a tape ring (instead of doing actual I/O to the device).
VMIXA SF:
Multiple users may have Expanded Storage attached to their virtual
machines.
Chapter 2. VM/XA SP CP Commands
29
ATTN
ATTN
Privilege Class: G
Use the ATTN command to make an attention interruption pending for your virtual
console.
ATTN
Usage Notes
1. The CP REQUEST command performs the same function as ATTN; you can
use the two commands interchangeably.
2. The CP BEGIN command is not required after you issue ATTN.
3. CP ignores the ATTN and REQUEST commands if an I/O operation is in
progress at the console, or if another interrupt is pending for your virtual
machine. This condition may also result if you issue the ATTN or REQUEST
commands by means of DIAGNOSE code X I 08 I .
Responses
None.
30
VM/XA SP2 CP Command Reference
AUTOLOG
AUTO LOG
Privilege Class: A, B
Use the AUTOLOG command to log on another virtual machine automatically.
Before a virtual machine can be logged on automatically, it must be defined in the
system directory and you must know its password. The virtual machine you
automatically log on operates in disconnected mode.
Note: You can also use the XAUTOLOG command to log on another virtual
machine. XAUTOLOG has parameters for defining the virtual machine and
changing the command synchronization. You do not need a password with
the XAUTOLOG command if you have class. A or class B privileges. If you
have class G privileges, you can use the XAUTOLOG command when you
are authorized in the other virtual machine's system directory entry. Read
the XAUTOLOG command description for more information about the
additional functions available.
AUTO LOg
userid
[password] [ console-input-data ]
where:
userid
is the user identification of the virtual machine you are logging on.
password
is the password of the virtual machine you are logging on.
If your installation has password suppression active, all the data following the
userid is console-input-data. Wait for the "ENTER PASSWORD ... " prompt
before you type in the password. The password is automatically masked, thus
improving system security.
If your installation allows a password to be specified on the AUTOLOG
command line, the first data item following the userid is taken as the password.
Any data following the password is console-input-data.
To determine whether password suppression is active, use the QUERY
PASSWORD command.
console-input-data
is data that you want used as virtual console input in response to the first read
issued by the user's virtual machine. You may use the remainder of the
command line to enter console data; the entire line including any logical-line-end
characters (#) are passed to the virtual machine.
Note: If you are using CMS and you specify console-input-data containing the
logical-line-end character (#) on the AUTOLOG command line, CMS
truncates the AUTOLOG command at the first logical-line-end character.
To avoid this situation, precede the logical-line-end character with a
logical-escape-character or precede the AUTOLOG command line with
#CP, where # is your logical-line-end character.
Chapter 2. VM/XA SP CP Commands
31
AUTOLOG
Usage Notes
1. The virtual machine that you log on using the AUTOLOG command must have
an IPL statement in its system directory entry.
2. The virtual machine that you log on using the AUTOLOG command operates in
disconnected mode. The same restraints that apply to any disconnected machine
also apply to virtual machines that are logged on with the AUTOLOG
command.
3. CP disables the AUTOLOG command for the rest of a user's logon session if a
user enters excessive incorrect passwords to automatically log on another userid.
The initial system limit is 4 incorrect passwords. Use the QUERY CMDLIMIT
command to see the system limit value set by your installation.
4. A secondary userid may be specified on the user's system directory CONSOLE
statement. All console messages are routed to the secondary userid, if
functional, once the user is automatically logged on.
5. If AUTOLOG is used in an EXEC or module, you must either put the password
in the command or set the DIAGNOSE code X'08' control bit to indicate that
you want a prompt. See VMjXA SP CP Programming Services for details about
DIAGNOSE X' 08' .
Response 1
ENTER PASSWORD (IT WILL NOT APPEAR WHEN TYPED):
is the response if you must enter a password. Enter the password of the userid you
want to automatically log on.
Response 2
AUTO LOGON ***
userid
USERS = nnnnn
is the response to issuer of the AUTOLOG command (if different from the system
operator) upon successful completion of the LOGON process of the user specified on
the AUTO LOG command.
where:
***
indicates there is no assigned line address for the virtual console.
userid
is the identification of the virtual machine initiated by the AUTO LOG
command.
USERS = nnnnn
is the number of logged-on users.
32
VM/XA SP2 CP Command Reference
AUTO LOG
Response 3
hh:mm:ss AUTO LOGON ***
userid
USERS
=
nnnnn BY {SYSTEM}
{userid2}
is the response to the system operator upon successful completion of the LOGON
process of the user specified on the AUTOLOG command.
where:
***
indicates there is no assigned line address for the virtual console.
userid
is the identification of the virtual machine initiated by the AUTOLOG
command.
USERS = nnnnn
is the number of logged-on users.
SYSTEM
indicates that the AUTOLOG process has occurred as part of VMjXA SP
system initialization. Typically, your primary system operator's virtual machine
is logged on as part of the system initialization process.
userid2
identifies the user who issued the AUTOLOG command.
Response 4
hh:mm:ss USER DSC LOGOFF AS userid
USERS
=
nnnnn FORCED
is the response to the system operator if an invalid IPL statement is processed for the
user specified on the AUTOLOG command.
where:
userid
is the identification of the virtual machine initiated by the AUTOLOG
command.
USERS = nnnnn
is the number of logged-on users.
Migration Notes
VM/SP HPO
1. VMjXA SP gives additional messages for VMjXA SP related situations.
2. If the number of incorrect passwords exceeds the system limit value, then all
AUTO LOG and XAUTOLOG commands are disabled for the remainder of the
session.
VMIXA SP
1. The former VMjXA SPI AUTOLOG command (syntax and function) is now
the XAUTOLOG command. The AUTOLOG command is now compatible
with VMjSP HPO.
2. No additional functions can be specified on the AUTO LOG command using
keyword parameters. If additional functions are required or you do not want to
supply a password, use the XAUTOLOG command.
Chapter 2. VM/XA SP CP Commands
33
AUTOLOG
3. The AUTOLOG command requires the use of a password (either in the
command or in response to a prompt).
4. The console-input-data is not preceded by the logical-Hne-end character (#).
5. The userid you are logging on must have an IPL statement defined in the system
directory.
6. The AUTO LOG command operates synchronously; this means that VM returns
control to you when the target userid is logged on and the IPL statement has
been verified.
34
VM/XA SP2 CP Command Reference
BACKSPACE/BACKWARD
BACKSPACE/BACKWARD
Privilege Class: D
Use the BACKSPACE command to restart or reposition the current output on a real
punch or printer. The BACKSPACE command is identical to the BACKWARD
command.
Printer BACKSPACE Format
BAckspace
BAckward
rdev
File
[
~nn
[EOF]
]
Punch BACKSPACE Format
I BAckspace
BAckward
rdev [Fi le]
where:
rdev
is the real device number of the punch or printer that is to be backspaced.
FILE
specifies that the output spool printer or punch file is to be restarted from the
beginning.
DDD
specifies the number of pages (in decimal, up to a maximum of 999) that you
want to backspace on the printer. If you do not specify a value, the printer is
backspaced to the beginning of the page being printed when the command is
received.
EOF
specifies that backspacing is to start from the end of the spool file and will then
continue backward the requested number of pages. Printing begins again from
this new position.
Usage Notes
1. If you issue a BACKSPACE command while an intervention required condition
is pending on your printer or punch, the command will not take effect
immediately. Once the intervention required condition is cleared and the current
outstanding I/O operation completes, then the BACKSPACE command will be
performed.
2. In BACKSPACE operations, pages are counted by looking for skip to channel 1
specifications (that is, page ejects). If a file does not contain skip to channel 1
specifications, 66 output lines (including blank lines) are treated as a "page."
Chapter 2. VMjXA SP CP Commands
35
BACKSPACE/BACKWARD
Responses
PRT, :,,} rdev BACKSPACE
{ PUN
user; d FI LE spool; d RECS {nnnn }COPY {*nnn} SEQ sss
nnnK
nnnM
nnn
where:
PRT
PUN
indicates the type of device that has been backspaced.
rdev
is the real device number.
userid
is the identification of the user whose file was active and backspaced.
FILE spoolid
is the system-assigned spoolid number by which VM/XA SP refers to the file.
nnnn
nnnK
nnnM
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy {*nnn}
nnn
is the remaining number of copies of the file to be produced. The asterisk (*) is
for the 3800 printer and indicates that the printer will copy each page nnn times
before going on to the next page.
SEQ sss
is the sequence number for the file on the printer or punch.
Migration Notes
VMISPHPO
1. VM/XA SP provides a one-line response instead of a two-line response as in
VM/SP HPO.
2. VM/XA SP allows you to spell out the entire command BACKSPACE.
3. VM/XA SP does not support server virtual machines for the real spooling
commands.
VMIXA SF: None.
36
VM/XA SP2 CP Command Reference
BEGIN
BEGIN
Privilege Class: G
Use the BEGIN command to resume execution on a virtual multiprocessor
configuration, or on a specific processor or processors.
Begin
r-
CPU
~
-
*
hexloc
1
cpuaddr
cpuaddrl cpuaddr ••.
cpuaddrl-cpuaddrn
ALL
~
-
where:
*
terminates hard-stop for the processor on which it is issued. No other virtual
processors are affected.
hexloc
is the hexadecimal storage location where execution is to begin for the processor
on which the command is issued. It will terminate hard-stop for the processor
on which it is issued without affecting any other processors. To begin multiple
processors at specified hexadecimal locations, lise the CP CPU command in
conjunction with the BEGIN command.
CPU cpuaddr
terminates hard-stop for the specified processors without affecting any other
processors.
CPU cpuaddrl cpuaddr...
is the list of addresses and/or ranges delimited by blanks.
CPU cpuaddrl-cpuaddrn
specifies a nonwrapping pair of addresses that is separated by a hyphen ("-")
and not separated by any blanks.
CPU ALL
specifies all virtual processors currently defined.
Usage Notes
1. If you enter the BEGIN command without operands, it will terminate soft-stop
on all virtual processors in your virtual machine configuration. If all of your
processors are in hard-stop, the BEGIN command will terminate hard-stop for
the processor on which it is executed.
2. If you enter the BEGIN command without designating an address where
execution is to begin (hexloc), execution will begin at the location pointed to by
the current virtual machine program status word (PSW). Unless the PSW has
been altered since CP command mode was entered, the location stored in the
PSW is the location where the virtual machine stopped.
3. If you enter the BEGIN command and specify a starting storage location,
execution will begin at that address. The address you specify will replace the
instruction address in the PSW, and then the PSW will be loa.ded.
Chapter 2. VMjXA SP CP Commands
37
BEGIN
4. BEGIN terminates SLEEP status. For more information about SLEEP status,
see the CP SLEEP command.
5. The BEGIN command cannot be used to resume execution on check-stop
processors. Refer to the SYSTEM RESET and SYSTEM CLEAR commands.
Responses
None.
Migration Notes
VMISP HPO: VM/XA SP supports additional operands:
VMIXA SF: None.
38
VM/XA SP2 CP Command Reference
* and CPU.
CHANGE
CHANGE
Privilege Class: D, G
Use the CHANGE command to alter one or more of the external attributes of a
closed spool file or files, or to alter the user HOLD status o(an active spool file (one
currently being printed or punched).
If you are a class D user, use the CHANGE command to change any spool files on
the system, regardless of origin, using the SYSTEM or userid options.
If you are a class G user, you cannot use the SYSTEM option; however, you can use
the userid option of the CHANGE command to manipulate your own files or files
that you created and subsequently transferred (as long as the transferred files are
unchanged).
CHange
[SYSTEM] {Reader }{CLass c -.}
Printer FORM form
PUnch
ALL
(options)
d.J{_Re~der
Prlnter }l.CLass.
(options)
[ useri
~
c
:FORM form
ALL
~pOOlld
PUnch
I
where:
SYSTEM
allows the class D user to manipulate any files in the system, regardless of
ownership. This is not allowed with the spoolid option.
userid
*
is the user identification for the user whose spool files are to be changed. If you
are changing your own files, you may specify your userid as an asterisk (*),
which is also the default.
READER
RDR
changes reader spool file(s).
PRINTER
PRT
changes printer spool file(s).
PUNCH
PCH
changes punch spool file(s).
CLASS c
designates a spool file class, where c is a I-character alphanumeric field from A
to Z or 0 to 9.
FORM form
designates a 1- to 8-character form name. Use this form name to select those
files you want to change. For the class G user, the form is the user form name.
For the class D user, form is the user form name when the "*,, option is
specified (or accepts the default). Otherwise, form is the operator form number.
Chapter 2. VMjXA SP CP Commands
39
CHANGE
ALL
specifies the files on which the CHANGE command is to operate.
If you want to change all files, regardless of their class, form, or spoolid, specify
ALL.
spoolid
is the spool file identifier by which you may select a particular file. spoolid is not
valid with the SYSTEM keyword.
options
See "CHANGE: Options" on page 41 for a complete description of these
options.
40
VMjXA SP2 CP Command Reference
CHANGE: Options
CHANGE: Options
Options:
,
, [HOl d ] [KEep ] [MSG ] [SYS ]
NOHold . NO Keep
NOMs;
NOSYS
[CLass c] [COpy [<]nnn]
[[TO] {use:id2}
[ FORM
[Dist {di~~~Ode} ]
[:~!~~~r]
]
{~~~ } ]
]
]
-
[[ CHars {~:~e [namel [name2 [name3]]] }]]
-
[' [CHars name€) [CHars name! [CHars name2 [CHars name3]]] ] ]
NAme {fname [ftype] } ]
dsname
,
[
NOName
Note: At least one of these options must be chosen. If you specify more than one,
you can combine them in any order, except for the NAME option which
must be specified last.
HOLD
NOHOLD
HOLD prevents the punching, printing, or reading of a file by placing it in a
user HOLD status. NOHOLD releases the specified spool file(s) currently in
user HOLD status.
KEEP
NO KEEP
KEEP specifies that the spool file is to be retained in user HOLD status after
processing. Specify NOKEEP to reset files that are in KEEP status.
Chapter 2. VM/XA SP CP Commands
41
CHANGE: Options
MSG
NOMSG
indicates whether messages are sent to the file owner when the file begins
processing and again when the file completes processing. Although you may
enter these options for any type of spool file, no message is sent when a virtual
reader processes the file. Specify NOMSG to reset the MSG option.
If you have issued the CP SET IMSG OFF command, messages are not sent.
SYS
NOSYS
SYS prevents the punching, printing, or reading of a file by placing it in a
system HOLD status. NOSYS releases the specified spool file(s) currently in
system HOLD status. User HOLD status can coexist with system HOLD status.
This option is available to class D users only.
CLASS c
designates the new class ("c") for the file(s).
COpy (*)nnn
specifies the number of file copies you want printed or punched when the file is
produced. The value of nnn (number of copies) must be a number from 1
through 255. Leading zeros do not need to be specified.
When you specify the optional asterisk (*), the 3800 printer prints each page
from the spooled output files nnn times before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
DIST distcode
specifies the new distribution code for the spool file(s). distcode is a I-to
8-character alphanumeric identifier that appears on the output separator of
punch or print files.
DIST , {?FF}
resets the distribution code of the spool file(s) to the default specified in your
entry in the system directory.
(TO)
userid2
*
sends the spool file to the virtual machine specified by userid2. If no device type
is specified immediately after userid2, the spool file is placed on userid2' s reader
queue. Specify an * if you want to direct the output to your own virtual
machine.
READER
RDR
PRINTER
PRT
PUNCH
PCH
specify, in conjunction with the TO operand, the file queue to which the spool
file( s) are to be directed.
42
VM/XA SP2 CP Commnnd Reference
CHANGE: Options
FORM form
designates the new form name for the spool file(s). form is 1 to 8 characters.
For the class G user, form is the user form name. For the class D user, form is
the user form name when the "*,, option is specified. Otherwise, form is the
operator form number.
FORM OFF
resets the form for the spool file(s) to the system default as specified by the
installation.
FLASH name
[ALL]
nnn
signifies that a form overlay contained in the 3800 printer is to be superimposed
(or flashed) onto the specified number of copies of the output. The name, to be
1 to 4 characters in length, identifies the forms overlay to be used in the
projection. The number, nnn, must be in the range from 0 to 255. The number
specifies that the first nnn copies of output are to be flashed.
For example, if you specify COpy 4 and FLASH name 2, the first two copies of
your file are flashed, while the last two copies remain unflashed. If ALL is
specified, the flash count always matches the copy count. ALL is the default.
FLASH OFF
resets the flash parameters. Blanks are inserted into the flash name field of the
specified spool file(s), and the count is set to O.
MODIFY name [n)
assigns a copy modification module to be used when printing the spool file(s) on
the 3800. This function makes it possible to alter text by either preventing
printing of certain information or adding labels to output. The name must be 1
to 4 characters.
n selects one of the character sets specified by the CHARS operand to be used
for the copy modification text. The values 0, 1, 2, or 3 correspond to the order
in which the character sets have been specified. If no n is specified, the first
character set (0) is assumed.
MODIFY OFF
resets the modify parameters. Blanks are inserted into the modify name field of
the spool file(s) and, when printed, no modification occurs. The modify number
(n) is set to O.
FeB
):re!
~
12 ,
specifies the forms control buffer to be used when printing the file on the 3800
printer. name is a 1- to 4-character name of an FCB image, or the number 6, 8,
10, or 12. The number tells the 3800 to print the entire spool file at 6, 8, 10, or
12 lines per inch, regardless of the size of the paper that is currently loaded. Use
of these unique numbers assures that printed material will fit onto a specified
page size. Note, however, that FCB 10 prints only on a 3800 Model 3 printer.
FeB OFF
resets the FCB parameter. Blanks are inserted into the FCB name field of the
spool file(s) and, when printed, a default FCB controls the vertical spacing of
the output text.
Chapter 2. VMjXA SP CP Commands
43
CHANGE: Options
CHARS nameO (name I (name2(name311J
CHARS nameO (CHARS namel (CHARS name2 [CHARS name31J]
specifies the name of the character set(s) used when printing the spool file(s) on
a 3800 printer. The name(s) must be from one to four characters with a
maximum of four names specified. The multiple use of CHARS need only be
used if nameN would conflict with an option name (for example, FORM) or
with a userid. If more than one name is specified, and modification is also
specified, the order in which the names appear determines which table is used for
copy modification ,text.
CHARS OFF
resets the CHARS parameters. Blanks are inserted into the name fields of the
character sets used for output generation. The spool file(s), therefore, use a
default character set when actually printed.
NAME { fname ( ftype I }
dsname
NONAME
indicates the name is to be assigned to the spool file for identification. For
output files, this name appears on the separator page or cards. Use the fname
ftype option to name files in the CMS filename and filetype format. Each of
these fields is a 1- to 8-character alphanumeric name. If you omit the ftype field,
blanks are substituted. If you want to name files in a format suitable for MVS
use (for example, SYS1.SYSLIB.MAC1), use the dsname option. You may
specify the dsname up to 24 characters in length; however, if the dsname is more
than 16 characters in length, it is truncated to 16 characters.
Specify NONAME to reset the name information to blanks.
If specified, the NAME option must be the last operand you enter on the
command line.
Usage Notes
1. You can use the CP QUERY RDRjPRTjPUN command to determine the
attributes of a spool file before and after the CHANGE command.
2. You may change the status of the file to HOLD in order to stop the processing
of the file that is currently being printed or punched. No other attributes of an
active file may be changed.
3. Class G users may change files that they own or that they have created.
4. If you use the CHANGE command to transfer a file to another user and you do
not specify a distribution code, the distribution code is set to the receiving user's
default distribution.
5. Although the CHANGE options FLASH, FCB, MODIFY, CHARS, and COpy
*nnn may be specified for any spool file or files, they only cause system action
when a spool file with these attributes is printed on a 3800 printer.
6. A user may also cancel settings of the CHARS, MODIFY, or FCB options by
specifying NULL in the name fields of these operands. In these cases, NULL
performs the same function as OFF.
7. The keyword OFF, which resets attributes to their default values, may not also
be used to specify a FORM, FLASH, FCB, MODIFY, DISTcode, or CHARS
name. Similarly, NULL may not be used to specify a CHARS, MODIFY, or
FCB name.
44
VMjXA SP2 CP Command Reference
CHANGE: Options
8. If the NORETURN option was specified when the file was created by
DIAGNOSE X 194 I , then the originator of the file cannot retrieve that file from
the current owner. If you try, the following message is issued:
FILE NOT CHANGED; FILE CREATED WITH THE NORETURN OPTION
9. When a file changes ownership, the spool file id number also changes. The new
number is obtained from the pool of available IDs of the recipient of the file.
Thus, if user DORA uses the CHANGE command to send file #3 to user LILA,
DORA gets the response:
RDR 0003 SENT TO LILA RDR AS 0018 RECS 1000 COpy 001 A NOHOLD NOKEEP
LILA would now have a file #18.
Response 1
{nnnnn~~} FILE(S) CHANGED
indicates how many files have been changed. This response is sent to the user who
issued the CHANGE command but is suppressed if the virtual machine user has
issued the SET IMSG OFF command.
Response 2
If you transfer a spool file to another user using the TO operand, the following
response is sent to you and to the user receiving the file (if that user is active on the
system):
RDR} FI LE spd1 SENT {TO } userid {RDR.} AS spd2 RECS {nnnn }COPY [*] nnn
PRT
FROM
PRT
nnnK
{ PUN
PUN
nnnM
C {HOLD
} {KEEP }
NOHOLD '. NOKEEP
.
where:
RDR
PRT
PUN
indicates the spool file queue. If you are transferring a file to another user's
virtual machine, this field indicates the queue from which the file originated. If
you are receiving a file from another user, this field indicates the file queue in
which the file has been added.
spdl
is the. spool identification number (spoolid) at the time the command is issued.
TO userid
indicates to whom the file has been sent.
FROM userid
indicates from whom the file came.
RDR
PRT
PUN
indicates the spool file queue. If you are transferring a file to another user's
virtual machine, this field indicates the queue in which the file has been added.
If you are receiving a file from another user, this field indicates the file queue in
which the file originated.
spd2
is the spool identification number of the file after the command is complete.
Chapter 2. VM/XA SP CP Commands
45
CHANGE: Options
RECS {nnnn }
nnnK
nnnM
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999,499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy [*)nnn
specifies the number of file copies you want printed or punched when the file is
produced.
When the optional asterisk (*) is specified, the 3800 printer prints each page
from the spooled output files nnn times before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
c
is the spool file class assigned to the file.
HOLD
NOHOLD
is the user HOLD status associated with the file.
KEEP
NO KEEP
is the KEEP status associated with the file.
This response is suppressed if the virtual machine user has issued the, SET IMSG
OFF command.
Response 3
PRT.}rdeV{PRINTING} userid FILE spoolid REcs.{,nnnn}coPY [*]nnn SEQ sss
{ PUN
PUNCH I NG
nnnK
,
nnnM
is the message you receive when the system begins processing a spool file that has
the MSG attribute.
where:
PRT
PUN
indicate the type of device on which the file is being processed.
rdev
is the real device number.
userid
is the name of the spool file owner.
FILE spoolid
is the spool file spoolid number.
46
VM/XA SP2 CP Command Reference
CHANGE: Options
RECS {nnnn }
nnnK
nnnM
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy [*)000
specifies the number of file copies you want printed or punched when the file is
produced.
When the optional asterisk (*) is specified, the 3800 printer prints each page
from the spooled output files nnn times before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
SEQ sss
is the sequence number for the file on the printer or punch.
Migration Notes
VMISP HPO
1. VMjXA SP truncates a name identification for dsnames to sixteen characters (if
longer than sixteen).
2. VMjXA SP does not allow users to specify SYSTEM and spoolid on the same
command line. VMjSP HPO (Release 5) users do not see this difference.
3. The VMjXA SP response includes the number of records and KEEP setting.
4. If the file is changed to another user, the VMjXA SP response includes the new
spoolid.
5. VMjXA SP supports additional options: TO, KEEPjNOKEEP, and
MSGjNOMSG.
6. VMjXA SP does not support the DEST or the UNCONV options.
7. VMjXA SP sets DIST to what is in the OPTIONS directory when
specified.
* (asterisk) is
8. VMjXA SP displays a 7-digit response for the number of files changed.
VMIXA SF
1. VMjXA SP does not allow users to specify SYSTEM and spoolid on the same
command line;
2. If the file is changed to another user, the VMjXA SP response includes the new
spoolid.
Chapter 2. VMjXA SP CP Commands
47
CLOSE
CLOSE
Privilege Class: G
Use the CLOSE command to terminate spooling activity on a virtual spooling device
(reader, printer, punch, or console). Options on the CLOSE command override the
options set on the virtual device or spool file(s).
CLose
{Reader} [OptionA]
Pri nter } [Opt i onA] [Opt i on8]
PUnch
{ CONsole
{vdev
}
where:
READER
RDR
PRINTER
PRT
PUNCH
PCH
CONSOLE
closes all reader, printer, punch or console devices. Once a virtual console spool
file is closed, it becomes a printer spool file and can be manipulated in the same
way as any printer spool file.
vdev
is the virtual device number of the device to be closed. The device number may
represent a console, reader, printer, or punch.
OptionA
OptionB
See "CLOSE: Options" on page 49.
The options of the CLOSE command override the corresponding options in effect
for the device that you are closing. If you do not specify any of the optional
operands, then the options in effect for the device or the status of the file that you
are processing will determine the file's disposition.
48
VM/XA SP2 CP Command Reference
CLOSE: Options
CLOSE: Options
OptionA:
{r
HOld
_NOHold
I
OptionB:
J
J
[KEep
NOKeep
[CLass c] [MSG
NOMsg
[EOF
.J [COpy
]
}
[PUrge]
[*] nnn] [Di st{di stcode,} ]
OFF
*
[FORM {~~;n}
FLash {name
nam~
[
-<
[
]
[ALL]
}
nnn
OFF
MOdi fy {name En] }
OFF
]
J
)0
-
-
[ [CHars {n~a [namel [name2 [name3] ]]}
[[CHars
.
_~
1J
name0 [CHars namel [CHars name2 [CHars name3]]]
[ NAme {fname [ftype] } ]
dsname
NOName
]]
~
Note: You can specify one or more of these options. If you specify more than one,
you can combine them in any order, except for the NAME option which
must be specified last.
where:
HOLD
NOHOLD
controls the user HOLD status.
/
For output devices, HOLD prevents files from being punched or printed on a
real device by putting a user HOLD status on the file. If you specify
NOHOLD, you will override the spool device HOLD option and prevent the file
from being placed in HOLD status.
Chapter 2. VM/XA SP CP Commands
49
CLOSE: Options
For input devices, the HOLD/NOHOLD options override the setting for the
virtual device or the spool file. The file is not put in HOLD status unless the
KEEP option is also specified. If you specify HOLD, the file will not be purged
after processing and will remain eligible for the device. If you specify NOHOLD,
the file will be purged unless the KEEP option is also specified.
KEEP
NOKEEP
controls the KEEP status, which indicates whether the current spool file is to be
placed in user HOLD after processing.
For output files, the KEEP status will be placed on the spool file. After it is
printed or punched, the file will be assigned user HOLD status, and will not be
purged. The file's KEEP status is retained. Specify NOKEEP to override the
current KEEP setting for the device so that KEEP is not set on the spool file.
F or input files, KEEP overrides the KEEP setting on either the virtual reader or
the spool file. After processing, the file is placed in HOLD status, and the
KEEP option on the file remains unchanged. Specify NO KEEP to override
either file or device KEEP characteristics. The disposition of a file closed
NOKEEP (whether it is purged or retained) is controlled by the HOLD status of
the virtual reader. If it were closed KEEP, it would never be purged.
EOF
closes the spool file on the specified device regardless of the CONT setting for
the device. This option is not meaningful for a reader.
PURGE
closes and purges the spool file on the specified device regardless of the CONT,
KEEP, and HOLD setting for the device.
CLASS c
specifies the spool class to be assigned to the file, where c is a one-character
alphanumeric field from A to Z or 0 to 9.
MSG
NOMSG
indicates whether you want to be informed about file printing and punching. If
you specify MSG, you will be informed of file printing and punching. The
message is sent to you when the file begins either printing or punching on a real
device. This message is not sent if you have issued CP SET IMSG OFF
command. Specify NOMSG to reset the MSG option.
COpy 1*)000
specifies the number of file copies you want printed or punched when the file is
produced. The value of nnn (number of copies) must be a number from 1
through 255. You do not need to specify leading zeros.
When the optional asterisk (*) is specified, the 3800 printer will print each page
from the spooled output files nnn times before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
DIST distcode
specifies the distribution code to be assigned to the resulting spool file. distcode
is a one-to-eight character alphanumeric identifier which will appear on the
output printer/punch separator.
50
VM/XA SP2 CP Command Reference
CLOSE: Options
DIST
J?FF}
resets the distribution code for the resulting spool file to the default specified in
the system directory for your userid.
[TO)
{U:rid }
directs the spool file from the device to the virtual machine specified by the
userid. Specify an asterisk (*) if you want to direct the file to your own virtual
machine.
READER
RDR
PRINTER
PRT
PUNCH
PCH
are used with the TO operand to specify the file queue to which the spool file is
to be directed. If you do not specify a queue, the file will be directed to the
reader.
FORM form
overrides the form name of a spool file. The form name is l-to-8 characters. If
FORM is not given for the CLOSE command, the file created has one of the
following forms: (1) form as specified by the last SPOOL command for the
device, or (2) a default name specified during system generation.
FORM OFF
resets the form to the default specified during system generation.
FLASH name { ALL }
nnn
signifies that a form overlay contained in the 3800 printer is to be superimposed
(or flashed) onto the specified number of copies of the output. The name, to be
l-to-4 characters in length, identifies the forms overlay to be used in the
projection. The number, nnn, must be in the range from 0 to 255. The number
specifies that the first nnn copies of output are to be flashed.
For example, if you specify COpy 4 and FLASH name 2, the first two copies of
your file are flashed, while the last two copies remain unflashed. If ALL is
specified, the flash count will always match the copy count. ALL is the default.
FLASH OFF
resets the flash parameters. Blanks are inserted into the flash name field of the
specified spool file, and the count is set to O.
MODIFY name [n)
assigns a copy modification module to be used when printing the spool file on
the 3800. This function makes it possible to alter text by either preventing
printing of certain information or adding labels to output. The name must be
one to four characters.
n selects one of the character sets specified by the CHARS operand to be used
for the copy modification text. The value 0, 1, 2, or 3 corresponds to the order
in which the character sets have been specified. If no n is specified, the first
character set (0) is assumed.
Chapter 2. VMjXA SP CP Commands
51
CLOSE: Options
MODIFY OFF
resets the modify parameters. Blanks are inserted into the modify name field of
the spool file and, when printed, no modification will occur. The modify number
(n) is set to o.
FeB
i;reJ
specifies the forms control buffer to be used when printing the file on a 3800
printer. name is the 1- to 4-character name of an FCB image, or the number 6,
8, 10, or 12. This number tells the 3800 to print the entire spool file at 6, 8, 10,
or 12 lines per inch, regardless of the size of the paper that is currently loaded.
Please remember, however, that FCB 10 will print only on a 3800 Model 3
printer.
FCB OFF
resets the FCB parameter. Blanks are inserted into the FCB name field of the
spool file and, when printed on a 3800 printer, a default FCB will control the
vertical spacing of the output text.
CHARS nameO (name 1 (name2(name3J1)
CHARS nameO (CHars namel(CHars name2(CHars name3)J1
specifies the name of the character set(s) used when printing the spool file on a
3800 printer. The name(s) must be from one to four characters with a maximum
of four names specified. The multiple use of CHARS need only be used if
nameN would conflict with an option name (for example, FORM) or with a
userid. If more than one name is specified, and modification is also specified, the
order in which they appear determines which table will be used for copy
modification text.
CHARS OFF
resets the chars parameters. Blanks are inserted into the name fields of character
sets to be used for output generation. The resulting spool file, therefore, will use
a default character set when actually printed on a 3800 printer.
NAME {. fname ( ftype] }
dsname
NONAME
.
allows you to assign a name to the spool file for identification.
The jname, jtype specification permits you to name a file in CMS filename and
filetype format. The fields jname and jtype are one to eight character alphameric
names. If you omit the jtype field, blanks will be substituted.
The dsname specified may consist of up to 24 characters; however, if more than
16 characters are specified, the name will be truncated to 16 characters. An
example could be: SYSl.SYSLIB.MACl.
Specify NONAME to reset the name information to blanks.
If specified, the NAME option must be the last operand you enter on the
command line.
52
VM/XA SP2 CP Command Reference
CLOSE: Options
Usage Notes
The optional operands of the CLOSE command override the corresponding options
in effect for the device that you are closing. If you do not specify any of the
optional operands, then the options in effect for the device or the status of the file
that you are processing determine the file's disposition.
1. Although the CLOSE options FLASH, FCB, MODIFY, and CHARS may be
specified for any virtual device except a reader, they only cause system action
when a spool file with these attributes is printed on a 3800 printer.
2. A user may also cancel settings of the CHARS, MODIFY, or FCB options by
specifying NULL in the name fields of these operands. In these cases, NULL
performs the same function as OFF.
3. The keyword OFF, which resets attributes to their default values, may not also
be used to specify a FORM, FLASH, FeB, MODIFY, DISTcode, or CHARS
name. Similarly, NULL may not be used to specify a CHARS, MODIFY, or
FCB name.
4. If you close an output device (printer, punch, console) and the file you created is
in hold, that file will not be available for processing. If the file is not in hold, it
will be available for processing. You can transfer a file to another user by using
the TO operand on the CP TRANSFER or CHANGE commands.
5. You can specify a filename and filetype to help you identify a file and its
contents. The filename and filetype you assign will have no effect on how CMS
names the file if it is read using the CMS READCARD or CMS DISK LOAD
commands.
6. If you are closing a reader, the file that is being processed will be purged unless
HOLD or KEEP is in effect for the device or for the file. Use the appropriate
CLOSE command option to override the effect of HOLD, NOHOLD, KEEP, or
NOKEEP established for the reader or for the file.
7. If an input spool file has been only partially read (that is, your virtual machine
did not get an end-of-file indication), you must issue a CLOSE READER
command.
8. When a file changes ownership, as when it is closed to a new user, the spool file
id number changes. The new number is obtained from the pool of available ids
of the recipient of the file. Thus, if user SAM clpses his reader to user HARRY,
he would get the response:
RDR 0003 SENT TO HARRY RDR AS 0018
HARRY would now have a file #18.
9. The disposition of a spool file that is to be processed on a real unit record device
depends upon the resolution of HOLD, CONT, and KEEP status as implied by
the device using the SPOOL and CLOSE commands.
For example, suppose your virtual printer is spooled CONT. You issue the
following command:
close prt class z
Since you did not specify the CLOSE operand EOF, the file will not become
available for processing on a real printer.
Chapter 2. VM/XA SP CP Commands
53
CLOSE: Options
After completion of the CLOSE command, CP checks the HOLD status of the
file to determine whether the files you closed can be processed. Thus, if HOLD
is in effect for any of the closed files because you specified HOLD on the
CLOSE command or because HOLD was set for the device using the CP
SPOOL command, the file will not be processed.
For readers only, the net effect of file status, device options, and the CLOSE
command overrides is in Table 7.
In all cases, the original KEEP /NOKEEP status of the file is unchanged by the
CLOSE operation.
Likewise, the disposition of a spool file that is to be processed on a real unit
record device depends upon the resolution of HOLD, CONT, and KEEP status
as implied by the device using the SPOOL and CLOSE commands.
Table 1. Effect of File Status, Device Options, and CLOSE Command
Options on Reader Files
Options in Effect
For the Input File
System Action
NOKEEP/NOHOLD
File is purged.
NOKEEP/HOLD
File is not purged and remains available for
processing in HOLD status.
KEEP/NOHOLD
File is not purged. It will be set in
NOHOLD/KEEP status and will not be
available for processing.
KEEP/HOLD
File is not purged. It will be set in
HOLD/KEEP status and will not be available
for processing.
Response 1
The CLOSE command is used to terminate the spooling activity on any virtual unit
record or console device. Below is the response issued when the system begins
processing a spool file that has the MSG attribute.
PRT} rdev {PRI NT I NG} useri d
{ PUN
PUNCHING
FILE spool id RECS{ nnnn }COPY [*]nnn SEQ sss
nnnK
nnnM
where:
PRT
PUN
indicates the type of device on which the file is being processed.
rdev
is the real device number.
userid
is the identification of the user whose file was active.
FILE spoolid
is the unique, system-assigned spoolid number by which VM/XA SP refers to the
file.
54
VMjXA SP2 CP Command Reference
CLOSE: Options
RECS {nnnn }
nnnK
nnnM
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy (*)onn
is the remaining number of copies of the file to be created.
When the optional asterisk (*) is specified, the 3800 printer will print each page
from the spooled output files nnn times before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
SEQ sss
is the sequence number for the file on the printer or punch.
Response 2
If you are using the TO operand with the CLOSE command, the following response
will be sent to you and to the operator receiving the file (assuming the operator is
active on the system):
Note: This response is not displayed if the SET IMSG OFF command has been
issued.
!
RDR.\.FILE spdl SENT {TO } userid {RDR.} AS spd2 RECS {nnnn}COPY [*] nnn
PRT
FROM
PRT
nnnK
PUN
PUN,
nnnM
CON
C
{HOLD } {,KEEP l
NOHOLD
NOKEEP f
where:
RDR
PRT
PUN
CON
indicates the spool file queue. If you are transferring a file to another user's
virtual machine, this field indicates the queue from which the file originated. If
you are receiving a file from another user, this field indicates the file queue in
which the file has been added.
spdl
is the spool identification (spoolid) of the file as seen by the owner of the file.
TO userid
is the recipient of the' spool file.
FROM userid
indicates from whom the file came. If the PURGE option is used with the
CLOSE command, this field is replaced by **** PURGED **** to indicate that
the file has been deleted.
Chapter 2. VMjXA SP CP Commands
55
CLOSE: Options
RDR
PRT
PUN
indicates the spool file queue. If you are transferring a file to another user's
virtual machine, this field indicates the queue in which the file has been added. If
you are receiving a file from another user, this field indicates the file queue in
which the file originated.
spd2
is the spool identification of the file when it is associated with the receiver of the
file.
RECS
{OOOO }
nooK
oooM
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy 1*)000
specifies the number of file copies you want printed or punched when the file is
produced.
When you specify the optional asterisk (*), the 3800 printer will print each page
from the spooled output files nnn times before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
c
is the spool file class.
HOLD
NOHOLD
is the user HOLD status associated with the file.
KEEP
NOKEEP
is the KEEP status associated with the file.
Migration Notes
VMISP HPO:
1. VM/XA SP truncates a name identification to 16 characters (if longer than 16).
2. The VMfXA SP response includes the number of records and KEEP setting.
3. If the file is closed to another user, the VM/XA SP response includes the new
spoolid.
4. VMfXA SP supports additional options: TO/FROM, KEEP /NOKEEP and
MSG/NOMSG.
5. VM/XA SP does not allow the specification of SYSTEM or userid.
6. VM/XA SP does not support the DEST and UNCONV operands.
56
VM/XA SP2 CP Command Reference
CLOSE: Options
7. VMjXA SP sets DIST to what is in the OPTIONS directory when
specified.
* (asterisk) is
VMIXA SF: If the file is closed to another user, the VMjXA SP response includes
the new spoolid.
Chapter 2. VMjXA SP CP Commands
57
COMMANDS
COMMANDS
Privilege Class: Any
Use the COMMANDS command to display the commands and DIAGNOSE codes
which you are authorized to use.
I
COMMands
[cmdl cmd2 cmd3 .•• ]
where:
cmdl cmd2 cmd3 ...
are the names of specific commands to be checked for authorization. The
response will show which default IBM privilege classes you have that correspond
with a specified command.
Usage Notes
1. The same function is available via the QUERY COMMANDS command.
2. Some commands have more than one version, but the user may not be
authorized to use all the versions of a particular command. If the system rejects
a command that is listed in the response, it is probably because the user is not
authorized to use the version that includes the operand or operands that were
entered.
3. For an indication of which versions of a command you are authorized to issue,
use "COMMANDS cmd," where "cmd" is the name of the command or
commands you are interested in. You will be shown the default IBM privilege
classes of the command that are authorized to you.
4. You may specify any number of commands on the "COMMANDS cmd ... "
command. If a command name is entered twice, it will be displayed twice in the
response. No checking is made for duplicate entries.
Response 1
comml
comm2
comm3
comm4
comm5
comm6
diag2
diag3
diag4
diag5
diag6
comm7
diagl
diag7
indicates the commands and diagnose codes that the user is authorized to issue.
where:
commx
is the name of a command you are authorized to use.
diagx
identifies a DIAGNOSE code you are authorized to use.
58
VMjXA SP2 CP Command Reference
COMMANDS
Response 2
cmd
IBMCLASS={Cl,C2,C3}
ANY
NONE
is the response when a user specifically enters commands to be checked for
authorization.
where:
cmdx
is the name of the command you entered on the command line.
mMCLASS = cl,c2,c3
are the IBM -defined privilege classes of this command.
ANY
indicates that the command is a class ANY command, and all users may issue
the command.
NONE
indicates that you are not authorized to issue any version of the command.
Migration Notes
VMISP HPO
* (asterisk) command, it does not include
* (asterisk) in the list of commands.
1. Although VM/XA SP does have the
the
2. VM/XA SP allows the specification of a particular command.
3. VM/XA SP allows commands up to 12 characters long (HPO only 8 characters
long).
4. For VM/XA SP only, equivalent function exists for QUERY COMMANDS.
Chapter 2. VM/XA SP CP Commands
59
COUPLE
COUPLE
Privilege Class: G
Use the COUPLE command to connect two virtual channel-to-channel adapters
(CTCA).
I COUPLE
vdevl
[TO]
userid vdev2
where:
vdevl
is the virtual device number of your virtual CTCA.
(TO) userid
is the user identification of the virtual machine to which vdevl is to be
connected.
vdev2
is the virtual device number of the virtual CTCA that you want to connect to
vdevl.
Usage Notes
1. The user you specify in the command line must be logged on and have a virtual
channel-to-channel adapter defined for his or her virtual machine configuration.
The virtual machine may be operating disconnected.
2. If you want to connect the CTCA you designated as vdevl to another CTCA in
your own virtual machine, you may specify userid as an asterisk (*).
3. If you omit the keyword TO from the command line, the userid you specify
cannot be T or TO.
4. If a vdev is already connected to another vdev, that connection is broken.
5. The other user must have authorized the connection using the CP DEFINE
CTCA command or the SPECIAL directory entry.
Responses
The originator of the command and the owner of the coupled-to CTCA (if different
from the originator) receive messages indicating that the CTCAs have been coupled.
Response 1
CTCA vdevl COUPLED TO userid vdev2
is the response sent to the originator of the COUPLE command.
where:
vdevl
is the device number of the originator's virtual CTCA.
use rid
is the identification of the receiving virtual machine.
vdev2
is the device number of the virtual CTCA of the receiving user. This may also
be a different channel-to-channel adapter in your own virtual machine.
60
VM/XA SP2 CP Command Reference
COUPLE
Response 2
CTCA vdev2 COUPLED BY userid vdevl
is the response sent to the owner of the coupled-to virtual CTCA, if he is not the
originator of the command.
where:
vdev2
is the device number of the virtual CTCA of the receiving user.
userid
is the identification of the user who issued the COUPLE command.
vdevl
is the device number of the originator's virtual CTCA.
Response 3
CTCA vdevl DROPPED FROM userid vdev2
is the response that the originator receives if the virtual CTCA vdevl was already
coupled. This response is also sent to the owner of the vdev from which the
connection was broken. The previous connection is terminated.
Response 1
where:
vdevl
is the virtual device number of the CTCA.
userid
is the user identification of the virtual machine to whose CTCA your CTCA had
been coupled.
vdev2
is the virtual device number of the other virtual machine's CTCA.
Migration Notes
VMISP HPO: The VMjXA SP response uses CTCA, COUPLED, and DROPPED
instead of CTC, COUPLE, and DROP as in VMjSP HPO.
Chapter 2. VMjXA SP CP Commands
61
CP
CP
Privilege Class: Any
Use the CP command as an optional preface to CP commands that you issue from
the CP command environment.
I
CP
[command line! [Icommand line2 I ... ]]
where:
command linel [#command line2 # .••1
is the name and operands for the CP command or commands you want to issue.
You must precede the first command line with at least one blank.
Usage Notes
1. The pound sign (#) shown in the format block represents the logical line end
symbol currently in effect for your virtual machine. If you have redefined the
logical line end symbol, you must substitute your line end symbol for the pound
sign when using this command. Before you issue the CP command, be sure that
your virtual machine is operating with the CP SET LINEDIT function set ON.
This is the default.
2. The CP command is treated as a null command by the control program and
therefore can precede any other command if one or more blanks separate CP
from the other command.
3. In the CP environment, you can enter multiple command lines as operands of
the CP command, but you must separate each command line by the logical line
end (#) symbol.
Responses
If you enter CP without a command line in the CP environment, there is no response
and CP READ appears in the status area.
If you enter CP with command lines, you receive the responses appropriate to the
individual commands you entered.
62
VM/XA SP2 CP Command Reference
CPFORMAT
CPFORMAT
Privilege Class: G
Use the CPFORMAT command to format, label, and/or allocate DASD volumes
for CP uses, such as paging, spooling, temporary disk, directory, nucleus, and
mini disk space.
Note: To use CPFORMAT, your virtual machine must be a System/370 mode
machine.
CPFORMAT
vdev
volid
~startcyl
[ -endcyl
-END
.ncyl
.END
Allocate
• Label
]
.
:.
Note: The CMS command, CPFMTXA, may be found in the VM/XA SP: CMS
Command Reference. The CPFMTXA command performs a function similar
to CPFORMAT but does not reset the user's virtual machine.
where:
vdev
is the virtual device number of the DASD device to be formatted. It is specified
as a 1- to 4-character hexadecimal number between X I 0 I and X I 1FFF I. The
device type associated with this vdev must be supported as a CP-owned volume
and the user must have write access to the device.
volid
is the volume identification label of the virtual device to be formatted, labelled,
and/or allocated. The volid is specified as a 1- to 6-character name (the
characters do NOT have to be alphanumeric). The volid is written if startcyl is
o or if you specify the "LABEL" option. Otherwise, the volid on the virtual
device is read and compared to the one that you specify on the command line.
starteyl
is the starting cylinder that is to be formatted. It is a 1- to 4-digit decimal
number; and must be within the size of the virtual device. If you do not specify
startcyl, LABEL, or ALLOCATE, then O-END is assumed. If the starting
cylinder is all that is specified, then only the one cylinder specified is formatted.
-endeyl
-END
is the last of the range of cylinders that are to be formatted. If specified, endcyl
is a 1- to 4-digit decimal number and must be within the size of the virtual
device. If specified, endcyl must be equal to or greater than startcyl. Specify
END to format all the cylinders on the virtual device, starting with the startcyl.
If you do not specify an endcyl or END, the default is one cylinder.
Chapter 2. VMjXA SP CP Commands
63
CPFORMAT
.ncyl
.END
is a 1- to 4-digit decimal number designating the number of cylinders to be
formatted. It must not be zero. The sum of startcyl and ncyl must not exceed
the size of the virtual device. Specify END to format all cylinders on the virtual
device, starting with the startcyl. If you do not specify an neyl or END, the
default is one cylinder.
ALLOCATE
indicates that you only want to reallocate a previously formatted CP volume.
LABEL
indicates that you only want to change the volume identification label. The
volume must have already been formatted.
Note: If you do not specify any of the startcyl, LABEL, or ALLOCATE options,
then you will, by default, format, allocate, and label the device. See Usage
Note 8 on page 66 for more information.
Changing the Allocation Map
Whenever you format a disk, or specify the "ALLOCATE" option, the current
allocation of the disk will be displayed as follows:
CURRENT ALLOCATION
TYPE CYLINDERS
type nnnn-nnnn
type nnnn-nnnn
type nnnn-nnnn
where:
type
is the designated usage of the extent listed. The usage type is what was specified
when the disk was last allocated (DRCT, PAGE, PERM, SPOL, or TDSK) or is
BAD. BAD indicates an allocation type that CPFORMAT cannot process,
which could result either from the pack not being formatted or from errors that
overlay the allocation map. If "type" is BAD, the disk has not been formatted
by CPFORMAT, and you should consider reformatting the entire disk, using
CPFORMAT.
nnnn-nnnn
is a range of cylinders of this type.
After the current extents are displayed, you will be prompted to update the
allocation map as follows:
ENTER ALLOCATION DATA
TYPE CYLINDERS
For each cylinder range that you want to re-allocate, you enter one line of allocation
data.
64
VMjXA SP2 CP Command Reference
CPFORMAT
The format for allocation data is:
l
{END }
l
DRCT
PAGE
PERM
SPOL
TDSK
startcyl
endcyl
END
-endcyl
-END
.ncyl
.END
where:
END
is entered to indicate that you have completed entering your allocation data.
DRCT
indicates that the corresponding cylinders are to be allocated as space for
directory files.
PAGE
indicates that the corresponding cylinders are to be allocated as space that will
be used solely for system paging activity.
PERM
indicates that the corresponding cylinders are to be allocated as space for CP
user minidisks, nucleus, checkpoint, warm start and other static space.
SPOL
indicates that the corresponding cylinders are to be allocated as space for
spooling, dump space or overflow paging activity.
TDSK
indicates that the corresponding cylinders are to be allocated as temporary disk
space, which will become available to users after they log on to the VMjXA SP
system.
starteyl
is the starting cylinder that is to be allocated. It is a 1- to 4-digit, decimal
number and must be within the size of the real device where the vdev is located.
For example, if the vdev is a 3330 Modell (which has 404 cylinders), the
starting cylinder must be any number from 0 to 403. If the starting cylinder is
all that you specify, only that cylinder will be allocated.
eodeyl
END
-eodeyl
is the last of the range of cylinders whose allocation is specified. It is specified
as a 1- to 4-digit decimal number. If specified, it must be equal to or greater
than startcyl. It must be within the size of the real device where the vdev is
located. For example, if the vdev is a 3330 Modell (which has 404 cylinders),
the endcyl must be a number from 0 to 403. Specify "END" to allocate all
cylinders as the specified type. For example, if you are allocating a 3330 Model
1 and have entered "SPOL O-END", then cylinders 0-403 will be allocated as
SPOL.
Chapter 2. VMjXA SP CP Commands
65
CPFORMAT
If you do not specify the dash ( - ) before endcyl or END, then you must leave
at least one blank between startcyl and endcyl or END .
.ncyl
.END
is a 1- to 4-digit decimal integer designating the number of cylind:ers being
allocated. If specified, ncyl must not be zero and the sum of startcyl and ncyl
must not exceed the size of the real DASD upon which the specified vdev is
located. For example, if the vdev is a 3330 Modell (which has 404 cylinders),
and the startcyl was 0, the ncyl must be a number from 1 to 404. Specify END
to allocate all cylinders as the specified type. If you do not specify ncyl or
END, one cylinder is the default.
Usage Notes
1. In order to use CPFORMAT, your virtual machine must be a Systemj370 mode
machine. Also, your virtual console address must be a 4-digit device address no
higher than X 1FFF
I
I •
2. Execution of the CPFORMAT command resets your virtual machine and clears
virtual storage. This means that, after issuing the CPFORMAT command, you
will have to re-IPL any system (such as CMS) that was running in your virtual
machine.
The CMS command, CPFMTXA, performs the same function as the CP
CPFORMAT command but does not reset your virtual machine.
3. The CPFORMAT command terminates all lUCY connections and releases the
IUCV buffer.
4. CPFORMAT runs in your virtual machine. You can interrupt CPFORMAT
processing by pressing the PAl key.
5. A V=R or V=F user cannot invoke the CPFORMAT command processor.
6. You must format a volume using CPFORMAT or CPFMTXA prior to using
the ALLOCATE option. Otherwise, an error message will be displayed.
7. You may use CPFORMAT to relabel a volume that was formatted by another
operating system. Only the volid is changed, but the rest of the label record
remains unchanged.
8. To prevent you from accidentally erasing a disk, CPFORMAT will prompt you
indicating the cylinders that will be formatted, and ask you if you want to
continue. If the cylinders are incorrect, you can reply "NO", and the disk will
remain unchanged. If they are correct, you can reply "YES", and processing
will continue.
9. If you issue the CPFORMAT command without the LABEL or ALLOCATE
options, it is assumed that you want to format the DASD. For example, assume
you enter the following command:
CPFORMAT 192 TEST1
CPFORMAT assumes that you want to format the entire device. All cylinders
will be formatted, and all cylinders will be initially allocated as "PERM" space.
Then, you will be prompted to update the DASD allocation, and the volume on
192 will be labelled "TEST 1" .
Assume, however, that you enter:
CPFORMAT 192 TEST2 0.3
66
VM/XA SP2 CP Command Reference
CPFORMAT
CPFORMAT will then format cylinders 0, 1, and 2, and ALL cylinders will be
initially allocated as "PERM" space. Then, you will be prompted to update the
DASD allocation, and the volume on 192 will be labelled "TEST2".
If you enter:
CPFORMAT 192 TEST3 1-3
CPFO RMAT will first check to see if the volid on 192 is "TEST3". If it isn't,
you will receive an error message indicating what the correct label is, and
CPFORMAT processing will terminate. If the volid is "TEST3", CPFORMAT
will format cylinders 1, 2, and 3, and you will be prompted to update the DASD
allocation. Note that in this case, the label is NOT written, and the cylinders
are NOT initially allocated as "PERM" because cylinder 0 is not being
formatted.
10. When allocating cylinders, you may enter the cylinders to be allocated in any
order, using any combination of the valid allocation types of DRCT, PAGE,
PERM, SPOL, and TDSK. Each entry in turn overlays the allocation record,
and any space not reallocated will remain the same. If an allocation function
overlays the previous cylinder allotment, then the previous cylinder space
allotment is truncated to the beginning of the next cylinder allotment. For
example, assume that the following is the current allocation of a vdev:
CURRENT ALLOCATION
TYPE CYLINDER
PERM 0000-0554
and you enter the following allocation data:
TDSK
DRCT
SPOL
PAGE
END
1-100
100-200
150-500
400.50
The following allocation will result:
CURRENT ALLOCATION
TYPE CYLINDERS
PERM 0000-0000
TDSK 0001-0099
DRCT 0100-0149
SPOL 0150-0399
PAGE 0400-0449
SPOL 0450-0500
PERM 0501-0554
11. You can allocate a minidisk as if it were a real disk. For example, if you are
allocating a 3350 minidisk, you can allocate 555 cylinders, even though your
minidisk may not have 555 cylinders.
12. PERM is the only type of space that should be allocated beyond the extent of
the virtual device.
13. Space for system dumps, named saved systems, saved segments, image library
files, and VCR class system data files needs to be allocated as SPOL.
14. You should not allocate cylinder 0 as TDSK.
Chapter 2. VMjXA SP CP Commands
67
CPFORMAT
Response 1
FORMAT WILL ERASE CYLINDERS range ON DISK vdev
DO YOU WANT TO CONTINUE? (YES I NO)
where:
range
is inclusive, and specifies those cylinder numbers that will be formatted.
vdev
is the virtual DASD that will be formatted.
This prompt is issued whenever you format a disk. If you reply "YES", processing
will continue, and the following response is issued:
FORMAT STARTED
If you reply "NO", you will receive messages indicating that the disk remains
unchanged, and that CPFORMAT has been terminated.
Response 2
CURRENT ALLOCATION
TYPE CYLINDERS
type nnnn-nnnn
type nnnn-nnnn
type nnnn-nnnn
ENTER ALLOCATION DATA
TYPE CYLINDERS
where:
type
can be BAD, DRCT, PAGE, PERM, SPOL, or TDSK.
nnnn-nnnn
is the cylinder range for the corresponding type.
These responses are issued whenever you want to update the allocation map. The
"CURRENT ALLOCATION" portion of the response displays how all cylinders on
the virtual device are currently allocated. The "ENTER ALLOCATION DATA"
portion of the response prompts you to update the allocation map. Enter your
allocation data from the console; this data must contain both (1) the allocation type,
and (2) the cylinders to be allocated as that type. When you enter END, the
updated allocation map will be displayed on your console using the "CURRENT
ALLOCATION" response.
Refer to the "Changing the Allocation Map" section in this command description
for further details.
68
VM/XA SP2 CP Command Reference
CPFORMAT
Response 3
REENTER: TYPE AND CYLINDERS OR 'END'
This prompt is issued whenever you make an error entering allocation data. An
error message will precede this prompt explaining the error. This prompt asks you
to correct and re-enter the line of allocation data that contained the error.
Response 4
FORMAT COMPLETE
This response is issued when all the specified cylinders have been formatted.
Response 5
ALLOCATE COMPLETE
This response is issued when the allocation record has been written on the DASD
volume.
Response 6
VOLUME LABEL IS NOW IXXXXXX I
This response is issued when the label record has been written on the DASD volume.
IXXXXXX I is the six-character volid with which the volume has been labelled.
Migration Notes
VMISP HPO: In HPO, this function is provided by the stand-alone VM/370
Format/Allocate program (DMKFMT).
Chapter 2. VMjXA SP CP Commands
69
CPTRAP
CPTRAP
VMfXA SP does not support the CPTRAP command. Equivalent function is
provided by the following CP commands:
• TRSOURCE - Supports definitions and control of I/O, data, and guest tracing.
• TRSAVE - Specifies where CP trace data or data from traces defined by the
TRSOURCE command are to be saved. CP trace data may be saved either in
system trace files or on tape. Data from traces defined by the TRSOURCE
command may be saved only in system trace files.
• SET CPTRACE - Activates or deactivates CPT RACE entry recording of real
machine events in the CP TRACE tables.
In addition, the following commands may be helpful:
• QUERY TRSAVE - Displays the destination of traces defined by TRSOURCE
or displays the current status of recording for CP system tracing (traces
controlled by the SET CPT RACE command).
• QUERY TRSOURCE - Displays the current status of the various traces that
have been defined using the TRSOURCE command.
• QUERY CPT RACE - Displays the current setting of the tracing of real system
events in the CP trace tables.
Migration Notes
VMISP HPO: Using any abbreviation for the QUERY CPT RAP command may
result in the QUERY CPT RACE command being invoked. This results in syntax
errors on that command.
70
VM/XA SP2 CP Command Reference
CPU
CPU
Privilege Class: G
Use the CPU command to:
• Designate the virtual processor on which a specified CP command will be
executed
• Select the virtual processor on which console function reads will be issued
• Choose the processor on which #CP commands will be executed.
puaddrl cpuaddr •..
cpuaddrl
cpuaddrl-cpuaddrn
ALL
CPU
~
J'
[CMD] command line
_ cpuaddr2
where:
cpuaddrl
is the processor address of the processor on which a CP command is to be
executed.
cpuaddrl cpuaddr...
is the list of addresses and/or ranges delimited by blanks.
cpuaddrl-cpuaddrn
specifies a nonwrapping pair of addresses separated by a hyphen ("-") and not
separated by any blanks.
ALL
specifies that the CP command executes on all virtual processors currently
defined.
CMD
must be specified if VM/XA SP would interpret the first token of the command
line as a hexadecimal address. For example, if you wish to specify that the
DISPLAY PROGRAM STATUS WORDS command be executed on the CPU
at address 1, do not specify:
CPU 1 0 PSW.
VM/XA SP would interpret the "D" as an address. Instead, specify:
CPU 1 CMD 0 PSW
command line
is the CP command you want to execute on the specified virtual processors.
When processing the CPU command, VM/XA SP does not check the validity of
the CP command you enter here. Only the processor that receives the command
checks it for validity and errors. CP commands that you enter as part of the
CPU command are not checked for validity or errors.
cpuaddr2
is the processor address of the processor on which console function mode is to
be entered and on which #CP commands are to be executed. Commands are
processed on cpuaddr2 until another CPU command is issued specifying another
cpuaddr.
Chapter 2. VMjXA SP CP Commands
71
CPU
Usage Notes
If a command line is specified, the command applies only to the virtual processors
specified. If the cpuaddr is the only operand, all future CP commands will apply to
the specified virtual processor until the next CPU command is issued.
Responses
XX:
where:
xx
is the processor in console function mode on which #CP commands are to be
executed.
Migration Notes
VMISP HPO: This command does not exist in HPO.
72
VMjXA SP2 CP Command Reference
DEDICATE
DEDICATE
Privilege Class: A
Use this command to dedicate (grant the sole usage of) a real processor to any
virtual machine user's virtual CPU.
DEDicate
CPU cpuaddr]
[ CPU ALL
where:
USER
{:serid }
specifies the user whose virtual CPU is to be dedicated to a real processor. If
the USER operand is specified, then either a userid or * must be specified. If
the USER operand is not specified, then the V = R user is the default.
CPU cpuaddr
is the virtual CPU address of the virtual machine guest's virtual CPU to which a
real processor is to be dedicated.
CPU ALL
will attempt to dedicate a real processor to every virtual CPU in the user's
virtual configuration. If the CPU operand is not specified, CPU ALL is the
default.
Usage Notes
1. The defaults for the DEDICATE command are CPU ALL and the userid of the
V = R machine. An attempt will be made to dedicate a real processor to every
virtual CPU defined in the V = R virtual configuration.
2. When DEDICATE USER userid CPU ALL is issued and there are more virtual
CPUs defined than available real processors, all the real processors (except the
master processor) are dedicated to those virtual CPUs starting at the lowest
virtual CPU address.
3. If you have a virtual Vector Facility defined for a virtual CPU being dedicated,
the system attempts to dedicate a real processor that has a Vector Facility
associated with it. If another nondedicated processor having no Vector Facility
associated with it is available, and the master processor has a Vector Facility,
then this may result in the master processor being reassigned to that processor.
If a matching real processor cannot be found, the real processor most closely
matching the characteristics of the virtual CPU being dedicated is assigned to
that virtual CPU.
Note: If the last nondedicated Vector Facility is being taken by a user issuing a
DEDICATE command, a message stating that no real Vector Facility is
available to service nondedicated users is issued back to that user.
Any guest that has a virtual Vector Facility defined when the last real Vector
Facility becomes unavailable subsequently receives a Vector Facility failure
message if the guest issues any vector instructions. Guests that define virtual
Vector Facilities after the last real Vector Facility has gone away receive a
warning message.
Chapter 2. VM/XA SP CP Commands
73
DEDICATE
If a processor with a real Vector Facility is dedicated to a virtual CPU that has
no virtual Vector Facility defined, the real Vector Facility will be unavailable for
use by anyone until an UNDEDICATE is issued or a virtual Vector Facility is
defined for the dedicated guest.
If "DEDICATE USER userid CPU ALL" is specified, all the currently defined
virtual CPUs for the userid are affected. In addition, if automatic dedication is
not in effect for this user and this user is V = R, then automatic dedication is
enabled for this user. To avoid enabling automatic dedication, use
"DEDICATE USER userid CPU nn" instead.
4. The CPU and USER operands can appear in any order.
5. If you issue the DEDICATE command to DEDICATE a processor to a V = R
machine that has automatic dedication disabled, and the dedicated processor is
subsequently undedicated for any reason (such as a CP abend), the dedicated
processor is not automatically rededicated.
Responses
COMMAND COMPLETE
is the response issued upon the successful completion of a DEDICATE CPU
command specifying a CPU address on the command line.
Migration Notes
VMISP HPO: This command does not exist in VMjSP HPO.
74
VM/XA SP2 CP Command Reference
DEFINE
DEFINE
Use the DEFINE command described in this section to alter the configuration of
your virtual machine.
Complete Format for DEFINE
The format box below shows all of the operands available with the DEFINE
command. Complete descriptions of the operands appear on the following pages, in
the same sequence as the operands appear here.
Class
DEFine
CONsole
[AS]
vdev
[3215J
3270.
CPU !CPuaddr
cpuaddr1 cpuaddr •..
cpuaddr1-cpuaddrn
cpuaddr2 [AS] CPU cpuaddr3
CTCa
[AS]
vdev
[USER]
G
l
userid
GRaf [AS] vdev [3270]
MDISK [AS] vdev scyl {cnt} volser
END
Reader
Printer
PUnch
1403
2501
2540P
2540R
3203
3211
3262
3505
3525
4245
4248
A
G
[AS]
vdev
Chapter 2. VM/XA SP CP Commands
75
DEFINE
DEFine
Class
raee }
G
[AS] vdev [Option]
3800-1
3800-3
STORage
[AS] {rmnnnnnK}
nnnM
T2305
T2314
,T2319
:T3310
'T3330
:T3340
T3350
T3370
T3375
T3380
TFB-512
.
[AS]
vdev [CYL]
nnnn
vdevl
[AS]
vdev2
VECtor
t{~~1-nn2} [{~~1-nn2}···
} \
ALL
Option
[[SIZe width length]
[4WC9m] [CFSJ
2Wcgm,
BTS
~ODatck JJ
DAtck
,
General Usage Notes for DEFINE
1. When you use the DEFINE command to alter the configuration of your virtual
machine, the changes are temporary and are only in effect for the current
session.
2. If your virtual machine is operating in 370-XA mode, the virtual device numbers
you specify can be no higher than FFFF. If your machine is operating in
System/370 mode, you can define virtual device numbers through FFFF;
however, your virtual machine can use only the virtual devices numbered 0
through 1FFF.
3. Informational responses are sent to your display to confirm that the
configuration change you requested has taken place. These responses do not
appear if you have issued the CP SET IMSG OFF command.
4. The temporary disks T2314, T2319, T3310, T3370, and TFB-512 are accepted
for compatibility but will result in a message indicating that the temporary disk
is not defined because space is not available.
Migration Notes
VMISP HPO
1. VM/XA SP does not support the TIMER, CHANNELS, LINE, and SYSVIRT
operands.
2. VM/XA SP does not allow the A abbreviation for AS.
76
VM/XA SP2 CP Command Reference
DEFINE CONSOLE
DEFINE CONSOLE
Privilege Class: G
Use DEFINE CONSOLE to add a virtual system console to your virtual machine
configura tion.
I
DEFine
CONsole [AS] vdev
3215J
[ 3270
where:
CONSOLE
indicates that you are defining a virtual system console for your virtual machine.
(AS) vdev
is the virtual device number of the console you are defining.
3215
3270
is the virtual console device type. 3215 is the default.
i
Usage Notes
1. If a terminal is controlled by a VTAM service machine with a level lower than
3.1.1., the console cannot be defined as a 3270. If you attempt tq do so, the
console is defined as a 3215 and an error message is displayed.
2. Only one virtual console is permitted. You will receive an error message if you
already have a virtual console defined.
3. The default spool file class given to spool files created on the virtual console is
class T.
4. Any time you issue the DEFINE CONSOLE command, you define the console
mode for your display. This becomes the console mode for the duration of the
session or until you reissue DEFINE CONSOLE or TERMINAL CONMODE.
For more information on the console mode setting and its significance to the
programs that you run in your virtual machine, see "TERMINAL CONMODE"
on page 640.
5. For additional information, refer to the "General Usage Notes for DEFINE."
Responses
CONSOLE vdev DEFINED
confirms the virtual console definition. This response will not appear if you have
issued the CP SET IMSG OFF command.
Migration Notes
VMISP HPO
1. VM/XA SP supports an additional option: the virtual console device type (3215
or 3270).
2. VM/XA SP does not accept 'A' for 'AS'.
Chapter 2. VM/XA SP CP Commands
77
DEFINE CPU
DEFINE CPU
Privilege Class: G
Use DEFINE CPU to add one or more virtual processors to your virtual machine
configuration, or to change the address of a currently defined virtual processor.
DEFine
CPU \CPuaddr
cpuaddrl cpuaddr .••
cpuaddrl-cpuaddrn
cpuaddr2 [AS] CPU cpuaddr3
I
.
where:
CPU cpuaddr
defines a virtual processor for your virtual machine configuration at the address
you specify for cpuaddr. You may specify multiple addresses in a list or in
range form. If you specify a list of addresses, separate each address from the
others by at least one blank. If you specify a range of addresses, specify the first
and last addresses in the range and put a hyphen between them. The processor
addresses can be any value from 0 to 3F; the initial address of your base
processor either is specified in your entry in the system directory or defaults to O.
CPU cpuaddrl cpuaddr..•
is a list of addresses and/or ranges delimited by blanks.
CPU cpuaddrl-cpuaddrn
specifies a nonwrapping pair of addresses separated by a hyphen (" -") and not
separated by any blanks.
CPU cpuaddr2 [AS) CPU cpuaddr3
changes the address of the processor currently defined at cpuaddr2 to the
address cpuaddr3.
Usage Notes
1. Your entry in the system directory specifies the maximum number of processors
you can define for your virtual machine.
2. If your entry in the system directory contains multiple CPU statements which
specify a virtual multiprocessing configuration, then it will be created for you at
logon time. If your directory entry does not specify additional processors, then
your virtual machine logs on as a uniprocessor machine. Once logged on, you
can use the DEFINE CPU command to modify your virtual configuration.
3. All future CP responses will be prefaced with the CPU number, with CPU
issuing the responses. This continues as long as you have the virtual
multiprocessor configuration.
4. When a virtual Vector Facility is associated with a virtual processor, a change of
the virtual processor address (via "DEFINE CPU nn AS CPU mm") also
changes the address of the virtual Vector Facility.
5. If the V = R user issues the DEFINE CPU command and has automatic
dedication enabled, the newly created CPU is dedicated to a real processor if one
is available. If you do not want this CPU dedicated to a real processor: (a) use
the DEFINE CPU command to get your new CPU and then use the
UNDEDICATE command to release the dedication, or (b) disable automatic
78
VMjXA SP2 CP Command Reference
DEFINE CPU
dedication (by issuing UNDEDICATE CPU ALL beforehand). Note that
UNDEDICATE is a privilege class A command.
If a V = R machine (with its OPTION directory statement set or defaulted to
DEDICATE) issues DEFINE CPU, CP attempts to dedicate a real processor.
6. For additional information, refer to the "General Usage Notes for DEFINE."
7. The protected application environment is supported only for virtual machines
consisting of a single processor. If you have previously established the protected
application environment by issuing the SET CONCEAL ON command or by
logging on with an OPTION CONCEAL directory statement, that environment
is terminated when you define additional CPU s. If you revert to a uniprocessor
configuration at a later time, you may reestablish the protected application
environment by issuing SET CONCEAL ON.
Responses
ee:
CPU
nn
DEFINED
confirms that the processor has been defined.
where:
00
is the number of the CPU responding to you.
nn
is the number of the CPU currently defined.
Chapter 2. VMjXA SP CP Commands
79
DEFINE CHANNEL-TO-CHANNEL ADAPTER
DEFINE CHANNEL-TO-CHANNEL ADAPTER
Privilege Class: G
Use DEFINE CHANNEL-TO-CHANNEL ADAPTER (CTCA) to define a virtual
channel-to-channel adapter for your virtual machine.
I DEFine
CTCa [AS]
vdev [USER]
userid
where:
CTCA
indicates that you are defining a channel-to-channel adapter for your virtual
machine.
[AS] vdev
is the virtual device number of the CTCA you are defining.
[USER] userid
is the user that you will permit to connect to this CTCA using the CP COUPLE
command.
Usage Notes
1. You cannot specify an asterisk in the command line to indicate your own userid.
This is an exception to the rule which states that an asterisk is a substitute for
your userid.
2. For more information, refer to the "General Usage Notes for DEFINE."
Responses
CTCA vdev DEFINED
confirms the definition of the virtual channel-to-channel adapter. This response will
not appear if you have issued the CP SET IMSG OFF command.
Migration Notes
VMISP HPO: On the VMjXA SP command line, you must specify the userid that
you will permit to connect to the virtual CTCA.
80
VM/XA SP2 CP Command Reference
DEFINE GRAF
DEFINE GRAF
Privilege Class: G
Use DEFINE GRAF to add a virtual display station to your virtual machine
configuration.
I DEFi ne
GRAF [AS]. vdev [3270]
where:
GRAF
indicates that you are defining a display station for your virtual machine.
(AS) vdev
is the virtual device number of the display you are defining.
3270
is the virtual device type of the display you are defining. This is the default.
Usage Notes
1. Once the display station is defined, you must issue the CP DIAL command from
a real display station in order to logically connect the display station to your
virtual machine. The device from which you issue the DIAL command must be
supported by the operating system that is running in your virtual machine and
by VMfXA SP.
2. For additional information, refer to the "General Usage Notes for DEFINE."
Responses
GRAF vdev DEFINED
confirms the definition of the virtual display station. This response will not appear
if you have issued the CP SET IMSG OFF command.
Migration Notes
VMISP HPO: VM/XA SP does not support GRAF as vaddr
(3036/3066/3138/3148/3158).
VMIXA SF: The VM/XA SP response uses GRAF instead of DISP.
Chapter 2. VM/XA SP CP Commands
81
DEFINE MDISK
DEFINE MDISK
Privilege Class: A (primary system operator only)
Use DEFINE MDISK to define a mini disk on a system volume or DASD volume
a ttached to the system.
DEFine
MDISK
[AS]
vdev scyl {cnt} vo 1ser
END
where:
MDISK
indicates that you are designating an area as a minidisk on a system volume or a
DASD volume attached to the system.
[AS) vdev
is the virtual device number of the minidisk you are defining.
scyl
is a 4-digit decimal starting cylinder number that specifies which cylinder on the
real disk corresponds to cylinder 0 of the virtual disk.
cnt
is a 4-digit decimal number that specifies the number of cylinders that is to make
up the MDISK definition.
END
specifies that the MDISK should be defined with the remaining available
cylinders.
volser
is the volume serial (one to six alphanumeric characters) of the real DASD
volume upon which the MDISK definition is to apply.
Usage Notes
1. The minidisk that you define remains available until you log off or detach the
virtual device on which it resides. Use this command only in disaster recovery
situations because it provides access to any area of a DASD volume without
requiring additional authorization.
2. You can define a minidisk as a full-pack minidisk. You must define the starting
cylinder number as zero and include all of a DASD volume's primary cylinders
and some or all of its alternate cylinders.
3. Minidisks created using the DEFINE MDISK command have cache access if
they are on a cached control unit.
4. Minidisks are not permitted on 3880 Model 11 and 21 subsystems.
Responses
DASD vdev DEFINED
where:
vdev
is the virtual device number of the minidisk you define.
82
VM/XA SP2 CP Command Reference
DEFINE (spooling device)
DEFINE (spooling device)
PriYilege Class: G
Use the DEFINE (spooling device) command to add a virtual spooling device to
your virtual machine configuration.
DEFine
Reader
Printer
PUnch
1403
2501
2540P
-2540R
,3203
3211
3262
3505
3525
4245
4248
[AS]
vdev
3800
} [AS] vdev [SIze width length] [2Wc gm',] rBTS][DATCK ]
3800-1
4Wcgm LCFS NODATCK
{ 3800-3
Note: If you specify a 3800-3 with 2WCGM, you will receive an error message.
where:
READER
RDR
specifies a 2540 card reader.
PRINTER
PRT
specifies a 1403 printer.
PUNCH
PCH
specifies a 2540 card punch.
1403
specifies a 1403 printer.
2501
specifies a 2501 card reader.
2540P
specifies a 2540 card punch.
2540R
specifies a 2540 card reader.
3203
specifies a 3203 printer.
Chapter 2. VM/XA SP CP Commands
83
DEFINE (spooling device)
3211
specifies a 3211 printer.
3262
specifies a 3262 printer.
3505
specifies a 3505 card reader.
3525
specifies a 3525 card punch.
4245
specifies a 4245 printer.
4248
specifies a 4248 printer.
3800
specifies a 3800 Modell printer.
3800-1
specifies a 3800 Modell printer.
3800-3
specifies a 3800 Model 3 printer in Model 1 compatibility mode.
(AS) vdev
is the virtual device number for the spooling device that you are defining.
SIZE width length
specifies the physical characteristics of the paper to be loaded into th~ 3800
printer. "width" indicates the hexadecimal width code of the paper. "length"
indicates the decimal length of the paper. Specify "length" as a whole number
using half-inches. If "width" and "length" are not specified, 14-7/8 x 11 inches
is assumed.
The default value of "width" is X OF
I
I.
The default value of "length" is 22 (eleven inches).
The following is a list of available form width codes. All other values will be
rejected.
CODE WIDTH IN INCHES
01
02
04
06
07
08
09
SA
08
00
0E
0F
84
6-1/2 in.
Reserved
8-1/2 in.
9-1/2 in.
9-7/8 in.
10-5/8 in.
11 in.
12 in.
Reserved
13-5/8 in.
14-3/10 in.
14-7/8 in.
VM/XA SP2 CP Command Reference
WIDTH IN MILLIMETERS
(165
(180
(215
(235
(250
(270
(280
(305
(322
(340
(363
(378
mm
mm
mm
mm
mm
mm
mm
mm
mm
mm
mm
mm
ISO)
ISO)
ISO)
ISO)
ISO)
ISO)
ISO)
ISO)
ISO)
ISO)
ISO)
ISO)
DEFINE (spooling device)
2WCGM
4WCGM
specifies the number of writable character generation modules (WCGM)
assumed for the virtual 3800 printer. A WCGM is a 64-position portion of the
3800's character generation storage that holds the scan elements of one character
set. A 3800 can have either two or four WCGMs. If neither is specified, a
default of 4WCGM is assumed.
Note: Specifying 3800-3 with 2WCGM results in an error message.
BTS
CFS
designates the stacker for the virtual 3800 printer. You may specify either CFS
(continuous forms stacker) or BTS (burster trimmer stacker). If neither is
specified, CFS is assumed.
DATCK
NODATCK
specifies the desired handling of certain virtual 3800 data checks. If you specify
DATCK, all 3800 data checks are reflected to the virtual machine (provided the
'BLOCK DATA CHECK' CCW has not been issued). If you specify
NODATCK, only data checks that occur due to invalid translate table
specifications or unmatched FCB codes are reflected to the virtual machine.
NODATCK is the default ~ondition.
Note: DATCK should be used only when absolutely necessary as it severely
increases the overhead associated with simulation of WRITE and SKIP
CCWs to the virtual 3800. In general, the reflection of data checks due
to overprinting and invalid EBCDIC codes is not necessary.
Usage Notes
1. Avoid using device addresses that can be mistaken for device types (such as
1403, 2501, and 3203). When CP encounters a device address on the device
command line that is the same as an IBM device type, CP assumes that you are
specifying a device type and not a device address.
2. If you define a virtual 3211 printer, it supports the CP LOADVFCB command
and the INDEX feature.
3. Default spool file classes given to spool files created on this device are:
reader-class A, punch-class A, printer-class A.
4. Virtual printers, consoles, and punches are created with the default option
"NOEOF."
Examples:
DEFINE Reader AS OOc
The parameters following the vdev specification may be given in any order and
multiple times. However, the last specification of a multiply-defined parameter
will be the one used. For example, if you issue:
DEF 3800 as OOA CFS DATCK SI 07 22 2W BTS
BTS is the value used instead of CFS because it was specified after CFS.
5. For more information, refer to the "General Usage Notes for DEFINE."
Chapter 2. VMjXA SP CP Commands
85
DEFINE (spooling device)
Responses
type vdev DEFINED
confirms that the device has been defined. This response will not appear if you have
issued the CP SET IMSG OFF command. The possible values for type are:
Type
Meaning
RDR
PRT
PUN
Card reader
Printer
Card punch
Migration Notes
VMISP HPO: VM/XA SP does not support DEFINE PRINTER As vaddr
1443/3289E.
86
VM/XASP2 CP Command Reference
DEFINE STORAGE
DEFINE STORAGE
Privilege Class: G
Use the DEFINE STORAGE command to change the storage size of your virtual
machine.
I DEFine
STORage [AS] {nnnnnK}
nnnM
where:
STORAGE (AS)
{oonOOK ,}
oooM
indicates that you are changing the storage size of your virtual machine. You
can specify the new storage size as nnnnnK (where K represents 1024 bytes) or
nnnM (where M represents 1,048,576 bytes).
Usage Notes
1. Specify the new storage size as a multiple of 64K bytes. The new storage size is
limited by the maximum size contained in your entry in the system directory.
The minimum size you can specify is 64Kb and the maximum size is 999Mb.
If the storage size you specify is not a multiple of 1Mb and is not greater than
16Mb, it is rounded up to the next 64Kb boundary. If the storage size you
specify is not a multiple of 1Mb and is greater than 16Mb, it is rounded up to
the next 1Mb boundary. If the storage size you specify remains the same, you
receive Response 1. No reset takes place if you try to define your storage to the
same value you currently have.
The storage size specified is rounded up to the next higher megabyte boundary
for both V = R and V = F users, even if the storage size specified is less than
16Mb.
2. The DEFINE STORAGE command causes the virtual machine to be reset and
storage to be cleared. It also terminates all IUCV connections and releases the
IUCV buffer. If the virtual machine was a member of a virtual machine group
(from prior IPL of a VMGROUP NSS), that group membership is canceled.
The virtual machine's IUCV connection to the signal system service is severed
and a signal-out message is broadcast by the signal system service to all other
members of the group who are enabled for signal-out notification.
3. If your virtual machine uses DIAGNOSE X 198 I for locking virtual machine
pages in real storage, issuing DEFINE STORAGE unlocks those pages.
DEFINE STORAGE releases all NSSs and saved segments from your virtual
machine. Locked shared pages are unlocked only by DIAGNOSE X 198 I or by
the release of the shared segment by the last user.
4. Whenever you change the virtual storage size, your virtual machine is reset as if
a CP SYSTEM CLEAR command had been executed. Because a reset clears all
virtual storage to binary zeros, you must repeat your IPL procedure to continue
operation.
5. If the V = R or V = F storage amount requirement cannot be allocated within the
V = R area, then this command is not processed and an error message is issued.
6. For more information, refer to "General Usage Notes for DEFINE" on
page 76.
Chapter 2. VM/XA SP CP Commands
87
DEFINE STORAGE
Response 1
STORAGE
={
nnnnnK }
nnnM
confirms the new storage size of your virtual machine. This response does not
appear on your display if you have issued the CP SET IMSG OFF command.
Response 2
STORAGE CLEARED - SYSTEM RESET
is issued whenever you change your storage size using DEFINE STORAGE.
Migration Notes
VMISP HPO
1. VM/XA SP does not allow a V = R user to define a storage size larger than the
V=R area;
2. VM/XA SP provides an additional response: STORAGE CLEARED - SYSTEM
RESET;
3. VM/XA SP allows you to specify storage sizes larger than 16Mb.
88
VM/XA SP2 CP Command Reference
DEFINE (temporary disk)
DEFINE (temporary disk)
Privilege Class: G
Use DEFINE (temporary disk) to define temporary virtual disks.
DEFine
T2305
T2314
T2319
T3310
T3330
T3340
T3350
T3370
T3375
T3380
TFB-512
[AS] vdev [CYL] nnnn
where:
T2305
T3330
T3340
T3350
T3375
T3380
adds a temporary virtual disk to your virtual machine configuration. The four
digits following the "T" correspond to the virtual device type.
T2314
T2319
T3310
T3370
TFB-512
are accepted for compatibility but will result in a message indicating that the
temporary disk is not defined because space is not available.
(AS) vdev
specifies the virtual device number of the disk.
(CYL) nnnn
specifies the number of cylinders contained in the virtual disk.
Usage Notes
1. Temporary disk space is assigned from a pool of DASD resources; therefore,
you should always format your temporary disk space before you use it.
2. Specify T3350 if a 3350 is used in native mode; specify T3330 if a 3350 is used in
3330 compatibility mode. Specify T3340 if a 3344 is used.
3. If you are defining a multiple-exposure device, the virtual device number that
you specify must be the first (base) exposure. Once you define the multiple
exposure device, all the exposures are defined.
4. TDISKs created via the DEFINE TDISK command will have cache access if
they are on a cached control unit.
5. For more information, refer to the "General Usage Notes for DEFINE."
Chapter 2. VM/XA SP CP Commands
89
DEFINE (temporary disk)
Responses
DASD vdev DEFINED
confirms the definition of the temporary disk. This response will not appear on your
display if you have issued the CP SET IMSG OFF command.
Migration Notes
VMISP HPO: VM/XA SP does not support DEFINE TFB-512/T3310/T3370 As
vaddr BLK nnnnnn, or DEFINE T2314/T2319 As vaddr CYL nnn.
90
VM/XA SP2 CP Command Reference
DEFINE (virtual device)
DEFINE (virtual device)
Privilege Class: G
Use DEFINE (virtual device) to change the virtual device number of any existing
virtual device in your configuration.
I
DEFine
vdevl
[AS]
vdev2
where:
vdevl
is the virtual device number of an existing virtual device.
[AS) vdev2
is the new virtual device number.
Usage Notes:
1. If you are changing the virtual device number of a multiple-exposure device,
specify the base exposure as the virtual device number in both vdev 1 and vdev2.
When you change the virtual device number of a multiple-exposure device, all
exposures are redefined. Thus, if IBO is the device number of a 2305, the
command:
define Ibe as Ide
redefines device numbers IBO through IB7 as IDO through ID7, respectively.
2. Avoid using device addresses that can be mistaken for device types (such as
1403, 2501, and 3203). When CP encounters a device address on the device
command line that is the same as an IBM device type, CP assumes that you are
specifying a device type and not a device address.
To avoid potential confusion and errors, use the REDEFINE command.
Note: If you redefine a System/370 device that is eligible for the start
interpretive execution assist as a vdev with an address greater than FFF,
you will lose the assist for that device.
3. Virtual paging subsystem devices cannot be redefined in order to protect the
integrity of the user's virtual paging subsystem.
4. For more information, refer to the "General Usage Notes for DEFINE."
Chapter 2. VM/XA SP CP Commands
91
DEFINE (virtual device)
Responses
type vdev DEFINED
confirms that the device number has been changed. This response will not be
displayed if you have issued the CP SET IMSG OFF command. The possible values
for type are:
Type
Meaning
DASD
TAPE
RDR
PRT
PUN
GRAF
CONS
CTCA
CTLR
MSC
DEV
Direct access storage device
Magnetic tape
Card reader
Printer
Card punch
Display graphic device
Console
Channel-to-channel adapter
3704 or 3705 Communications Controller
Mass Storage Controller
Any other device
Migration Notes
VMISP HPO
1. VM/XA SP does not support DEFINE 1443/3088/3289E As vaddr.
2. Within VM/XA SP, when CP encounters a device address on the device
command line that is the same as an IBM device type, CP assumes that you are
specifying a device type and not a device address.
VMIXA SF: VM/XA SP uses GRAF rather than DISP in its response.
92
VMjXA SP2 CP Command Reference
DEFINE VECTOR
DEFINE VECTOR
Privilege Class: G
Use DEFINE VECTOR to create a virtual Vector Facility (VF) on one or more
CPUs of your virtual machine configuration. If VF use is not restricted by directory
option, a virtual VF may be defined for each virtual CPU that has been defined. A
virtual Vector Facility may be defined for each virtual CPU.
A virtual VF can only be defined if VMfXA SP is running on a machine with at
least one real VF installed.
DEFine
VECtor
where:
VECTOR
defines a virtual VF for the virtual machine configuration at the address or
addresses specified. Multiple addresses may be specified in the form of a list of
single numbers or ranges.' The addresses may be any value from hex 0 to 3F,
provided a CPU with the same address has been defined.
nn
is a single virtual CPU address in hexadecimal.
nnl-nn2
is a nonwrapping pair of addresses in hexadecimal separated by a hyphen and
not separated by any blanks.
ALL
specifies that a virtual VF is to be defined for every virtual CPU in the
configuration that does not already have one.
Usage Notes
1. If you define a new virtual Vector Facility for a virtual CPU that is currently
dedicated to a real processor that doesn't have a Vector Facility installed, you
will have to rededicate (UNDEDICATE and then DEDICATE) the virtual
CPU. (The exception to this is if the processor is dedicated to a V = R user with
automatic dedication set to on.)
2. When you redefine a virtual CPU with the DEFINE CPU nn AS mm command,
you also cause the associated Vector Facility address to be redefined.
3. When a virtual VF is defined on a dedicated virtual CPU of the preferred
(V = R) guest and automatic dedication is set on, VMjXA SP attempts to
reassign that virtual CPU to a real processor with a real VF. If this attempt
fails (because there is no nondedicated real processor with VF), then the virtual
CPU remains dedicated to a processor without VF, and the virtual Vector
Facility appears not operational to the guest. The system issues a warning
message to this effect.
Chapter 2. VMjXA SP CP Commands
93
DEFINE VECTOR
4. When a user defines a virtual VF on a dedicated virtual CPU of a preferred
(V = R) guest and automatic dedication is set on, this may leave no real VF for
nondedicated virtual CPUs, including all V = V users. Therefore, this command
should be used with care by the V = R guest.
Examples
To define a virtual VF for CPU 1, enter:
DEFINE VECTOR 1
To define virtual VFs for CPUs 0, 2, and 3, enter:
DEFINE VECTOR
e 2-3
Response 1
VECTOR FACILITY
nn
DEFINED
nn
is the virtual CPU address on which the virtual Vector Facility has been created.
Response 2
ALL VECTOR FACILITIES ALREADY DEFINED
is displayed when DEFINE VECTOR ALL is issued and all virtual CPUs already
have virtual Vector Facilities defined on them.
94
VM/XA SP2 CP Command Reference
DEFSEG
DEFSEG
Privilege Class: E
Use the DEFSEG command to define a skeleton (class S) system data file (SDF) for
the saved segment. The skeleton file consists only of a descriptor page, containing
all the information necessary for keeping the saved segment when using the
SAVESEG command. Users cannot access the saved segment until it has been
saved.
DEFSEG
dcssname{{heXpagel-hexpage2 type} ___ } [RSTD] [SPACE spacename ]
SAME range
where:
dcssname
is the name of the saved segment (a 1- to 8-character alphanumeric string).
When used with SPACE, the dcssname specified here is known as the member
name and must be different from the SPACE name.
hexpagel-hexpage2
is a range of pages to be saved. When hexpageJ and hexpage2 are the same,
only that page is saved. The range may be contained in a single i-megabyte
segment, or it may comprise a contiguous area in two or more segments. You
may use multiple page ranges to define a i-megabyte segment. However, the
page descriptor codes of all page ranges in the same segment must have the same
shared or exclusive attribute.
Define only those pages whose data must be saved. Any page or pages in a
segment not explicitly defined in a page range on the DEFSEG command will
default to the no data saved attribute. If other pages in the segment were defined
with the shared attribute (page descriptor codes SR, SW, SN and SC), pages not
specified on the command line become shared read-only pages whose data are
not saved. No page descriptor code corresponds to this state; it has the same
attributes as the state defined by page descriptor code SC, except that CP will
not write into these pages.
If other pages in the segment were defined with the exclusive attribute (page
descriptor codes ER, EW, and EN), any pages not specified on the command
line become exclusive read/write pages whose data are not saved. This
corresponds to page descriptor code EN.
The page ranges of a member saved segment cannot overlap with the specified
page ranges of another member saved segment associated with the same segment
space. Areas not specified (defaulted to no data saved) may be taken by another
member saved segment. If the member uses these pages but doesn't need the
pages' data saved, the range with the EN or SN attribute type must be specified.
Also, this member saved segment's range descriptor code cannot conflict with
those of an existing member that has ranges defined in the same segment of
storage.
Chapter 2. VMjXA SP CP Commands
95
DEFSEG
The page number is a hexadecimal value less than or equal to X I 3E6FF I (999
Mb). The following list shows examples of how storage addresses translate into
page numbers:
Hexadecimal
Storage Address
eeeeexxx
eeeelxxx
eee22xxx
ee333xxx
e4444xxx
3E6FFxxx
Hexadecimal
Page Number
e
1
22
333
4444
3E6FF
type
refers to the page descriptor code of the page range in the saved segment. It
indicates the type of virtual machine access permitted to pages in the range.
The first character is either "E" for exclusive access or "S" for shared access.
Sharing of storage between virtual machines is based on one-megabyte segments,
so all 256 pages in anyone segment must be either exclusive or shared.
The second character of the page descriptor code defines the storage protection
characteristics of the page. These character designators are as follows:
"R" indicates that page protection is used to make the page range read-only.
"W" means that the page is not protected, and users have read/write access.
"N" stands for "read/write, no data saved," meaning that the page is treated as
a new page when the user references it. The contents of and storage keys for
"no data saved" pages are not saved by the SAVESEG command.
"C" stands for "CP-writeable, virtual machine read-only, no data saved,"
meaning virtual machines have read-only access to these pages, but CP services
may change the data in the pages.
The contents of storage keys for "no data saved" pages are not saved by the
SAVESEG command.
Valid page descriptor codes are:
EW
EN
ER
SW
SN
SR
SC
--------
exclusive read/write access
exclusive read/write access, no data saved
exclusive read-only access
shared read/write access
shared read/write access, no data saved
shared read-only access
CP writeable pages, shared read-only access
by virtual machine, no data saved
The user must define all pages in segment zero in ranges with an exclusive page
descriptor code (EW, ER, or EN). The system will reject the DEFSEG
command if the user defines any pages in segment zero with a shared access page
descriptor code.
96
VM/XA SP2 CP Command Reference
DEFSEG
SAMERANGE
specifies that this member saved segment definition is the same as one specified
by a previous DEFSEG. This operand is mutually exclusive with the
hexpagel-hexpage2 operands. When you specify SAME RANGE, you also must
specify SPACE.
You don't have to specify SAVESEG if you use DEFSEG with the SAME
operand for a class A member saved segment. However, if the member saved
segment you're referencing is a class S file, you must still use SAVESEG to save
the file.
SAMERANGE makes it easier to create overlaying segment spaces by using the
same member for both segment spaces.
If you use this operand with a spacename that doesn't exist, the member that
you specify must be a class S (skeleton) file.
You must have either a class S or class A file with the same dcssname when you
use this operand. If you have both class A and class S files, the command uses
the information in the class S file.
RSTD
indicates a restricted saved segment. The user must have a corresponding
NAMESAVE directory statement to access this saved segment. If any member
of a segment space is defined with the restricted operand (that is, the SPACE
operand is used), the entire segment space is then restricted. This means that the
restricted spacename is that which must be used on the NAMESAVE directory
statement. If you didn't specify SPACE, then the dcssname is restricted. If you
use the RSTD operand, make sure that you use the NAMESAVE directory
statement to allow authorization.
If you used the SAMERANGE operand, you can use RSTD. This will affect
the authorization of the segment space that you specified in the DEFSEG
definition. The spacename is that which must be used on the NAMESAVE
directory statement.
SPACE
specifies the definition of a segment space. Use this operand to make the
dcssname that you are defining a member of this segment space.
spacename
is the name of the segment space (a 1- to 8-character alphanumeric string). You
must specify this if you use the SPACE operand. The spacename must be
different from any dcssname known to CP.
Usage Notes
1. Pages either defined as or defaulted to no data saved are initialized to a page of
zeros when first referenced. If the pages are in an exclusive segment, changes
will be seen only by the one user. If the pages are in a shared segment, any
changes previously made by any sharing user (if allowed) will be visible to all
other users sharing that same page.
2. Storage keys are not saved for pages either defined as or defaulted to no data
saved. When first referenced, they have keys of zero.
3. A segment space has a range that may span one or more physical one megabyte
segments. The beginning address of a segment space is rounded down to the
nearest megabyte boundary of the member having the lowest page value. The
ending address of a segment space is rounded up to the last address of the last
Chapter 2. VM/XA SP CP Commands
97
DEFSEG
page within the megabyte occupied by the member having the highest page
value.
4. Each member saved segment has a range that may span one or more pages. The
beginning address of a member saved segment is determined by its lowest page
value. The ending address is determined by the last address of the highest page
value.
5. Segment zero must always have the exclusive access attribute "Ex." If a shared
("Sx") page descriptor code is used for any pages in segment zero, the command
is rejected.
6. A CP DCSS (SC mode) contains CP-writeable pages, to which virtual machine
users have just read-only access. CP will write data into these pages, which may
then be referenced by virtual machines. Serialization of data in the CP-writeable
pages, if desired, must be arranged between the CP function providing the data
and the virtual machines referencing it.
7. A CP DCSS may not be loaded in non-shared (exclusive) mode by DIAGNOSE
X ' 641.
8. Saved segments are loaded via DIAGNOSE code X'64'. Named saved systems
(NSS) are loaded via the IPL command.
9. Only one skeleton (class S) ncss can exist with a specific name. If one already
exists and a second DEFSEG command is issued specifying the same name, the
command is rejected.
10. Each name may be used for only one of the following: a segment space, a
member saved segment, or a DCSS.
11. Defining members which use undefined areas within other members of the same
segment space is not recommended. However, in support of multiple products
requiring both shared and exclusive segment types and to minimize storage use,
definition of members with interleaved ranges is supported.
12. You can only use the SAME RANGE operand with the SPACE operand.
Note: You cannot use the SAME operand with a dcssname containing SW, SN,
EW, or EN page types.
13. A DEFSEG with a SAMERANGE operand can be the first definition of a
segment space only if the specified member is a class S file.
14. A DEFSEG with a SAMERANGE operand doesn't need a corresponding
SAVESEG if the member saved segment is already saved. If the member saved
segment isn't saved, you need to use the SAVESEG command.
15. A member of a segment space cannot overlap any of the ranges specified for an
existing member within the same segment space. Also, the members cannot have
conflicting descriptor codes for ranges defined within the same segment of
storage.
16. You cannot specify a DEFSEG with the SAMERANGE operand for a segment
space that already has a member saved segment with that name.
17. Putting a member name in a directory statement will have no effect; use the
segment space name.
98
VMjXA SP2 CP Command Reference
DEFSEG
Security Notes
1. When RSTD is specified, (indicating a restricted saved segment) only those users
whose directory entries contain a NAMESAVE statement specifying the name of
the restricted system data file are allowed to load this saved segment. If RSTD
was specified without the SPACE operand, the directory entries must contain a
NAMESAVE statement specifying the dcssname. If RSTD was specified with
the SPACE operand, the directory entries must contain a NAMESAVE
statement specifying the spacename. This allows an installation to ensure data
integrity by restricting access to saved segments that contain shared writable
storage (defined with the SW and SN page descriptor codes) or to CP DCSSs
(defined with the SC page descriptor code), which may contain sensitive data.
2. Virtual machines which share read/write pages, defined with the SW and SN
page descriptor codes, are responsible for the integrity of the shared data. The
operating system that uses these shared writable pages should ensure that these
virtual machines are properly protected from one another.
Examples
DEFSEG USERSEG l00-lFF SR RSTD
DEFSEG SEGI 1000-lFFF EN 2000-2FFF SR 3000-3FFF ER
DEFSEG PPA 700-721 SR SPACE GROUP1
DEFSEG PPB 722-7Al SR SPACE GROUPI
DEFSEG PPC 7A2-7F0 SR SPACE GROUPI
DEFSEG PPX 700-721 SR RSTD SPACE GROUP1A
DEFSEG PPB SAME SPACE GROUP1A
DEFSEG PPC SAME SPACE GROUPlA
DEFSEG PPD 700-740 SR SPACE GROUP3
DEFSEG PPE 741-779 SR SPACE GROUP3
DEFSEG PPE 7A0-7FF SR SPACE GROUP3
For more explanations and examples, please refer to VM/XA SP Planning and
Administration .
"
.
Chapter 2. VM/XA SP CP Commands
99
DEFSEG
Responses
None.
Migration Notes
VMISPHPO
1. In HPO, this function is performed at system generation time by the NAMESYS
entries in DMKSNT.
2. VM/XA SP allows this function to be done dynamically, at any time during
system operation, so that an existing saved segment can be changed without
regenerating the system.
VMIXA SF
1. The VM/XA SP DEFSEG syntax (without the SPACE operand) defines a DCSS
that has no members. This DCSS contains the definition of the saved segment.
When this is loaded (via DIAGNOSE XI 64 I), the range information is as
follows:
• The beginning address is equal to the lowest page value specified on the
DEFSEG command.
• The ending address is rounded up to the last address of the last page in the
megabyte related to the highest page specified on the DEFSEG command.
2. If the same definition was specified with a DEFSEG command using the SPACE
operand, then loaded (via DIAGNOSE X 164 1), the range information is as
follows:
• The beginning address is equal to the lowest page value specified on the
DEFSEG command.
• The ending address equal to the highest page value specified on the
DEFSEG command.
3. VM/XA SP supports a CP writable DCSS. This DCSS has restrictions against
multiple copies. Saved segments not defined with an SC page range are
unaffected, except that you can't define both a CP and non-CP DCSS with the
same name.
4. VM/XA SP keeps saved segments over a cold start.
,
100
VM/XA SP2 CP Command Reference
DEFSYS
DEFSYS
Privilege Class: E
Use the DEFSYS command to define a skeleton (class S) system data file (SDF) for
the named saved system (NSS). The skeleton file consists only of a descriptor page,
containing all the information necessary for saving the NSS when using the
SAVESYS command. Users cannot access the NSS until it has been saved.
DEFSYS
name {{hexpagel-hexpage2 type} •.• } MINSIZE={nnnnnK} [options]
nnnM
options:
[RSTD]
[PARMREGst~~~n
]
[VMGROUP]
where:
name
is the name of the NSS that is a 1- to 8-character alphanumeric string.
Be careful not to specify a name that could be a hexadecimal device number
because the device, if one exists, would be IPLed instead of the named saved
system.
hexpagel-hexpage2
is a range of pages to be saved. When "hexpagel" and "hexpage2" are the
same, only that page is saved. The range may be contained in a single 1Mb
segment, or it may comprise a contiguous area in two or more segments. You
may use multiple page ranges to define a 1Mb segment. However, the page
descriptor codes of all page ranges in the same segment must have the same
shared or exclusive attribute. (See the type parameter for information about
page descriptor codes.)
Define only those pages whose data must be saved. Any page or pages in a
segment not explicitly defined in a page range on the DEFSYS command
defaults to the "no data saved" attribute. If other pages in the segment were
defined with the shared attribute (page descriptor codes SR, SW, SN and SC),
pages not specified on the command line become shared read-only pages whose
data is not saved. No page descriptor codes correspond to this state; it has the
same attributes as the state defined by page descriptor code SC, except that CP
does not write into these pages.
If other pages in the segment were defined with the exclusive attribute (page
descriptor codes ER, EW and EN), any pages not specified on the command line
become exclusive read/write pages whose data is not saved. This corresponds to
page descriptor code EN.
The page number is a hexadecimal value less than or equal to X I 3E6FF I (999
Mb). The following list shows examples of how storage addresses translate into
page numbers:
Chapter 2. VM/XA SP CP Commands
101
DEFSYS
Hexadecimal
Storage Address
Hexadecimal
Page Number
o
00000xxx
00001xxx
00022xxx
00333xxx
04444xxx
3E6FFxxx
1
22
333
4444
3E6FF
type
refers to the 2-character page descriptor code of the page range in the NSS. It
indicates the type of virtual machine access permitted to pages in the range.
The first character is either "E" for exclusive access or "S" for shared access.
Sharing of storage between virtual machines is based on one-megabyte segments,
so all 256 pages in anyone segment must be either exclusive or shared.
The second character of the page descriptor code defines the storage protection
characteristics of the page. These character designators are as follows:
"R" indicates that page protection is used to make the page range read-only.
"W" means that the page is not protected, and users have read/write access.
"N" stands for "read/write, no data saved," meaning that the page is treated as
a new page when the user references it. The contents of and storage keys for
"no data saved" pages are not saved by the SAVESYS command.
"C" stands for "CP-writeable, virtual machine read-only, no data saved,"
meaning virtual machines have read-only access to these pages, but CP services
may change the data in the pages.
The contents of and storage keys for "no data saved" pages are not saved by the
SAVESYS command.
Valid page descriptor codes are:
EW
EN
ER
SW
SN
SR
SC
--------
exclusive read/write access
exclusive read/write access, no data saved
exclusive read-only access
shared read/write access
shared read/write access, no data saved
shared read-only access
CP writeable pages, shared read-only access
by virtual machine, no data saved
Any page ranges defined in segment zero must have an exclusive page descriptor
code (EW, ER, or EN). If any pages in segment zero are defined with a shared
access page descriptor code, the command is rejected.
MINSIZE =
oooonK }
oooM
indicates the minimum storage size of the virtual machine into which the NSS
can be loaded.
{
nnnnnK is the storage size in decimal kilobytes
nnnM
102
VMjXA SP2 CP Command Reference
is the storage size in decimal megabytes
DEFSYS
For example, MINSIZE = 256K.
RSTD
indicates a restricted NSS. The user must have a corresponding NAMESAVE
directory statement to access this NSS.
PARMREGS
= { m(-n)
}
NONE
specifies a range of general purpose registers to contain the IPL parameter string
when the NSS receives control from CP.
m and n are decimal values from 0 to 15. If you specify two registers, n must be
greater than or equal to m. If only one register is required, you may specify
"PARMREGS = m".
NONE specifies that no parameters may be passed to this NSS.
VMGROUP
indicates that a user who IPLs this NSS becomes a member of a virtual machine
group, identified by the name of the NSS.
Usage Notes
1. Page 0 should always be saved for an operating system. If not saved, certain
information (such as the interval timer value for Systemj370 guests) may be lost.
IBM recommends that page 0 be saved with the exclusive write (EW) page
descriptor code.
2. Segment 0 should always have the exclusive access attribute (EW, EN, or ER).
If a shared page descriptor code (SW, SN, SR, or SC) is used for any pages in
segment 0, the command is rejected.
3. Pages either defined as or defaulted to "no data saved" are initialized to a page
of zeros when first referenced. If the pages are in an exclusive segment, changes
are seen only by the one user. If the pages are in a shared segment, any changes
previously made by any sharing user are visible to all other users sharing that
same page.
4. A CP NSS (SC mode) contains CP-writeable pages, to which virtual machine
users have just read-only access. CP writes data into these pages, which may
then be referenced by virtual machines. Serialization of data in the CP-writeable
pages, if desired, must be arranged between the CP function providing the data
and the virtual machines referencing it.
5. The use of the PARMREGS values is described with the IPL command.
6. Named saved systems (NSS) are loaded using the IPL command. Saved
segments are loaded using DIAGNOSE X ' 64 1 , the CMS SEGMENT assembler
language macro, or the CMS SEGMENT command.
7. When the user references any pages either defined as or defaulted to "no data
saved," the user gets a new page. A new page is assigned as a full frame of
zeros just as any page that does not have a copy backed on auxiliary storage.
8. Storage keys are not saved for pages either defined as or defaulted to "no data
saved." When these pages are first referenced, they have keys of zero. The
virtual machine may set the keys for writable storage appropriately.
9. Each segment has an associated address range of 1Mb, regardless of the number
of pages specified.
Chapter 2. VM/XA SP CPCommands
103
DEFSYS
Security Notes
1. When RSTD is specified, only those users whose directory entries contain a
NAMBSAVB statement specifying this "name" are allowed to IPL the NSS.
This allows the installation to ensure data integrity by restricting access to NSSs
that contain shared writable storage (defined with the SWand SN page
descriptor codes), or to a CP NSS (defined with the "SC" page descriptor code),
which may contain sensitive data.
2. Virtual machines which share read/write pages, defined with the SW and SN
page descriptor codes, are responsible for the integrity of the shared data. The
operating system that uses these shared writable pages should ensure that these
virtual machines are properly protected from one another.
Example
DEFSYS CMS 0-4 EW E-21 EW 800-86F SR MINSIZE=256K PARMREGS=0-15
DEFSYS WSS 0-8 EW 300-5FF SW 600-FFF SN MINSIZE=4M RSTD
DEFSYS GCS 0-8 EW 300-5FF SW 600-FFF SN MINSIZE=4M RSTD VMGROUP
Responses
None.
Migration Notes
VMISP HPO: In VM/SP HPO, NSSs are defined at system generation time by the
NAMBSYS entries in DMKSNT. VM/XA SP allows this function to be done
dynamically at any time during system operation so that an existing NSS can be
changed without regenerating the system.
VMIXA SF: VM/XA SP has a CP writable NSS. This has restrictions against
multiple copies. NSSs not defined with an SC page range are unaffected, except that
you can't define both a CP and non-CP NSS with the same name.
104
VMjXA SP2 CP Command Reference
DETACH
DETACH
Use the DETACH command to:
• Remove real or logical devices from your virtual machine configuration or from
the CP system.
• Remove virtual devices, virtual processors, real Expanded Storage, or a virtual
Vector Facility from your virtual machine configuration.
The format box below shows all the operands available with the DETACH
command. Complete descriptions of the operands appear on the following pages, in
the same sequence as the operands appear here.
DETach
~~~:~~~~ cpuaddr •••
cpuaddrl-cpuaddrn
CPU
\
~~:~ ...
{
rdev-rdev
ldev
ldev .••
rdev ldev
ldev-ldev
1
I
ALL
1
[ FRom] { userid
SYSTEM
*
. ·1
[ FRom
1
G
B
l{ use:; d }
G
{Virtual} { vdev
}
vdev ••.
vdev-vdev
VECtor
Class
{nn
{nnl-nn2}} [{nn
nnl-nn2} ••.
JI
G
\ ALL
XSTore { [FRom] userid}
{ XSTorage
B
XSTore }
{ XSTorage
G
General Usage Notes for DETACH
You cannot be certain that the device or Expanded Storage capability has been
detached until you receive the appropriate response from the system. If after a
reasonable amount of time you haven't received the expected response, issue the
QUERY command to determine the status of the device. Detachment may be
pending or may have been unsuccessful. Note that if you issued the command from
the CMS environment and received a return code of 0, you cannot assume that the
device has been detached. A return code of 0 indicates only that your request has
been accepted.
Chapter 2. VMjXA SP CP Commands
105
DETACH
Migration Notes
VMISP HPO: The LEAVE and UNLOAD options are not supported by VM/XA
SP.
106
VM/XA SP2 CP Command Reference
DETACH CPU
DETACH CPU
Privilege Class: G
Use DETACH CPU to remove one or more virtual processors from your virtual
machine configuration.
DETach
1
CPU cpuaddr
cpuaddrl cpuaddr ...
cpuaddrl-cpuaddrn
ALL
l
where:
CPU cpuaddr
is the processor address of the processor that you want to detach from your
virtual machine configuration.
CPU cpuaddrl cpuaddr...
is a list of addresses and/or ranges delimited by spaces.
CPU cpuaddrl-cpuaddrn
specifies a nonwrapping pair of addresses separated by a hyphen ("-") and not
separated by any blanks.
CPU ALL
specifies all virtual processors currently defined.
Usage Notes
1. You can detach any virtual processor from your virtual machine configuration
except the base processor. You cannot detach the base processor from your
virtual machine system.
2. Whenever you detach a virtual processor, your virtual machine is reset as if a CP
SYSTEM CLEAR command had been executed. All virtual storage is cleared
to binary zeros. Therefore, you must repeat your IPL procedure to proceed.
3. When a virtual processor is detached, the associated virtual Vector Facility, if
any, is also detached.
4. The DETACH CPU command terminates all IUCV connections and releases the
IUCV buffer.
Responses
CPU nn DETACHED
indicates that the command has been successfully executed.
This response is followed by:
STORAGE CLEARED - SYSTEM RESET
indicating that all of your virtual machine's storage has been cleared to binary zeros
and your processor(s) and I/O configuration have been reset.
Chapter 2. VM/XA SP CP Commands
107
DETACH (real device)
DETACH (real device)
Privilege Class: B
Use DETACH (real device) to remove real local or remote devices from a user's
virtual machine or from the CP system. When detaching a remote device, specify its
logical device address.
DETach
rdev
} [FRom] {user; d}
rdev ..•
SYSTEM,
{
rdev-rdev
*
/~ ~:~ ... ...l
1
[FRom]
{use;; d}
ldev-ldev
rdev ldev
where:
rdev
rdev ..•
rdev-rdev
is a real device number, a list of real device numbers, or a range of real device
numbers to be detached from the indicated user or from the system. On a single
command line, you may combine device numbers, lists of device numbers, and
ranges of device numbers. Specify a real device number as four hexadecimal
digits.
ldev
ldev .•.
ldev-ldev
is a logical device number, a list of logical device numbers, or a range of logical
device numbers to be detached from the indicated user or from the system. On
a single command line, you may combine device numbers, lists of device
numbers, and ranges of device numbers. Specify a logical device number as an
"L" followed by four hexadecimal digits.
rdev ldev
specifies a list of logical and real device numbers.
[FROM) {USerid
SYSTEM
}
*
is the user identification of the virtual machine to which the device is currently
attached. The specified user must be logged on, not in the process of logging
on. If you are issuing the DETACH (real device) command to detach a device
from your own virtual machine, you may specify userid as an asterisk (*).
Specify SYSTEM to indicate that the device is a DASD device used by CP for
allocation and control.
Usage Notes
I. CP does not REWIND/UNLOAD a tape when the tape is detached.
2. When a device is detached, all data blocks associated with the device are
removed from the minidisk cache.
108
VM/XA SP2 CP Command Reference
DETACH (real device)
3. If you are detaching a multiple-exposure device, the device number that you
specify must be the base exposure. When you detach a dedicated
multiple-exposure device from a user, all exposures are processed.
4. If you specify multiple device numbers or a range of device numbers on the
DETACH (real device) command line, you will receive an affirmative response
for each device that is successfully detached and an error message for each
device that cannot be detached.
5. If you attempt to detach an active shared device from the system, you will
receive an error message indicating that the device is being "shared by multiple
users. In order to detach the device, each of the affected users must detach the
device from their virtual systems.
6. You cannot detach volumes in the SYSCPVOL list that are in use by the system,
or devices containing minidisks to which users are linked.
7. Tape devices are automatically rewound and unloaded when detached.
8. A previously attached device can be detached from a user even if the device is
still in use.
9. If a device was attached using the CP ATTACH command and later detached,
the system operator receives a message saying that the device is free.
10. The DETACH (real device) command does not execute synchronously when you
are detaching real devices from another userid. The user of this command may
receive control before all processing has been completed on behalf of the other
user. Any later attempt to use the device before it becomes detached may yield
unexpected results.
For example, suppose the following CMS command sequence exists in a CMS
EXEC procedure:
CP DETACH 250 USERA
CP ATTACH 250 SYSTEM
CP will begin to ATTACH device 250 to the system before the DETACH
command completes. Since the device is still attached to USERA, you will
receive an error message for the ATTACH command.
Thus, if you intend to issue commands using the same real device owned by
another user, do not string the commands together (using the logical line end
character) and do not issue the commands one right after the other in a CMS
EXEC.
Responses
The user who currently owns the device (if different from the primary system
operator), the user who issued the DETACH (real device) command (if different
from the owner of the device), and the primary system operator (if different from the
user who issued the command) each receive messages indicating that the DETACH
(real device) was successful.
Response 1
type vdev DETACHED BY originator
is the response sent to the device owner (if the device owner is p.ot the primary
system operator). Note that the response refers only to the virtual device number
(vdev) because this is the number by which the owner knows the device:
Chapter 2. VMjXA SP CP Commands
109
DETACH (real device)
Response 2
type '{.rdev} DETACHED {userid vdev}.
1dey
SYSTEM
is the response issued to the originator of the DETACH (real device) command if
the originator of the command is not the owner of the device.
Response 3
type {rdev} DETACHED {:userid vdev} BY originator
ldev
SYSTEM
is the response sent to the primary system operator if another user (the originator)
issued the DETACH (real device) command.
Response 4
DASD vdev vdev vdev vdev DETACHED BY originator
The user receives this response when a 3880 paging subsystem is detached by a class
B user. The virtual base address and virtual exposures of the detached device are
shown.
Response 5
DASD jrdev rdev rdev rdeV} DETACHED {userid}. vdev vdev vdev vdev
tldev ldev ldev ldev
SYSTEM
The originator receives this response when a 3880 paging subsystem is detached if
the originator is not the owner of the device. The virtual base and virtual exposures
of the detached device are shown.
Response 6
DASD {rdev rdev rdev rdev} DETACHED {uSerid}. vdev vdev vdev vdev BY originator
SYSTEM
ldev ldev ldev ldev
The primary system operator receives this response when a 3880 paging subsystem is
detached if another user issued the DETACH (real device) command. The virtual
base and virtual exposures of the detached device are shown.
In the these responses, the term "type" is one of the following:
110
Type
Meaning
DASD
TAPE
RDR
PRT
PUN
GRAF
CTCA
CTLR
MSC
DEV
Direct access storage device
Magnetic tape
Card reader
Printer
Card punch
Display device
Channel-to-channel adapter
3704 or 3705 Communications Controller
Mass Storage Controller
Any other device
VMjXA SP2 CP Command Reference
DETACH (real device)
Migration Notes
VMISP HPO
1. VMjXA SP supports neither the CHANNEL operand nor two options for tape
devices: UNLOAD and LEAVE.
2. In VMjXA SP, if a person issues a DETACH command on behalf of another
user, the detachment does not take place immediately (it is asynchronous). The
detachment occurs just prior to the other user being dispatched.
3. VMjXA SP provides a response for each detached device.
4. The VMjXA SP response includes the user's virtual device address.
5. VMjXA SP limits the range of devices detached to 256.
6. VMjXA SP accepts FR as the minimum truncation for FROM.
VMIXA SF: VMjXA SP uses GRAF rather than DISP in its response.
Chapter 2. VMjXA SP CP Commands
111
DETACH VIRTUAL (devices)
DETACH VIRTUAL (devices)
Privilege Class: G
Use DETACH virtual (devices) to remove virtual devices from your virtual machine
configuration.
DETach
[Vi rtua 1] {VdeV
vdev •••
vdev-vdev
}
where:
VIRTUAL
indicates you are detaching virtual devices
vdev
vdev •••
vdev-vdev
is a virtual device number, a list of virtual device numbers, or a range of virtual
device numbers to be detached from your virtual machine. On a single
command line, you may combine device numbers, lists of device numbers, and
ranges of device numbers. If you are detaching a list of virtual devices, insert at
least one blank between the device numbers you specify. If you are detaching a
range of devices, insert a hyphen (-) between the device numbers you specify.
The maximum number of devices allowed in a range is 256.
Usage Notes
I. You can detach a virtual device even if it is currently in use.
2. When you detach a virtual device, it becomes inaccessible to your virtual
machine. When you detach a real device, it is released and becomes available
for attaching to your virtual machine, another user, or the CP system.
3. Tape devices are automatically rewound and unloaded when detached.
4. If you detach a dedicated device, the system operator will receive a message
indicating that the device is free.
5. If you are detaching a dedicated multi-exposure device, specify the base exposure
as the virtual device number.
If you are detaching a multi-exposure device and have specified a range of
virtual device numbers, all of the exposures will be detached when the base
exposure is encountered. The range that you specified may not include all of the
exposures; this is not an error situation. All of the exposures will be detached.
The DETACH VIRTUAL command uses only the base exposure device number
when you specify multiple virtual device numbers on the command line. Any
device number other than the base exposure will be reported as an error.
6. Command processing does not terminate if an error (other than a syntax error)
is encountered when processing a range of device numbers or multiple device
numbers. Instead, an error message is issued for each device that cannot be
detached. Informational messages are issued to identify those devices that were
successfully detached. These informational messages may appear several times
in one command execution when you have specified on the command line a
range of device numbers or multiple device numbers.
112
VM/XA SP2 CP Command Reference
DETACH VIRTUAL (devices)
Response 1
type vdev DETACHED
is the response you receive for each device that was successfully detached (if you are
not the primary system operator).
Response 2
type rdev DETACHED userid vdev
is the response sent to the system operator each time a real device is detached from
the specified user. rdev is the real device number associated with the device.
Response 3
CTCA vdev DROPPED FROM userid vdev
is the response if the device detached was a virtual CTCA connected using the
COUPLE command.
where:
CTCA vdev
is the virtual device number of the CTCA that you detached.
userid vdev
is the user identification and virtual device number of the CTCA that your
CTCA had been coupled to.
This response is always followed by the response:
CTCA vdev DETACHED
to indicate that the command has been successfully executed. The response:
CTCA vdev DROPPED BY userid vdev
is sent to the user whose CTCA connection was dropped.
Response 4
vdev pagedevl pagedev2 pagedev3 DETACHED
is the response the user receives when a 3350 DASD attached to a 3380 model 11 or
21 storage control unit is detached after the user has initiated the detach operation.
where:
vdev
is the base virtual device number of the multiple-exposure device that was
detached.
pagedevl
pagedev2
pagedev3
are the virtual paging device numbers of the multiple-exposure device that was
detached.
Chapter 2. VM/XA SP CP Commands
113
DETACH VIRTUAL (devices)
Response 5
vdev pagedevl pagedev2 pagedev3 DETACHED BY OPERATOR
is the response the user receives when a 3350 DASD attached to a 3380 model 11 or
21 storage control unit is detached by the operator.
where:
vdev
is the base virtual device number of the multiple-exposure device that was
detached.
pagedevl
pagedev2
pagedev3
are the virtual paging device numbers of the multiple-exposure device that was
detached.
operator
is the userid of the operator who detached your virtual device.
Response 6
DASD {rdev rdev rdev rdev} DETACHED {userid} rdev rdev rdev rdev
1dev 1dev 1dev 1dev
SYSTEM,.
The primary system operator receives this response when a real 3880 paging
subsystem is detached from a specified user. The virtual base address and virtual
exposures of the detached device are shown.
In the above responses, 'type' is one of the following:
Type
Meaning
DASD
TAPE
RDR
PRT
PUN
Direct access storage device
Magnetic tape'
Card reader
Printer
Card punch
Display device
Console
Channel-to-channel adapter
3704 or 3705 Communications Controller
Mass Storage Controller
Any other device
GRAF
CONS
CTCA
CTLR
MSC
DEV
Migration Notes
VMISP HPO:
1. VM/XA SP returns a response line for each detached device.
2. The VM/XA SP response from detaching a virtual CTCA device uses CTCA, or
DROPPED instead of CTC, or DROP as in VM/SP HPO.
3. VM/XA SP allows DETACH during I/O tracing.
4. The VM/XA SP response has five digits for the number of users.
114
VM/XA SP2 CP Command Reference
DETACH VIRTUAL (devices)
VMIXA SF
1. VM/XA SP uses GRAF rather than DISP in its response.
2. The VM/XA SP response from detaching a 3880 paging subsystem will not
contain the letters D-A-S-D, as will the response in VM/XA SF.
Chapter 2. VMjXA SP CP Commands
115
DETACH VECTOR
DETACH VECTOR
Privilege Class: G
Use the DETACH VECTOR command to remove a virtual Vector Facility from a
virtual configuration.
DETach
VECtor
l{
1
nn
} rJnn
} "."" ]
nnl-nn2 It.nnl-nn2
.
ALL
where:
VECTOR
detaches the virtual Vector Facilities from the virtual processors with the
addresses specified.
nn
is a single virtual processor address in hexadecimal.
nnl-nn2
is a nonwrapping pair of addresses in hexadecimal separated by a hyphen and
not separated by any blanks.
ALL
specifies all virtual vector facilities currently defined.
Usage Notes
1. The virtual Vector Facility is also removed if its associated virtual processor is
detached.
2. When a virtual VF is detached from a dedicated virtual processor of the
preferred 01 = R) guest and automatic dedication is set on, VM/XA SP attempts
to reassign that virtual processor to a real processor without a real VF. If this
attempt fails (because there is no nondedicated real processor without VF), then
the virtual processor remains dedicated to a processor with VF, and that real VF
becomes idle. It cannot be shared by other users until the processor has been
undedicated.
3. If the virtual CPU belongs to the V = R guest who has the automatic dedication
option turned off, or the virtual CPU belongs to a V = V or V = F user, the real
processor is not undedicated by the DETACH VECTOR command.
Examples
To detach the virtual VF from CPU 1, enter:
DETACH VECTOR 1
To detach the virtual VFs from CPUs 0, 2, and 3, enter:
DETACH VECTOR
116
e 2-3
VM/XA SP2 CP Command Reference
DETACH VECTOR
Responses
VECTOR FACILITY
nn
DETACHED
where:
nn
is the virtual processor address from which the virtual VF has been detached.
Chapter 2. VMjXA SP CP Commands
117
DETACH XSTORE
DETACH XSTORE
Privilege Class: B, G
Use DETACH XSTORE to remove a real Expanded Storage partition from a user's
virtual machine.
Class
DETach
{XSTore } {[FRom]
userid}
B
XSTorage
{XSTore }
G
XSTorage
where:
XSTORE
XSTORAGE
indicates that you are detaching Expanded Storage.
FROM userid
is the user identification of the virtual machine to which Expanded Storage is
currently attached. The specified user must be logged on, not in the process of
logging on. SYSTEM is not a valid userid.
Usage Notes
1. The detached virtual machine partition becomes immediately available for CP
usage.
2. Expanded Storage can be detached from a user even if it is still in use.
However, unexpected results can occur.
3. Whenever the Expanded Storage is detached, the system operator receives a
message indicating that the storage is available.
4. The DETACH XSTORE command does not execute synchronously when you
are detaching Expanded Storage from another userid. The issuer of this
command may regain control before all processing has been completed for the
other user.
For example, suppose the following CMS command sequence exists in a CMS
exec procedure:
CP DETACH XSTORE USERA
CP ATTACH XSTORE USERB
CP may begin to attach Expanded Storage to USERB before the DETACH
command completes. Since Expanded Storage is still attached to USERA, a
delay occurs until the detachment is complete.
5. If a class B user issues DETACH XSTORE with no operands, then the
command is in the class G format. Therefore, the command detaches any
Expanded Storage from the user issuing the command.
6. If a RETAIN XSTORE command was issued but left pending RETAIN, the
Expanded Storage detached will be used in an attempt to satisfy the amount
remaining from the RETAIN request.
118
VMjXA SP2 CP Command Reference
DETACH XSTORE
Responses
Receiving messages indicating that the DETACH XSTORE was successful are: the
user who currently owns the Expanded Storage partition, the user who issued the
DETACH XSTORE command (if different from the owner of the Expanded Storage
partition), and the primary system operator (if different from the user who issued the
command).
Response 1
XSTORE DETACHED BY originator
is the response sent to the owner of the Expanded Storage partition.
Response 2
XSTORE DETACHED FROM userid
is the response issued to the originator of the DETACH XSTORE command if the
originator is not the owner of the Expanded Storage partition.
Response 3
XSTORE DETACHED FROM userid BY originator
is the response sent to the primary system operator if another user (the originator)
issued the DETACH XSTORE command.
Chapter 2. VM/XA SP CP Commands
119
DIAL
DIAL
Privilege Class: Any
Use the DIAL command to connect a display logically for use by a multiple-access
operating system running in a virtual machine.
I
Dial
userid
[vdev]
where:
userid
is the identification of the virtual machine in which the multiple-access operating
system is running. SYSTEM and * are not valid userids for this command.
vdev
is the device number of the local virtual display to which the connection is to be
made.
Usage Notes
1. VMjXA SP accepts a DIAL command only at logon, and only as a substitute
for a LOGON command. The display you use must be supported by both
VMjXA SP and the multiple-access operating system.
2. Once the connection is made, your display operates entirely under the control of
the multiple-access operating system. The DIAL command matches your
display to an equivalent type defined in the multiple-access system. If no
matching display type exists, the connection cannot be made and an error
message is issued.
3. The operator of a virtual system can return the display to CP control by issuing
the CP RESET command. A virtual system user can return the display by
causing an unsolicited device end to be generated for the dialed display. To
generate an unsolicited device end, you can use the TESTjNORMAL or
POWER OFF jPOWER ON functions.
4. A SNAjCCS terminal user cannot dial into the VTAM service machine
controlling the terminal.
5. The write-for-position operation is not supported for SNAjCCS terminals that
are controlled by a level of VTAM service machine that is prior to ACF jVTAM
Version 3, Release 1.1, for VMjSP (VMjVTAM). For this operation, a write
CCW is chained to a read CCW; the write operation sets the 3270 buffer address
from which the read operation is to begin. If a user attempts a
write-for-position operation that is not supported by the controlling VTAM
service machine, then the virtual machine receives an operation exception on the
read operation.
6. The DIAL command is not supported for SNAjCCS terminals controlled by a
VCNA level ofVTAM service machine. ACFjVTAM Version 3 for VMjSP
(VMjVTAM) VSMs and later support the DIAL command for SNAjCCS
terminals.
120
VM/XA SP2 CP Command Reference
DIAL
Response 1
DIALED TO userid vdev
is the response sent to the user indicating that a logical connection has been made.
where:
userid
is the user identification of the virtual machine in which the multiple-access
operating system that you want to use is running.
vdev
is the virtual device number of the display to which the dialed connection has
been made.
Response 2
type
{
{~~:~}} DIALED TO userid DIALED
=
nnnnn
luname
is the response sent to the primary system operator. It indicates a successful
connection to the virtual machine (userid) and the total number of VM/XA SP
displays (nnnnn) currently connected to other virtual machines.
type
is the user's display device type.
rdev
Idev
is the real or logical device number of your console.
luname
identifies a SNA/CCS terminal controlled by a VT AM service machine. It is the
name from the VTAM definition of the terminal as an SNA logical unit.
Response 3
DROP FROM userid vdev
is the message sent to the user when the display is reset.
Response 4
type
{
{~~:~}} DROP FROM userid DIALED
=
nnnnn
luname
is the message sent to the primary system operator when the display is reset.
Migration Notes
VM/SP HPO: The VM/XA SP response has five digits for the number of users.
VMIXA SF: The VM/XA SP responses are different and type rdev is omitted from
the beginning of the responses.
Chapter 2. VMjXA SP CP Commands
121
DISABLE
DISABLE
Privilege Class: A, B, F
Use the DISABLE command to prevent display stations and SNA/CCS terminals
from accessing the VM/XA SP system.
DISAble
rdev
rdev
rdev-rdev
ldev
ldev
ldev-ldev
rdev ldev
SNA [useri d]
ALL
where:
rdev
rdev.o.
rdev-rdev ...
is a real device number, a list of real device numbers, or a range of real device
numbers of display stations that you want to disable. Specify each real device
number as one to four hexadecimal digits. If you specify more than one device
number, each must be separated from the others by at least one blank.
ldev
ldev ...
ldev-Idev ...
is a logical device number, a list of logical device numbers, or a range of logical
device numbers of 328x display printers that you want to disable. Only 328x
display printers are valid for this operand. Specify a logical device number as an
"L" followed by four hexadecimal digits. If you specify more than one device
number, each must be separated from the others by at least one blank.
rdev ldev ...
is a list of real and logical device numbers of display stations that you want to
disable. Each must be separated from the others by at least one blank.
SNA userid
disables communication with the SNA/CCS terminals owned by the VT AM
service machine whose userid is specified. If no userid is specified,
communication with all SNA/CCS terminals for all VTAM service machines is
disabled.
ALL
disables all real 3270 displays, including the operator's display, all real 328X
printers, and all SNA/CCS terminals.
Note: The logical 328X printers are not disabled.
122
VM/XA SP2 CP Command Reference
DISABLE
Usage Notes
1. On a single command line you may combine device numbers, lists of device
numbers, and ranges of device numbers. The beginning and ending device
numbers of a range must either be both real display device numbers or logical
display printer numbers.
2. If the displays you specify on the DISABLE command are not active, they are
disabled immediately. If the displays are active, they are disabled when the user
issues a CP LOGOFF or CP DISCONNECT command. A display is active if a
user is logged on to it, or if a user is dialed from it.
3. If you issue a CP ENABLE command to a display before it is physically
disabled, you reinstate the display's enabled status and negate previously issued
DISABLE commands directed to the display.
Responses
COMMAND COMPLETE
indicates the successful execution of the command.
Migration Notes
VMISP HPO: If VMjXA SP encounters an invalid device number in a list, it issues
an error message and continues processing the rest of the devices.
Chapter 2. VM/XA SP CP Commands
123
DISCONNECT
DISCONNECT
Privilege Class: Any
Use the DISCONNECT command to disconnect your display station from the
VM/XA SP system without stopping operations in your virtual machine.
I
DISConnect
[HOLD]
where:
HOLD
causes the TTY display terminal telecommunication connection to the 7171
ASCII DACU to remain after your session is disconnected.
Usage Notes
1. Once you have issued the DISCONNECT command, you remain disconnected
until you issue the CP LOGON command. If your virtual machine goes into a
disabled wait state or if a read is posted from the virtual machine or CP, and no
stacked console input exists (that is, physical interaction from the console is
necessary), you have 15 minutes in which to log on or your virtual machine is
automatically logged off. This is an important consideration if you are using an
operating system that issues frequent "reads" to your console.
2. If your connection is broken because of console errors, CP places your virtual
machine in disconnect mode for up to 15 minutes. Your virtual machine will
not continue to run unless you have previously issued CP SET RUN ON. You
can log on within the IS-minute interval if you want to continue operations on
your virtual machine; if you do not log on or your secondary user does not log
on within the 15 minute interval your virtual machine is automatically logged
off. .
3. If you do not have a functional secondary user and your virtual machine is in
disconnect mode, all "writes" or output messages sent to your virtual console are
ignored unless you have issued the CP command SPOOL CONSOLE START.
If you have a secondary user who is logged on and not disconnected, that user
receives your messages and can enter commands and responses for you.
4. When your virtual machine is reconnected using the normal logon procedure, it
is placed in CP console function mode. To resume execution on your virtual
machine, enter the CP BEGIN command.
5. If you specify the HOLD option on a SNA/CCS terminal, the command is
invalid and an error message is issued. If you specify the HOLD option on a
TTY display terminal connected to a 7171 ASCII DACU, it is accepted and
processed. The HOLD option is accepted but ignored on all other terminals.
6. If your installation has coded the E3270HLD feature in the system real I/O
configuration file for your TTY display terminal, the telecommunication
connection will always remain, regardless of the HOLD option.
124
VM/XA SP2 CP Command Reference
DISCONNECT
Response 1
DISCONNECT AT hh:mm:ss zone weekday mm/dd/yy
is the response to the user who issued the command.
where:
hh:mm:ss
is the current time
zone
is the time zone
weekday
is the current day of the week
mm/dd/yy
is the current date in monthjday-of-monthjyear format.
Response 2
~type {~~:~}}DISCONNECT userid USERS = nnnnn
tluname
is the response sent to the primary system operator
where:
type
is the user's display type.
rdev
ldev
is the real or logical device number associated with the display.
luname
identifies a SNAjCCS terminal controlled by a VTAM service machine. It is the
name from the VTAM definition of the terminal as an SNA logical unit.
userid
is the identification of the user who has disconnected from the system.
USERS = nnnnn
is the total number of users remaining on the system.
Migration Notes
VMISP HPO: VMjXA SP allows you to spell out the entire command
DISCONNECT.
Chapter 2. VMjXA SP CP Commands
125
DISPLAY
DISPLAY
Use the DISPLAY command described in this section to display the following real
and virtual machine components:
• Contents of first-level storage (the real storage of the 370-XA processor
environment)
• Contents of second-level storage (the storage that appears real to the operating
system running in your virtual machine)
• Contents of third-level storage (the storage that appears virtual to the operating
system running in your virtual machine)
• Old and new PSWs and interrupt information for the following interrupts:
SVC
I/O
PROGRAM
EXTERNAL
MACHINE CHECK
• Storage keys
• Contents of registers:
Prefix
General
Floating-point
Control
• Subchannel information blocks (SCHIBS)
• The current program status word (CURRENT PSW)
• The contents of registers, activity count, and section size for the Vector Facility:
Vector registers (VR)
Vector register pair(s) (VP)
Vector status register (VSR)
Vector mask register (VMR)
Vector activity count (VAC)
Vector section size (VSS).
Complete Format for DISPLAY
The format box below shows all of the operands available with the DISPLAY
command. Complete descriptions of the operands appear on the following pages, in
the same sequence as the operands appear here.
126.
VM/XA SP2 CP Command Reference
DISPLAY
Display
]
[~l ~ l[hex~ocIJ [t}~.~~10C2 l
.
~
"
J
-
w
Class
G
J
{ . } f"bytecountJ
I
N
LEND
U
... -
hexloc2
,. ~-1 [heX~Oc1J ~{'}r;rbytecount ]J]l
H T
- '
I
{ .}
.N
C/E
!
LEND
U
-PREFIX
G
,..;
...,
Psw EXT
SVC
PROG
PRG
MCH
I/O
ALL
-
G
...
G
[vschl] [n~~~h2 J]
<
{ • } rcount J Il
G
SCHib \
~
I
LEND
I'
---
)
ALL
J]]
[,eltl [t} [E~~t2 J]]
{.} [regcountJ
{.} reltcountJ
~~:~ [regl[n[~~62
END:
G
LEND:
VSR
VMR
VAC
VSS
Chapter 2. VMjXA SP CP Commands
127
DISPLAY
General Usage Notes for DISPLAY
1. Using a single command, you can display the contents of multiple storage
locations, registers, and control words.
There are two rules that you must follow in order for the command to execute
properly:
a. Do not put blanks between operands that relate to a single DISPLAY
request, except for PSW and SCHIB which require at least one blank
between the first and second operands.
For example, if you want to display first-level storage location 40, enter:
display
h40
b. Separate each set of display requests from others by at least one blank.
For example, if you want to display first-level storage location 40 and the
contents of register 5, enter:
display h40 95
2. The defaults for the following DISPLAY operands are:
COl1llland
Operand
G
GG-5
G5G5
T
TT-1000
T1000T1000
PSW
Default
Before Rounding
0-end
0-end
0-G5
G5-end
G5
error
T0-end
T0-1000
T1000-end
T1000
current
When displaying a range of addresses or subchannels, the command operand
must be followed by an address, a range, or a punctuation mark (' - " ':', '.'),
which will form a range. When displaying registers, the command operand can
stand alone.
3. If you enter a command line that contains an invalid operand, the DISPLAY
command will terminate when it encounters that operand. Any previous valid
operands are processed before termination occurs.
4. The DISPLAY command allows you to display information in the following
formats:
•
•
•
•
•
128
Hexadecimal string/Hexadecimal word segments
EBCDIC translation for uppercase letters and numbers 0-9
Hexadecimal word segments with EBCDIC translation
Instruction
Storage key
VMjXA SP2 CP Command Reference
DISPLAY
Note: Hexadecimal to EBCDIC translation is done for the numerals 0 - 9 and
uppercase letters A - Z only. If you enter mUltiple operands on a single
command line to display storage or a register and do not specify the
format that you want the DISPLAY command processor to use, the last
format type that you explicitly entered on the command line will define
the type of display that you receive. That is, whenever you explicitly
enter a display type, you implicitly define the default for subsequent
operands of the current display function. If you do not enter any display
format type on the command line, the system defaults will be employed.
F or example, the command:
display 10 20 T40 80 G12 5 L60-100
displays the following, respectively:
hexadecimal location 10 without EBCDIC translation
hexadecimal location 20 without EBCDIC translation
hexadecimal location 40 with EBCDIC translation
hexadecimal location 80 with EBCDIC translation
general register 12
general register 5
hexadecimal locations 60 through 100 with EBCDIC translation
5. If you want to terminate the DISPLAY function while data is being displayed,
press the PAl key. When the display terminates, you can enter another
command.
6. Use the DISPLAY command to display the contents of various storage
locations, registers, and control words. You can examine this information
during program execution, and may be able to determine the cause of program
errors.
To do this, you would typically define a TRACE trap, using the CP TRACE
command, that will stop program execution at a specified point. Once program
execution suspends, your virtual machine will enter the CP environment, and
you can then issue the DISPLAY command. Alternatively, you can execute the
DISPLAY command directly from TRACE using the TRACE command CMD
option. For more information, see the description of the CP TRACE command.
7. If the DISPLAY command processor is suppressing identical lines, it issues a
response every time a segment boundary is crossed rather than waiting for a
nonidentical line. This provides you with an opportunity to terminate
DISPLAY processing by pressing the PAl key.
Migration Notes
VMISP HPO: In VM/XA SP, you can store into the CAW or CSW but you cannot
display their contents.
Chapter 2. VMjXA SP CP Commands
129
DISPLAY GUEST STORAGE
DISPLAY GUEST STORAGE
Privilege Class: G
Use DISPLAY GUEST STORAGE to display the contents of storage at specified
locations in your virtual machine.
Display
[t]
r""rK
s
I
eex~oc~ [t}[~~~10C2
jl
J]l
{ •} ~ytecount] .
N ,END
'
U
-- 'Note: Do not put blanks between operands that relate to a single DISPLAY
request, except for PSW and SCHIB which require at least one blank between
the first and second operands. For more information, see "General Usage
Notes for DISPLAY" on page 128.
where:
R
displays the contents of second-level storage (storage that appears real to your
virtual machine).
L
displays the contents of second-level storage (storage that appears real to your
virtual machine) if the guest virtual machine is operating in DAT OFF mode;
displays the contents of third-level storage (storage that appears virtual to your
virtual machine) if the guest virtual machine is operating in DAT ON mode.
v
displays the contents of third-level storage (storage that appears virtual to your
virtual machine) using control register 1.
w
displays the contents of third-level storage (storage that appears virtual to your
virtual machine) using control register 7.
T
displays the contents of storage in hexadecimal with EBCDIC translation.
Storage is displayed in word segments. An address range will be displayed
starting at the X 110 I boundary in which the specified address resides. Storage is
displayed in X I 10 1 increments.
The storage key is displayed on the first line, as well as at every page boundary.
K
displays the storage keys in hexadecimal for all page frames or partial page
frames included in the specified address range.
s
displays the contents of storage in hexadecimal· translation. Storage is displayed
as a string starting at the location specified. The specified address range is not
boundary aligned.
The storage key is displayed on the first line, as well as at every page boundary.
130
VMjXA SP2 CP Command Reference
DISPLAY GUEST STORAGE
I
displays the contents of storage in instruction format. The specified address is
rounded down to the nearest half word boundary.
The storage key is displayed on the first line, as well as at every page boundary.
N
displays the contents of storage in hexadecimal without EBCDIC translation.
This is the default. Storage is displayed in word segments. An address range
will be displayed starting at the full word in which the specified address resides.
Storage is displayed in full word increments.
The storage key is displayed on the first line, as well as at every page boundary.
u
displays the contents of storage in EBCDIC translation. Storage is displayed as
an EBCDIC string starting at the address specified. The specified address range
is not boundary aligned.
The storage key is displayed on the first line, as well as at every page boundary.
If you do not specify any of the options T, K, S, I, N, or U, the contents on
storage are displayed in hexadecimal word segments.
hexlocl
is the starting storage location that is to be displayed. The address hexlocl may
be one-to-eight hexadecimal digits; leading zeros are optional. The default is
zero.
Storage locations and the minimum amount displayed are rounded according to
the following conventions:
Rounding Conventions (in hex)
Storage
Locations
T
K
S
Start
Minimum
Length
10
10
7FF
7FF
1
I
2
N
U
4
1
1
2-6 (depending on instruction)
4
1
.-} .hexloc2
{ : END
is the last of a range of hexadecimal storage locations whose contents are to be
displayed. If specified, hexloc2 must be equal to or greater than hexlocl and
must be within the virtual machine storage size. The address, hexloc2, may be
from one-to-eight hexadecimal digits; leading zeros are optional. The symbol ":"
means the same as a "-" when you specify a range of addresses.
Specify END if you want to display the remaining contents of storage. END is
the default. and you specify "-", ":", or ".".
{.} bytecount
END
is a hexadecimal integer designating the number of bytes of storage (starting
with the byte at hexlocl) to be displayed.
The bytecount that you specify must have a value of at least one and may be
from one to eight hexadecimal digits. Leading zeros are optional.
Chapter 2. VMjXA SP CP Commands
131
DISPLAY GUEST STORAGE
Specify END if you want to display the remaining contents of storage. END is
the default if you specify: "-", ":", or ".".
Usage Notes
When running with a saved segment, you can display storage locations outside the
range of your virtual machine size if they are within the saved segment. If locations
exist between the upper limit of your virtual machine and the address at which the
saved segment was saved, any attempt to display those locations (or associated keys)
results in the' "nonaddressable storage" response being displayed.
Refer to "General Usage Notes for DISPLAY" on page 128.
Responses
One or more of the following responses is displayed, depending upon the operands
you specified:
Response 1
Xhexloc wordl word2 word3 word4 [Key] [*EBCDIC TRANSLATION*] [Lhexloc]
This is the response you receive if your display request was L, R, V, or W, with the
T or N option. X indicates the type of display request (L, R, V, or W). The
EBCDIC translation is given only for the T option. The storage key is displayed on
the first line of a request, and at every page boundary.
For a Vhexloc or Whexloc request, the Lhexloc trailer shows the second-level
address that corresponds to the given third-level address. The Lhexloc trailer is
shown also when DAT-ON mode causes Lhexloc to resolve to a third-level address.
The storage key is displayed on the first line of a request, and at every page
boundary.
Response 2
Xhexloc *EBCDIC TRANSLATION* [key] [Lhexloc]
This is the response you receive when your display request is L, R, V, or W, with the
U option. Xhexloc is the hexadecimal location of the first data byte to be displayed
and X can be L, R, V, or W, depending on your display request. A minimum of 1
character and a maximum of 32 characters will be displayed on each line. The
contents of storage are displayed only in an EBCDIC translation. Periods in your
display represent nonprintable characters. The storage key is displayed on the first
line of a request and at every page boundary.
For a Vhexloc or Whexloc request, the Lhexloc trailer shows the second-level
address that corresponds to the given third-level address. The Lhexloc trailer is
shown also when DAT-ON mode causes Lhexloc to resolve to a third-level address.
The storage key is displayed on the first line of a request, and at every page
boundary.
Response 3
Xhexloc mnemonic X-X mnemonic X-X mnemonic X-X [key] [Lhexloc]
This is the response you receive when your display request is L, R, V, or W, with the
I option. Xhexloc is the hexadecimal storage location of the first instruction to be
displayed and X can be L, R, V, or W, depending on the request. Mnemonic is up
to a five character representation of the instruction code. x-X is the actual
132
VM/XA SP2 CP Command Reference
DISPLAY GUEST STORAGE
hexadecimal contents of storage and is either two, four, or six bytes as determined
by the instruction length code. Unrecognizable instruction codes will be indicated by
a series of asterisks. A minimum of one instruction and a maximum of three
instructions will be displayed on each line. The storage key is displayed on the first
line of a request and at every page boundary.
For a Vhexloc or Whexloc request, the Lhexloc trailer shows the second-level
address that corresponds to the given third-level address. The Lhexloc trailer is
shown also when DAT-ON mode causes Lhexloc to resolve to a third-level address.
The storage key is displayed on the first line of a request, and at every page
boundary.
Response 4
Xhexloc stringhexadecimaldata [key][Lhexloc]
This is the response you receive if your display request was L, R, V, or W with the S
option. X indicates the type of display request (L, R, V, or W). The storage key is
displayed on the first line of a request, and at every page boundary:
For a Vhexloc or Whexloc request, the Lhexloc trailer shows the second-level
address that corresponds to the given third-level address. The Lhexloc trailer is
shown also when DAT-ON mode causes Lhexloc to resolve to a third-level address.
The storage key is displayed on the first line of a request, and at every page
boundary.
Response 5
Xhexlocl TO hexloc2 KEY
=
kk
This is the response when your display request is L, R, V, or W, with the K option.
hexlocl and hexloc2 are storage locations, and kk is the associated storage key. The
X in Xhexloc can be L, R, V, or W, depending upon the display request. A response
will be sent for every contiguous address range that has unique storage keys and
whenever a segment boundary is crossed.
Response 6
If your display request includes a request to display nonaddressable storage, you
receive the following response:
Xhexlocl TO hexloc2 NON-ADDRESSABLE STORAGE
hexlocl and hexloc2 are storage locations. The X in Xhexlocl can be L, R, V, or
W, depending on the request.
Response 7
If your display request includes a request to display one or more lines identical to
the previous line, you receive the following response:
Xhexlocl TO hexloc2 SUPPRESSED LINE(S) SAME AS ABOVE .••
hexloc 1 and hexloc2 are storage locations. The X in Xhexloc1 can be L, R, V, or
W, depending on the request.
Chapter 2. VMjXA SP CP Commands
133
DISPLAY GUEST STORAGE
Migration Notes
VMISP HPO
I. In VMjXA SP you can display larger storage sizes than in VMjSP HPO.
2. In VMjXA SP you can display more levels of storage than in VMjSP HPO.
VMIXA SF
I. In VMjXA SP, the response SUPPRESSED LINE(S) SAME AS ABOVE
appears whether or not the amount of storage to be displayed exceeds XIIOOI
bytes.
2. VMjXA SP displays storage keys at the first line of a request and at every page
boundary. It shows storage keys even if you request only one address.
3. In VMjXA SP, the default option is N.
4. In VMjXA SP, the N option rounds storage locations to fullword boundaries,
and displays storage in fullword increments.
134
VM/XA SP2 CP Command Reference
DISPLAY HOST STORAGE
DISPLAY HOST STORAGE
Privilege Class: C and E
Use DISPLAY HOST STORAGE to display the contents of first-level storage .
Display
H .... TK
S
I
N
l[hex~ J:{-}
oel
[heX1oc2
END
{ .} [bytecount
END
Jl
J
... UNote:
Except for DISPLAY PSW and DISPLAY SCHIB, do not put blanks
between operands that relate to a single DISPLAY request. DISPLAY PSW
and DISPLAY SCHIB require at least one blank between the first and
second operands. For more information, see "General Usage Notes for
DISPLAY" on page 128.
where:
H
displays the contents of first-level storage (storage that appears real to CP).
T
displays the contents of storage in hexadecimal with EBCDIC translation.
Storage is displayed in word segments. An address range will be displayed
starting at the X I 10 1 boundary in which the specified address resides. Storage is
displayed in X I 10 1 increments.
The storage key is displayed on the first line, and at every page boundary.
K
displays in hexadecimal the storage keys for all page frames or partial page
frames included in the specified address range.
s
displays the contents of storage in hexadecimal translation. Storage is displayed
as a string starting at the location specified. The specified address range is not
boundary aligned.
The storage key is displayed on the first line, and at every page boundary.
I
displays the contents of storage in instruction format. The specified address is
rounded down to the nearest half word boundary.
The storage key is displayed on the first line, and at every page boundary.
N
displays the contents of storage in hexadecimal without EBCDIC translation.
This is the default. Storage is displayed in word segments. An address range
will be displayed starting at the full word in which the specified address resides.
Storage is displayed in full word increments.
The storage key is displayed on the first line, and at every page boundary.
Chapter 2. VM/XA SP CP Commands
135
DISPLA Y HOST STORAGE
u
displays the contents of storage in EBCDIC translation. Storage is displayed as
an EBCDIC string starting at the address specified. The specified address range
is not boundary aligned.
The storage key is displayed on the first line, and at every page boundary.
If you do not specify any of the options T, K, S, I, N, or U, the contents of
storage are displayed in hexadecimal word segments.
hexlocl
is the starting storage location that is to be displayed. The address hexlocl may
be one to eight hexadecimal digits; leading zeros are optional. The default is
zero.
J'
{-} [heXIoc2
{:} END
is the last of a range of hexadecimal storage locations whose contents are to be
displayed. If specified, hexloc2 must be equal to or greater than hexlocl, and
must be within the bounds of addressable storage. The address hexloc2 may be
from one to eight hexadecimal digits; leading zeros are optional. The symbol ":"
means the same as "-" when specifying a range of addresses.
Specify END if you want to display the remaining contents of storage. END is
the default if you specify "-", ":", or ".".
J
{.} [bytecount
END
is a hexadecimal integer designating the number of bytes of storage (starting
with the byte at hexlocl) to be displayed. The sum of hexloc1 and bytecount
must be less than the bounds of addressable storage. This value is the lesser of
the storage size specified at system generation and the real storage size.
The specified bytecount must have a value of at least one and may be from one
to eight hexadecimal digits. Leading zeros are optional.
Specify END if you want to display the remaining contents of storage. END is
the default if you specify "-", ":", or ".".
Usage Notes
Only CP-owned pages may be displayed.
While displaying data in CP storage, the running of a virtual machine or someone
else using the STORE HOST command could cause data to be changed. This could
create an inconsistency in the data that is viewed.
Responses
One or more of the following responses is displayed, depending upon the operands
specified.
Response 1
Hhexloc wordl word2 word3 word4 [Key] [*EBCDIC TRANSLATION*]
This is the response for the storage location requests when H is your display request
with T or N option. The EBCDIC translation is only displayed if you have also
entered the T option. The storage key is displayed on the first line, and at every
page boundary.
136
VM/XA SP2 CP Command Reference
DISPLAY HOST STORAGE
Response 2
Hhexloc *EBCDIC TRANSLATION* [key]
If your display request is H with the U option, you receive this response. Hhexloc is
the hexadecimal location of the first data byte to be displayed. A minimum of 1
character and a maximum of 32 characters will be displayed on each line. The
contents of storage will be displayed only in EBCDIC translation. Periods in the
display data represent nonprintable characters. The storage key is displayed on the
first line, and at every page boundary.
Response 3
Hhexloc mnemonic X-X mnemonic X-X mnemonic X-X [key]
If your display request is H with the I option, you receive this response. Hhexloc is
the hexadecimal storage location of the first instruction to be displayed. mnemonic
is up to a 5-character representation of the instruction code. x-x is the actual
hexadecimal contents of storage and is either 2, 4, or 6 bytes as determined by the
instruction length code. Unrecognizable instruction codes will be indicated by a
series of asterisks. A minimum of one instruction and a maximum of three
instructions will be displayed on each line. The storage key is displayed on the first
line and at every page boundary.
Response 4
Hhexloc stringhexadecimaldata [key]
This is the response you receive if your display request was H with the S option.
The storage key is displayed on the first line of a range, and at every page boundary.
Response 5
Hhexlocl TO hexloc2 KEY
=
kk
If your display request is H with the K option, you receive this response. hexlocl
and hexloc2 are storage locations and kk is the associated storage key for Hhexlocl.
You will receive this response for every contiguous address range that has unique
storage keys, and whenever a segment boundary is crossed.
Response 6
If the storage location you indicated in the command line is not a CP-owned page,
you receive the following response:
Hhexlocl TO hexloc2 SUPPRESSED NON-CONTROL-PROGRAM PAGE
hexlocl and hexloc2 are storage locations.
Response 7
If your display request includes a request to display one or more lines identical to
the previous line, you receive the following response:
Xhexlocl TO hexloc2 SUPPRESSED LINE(S) SAME AS ABOVE •••
hexlocl and hexloc2 are storage locations. The X in Xhexloc can be L, R, V, or W,
depending on the request.
Chapter 2. VM/XA SP CP Commands
137
DISPLAY HOST STORAGE
Migration Notes
VMIXA SF
1. In VMjXA SP, the response· SUPPRESSED LINE(S) SAME AS ABOVE
appears whether or not the amount of storage to be displayed exceeds X 1100
bytes.
I
2. VM/XA SP displays storage keys at the first line of a request and at every page
boundary. It shows storage keys even if you request only one address.
3. In VM/XA SP, the default format is N.
4. In VM/XA SP, the N option rounds storage locations to fullword boundaries,
and displays storage in fullword increments.
138
VM/XA SP2 CP Command Reference
DISPLAY PREFIX
DISPLAY PREFIX
Privilege Class: G
Use DISPLAY PREFIX to display the contents of the prefix register, which is the
absolute location of the guest page O.
I
Di spl ay
PREFIX
where:
PREFIX
displays the contents of the prefix register.
Responses
PREFIX
= xxxxxxxx
displays the contents of the prefix register in hexadecimal.
Chapter 2. VMjXA SP CP Commands
139
DISPLAY PROGRAM STATUS WORDS
DISPLAY PROGRAM STATUS WORDS
Privilege Class: G
Use DISPLAY PROGRAM STATUS WORDS to display information about your
virtual machine's program status words (PSWs) as two hexadecimal words.
Psw ~EXT SVC
PROG
PRG
MCH
I/O
_ALL _
Display
where:
PSW
requests the display of a current virtual machine PSW. When entered without
additional operands, the value of the current PSW will be displayed.
EXT
SVC
PROG
PRG
MCH
1/0
displays the current values and appropriate interrupt information for both the
new and old PSWs specified, that is, EXTERNAL, SVC, PROGRAM CHECK,
MACHINE CHECK, and I/O.
ALL
displays the current values and appropriate interrupt information for the current
PSW and all old and new interrupt PSWs (except RESTART).
Responses
One or more of the following responses is displayed, depending upon the operands
specified.
Response 1
PSW
=
xxxxxxxx xxxxxxxx
displays the contents of the PSW in hexadecimal.
Response 2
EXT
SVC
PRG
MCH
I/O
nnnn
nnnn
nnnn
nnnn
nnnn
18
20
28
30
38
OLD
OLD
OLD
OLD
OLD
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
58
60
68
70
78
NEW
NEW
NEW
NEW
NEW
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
displays the contents of the old and new PSWs and the interruption codes in
hexadecimal. Each nnnn represents the EC-mode interruption code. The numbers
18, 20, 28 ... are storage locations. The X's represent the contents of the PSWs.
140
VM/XA SP2 CP Command Reference
DISPLA Y REGISTERS
DISPLAY REGISTERS
Privilege Class: G
Use DISPLAY REGISTERS to display the contents of general purpose registers,
floating point registers, or control registers.
Display
Note: Do not put blanks between operands that relate to a single DISPLAY request
(except for PSW and SCHIB which require a blank). For more information,
see "General Usage Notes for DISPLAY" on page 128.
where:
Gregl
is a decimal number from 0 to 15 or a hexadecimal integer from 0 to F
representing the first, or only, general register whose contents are to be
displayed. If you specify G without a register number, the contents of all the
general registers are displayed.
Yregl
is an integer (0, 2, 4, or 6) representing the first, or only, floating-point register
whose contents are to be displayed. If you specify Y without a register number,
the contents of all of the floating-point registers are displayed.
Xregl
is a decimal number from 0 to 15 or a hexadecimal number from 0 to F
representing the first, or only, control register whose contents are to be
displayed. If you specify X without a register number, the contents of all the
control registers are displayed.
{~} ;~~
is a number representing the last register whose contents are to be displayed.
You must specify the hyphen "-" when you are requesting more than one
register by register number. You must specify the range of registers in ascending
order. Therefore, the value you specify for reg2 must be equal to or greater than
the value you specify for regl.
The symbol ":" means the same as "-" when specifying a range of addresses.
If you specify G or X, reg2 may be a decimal number from 0 to 15 or a
hexadecimal number from 0 to F. If you specify Y, reg2 may be 0, 2, 4, or 6.
The contents of registers regl through reg2 are displayed.
Specify END to display the contents of all remaining registers. END is the
default. Remaining registers are those in the range:
• From regl through register 15, if you are displaying general registers
• From regl through register 6, if you are displaying floating point registers
• From regl through register 15, if you are displaying control registers
Chapter 2. VM/XA SP CP Commands
141
DISPLAY REGISTERS
{.} regcount
END
is a decimal number from 1 to 16 or a hexadecimal number from 1 to F
specifying the number of registers (starting with regl) whose contents are to be
displayed. If you specify G or X, regcount can be 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 regl
and regcount must be a number that does not exceed the maximum register
number for the type of registers being displayed.
Specify END to display the contents of all remaining registers. END is the
default. Remaining registers are those in the range:
• From regl through register 15, if you are displaying general registers
• From regl through register 7, if you are displaying floating point registers
• From regl through register 15, if you are displaying control registers
Responses
One or more of the following responses is displayed, depending upon the operands
specified.
Response 1
Displaying General Registers:
GPR nn
=
genregl genreg2 genreg3 genreg4
is the response you receive when you display general registers. nn indicates the first
(or only) register whose contents are to be displayed; these contents are displayed in
genregl.
The contents of each register is displayed in hexadecimal. Up to four registers per
line are displayed for each range you specify. If required, multiple lines are
displayed, up to a maximum of four lines.
Response 2
Displaying Floating Point Registers:
FPR nn
=
xxxxxxxxxxxxxxxx
± . ddddddddddddddddd
E dd
This is the response you receive when you display floating-point registers. nn is the
even-number floating-point register whose contents are displayed on the line. The
contents of the floating-point registers are displayed in both the internal hexadecimal
format and the E format; the first part of the response is the contents of the register
in hexadecimal and the second part of the response is the contents in exponential
decimal format. Only one register is displayed per line. If you specified a range of
registers, multiple response lines are displayed.
Response 3
Displaying Control Registers:
ECR nn
=
ctlregl ctlreg2 ctlreg3 ctlreg4
This is the response you receive when you display control registers; nn is the first (or
only) control register whose contents you want to display.
142
VMjXA SP2 CP Command Reference
DISPLA Y REGISTERS
The contents of the requested control registers are displayed in hexadecimal. Up to
four registers per line are displayed. If required, multiple response lines are
displayed.
Migration Notes
VMIXA SF: The VMjXA SP response uses GPR, FPR and ECR instead of G, Y,
and X as in VMjXA SF.
Chapter 2. VM/XA SP CP Commands
143
DISPLAY SCHIB
DISPLAY SCHIB
Privilege Class: G
Use DISPLAY SCHIB to display information from your subchannel information
blocks (SCHIBs).
Note: This command is only valid if your virtual machine is operating in 370-XA
mode.
Display
SCHi b [vsch1]
[tH
~~~h2J] I
{.} [count]
/
END,
,
ALL
where:
SCHm
displays information from your subchannel information blocks.
vschl
is the starting (or only) virtual subchannel whose SCHIB is to be displayed.
t} ;SC~
specifies that all SCHIBs in the range vschl to vsch2 are to be displayed, or that
all SCHIBs from vschl to the highest number subchannel are to be displayed.
END is the default if you specify dash (-), a colon (:), or a period (.).
The symbol ":" means the same as "-" when specifying a range.
{.} count
END
is the number of consecutive SCHIBs starting at vschl that are to be displayed.
Specify END to display all SCHIBs from vschl to the highest number
subchannel. END is the default if you specify dash (-), a colon (:), or a
period(.).
ALL
specifies that SCHIBs for all virtual devices are to be displayed.
Usage Notes
1. If you specify a list of SCHIBS, and one is not found, the DISPLAY command
will terminate. For example, if you enter:
display SCHIB 0022 0055 0011
and subchannel 0055 is not found, the command will terminate. If you specify a
range of SCHIBs, the DISPLAY command will terminate if the first SCHIB in
the range is not found. Otherwise, all those SCHIBs that were found will be
displayed.
2. If your virtual machine is running in 370-XA mode, you can use the CP
QUERY VIRTUAL command to determine the subchannel number associated
with a virtual device.
144
VM/XA SP2 CP Command Reference
DISPLAY SCHIB
3. The response to this command is a header line followed by a line of information
for each SCHIB that you specify. (The header line identifies, column by
column, the SCHIB information below it. See "Responses" below.) After every
ten lines of SCHIB information, the header line reappears.
Responses
SCHIB DEV INT-PARM ISC FlG lP PNO lPU PI MBI PO PA CHPID0-3 CHPID4-7
nnnn nnnn nnnnnnnn n nn nn nn nn nn nnnn nn nn nnnnnnnn nnnnnnnn
If an interrupt is pending for the virtual subchannel, the following line describes the
pending interrupt:
KEY ECC FPI ZN SCTl CCW-ADDR DS SS CNT EXT-lOG
n n n n nnnn nnnnnnnn nn nn nnnn nnnnnnnn
where:
INT-PARM
ISC
FLG
LP
PNO
LPU
PI
MBI
PO
PA
CHPID
is the interrupt parameter.
is the interrupt subclass.
is the flag field.
is the logical path mask.
is the path not operational mask.
is the last path used mask.
is the path installed mask.
is the measurement block index.
is the path operational mask.
is the path available mask.
are the channel path identifiers.
For the second line of the response, provided when an interrupt is pending on the
subchannel:
KEY
ECC
FPI
ZN
SCTL
CCW-ADDR
DS
SS
CNT
EXT-LOG
is the SCSW protect key.
are the logout condition code bits.
are the format, prefetch, and initial response bits.
the initial status condition.
are the function and activity control bytes.
is the SCSW CCW address.
are the SCSW device status bits.
are the subchannel status bits.
is the SCSW residual CCW data count.
is the extended status/time word.
Chapter 2. VMjXA SP CP Commands
145
DISPLAY VECTOR
DISPLAY VECTOR
Privilege Class: G
This command displays to the terminal all the contents of the following:
• Vector registers (VR)
• Vector register pair or pairs (VP)
• Vector status register (VSR)
• Vector mask register (VMR)
• Vector activity count (VAC)
• Vector section size (VSS).
Display
9
{~:} [r,e1[ t} ~:~2
J,]] [,eltl[t} [~~~2 J]]
{ .} ~egcountJ
END
{ .} [e 1tcountJ
END
,
VSR
VMR
VAC
VSS
where:
VR
displays one or more, vector registers in hexadecimal.
VP
regl
displays one or more even-odd vector register pairs as 64-bit elements in
hexadecimal, along with the decimal equivalent in exponential format.
If you wish to display vector registers (VR), regl is a decimal number from 0 to
15 or a hex number from XIQI to X'F' representing the first, or only, vector
register whose contents are to be displayed. If VR is specified without a register
number, it will default to register O.
If you wish to display a vector register pair (VP), regl is an even decimal
number from 0 to 14 or an even hexadecimal number from X I 0 I to X I E I of the
first or only vector register pair. If regl is not specified with VP, it will default
to vector register pair O.
{~yeg2
If you wish to display a range of vector registers, reg2 is a decimal number from
15 or a hex number from X I 0 I to X I F I representing the last vector register
whose contents are to be displayed. If you specify VP, reg2 must designate an
even-numbered register. The dash (-) or colon (:) following regl specifies a
range of register values for display. Specify the range of registers in ascending
order. Reg2 must be equal to or greater than regl. The contents of registers
regl to reg2 will then be displayed.
o to
146
VMjXA SP2 CP Command Reference
DISPLAY VECTOR
ttNDI
When used in the register specification, this calls for a display of all register
contents from the starting registers specified by regl to register 15, or register
pair 14-15.
{.} regcount
is a decimal number from 1 to 16 or a hex number from 1 to F specifying the
number of vector registers or pairs whose contents are to be displayed. If VP is
specified, the valid range is 1 to 8. If you display vector registers, the sum of
regl and regcount must not be larger than 16.
,eItI
The comma indicates that a register element specification follows. If the comma
and element specification is not given, CP displays the contents of elements 0-3
for VR, or element 0 only for VP. Eltl is a hexadecimal number from zero to
one less than the section size representing the first, or only, element to be
displayed.
t}elt2
is a hexadecimal number from 0 to one less than the section size representing the
last element whose contents are to be displayed. The dash (-) and colon (:)
before indicates that you wish to display a range of elements. The range of
elements must be specified in ascending order. The operand elt2 must be equal
to or greater than elt1. The contents of elements elt1 to elt2 are displayed.
{. }eltcount
is a hexadecimal number from I to the section size specifying the number of
elements whose contents are to be displayed starting with elt1. The range
indicated by eltl and eltcount must not exceed the section size.
{~}[ENDI
When used in the element specification, this calls for a display of the contents of
all elements from the starting element specified by eltl to the last element, which
is one less than the section size.
VSR
displays the current vector status register.
VMR
displays the current vector mask register.
VAC
displays the current vector activity count.
VSS
displays the vector section size.
Usage Notes
No blanks are allowed between operands that relate to a single display request.
Chapter 2. VM/XA SP CP Commands
147
DISPLA Y VECTOR
Response 1
VRnn,elt = xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx
The vector register elements are always displayed in groups of four with the contents
shown in hexadecimal. If required, multiple lines are displayed for each register.
where:
nn
indicates the register whose contents are displayed.
eIt
indicates the first element number whose contents are displayed.
Response 2
VPnn,elt = xxxxxxxxxxxxxxxx s.dddddddddddddddd Esdd
The contents of the register pair is displayed in both the hexadecimal format (the
first part of the response) and in exponential decimal format (the second part of the
response). One element of a register pair is displayed per line. If required, multiple
lines are displayed for each register pair.
where:
nn
indicates the register whose contents are to be displayed.
elt
indicates the first element number whose contents are to be displayed.
s
is the positive or negative indicator.
Response 3
VSR = xxxxxxxx xxxxxxxx
The vector status register contents are displayed in hexadecimal.
Response 4
VMR = xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx
The vector mask register contents are displayed in hexadecimal.
Response 5
VAC = xxxxxxxx xxxxxxxx
The vector activity count contents are displayed in hexadecimal.
Response 6
VECTOR SECTION SIZE: nnn
The vector section size is displayed in hexadecimal.
148
VMjXA SP2 CP Command Reference
DISPLAY VECTOR
Response 7
VXn
= ZERO (IN-USE BIT IS OFF)
This response is given when the "in-use" bit of the referenced vector pair in the
vector status register is off for a display vector register request. When the in-use bit
is off, the register contents are defined at zero.
x
is the indicator for "R" (register) or "P" (pair).
n
is the hexadecimal register number.
Migration Notes
VMISP HPO: VM/XA SP evaluates the command for proper syntax prior to
checking whether the Vector Facility is available.
Chapter 2. VMjXA SP CP Commands
149
DRAIN
DRAIN
Privilege Class: D
Use the DRAIN command to stop spooling operations on the specified real unit
record devices after the file currently being processed has completed.
DRain
Reader
]
Printer
PUnch
[ rdev rdev ...
,ALL
where:
READER
RDR
PRINTER
PRT
PUNCH
PCH
drains all readers, printers, or punches.
rdev rdev ...
is a real device number or list of real device numbers of the real spooled devices
that you want drained.
ALL
drains all spooled unit record devices in the system.
Usage Notes
1. Use the DRAIN command to bring the spooling system or a specified device to
a controlled halt. You would normally drain all unit record devices before a
system shutdown, and drain a printer before you change the contents of the
UCS printer buffer.
2. A device is drained immediately if it is not active when the DRAIN command is
issued; otherwise, it is drained when processing of the current file has completed.
You can restart a drained device by issuing the CP START command. If you
issue a START command to a device before draining has been completed, the
device does not enter drained status and it continues processing.
3. If you specify more than one real device number, execution of the DRAIN
command terminates upon encountering an invalid real device number. None of
the remaining devices are drained.
150
VMjXA SP2 CP Command Reference
DRAIN
Responses
Inactive Printer Responses
The following response occurs for each printer that attains the drained status:.
PRT rdev DRAINED userid
CLASS c ...
PRT rdev FORM form {AUTO } {SEP } {N03S00 .}
MANUAL NOSEP BEG3S00
SETUP
ANY3S00
For 3800 printers only (third line):
PRT rdev FLASH name IMAGE imagel ib CHARS name FCB lname!{HOLD }
6
PURGE
S
10
12
For impact printers only (third line):
PRT rdev {,NOFOLD} IMAGE imagelib CHARS chars [FCB name] [INDEX nn]
FOLD
Inactive Punch Responses
The following response occurs for each punch that attains the drained status:
{PUN} rdev DRAINED userid CLASS c •..
{PUN} rdev FORM form {AUTO } {SEP }
MANUAL NOSEP
SETUP
Inactive Reader Response
{RDR} rdev DRAINED SYSTEM
Active Printer Responses
The following response occurs for each printer that attains the drained status:
PRT rdev DRAINING userid
CLASS c ..•
PRT rdev FORM form {AUTO '} '{' SEP } {N03S00 }
~ MANUAL NOSEP BEG3S00
tSETUP
ANY3S00
Chapter 2. VM/XA SP CP Commands
151
DRAIN
For 3800 printers only (3rd and 4th lines):
PRT rdev FLASH name IMAGE imagelib CHARS name
FCB iname!
6 {HOLD}
PURGE
8
.,
10
12
PRT rdev {PRINTING} userid FILE spoolid RECS {nnnn} COpy [*]nnn SEQ sss
nnnK
nnnM
For impact printers only (3rd and 4th lines):
PRT rdev {NOFOLD} IMAGE imagelib CHARS chars [FCB name] [INDEX nn]
FOLD
PRT rdev {PRINTING} userid FILE spoolid RECS{nnnn.} COPY [*]nnn SEQ sss
nnnK
nnnM:
is the message you receive when the system begins processing a spool file that has
the MSG attribute.
Active Punch Responses
The following response occurs for each punch that attains the drained status:
{PUN} rdev DRAINING userid CLASS c
000
{PUN} rdev FORM form {AUTO '} {SEP }
MANUAL NOSEP
SETUP
{PUN} rdev {PUNCHING} userid FILE spoolid RECS {nnnn.} COpy [*]nnn SEQ sss
nnnK
nnnM
Active Reader Response
{RDR} rdev DRAINING SYSTEM
where:
PRT
PUN
RDR
is the device that you drained or are draining.
rdev
is the real device number of the drained or draining device.
152
VM/XA SP2 CP Command Reference
DRAIN
CLASS c ...
are those output classes that the drained or draining device was servicing. One
to eight classes are displayed for each printer or punch device that was drained
or is draining.
FORM form
changes the form name of a spool file. The form name is one-to-eight characters.
AUTO
indicates that the operator wants CP to schedule forms output. The currently
active form is processed first. When all files with the current form have been
printed or punched, CP automatically selects a new form for the device. The
operator will receive a message to change forms, and the output device will be
idle. The operator can then put in the new form and press the START button
(or issue the START command) to print files with the new form.
MANUAL
indicates that the operator will schedule output forms. Only spool files with the
form currently active on the device are processed. When the last spool file with
the current form is printed or punched, the output device stops. The operator
can then schedule a new form by issuing a START command with the FORM
option.
SETUP
indicates that the operator wants CP to print a page so that forms alignment can
be verified. (This option is only valid for impact printers.) The operator will get
a message indicating that he or she should set up the forms. When the form has
been set up, the operator should press the STOP button, then the START
button. An alignment page will then be printed. It is the first page of the file,
with letters replaced with X's and the numbers replaced by 9' s. Each time the
operator presses the STOP or START buttons after a full alignment page has
been printed, another alignment page will be printed. When the forms are
aligned, you should issue the "START" command for the device. The printer
will then return to its previous mode (AUTO or MANUAL) and the file will
print in its entirety.
If neither MANUAL, AUTO, nor SETUP is specified and the printer is currently in
SETUP mode, it will return to the previous mode, AUTO or MANUAL. If no
START command has been issued with the MANUAL, AUTO, or SETUP options
since a system cold start, the default is MANUAL.
SEP
NOSEP
indicates the current separator status.
N03800
BEG3800
ANY3800
specifies the restrictions on the 3800 load CCWs in effect once the device is
STARTed again.
rdev
is the real 3800 printer or list of 3800 printer numbers that you want drained.
FLASH name
signifies that a form overlay contained in the 3800 printer is to be superimposed
(or flashed) onto the specified number of copies of the output. The name, to be
one-to-four characters in length, identifies the forms overlay to be used in the
projection.
Chapter 2. VM/XA.SP CP Commands
153
DRAIN
IMAGE imagelib
specifies the name of the system image library file which will contain the load
images (character sets), FCBs, graphic character modifications, or copy
modifications that will be used for printing files and separators. "imagelib" may
be from one-to-eight characters in length, and must be an existing image library
file.
FCB name
is the name of the forms control buffer (FCB) module to be used by the printer
in the vertical formatting of a page.
Note:
This does not appear for 1403 type printers.
CHARS name
specifies the name of the default character set used when printing spool files
which do not specify a character set.
HOLD
prevents the printing of a file by placing it in a user HOLD status.
PURGE
closes and purges the spool file on the specified 3800 printer regardless of the
CONT, KEEP, and HOLD setting for the device.
NOFOLD
FOLD
indicates whether lowercase characters are being translated (folded) into
uppercase for printing.
CHARS chars
indicates the character set being used by the printer.
INDEX nn
indicates the character position on the page at which to begin printing.
Note:
This only appears for 3211 type printers.
PRT
PUN
indicate the type of device on which the file is being processed.
rdev
is the real device number.
userid
is the name of the spool file owner.
FILE spoolid
is the spool file spoolid number.
RECS {nnnn }
nnnK
nnnM
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
154
VMjXA SP2 CP Command Reference
DRAIN
COpy (*)000
specifies the number of file copies you want printed or punched when the file is
produced.
When the optional asterisk (*) is specified, the 3800 printer will print each page
from the spooled output files nnn times before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
SEQ sss
is the sequence number for the file on the printer or punch.
Migration Notes
VMISP HPO
1. The VM/XA SP response provides more detail (two lines) than VM/SP HPO
concerning the printer being drained.
2. VM/XA SP does not support logical printers.
VMIXA SF: A third line appears for impact printers other than the 1403 without the
ues feature.
Chapter 2. VM/XA SP CP Commands
155
DUMP
DUMP
Use the DUMP command described in this section to dump the following real and
virtual machine components to your virtual printer:
• Contents of first-level storage
• Contents of second-level storage
• Contents of third-level storage
• Old and new PSW s and interrupt information for the following interrupts:
SVC
I/O
PROGRAM
EXTERNAL
MACHINE CHECK
• Storage keys
• Contents of registers:
Prefix
General
Floating-point
Control
• Subchannel information blocks (SCHIBs)
• The current program status word (CURRENT PSW)
• The following Vector Facility information:
Vector registers (VR)
Vector register pair(s) (VP)
Vector status register (VSR)
Vector mask register (VMR)
Vector activity count (VAC)
Vector section size (VSS).
Complete Format for DUMP
The format box below shows all of the operands available with the DUMP
command. Complete descriptions of the operands appear on the following pages, in
the same sequence as the operands appear here.
156
VM/XA SP2 CP Command Reference
DUMP
Class
DUmp
t~.V "ts l~heXlOCll
L
J. . r~}r;.~~~10C2 J).\.
~
Q
.W,
I'
~
!
J
rlreX~OCIJ [{~}.~.~~~10C2 J].\
{ . } rbytecount
lFND
I
!!
.
[*dUmpld]
{ • } fbytecountl
_.
_U~
H
G
J.
C/E
[*dumpid]
I
U
:---
PREFIX [*dumpid]
G
Psw EXT
SVC
PROG
PRG
MCH
I/O
G
-ALL
...,;
[*dumpid]
-
1
~-}~re92 J]
{U [9 ~:}[~;countl
J
'[vschl]
r.
SCHib
~
[*dumpidl
~}~.:~h2 J]I'
{.} [count
\ ALL
G
LEND
J
G
[*dumpid]
>
I
{~:} [regf~. ~}[~~2 J]] [eltl~.~}~~~2 J. ]][*dU~Pid]
{ . } rregcountJ
LEND
G
'{ . } re 1tcountl
.
LEND
j
VSR [*dumpid]
VMR [*dumpid]
VAC [*dumpid]
VSS [*dumpid]
Chapter 2. VMjXA SP CP Commands
157
DUMP
General Usage Notes for DUMP
1. The DUMP command prints the contents of various storage locations, registers,
and control registers. You may be able to detect the cause of program errors by
examining this information.
2. Using a single DUMP command, you can dump multiple storage locations,
registers, and control words.
There are two rules that you must follow in order for the command to execute
properly:
a. Do not put blanks between operands that relate to a single DUMP request,
except for PSW and SCHIB which require at least one blank between the
first and second operands:
For example, if you want to dump hexadecimal location 40, enter:
dump
h40
b. Separate each set of dump requests from others by at least one blank.
For example, if you want to dump the hexadecimal location 40 and the
contents of register 5, enter:
dump h40 g5
3. You can assign a dump identification to any dump that you create by means of
the DUMP command. Note, however, that even though you can use a single
DUMP command to make multiple DUMP requests, you can assign only one
dump identification per command.
The dump identifier is an asterisk (*) followed by a 1- to 97-character identifier
that is to be assigned to the dump. If specified, the dump identifier must be the
last operand you enter on the command line. Blanks are permitted in the dump
identification.
For example:
dump 9 *general registers
creates a dump of your general registers, and assigns the dump the identifier
"general registers."
4. As each request is processed, a message is sent to your display device. This will
permit you to terminate DUMP processing by pressing the PAl key. When the
command terminates, you may enter another command.
158
VM/XA SP2 CP Command Reference
DUMP
5. The defaults for the following DUMP operands are:
COlll11and
Operand
Default
Before Round;ng
G
GG-5
G5G5
T
TT-U)00
T1000T1000
PSW
0-end
0-end
0-G5
G5-end
G5
error
H)-end
T0-1000
T1000-end
T1000
current
6. When dumping a range of addresses or subchannels, the command operand must
be followed by an address, a range, or a punctuation mark (" -", ":", "."),
which will form a range. When dumping registers, the command operand can
stand alone.
7. If you enter a command line that contains an invalid operand, the DUMP
command will terminate when it encounters that operand. Any previous valid
operands will be processed before termination occurs.
8. The DUMP command allows you to dump information in the following formats:
•
•
•
•
•
Hexadecimal string/Hexadecimal word segments
EBCDIC translation for uppercase letters and numbers 0-9
Hexadecimal word segments with EBCDIC translation
Instruction
Storage key.
Note: Hexadecimal to EBCDIC translation is done for the numerals 0 to 9 and
uppercase characters A to Z only.
If you enter multiple operands on a single command line for a storage or register
dump, and do not specify the format that you want the DUMP command
processor to use, the last format type that you explicitly entered on the
command line will define the type of dump that you receive. That is, whenever
you explicitly enter a dump type, you implicitly define the default for subsequent
operands of the current dump function. If you do not enter any dump format
type on the command line, the system defaults will be employed.
F or example:
dump 10 20 T40 80 G12 5 L60-100
dumps the following, respectively:
Hexadecimal
Hexadecimal
Hexadecimal
Hexadecimal
The contents
The contents
Hexadecimal
location 10 without EBCDIC translation
location 20 without EBCDIC translation
location 40 with EBCDIC translation
location 80 with EBCDIC translation
of general register 12
of general register 5
locations 60 through 100 with EBCDIC translation
Chapter 2. VMjXA SP CP Commands
159
DUMP
The DUMP command suppresses identicallines and imbeds a response whenever
a page boundary is crossed.
Migration Notes
VM/SP HPO
1. In VMjXA SP, you can store into CAW or CSW but you cannot dump their
contents.
160
VMjXA SP2 CP Command Reference
DUMP GUEST STORAGE
DUMP GUEST STORAGE
Privilege Class: G
Use DUMP GUEST STORAGE to dump the contents of specified locations in
virtual machine storage.
DUmp
~R~
.~. ~T-'~
~. ~eX~Oc1J [{-}
:
.W.
I
H
J]l
[heX10C2
END
.
{. } [bYtecoun~
I
[*dumpid]
I
END
U'
"'"-_ ....
Note: Do not put blanks between operands that relate to a single DUMP request
(except for PSW and SCHIB). Note that you can assign only one dump
identifier (*dumpid) per command. For more information, see "General
Usage Notes for DUMP" on page 158.
where:
R
dumps the contents of second-level storage.
L
dumps the contents of second-level storage if the guest virtual machine is
operating in DAT OFF mode; dumps the contents of third-level storage if the
guest virtual machine is operating in DAT ON mode.
v
dumps the contents of third-level storage using control register 1.
w
dumps the contents of third-level storage using control register 7.
T
dumps the contents of storage in hexadecimal with EBCDIC translation.
Storage is dumped in word segments. An address range will be dumped starting
at the X 110 I boundary in which the specified address resides. Storage is
dumped in X I I0 1 increments.
The storage key is dumped on the first line and at every page boundary.
K
dumps the storage keys in hexadecimal for all page frames or partial page
frames included in the specified address range.
s
dumps the contents of storage in hexadecimal translation. Storage is dumped as
a string starting at the location specified. The specified address range is not
boundary aligned.
The storage key is dumped on the first line and at every page boundary.
I
dumps the contents of storage in instruction format. The specified address is
rounded down to the nearest half word boundary.
The storage key is dumped on the first line and at every page boundary.
Chapter 2. VMjXA SP CP Commands
161
DUMP GUEST STORAGE
N
dumps the contents of storage in hexadecimal without EBCDIC translation. This
is the default. Storage is dumped in word segments. An address range will be
dumped starting at the full word in which the specified address resides. Storage
is dumped in full word increments.
The storage key is dumped on the first line and at every page boundary.
u
dumps the contents of storage in EBCDIC translation. Storage is dumped as an
EBCDIC string starting at the address specified. The specified address range is
not boundary aligned.
The storage key is dumped on the first line and at every page boundary.
If you do not specify any of the options T, K, S, I, N, or U, the contents of
storage are dumped in hexadecimal word segments.
hexlocl
is the starting storage location that is to be dumped to your virtual printer. The
address hexlocl may be one-to-eight hexadecimal digits; leading zeros are
optional. The default is O. The starting address will be translated to a hex 10
boundary.
Storage locations and the minimum amount dumped are rounded according to
the following conventions:
Rounding Conventions (in hex)
Storage
Locations
Start
T
K
S
10
7FF
1
I
N
U
2
4
1
Minimum
Length
10
7FF
1
2-6 (depending on instruction)
4
1
-} hexloc2
{ :' END
is the last of a range of hexadecimal storage locations whose contents are to be
dumped to your virtual printer. If specified, hexloc2 must be equal to or greater
than hexlocl and within the virtual storage size. The address, hexloc2, may be
from one-to-eight hexadecimal digits; leading zeros are optional.
Specify END if you want to dump the remaining contents of storage. EN-D is
the default if you specify "-", ":", or ".".
The symbol ":" means the same as "-" when specifying a range of addresses.
{.} bytecount
END
is a hexadecimal number designating the number of bytes of storage (starting
with the byte at hexloc1) to be dumped to your virtual printer.
The specified bytecount must have a value of at least one and may be from one
to eight hexadecimal digits; leading zeros are optional.
Specify END if you want to dump the remaining contents of storage. END is
the default if you specify" -", ":", or ".".
162
VM/XA SP2 CP Command Reference
DUMP GUEST STORAGE
*dumpid
is an asterisk followed by a 1- to 97 -character identifier that is to be assigned to
the dump. If specified, the dumpid must be the last operand you enter on the
command line.
Usage Notes
1. The DUMP GUEST STORAGE command dumps the program status words
(PSWs) and the contents of registers (general, floating-point, control, and prefix)
along with the contents of the specified storage. If your virtual machine is
operating in 370-XA mode, the subchannel information blocks (SCHIBs) are
dumped. If you define a Vector Facility, then the vector registers (VR), vector
register pairs (VP), vector status register (VSR), vector mask register (VMR),
vector activity count (VAC), and vector section size (VSS) are dumped.
2. You can dump storage locations outside the range of your virtual machine size if
they are within a saved segment. Any attempt to dump locations (or associated
keys) between the upper limit of your virtual machine and the address at which
the saved segment is saved results in the "nonaddressable storage" response
appearing in the printed output.
Responses
One or more of the following responses appears in your spooled output, depending
upon the operands that you specified:
Response 1
Xhexloc wordl word2 ...•. word8 [Key] [*EBCDIC TRANSLATION*] [Lhexloc]
This is the response you receive if your request was L, R, V, or W with the T or N
option. X indicates the type of request (L, R, V, or W). The EBCDIC translation is
given only for the T option.
The storage key will be dumped on the first line, and at every page boundary.
F or a Vhexloc or Whexloc request, the Lhexloc trailer shows the guest real address
corresponding to the given guest virtual address. The Lhexloc trailer is also shown
when DAT-ON mode causes Lhexloc to resolve to a third-level address. The storage
key is dumped on the first line of a request and at every page boundary.
Response 2
Xhexloc *EBCDIC TRANSLATION* [key] [Lhexloc]
This is the response you receive when your request is L, R, V, or W, with the U
option. Xhexloc is the hexadecimal location of the first data byte to be dumped; X
can be L, R, V, or W, depending on your request. A minimum of 1 character and a
maximum of 64 characters appear on each line. The contents of storage are dumped
in EBCDIC translation only. Periods represent nonprintable characters. The
storage key is dumped on the first line of a request and at every page boundary.
F or a Vhexloc or Whexloc request, the Lhexloc trailer shows the guest real address
corresponding to the given guest virtual address. The Lhexloc trailer is also shown
when DAT-ON mode causes Lhexloc to resolve to a third-level address. The storage
key is dumped on the first line of a request and at every page boundary.
Chapter 2. VM/XA SP CP Commands
163
DUMP GUEST STORAGE
Response 3
Xhexloc mnemonic X-X mnemonic X-X mnemonic X-X [key] [Lhexloc]
This is the response you receive when your request is L, R, V, or W, with the I
option. Xhexloc is the hexadecimal storage location of the first instruction to be
dumped and X can be L, R, V, or W, depending on the request. Mnemonic is up to
a 5-character representation of the instruction code. x-x is the actual hexadecimal
contents of storage and is either 2, 4, or 6 bytes as determined by the instruction
length code. Unrecognizable instruction codes are indicated by a series of asterisks.
The minimum of one instruction and a maximum of five instructions are dumped per
line. The storage key is dumped on the first line of a request and at every page
boundary.
For a Vhexloc or Whexloc request, the Lhexloc trailer shows the guest real address
corresponding to the given guest virtual address. The Lhexloc trailer is also shown
when DAT-ON mode causes Lhexloc to resolve to a third-level address. The storage
key is dumped on the first line of a request and at every page boundary.
Response 4
Xhexloc stringhexadecimaldata [key][Lhexloc]
This is the response you receive if your dump request was L, R, V, or W with the S
option. X indicates the type pf dump request (L, R, V, or W). The storage key is
dumped on the first line of a request, and at every page boundary.
F or a Vhexloc or Whexloc request, the Lhexloc trailer shows the guest real address
corresponding to the given guest virtual address. The Lhexloc trailer is also shown
when DAT -ON mode causes Lhexloc to resolve to a third-level address. The storage
key is dumped on the first line of a request and at every page boundary.
Response 5
Xhexlocl TO hexloc2 KEY
=
kk
This is the response when you dump storage keys; hexlocl and hexloc2 are storage
locations and kk is the associated storage key for Xhexlocl. X can be L, R, V, or
W, depending upon your dump request. A response is dumped for every contiguous
address range that has unique storage keys, and whenever a segment boundary is
crossed.
Response 6
If your request includes a request to dump nonaddressable storage, you receive the
following response:
Xhexlocl TO hexloc2 NON-ADDRESSABLE STORAGE
hexlocl and hexloc2 are storage locations. The X in Xhexloc can be L, R, V, or W,
depending on the request.
Response 7
If your request includes a request to dump one or more lines identical to the
previous line, you receive the following response:
Xhexlocl TO hexloc2 SUPPRESSED LINE(S) SAME AS ABOVE ...
hexloc1 and hexloc2 are storage locations. The X in Xhexloc can be L, R, V, or W,
depending on the request.
164
VM/XA SP2 CP Command Reference
DUMP GUEST STORAGE
Response 8
Responses 8 and 9 appear on your display screen.
DUMPING LOC Xhexloc
This response is sent to your console to indicate that a segment boundary has been
reached. Each segment boundary location has an address that ends in X I 0000 I •
In this response, hexloc is the storage boundary that has been reached, and X can be
L, R, V, or W, depending upon your dump request.
Response 9
COMMAND COMPLETE
indicates that the command has completed.
Migration Notes
VMISP HPO
1. In VMjXA SP, you can dump larger storage sizes than in VMjSP HPO.
2. In VMjXA SP, you can dump more levels of storage than in VMjSP HPO.
3. VMjXA SP also dumps subchannel information blocks (SCHIBs) when in
370-XA mode, and all vector information when a Vector Facility is defined.
VMIXA SF
1. In VM/XA SP, the response SUPPRESSED LINE(S) SAME AS ABOVE
appears whether or not the amount of storage to be dumped exceeds X 100
bytes.
I
I
2. In VM/XA SP, storage keys are dumped at the first line of a request and at
every page boundary. It shows storage keys even if you request only one
address.
3. In VM/XA SP, the default option is N.
4. In VM/XA SP, the N option rounds storage locations to fullword boundaries,
and dumps storage in fullword increments.
Chapter 2. VM/XA SP CP Commands
165
DUMP HOST STORAGE
DUMP HOST STORAGE
Privilege Class: C,E
Use DUMP HOST STORAGE to dump the contents of first-level storage in
specified locations.
,--
DUmp
H
.r
:K
's
,I
:N,
~eex~oc~ [0
JJ!
.:. ~heXl0C2
END
.•.•
.
[{ .} [~~~ecountJ J
[*dumpid]
....:u..;..
Note: Do not put blanks between operands that relate to a single DUMP request,
except for PSW and SCHIB which require at least one blank between the first
and second operands. Note that you can assign only one dump identifier
(*dumpid) per command. For more information, see "General Usage Notes
for DUMP" on page 158.
where:
H
dumps the contents of first-level storage.
T
dumps the contents of storage in hexadecimal with EBCDIC translation.
Storage is dumped in word segments. An address range will be dumped starting
at the X I 10 1 boundary in which the specified address resides. Storage is
dumped in X I 10 1 increments.
The storage key is dumped on the first line and at every page boundary.
K
dumps the storage keys in hexadecimal for all page frames or partial page
frames included in the specified address range.
s
dumps the contents of storage in hexadecimal translation. Storage is dumped as
a string starting at the location specified. The specified address range is not
boundary aligned.
The storage key is dumped on the first line and at every page boundary.
I
dumps the contents of storage in instruction format. The specified address is
rounded down to the nearest half word boundary.
The storage key is dumped on the first line and at every page boundary.
N
dumps the contents of storage in hexadecimal without EBCDIC translation. This
is the default. Storage is dumped in word segments. An address range will be
dumped starting at the full word in which the specified address resides. Storage
is dumped in full word increments.
The storage key is dumped on the first line, as well as at every page boundary.
166
VM/XA SP2 CP Command Reference
DUMP HOST STORAGE
u
dumps the contents of storage in EBCDIC translation. Storage is dumped as an
EBCDIC string starting at the address specified. The specified address range is
not boundary aligned.
The storage key is dumped on the first line and at every page boundary.
If you do not specify any of the options T, K, S, I, N, or U, the contents of
storage are dumped in hexadecimal word segments.
hexlocl
is the starting storage location that is to be dumped to your virtual printer. The
address hexlocl may be one to eight hexadecimal digits; leading zeros are
optional. The default is O.
-..} hexloc2
{ : END
is the last of the range of hexadecimal storage locations whose contents are to be
dumped to your virtual printer. If specified, hexloc2.must be equal to or greater
than hexlocl and within the bounds of addressable storage (the lesser of the
storage size specified at system generation and the real storage size). The
address, hexloc2, may be from one to eight hexadecimal digits; leading zeros are
optional.
Specify END if you want to dump the remaining contents of storage. END is
the default.
The symbol ":" means the same as "-" when specifying a range of addresses.
{.} bytecount
END
is a hexadecimal integer designating the number of bytes of storage (starting
with the byte at hexloc1) to be dumped to your virtual printer. The sum of
hexloc1 and bytecount must be an address that does not exceed the bounds of
addressable storage (the lesser of the storage size specified at system generation
and the real storage size). The specified bytecount must have a value of at least
one and may be from one to eight hexadecimal digits. Leading zeros are
optional.
Specify END if you want to dump the remaining contents of storage. END is
the default.
*dumpid
is an asterisk followed by a 1- to 97 -character identifier that is to be assigned to
the dump. If specified, the dumpid must be the last operand you enter on the
command line.
Usage Notes
You can dump only CP owned pages.
While dumping data in CP storage, the running of a virtual machine or someone
using the STORE HOST command could cause data to be changed. This could
create an inconsistency in the data that is viewed.
Chapter 2. VM/XA SP CP Commands
167
DUMP HOST STORAGE
Responses
One or more of the following responses appears in your spooled output, depending
upon the operands specified.
Response 1
Hhexloc wordl word2 .••.• word8 [Key] [*EBCDIC TRANSLATION*]
This is the response for the storage location requests when H is your dump request
with the T or N option. The EBCDIC translation is only dumped if you have also
entered the T option.
The storage key is dumped on the first line, and at every page boundary.
Response 2
Hhexloc *EBCDIC TRANSLATION* [key]
If your request is H with the U option, you receive this response. Hhexloc is the
hexadecimal location of the first data byte to be dumped. A minimum of 1
character and a maximum of 64 characters are dumped per line. The contents of
storage will be dumped only in EBCDIC translation. Periods represent nonprintable
characters. The storage key is dumped on the first line and at every page boundary.
Response 3
Hhexloc mnemonic X-X mnemonic X-X mnemonic X-X [key]
If your request is H with the I option, you receive this response. Hhexloc is the
hexadecimal storage location of the first instruction to be dumped. mnemonic is up
to a 5-character representation of the instruction code. x-x is the actual
hexadecimal contents of storage and is either 2, 4, or 6 bytes as determined by the
instruction length code. Unrecognizable instruction codes are indicated by a series
of asterisks. A minimum of one instruction and a maximum of five instructions are
dumped per line. The storage key is dumped on the first line and at every page
boundary.
Response 4
Hhexloc stringhexadecimaldata [key]
This is the response you receive if your dump was H with the S option. The storage
key is dumped on the first line and at e~ery page boundary.
Response 5
Hhexlocl TO hexloc2 KEY
=
kk
If your request is H with the K option you receive this response. hexlocl and
hexloc2 are storage locations and kk is the associated storage key. You will receive
this response for every contiguous address range that has unique storage keys, and
whenever a segment boundary is crossed.
Response 6
If the storage location you indicated in the command line is not a CP owned page,
you receive the following response:
Hhexlocl TO hexloc2 SUPPRESSED NON-CONTROL-PROGRAM PAGE
hexloc1 and hexloc2 are storage locations.
168
VM/XA SP2 CP Command Reference
DUMP HOST STORAGE
Response 7
If your request includes a request to dump one or more lines identical to the
previous line, you receive the following response:
Xhexlocl TO hexloc2 SUPPRESSED LINE(S) SAME AS ABOVE ••.
hexloc1 and hexloc2 are storage locations. The X in Xhexloc can be L, R, V, or W,
depending on the request.
Response 8
Responses 8 and 9 appear on your display screen.
DUMPING LOC Hhexloc
This response is sent to your console to indicate that a segment boundary has been
reached. Each segment boundary has an address that ends in X 10000
I •
Response 9
COMMAND COMPLETE
indicates that the command has successfully executed.
Migration Notes
VMIXA SF
1. In VMjXA SP, the response SUPPRESSED LINE(S) SAME AS ABOVE
appears whether the amount of storage to be dumped exceeds X 1100 I bytes.
2. VMjXA SP dumps storage keys at the first line of a range and at every page
boundary. It shows storage keys even if you request only one address.
3. In VMjXA SP, the default format is N.
4. In VMjXA SP, the N option rounds storage locations to fullword boundaries
and dumps storage in fullword increments.
Chapter 2. VM/XA SP CP Commands
169
DUMP PREFIX
DUMP PREFIX
Privilege Class: G
Use DUMP PREFIX to dump the contents of the prefix register to your virtual
printer.
I
PREFIX [*dumpid]
DUmp
where:
PREFIX
dumps the contents of the prefix register.
*dumpid
is an asterisk followed by a 1- to 97-character identifier that is to be assigned to
the dump. If specified, the dumpid must be the last operand you enter on the
command line.
Usage Notes
The contents of the prefix register is the absolute location of the guest page O.
Response 1
PREFIX
=
xxxxxxxx
is the contents of the prefix register in hexadecimal.
The following response will appear on your display screen.
Response 2
COMMAND COMPLETE
indicates that the command has successfully executed.
170
VM/XA SP2 CP Command Reference
DUMP PROGRAM STATUS WORDS
DUMP PROGRAM STATUS WORDS
Privilege Class: G
Use DUMP PROGRAM STATUS WORDS to dump information about your
virtual machine's program status words (PSWs) as two hexadecimal words.
r-
DUmp
Psw EXT
[*dumpid]
SVC
PROG
PRG
MCH
I/O
ALL
-
where:
PSW
requests the dump of a current virtual machine PSW. When entered without
operands, the value of the current PSW will be dumped.
EXT
SVC
PROG
PRG
MCH
1/0
dumps the current values and appropriate interrupt information for both the
new and old PSWs specified, that is, EXTERNAL, SVC, PROGRAM CHECK,
MACHINE CHECK, and I/O.
ALL
dumps the current values and appropriate interrupt information for the current
PSW and all old and new interrupt PSWs (except RESTART).
*dumpid
is an asterisk followed by a 1- to 97 -character identifier that is to be assigned to
the dump. If specified, the dumpid must be the last operand you enter on the
command line.
Responses
One or more of the following responses appears in your spooled output, depending
upon the operands specified.
Response 1
Dumping the Current PSW
PSW = xxxxxxxx xxxxxxxx
The contents of the PSW are dumped in hexadecimal.
Chapter 2. VM/XA SP CP Commands
171
DUMP PROGRAM STATUS WORDS
Response 2
EXT
SVC
PRG
MCH
I/O
nnnn
nnnn
nnnn
nnnn
nnnn
18
20
28
30
38
OLD
OLD
OLD
OLD
OLD
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
58
60
68
70
78
NEW
NEW
NEW
NEW
NEW
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
The contents of the old and new PSWs and the interruption codes are dumped in
hexadecimal. The nnnn represents the interruption code. The numbers 18, 20, 28 ...
are storage locations. The X's represent the contents of the PSWs.
The following response will appear on your display screen.
Response 3
COMMAND COMPLETE
indicates that the command has successfully executed.
172
VMjXA SP2 CP Command Reference
DUMP REGISTERS
DUMP REGISTERS
Privilege Class: G
Use DUMP REGISTERS to dump the contents of general purpose registers,
floating point registers, or control registers.
DUmp
Note: Do not put blanks between operands that relate to a single DUMP request,
except for PSW and SCHIB which require at least one blank between the first
and second operands. Note that you can assign only one dump identifier
(*dumpid) per command. For more information, see "General Usage Notes
for DUMP" on page 158.
where:
Gregl
is a decimal number from 0 to 15 or a hexadecimal integer from 0 to F
representing the first, or only, general register whose contents are to be dumped
to your virtual printer. If you specify G without a register number, the contents
of all the general registers are dumped.
Yregl
is an integer (0, 2, 4, or 6) representing the first, or only, floating-point register
whose contents are to be dumped to your virtual printer. If you specify Y
without a register number, the contents of all of the floating-point registers are
dumped.
Xregl
is a decimal number from 0 to 15 or a hexadeCimal number from 0 to F
representing the first, or only, control register whose contents are to be dumped
to your virtual printer. If you specify X without a register number, the contents
of all of the control registers are dumped.
t}~~~
is a number representing the last register whose contents are to be dumped. You
must specify the hyphen "." or ":" when you are requesting more than one
register by register number. You must specify the range of registers in ascending
order. Therefore, the value you specify for reg2 must be equal to or greater than
the value you specify for regl.
If you specify G or X, reg2 may be a decimal number from 0 to 15 or a
hexadecimal number from 0 to F. If you specify Y, reg2 may be 0, 2, 4, or 6.
The contents of registers regl through reg2 are dumped to your virtual printer.
The symbol ":" means the same as "." when specifying a range of addresses.
Chapter 2. VM/XA SP CP Commands
173
DUMP REGISTERS
Specify END to dump the contents of all remaining registers. END is the
default. Remaining registers are those in the range:
• From regl through register 15, if you are dumping general registers
• From regl through register 6, if you are dumping floating point registers
• From regl through register 15, if you are dumping control registers.
{•} regcount
END
is a decimal number from 1 to 16 or a hexadecimal number from 1 to F
specifying the number of registers (starting with regl) whose contents are to be
dumped. Specify END to dump the contents of all remaining registers. END is
the default. Remaining registers are as follows:
• General registers 1-15
• Floating point registers 1-7
• Control registers 1-15.
If the dump type G or X is specified, regcount can be a decimal number from 1
to 16 or a hexadecimal number from 1 to F.
If dump type Y is specified, regcount must be 1, 2, 3, or 4. The sum of reg 1 and
regcount must be a number that does not exceed the maximum register number
for the type of registers being dumped.
*dumpid
is an asterisk followed by a 1- to 97-character identifier that is to be assigned to
the dump. If specified, the dumpid must be the last operand you enter on the
command line.
Responses
One or more of the following responses appears in your spooled output, depending
upon the operands that you specified:
Response 1 -- Dumping General Registers
GPR nn = genregl genreg2 genreg3 genreg4
This is the response you receive when you dump general registers. nn indicates the
first (or only) register whose contents are to be dumped; the contents of nn are
dumped in genregl. The contents of the registers are dumped in hexadecimal. Up
to four registers per line are dumped for a range of registers. Multiple lines are
dumped if required, with a maximum of four lines needed to dump all 16 general
registers.
Response 2 -- Dumping Floating-Point Registers
FPR nn = xxxxxxxxxxxxxxxx
±.ddddddddddddddddd E dd
This is the response you receive when you dump floating-point registers. nn is the
0"'""
p"p1"'l_nl11:'nhp
f1,n"'t.1"'ItT_"',n
t ...PtT.c
STORage
SEEKS
DEVi ce
{~~:~
rdev .•. }
rdev-rdev .•.
TYpe
type-list
VOLume {Valid-list}
CPVOL
ALL
-
>
,
{BLock m}
STArt
{ STOP
[ BLock m ] [PARTition n] }
Chapter 2. VMjXA SP CP Commands
253
MONITOR
MONitor
SAMPle
~
t
- 'I/O
ev
DEVice rdev rdev ... '
rdev-rdev •.. }
CLass class-list
TYpe
type-list
DISable
VOLume {VOlid-list}
CPVOL
ALL
ENable
USER {USERID useri d-l i st }
ALL
PROCessor
STORage
- ,ALL
....
{INTerval
{RATE
J
}
n [MINutes]
[SEConds]
{n [SEConds]
STOP
}}
{STArt}
STOP
{STArt} [ BLock m][ PARTition n ]
STOP
General Usage Notes:
1. Do the following before trying to start event or sample monitoring:
• Define and save a saved segment for MONITOR.
• Load the monitor saved segment and connect to the *MONITOR CP system
service via IUCV, using an application program running in a virtual
machine.
2. Both the event and sample profiles can be changed after monitoring has started.
The only exception is that the partition size of the saved segment cannot be
changed unless event monitoring is stopped. New event domains will be
activated upon completion of the EVENT command, and new sample domains
will be activated when the next interval elapses.
3. For a detailed description of data collected, refer to the monitor records in the
VM/XA SP CP Programming Services manual.
4. The valid classes and types for use with SEEKS and I/O domains are listed in
the following table:
254
VMjXA SP2 CP Command Reference
MONITOR
Table 8. Valid classes and types for SEEKS and I/O domains
CLASS
TYPE
Other
Valid For
TYPES
SEEKS
Valid For
1/0
included
TAPE
DASD
SPOOL
3420
X
3430
X
3480
X
2305
X
3330
3333
X
X
3340
3344
X
X
3350
X
X
3370
X
X
3375
X
X
3380
X
X
1403
X
2501
X
2540
X
3203
X
3211
X
3262
X
3505
X
3525
X
3800
X
4245
X
4248
GRAF
GPRT
X
1
GTERM 1
X
X
IGPRT represents all graphic display printers; GTERM represents all display
terminals. For a list of graphic devices supported, see VMjXA SP General
Information.
Migration Notes
VMISP HPO: VMjXA SP uses different commands, produces different data records,
and has different collection mechanisms.
Chapter 2. VM/XA SP CP Commands
255
MONITOR EVENT
MONITOR EVENT
Privilege Class: A,E
Use the MONITOR EVENT command to establish a profile for event data
collection. An event data profile lists the data domains and their elements that are
to be monitored for event data. The profile also includes the block and partition
values for the shared segment. This command can also be used to activate or
deactivate event data collection.
MONitor
EVent
,...
-
I/O
DEVi ce
I
{~~:~ rdev ...}' ,
rdev-rdev •••
CLass class-list
~ TYpe
type-l i st
VOLume {VOlid-list}
CPVOL
, ALL
DISable
>
USER {USERID useri d-l i st }
ALL
PROCessor
SCHeduler {USERID userid-list}
ALL
:STORage
SEEKS
, DEVi ce
{~~:~ rdev ... }'
rdev-rdev •••
TYpe
type-list
VOLume {VOl id-l ist}
CPVOL
,ALL
-
>
I
ALL
{BLock m}
STArt
{ STOP
[ BLock m ] [PARTition n]
}
where:
EVENT
indicates that the command is for event-driven data collection.
DISABLE
disables the specified domains or their elements from event data collection.
Note: The MONITOR domain cannot be disabled from monitoring.
256
VMjXA SP2 CP Command Reference
MONITOR EVENT
ENABLE
enables the specified domains and their elements for event data collection.
Event data shall be collected only from those domains that have been enabled.
ENABLE is the default.
Note: The MONITOR domain is always enabled for event monitoring.
1/0
specifies that the I/O domain is to be enabled or disabled for event data
collection. An I/O domain is comprised of all real I/O devices. Event
monitoring may be enabled or disabled on all devices, or it may be restricted by
their device numbers, classes, types, or volumes. I/O-domain events include such
activities as VARY ON and VARY OFF, attachment and detachment of
devices.
1/0 DEVICE rdev
1/0 DEVICE rdev rdev...
1/0 DEVICE rdev-rdev ..•
specifies the device number of the real device to be enabled or disabled for event
data collection in the I/O domain. You may specify a list, a range of devices, or
a combination of both. If you specify a range, all valid devices in the range,
inclusively, will be enabled or disabled. For additional information, see the
specific usage notes for I/O.
1/0 CLASS class-list
specifies a list of device classes that are to be enabled or disabled for event
monitoring in the I/O domain. A class list is one or more device classes,
separated by blanks. The valid classes are DASD, TAPE, SPOOL, and GRAF.
All real devices of the specified class or classes will be monitored.
1/0 TYPE type-list
specifies a list of device types that are to be enabled or disabled for event
monitoring in the I/O domain. A type list is one or more device types (such as
3380), separated by blanks. For valid device types, see Table 8 on page 255.
All real devices of the specified type or types will be monitored.
1/0 VOLUME volid-Iist
1/0 VOLUME CPVOL
specifies a list of volumes that are to be enabled or disabled for monitoring in
the I/O domain. A volid list is one or more volume identifiers, separated by
blanks. If CPVOL is specified, then all CP owned volumes are monitored. A CP
owned volume is any volume specified on the SYSCPVOL macro of HCPSYS
ASSEMBLE.
1/0 ALL
specifies that all real devices are to be enabled or disabled for monitoring in the
I/O domain.
USER
specifies that the USER domain is to be enabled or disabled for event data
collection. An USER domain is comprised of all users. All or selected users
may be specified for monitoring.
User domain events include such activities as logon and logoff, defining and
detaching a virtual CPU, and an end of transaction.
USER USERID userid-Iist
specifies a list of users that are to be enabled or disabled in the USER domain.
A userid list is one or more user identifiers, separated by blanks.
Chapter 2. VM/XA SP CP Commands
257
MONITOR EVENT
USER ALL
specifies that all users are to be enabled or disabled for event data collection in
the USER domain.
PROCESSOR
specifies that the PROCESSOR domain is to be enabled or disabled for event
data collection. Events such as VARY ON or VARY OFF of a processor will
be monitored.
SCHEDULER
specifies that the SCHEDULER domain is to be enabled or disabled for event
data collection. Event data for this domain include statistics such as scheduler
queue manipulation, flow of work through the system, and resource allocation
strategies of the scheduler and the dispatcher.
SCHEDULER USERID userid-list
specifies a list of users that are to be enabled or disabled for event data
collection in the SCHEDULER domain. A userid list is one or more user
identifiers, separated by blanks.
SCHEDULER ALL
specifies that all users are to be enabled or disabled for event data collection in
the SCHEDULER domain.
STORAGE
specifies that the STORAGE domain is to be enabled or disabled for event data
collection. Events such as defining and purging of a named saved system or a
saved segment, and attaching or detaching a CP volume are monitored.
SEEKS
specifies that the SEEKS domain is to be enabled or disabled for event data
collection. A SEEKS domain is comprised of all DASD devices. Event
monitoring may be enabled or disabled for all DASD devices, or it may be
restricted by their device numbers, types, or volumes.
Event data will be collected on every I/O request on such enabled DASD
devices.
SEEKS DEVICE rdev
SEEKS DEVICE rdev rdev .. .
SEEKS DEVICE rdev-rdev .. .
specifies the device number of a DASD device to be enabled or disabled for
event data collection. You may specify a list, a range of devices, or a
combination of both. If you specify a range, all valid DASD devices in the
range, inclusively, are enabled or disabled. See the specific SEEKS usage notes
for additional information.
SEEKS TYPE type-list
specifies a list of DASD device types that are to be enabled or disabled for
SEEKS monitoring. A type list is one or more device types (such as a 3380),
separated by blanks. All DASD devices of the specified type or types will be
monitored. For valid device types, see Table 8 on page 255.
SEEKS VOLUME volid-Iist
SEEKS VOLUME CPVOL
specifies a list of volumes that are to be enabled or disabled for SEEKS
monitoring. A volid ist is one or more volume identifiers, separated by blanks.
If CPVOL is specified, then all CP owned volumes are enabled or disabled. A
CP owned volume is any volume specified on the SYSCPVOL macro of
HCPSYS ASSEMBLE.
258
VM/XA SP2 CP Command Reference
MONITOR EVENT
SEEKS ALL
specifies that all real DASD devices are to be enabled or disabled for SEEKS
monitoring.
ALL
specifies that all domains and all their elements are to be enabled or disabled for
event data collection. This includes all six domains: I/O (all devices), USER (all
users), SEEKS (all DASD devices), SCHEDULER (all users), PROCESSOR,
and STORAGE.
Note: The MONITOR domain is enabled for event data collection at all times.
BLOCKm
is described as part of the MONITOR EVENT START command below. If the
command is issued when event monitoring is not active, the value of m will not
be verified until monitoring has been activated by the MONITOR START
EVENT or the MONITOR START commands.
START
activates event-driven data collection for the domains specified in preceding
MONITOR EVENT commands. At startup, the profile records from the
monitor domain are also generated.
BLOCKm
specifies the number of 4Kb shared-segment frames (m) that will be
accumulated before the virtual machine is notified that the event data is
available for data collection. The BLOCK value may be modified via the
MONITOR EVENT BLOCK command while event monitoring is active.
PARTITION n
specifies that the number of 4Kb shared-segment frames (n) to be reserved
for event data. The rest of the shared segment will then be used for sample
data.
STOP
deactivates the event-driven data collection. The monitor event profile is not
affected by this command, except for PARTITION which is set to O.
General Usage Notes
1. Both event and sample monitoring can be active at the same time. Monitoring
of both types of data can be started by using the MONITOR START command,
or for event data by issuing the MONITOR EVENT START command.
Similarly, monitoring can be stopped by the appropriate stop commands,
MONITOR EVENT STOP or MONITOR STOP.
2. The following must be done before event monitoring can be started:
• A saved segment must be defined and saved for MONITOR.
• An application program running in a virtual machine must load the monitor
saved segment and connect to the *MONITOR CP system service via IUCV.
3. The event profiles can be changed after monitoring has started. The only
exception is that the partition size of the saved segment cannot be changed
unless event monitoring is stopped. New event domains will be activated upon
completion of the event command.
4. Event monitoring can result in large volumes of data generated, and in increased
CP overhead, particularly in the SEEKS and SCHEDULER domains. These
domains should be enabled only when problems are suspected.
Chapter 2. VMjXA SP CP Commands
259
MONITOR EVENT
Specific Usage Notes for 1/0 and SEEKS
1. Any overlapping of I/O devices can exist in a series of MONITOR EVENT
commands on the I/O domain and the SEEKS domain. For example, if this
command:
MONITOR EVENT ENABLE I/O TYPE 3380
is followed by this command:
MONITOR EVENT ENABLE I/O CLASS DASD
then all DASD devices will be enabled for monitoring. However, if this is
followed by this command:
MONITOR EVENT DISABLE I/O TYPE 3380
monitoring will cease for all 3380 devices, but will continue for all other types of
DASD devices.
2. A message will be issued for any device which does not exist or, for the SEEKS
domain, is not a DASD device.
3. Devices which are enabled but are found to be offline will be monitored once
they have been varied online or attached to the system.
4. A summary message will be issued indicating how many devices are enabled for
monitoring, and how man~ are offline.
5. The VOLUME operand can only be used for volumes attached to the system
since CP associates a volUme label to a device number only at the time it is
attached. If you want to enable a DASD device not attached to the system, use
the DEVICE option.
6. For a multiple-exposure device, all exposures associated with the volume are
enabled or disabled.
7. The volume to be monitored is maintained by its device address. Enabling or
disabling a volume for monitoring remains valid as long as its device address
does not change. For example, if a volume is detached and a volume with the
same label at a different address is attached, the volume must be enabled again
to be monitored and its pievious device address disabled.
Specific Usage Notes for BLOCK
1. If BLOCK is not specified, the default is four 4Kb frames.
2. The minimum value for BLOCK is four 4Kb frames.
3. The maximum value for BLOCK is half the size of the PARTITION.
4. The value of BLOCK will be saved when monitoring is stopped.
Specific Usage Notes for PARTITION
1. If PARTITION is not specified, the initial value is half the size of the saved
segment.
2. The minimum PARTITION size is eight 4Kb frames.
3. The maximum PARTITION size is the size of the saved segment. If sample
monitoring is active, the maximum PARTITION size is the size of the saved
segment minus one 4Kb frame.
4. The value of PARTITION will not be saved when monitoring is stopped.
260
VMjXA SP2 CP Command Reference
MONITOR EVENT
Response 1
The command, MONITOR EVENT START, activates event-driven data collection
based on the previously specified event profile if an application program is retrieving
event records. The response is:
MONITOR EVENT STARTED
Response 2
MONITOR EVENT STOP deactivates all current event-driven data collection. The
response when event-driven data collection is active is:
MONITOR EVENT STOPPED
The following response is issued for all other valid commands entered:
COMMAND COMPLETE
Chapter 2. VMjXA SP CP Commands
261
MONITOR SAMPLE
MONITOR SAMPLE
Privilege Class: A,E
Use the MONITOR SAMPLE command to establish a profile for sample data
collection, including single sample data and high frequency sample data. Single
sample data are a set of counters and data that characterize a system operation.
High frequency sample data are a set of counters and data that represent the state of
the system at the moment they are sampled.
As established by this command, a sample profile lists the data domains and their
elements to be monitored, the rate at which high frequency sample data is to be
collected, and the time interval at which sample data is to be reported.
l
This command can also be used to activate or deactivate sample data collection.
MONitor
-
SAMPle
rdev rdev ...
I/O DEVice {rdev
rdev-rdev ..•
CLass class-list
TYpe
type-list
DISable
{
~
VOLume {VOl id-l ist} }
CPVOL
{ALL
,
}!'
}
J
'USER {USERID userid-l ist }'
ALL
PROCessor
STORage
...
.. ,ALL
{INTerva 1
{RATE
n [MINutes]
[SEConds]
}
n [SECOndS]} }
{ STOP
STArt}
{ STOP
where:
SAMPLE
indicates that the command is for single sample and high frequency sample data
collection types.
DISABLE
disables the specified domains or their elements from monitoring.
Note: The MONITOR domain and the SYSTEM domain cannot be disabled
from sample data collection.
262
VM/XA SP2 CP Command Reference
MONITOR SAMPLE
ENABLE
enables the specified domains and their elements for sample data collection.
Sample data shall be collected only from those domains that have been enabled.
ENABLE is the default.
Note: The MONITOR domain and the SYSTEM domain are always enabled
for sample data monitoring.
1/0
specifies that the I/O domain is to be enabled or disabled for sample data
collection. The I/O domain is comprised of all real I/O devices; monitoring may
be enabled or disabled on all devices, or it may be restricted by their device
numbers, classes, types, or volumes.
1/0 DEVICE rdev
1/0 DEVICE rdev rdev .. .
1/0 DEVICE rdev-rdev .. .
specifies the device number of the real device to be enabled or disabled for
sample data collection in the I/O domain. You may specify a list, a range of
devices, or a combination of both. If you specify a range, all valid devices in the
range, inclusively, will be enabled or disabled. For additional information, see
the specific usage notes for I/O.
1/0 CLASS class-list
specifies a list of device classes that are to be enabled or disabled for sample
data collection. A class list is one or more device classes, separated by blanks.
The valid classes are DASD, TAPE, SPOOL, and GRAF. All real devices of
the specified class or classes will be monitored.
1/0 TYPE type-list
specifies a list of device types that are to be enabled or disabled for sample data
collection. A type list is one or more device types (such as the 3380), separated
by blanks. For valid device types see Table 8 on page 255. All real devices of
the specified type or types will be monitored.
1/0 VOLUME volid-Iist
1/0 VOLUME CPVOL
specifies a list of volumes that are to be enabled or disabled for sample data
collection. A volid list is one or more volume identifiers, separated by blanks. If
CPVOL is specified, then all CP owned volumes are monitored. A CP owned
volume is any volume specified on the SYSCPVOL macro of HCPSYS
ASSEMBLE.
1/0 ALL
specifies that all real devices are to be enabled or disabled for sample data
collection.
USER
specifies that the USER domain is to be enabled or disabled for sample data
collection. The USER domain is comprised of all users. Data collected for this
domain consists of user resource utilization and status data for all or selected
users.
USER USERID userid-list
specifies a list of users that are to be enabled or disabled for sample data
collection. A userid list is one or more user identifiers, separated by blanks.
USER ALL
specifies that all users are to be enabled or disabled for sample data collection.
Chapter 2. VM/XA SP CP Commands
263
MONITOR SAMPLE
PROCESSOR
specifies that the PROCESSOR domain is to be enabled or disabled for sample
data collection. Data related to work dispatched on each processor is collected.
STORAGE
specifies that the STORAGE domain is to be enabled or disabled for sample
data collection. Status and utilization data of real, virtual, expanded, shared,
and auxiliary storage are collected.
ALL
specifies that all domains and all their elements are to be enabled or disabled for
sample data collection. This includes all the four domains: I/O (all devices),
USER (all users), PROCESSOR, and STORAGE.
Note: SYSTEM and MONITOR domains are enabled for sample monitoring at
all times.
SAMPLE INTERVAL n MINUTES
SAMPLE INTERVAL n SECONDS
specifies the time interval at which the sample data is to be reported.
MINUTES is the default. For additional information, see the specific usage
notes for INTERVAL.
SAMPLE RATE n SECONDS
specifies the frequency at which the high frequency sample data is to be
collected. High frequency sample data is a set of counters and data which
represent the state of the system at the moment they are sampled.
High frequency sampling will be automatically activated whenever the
MONITOR SAMPLE START command is issued, unless the RATE value has
been previously set to STOP. For additional information, see the specific usage
notes for RATE.
SAMPLE RATE STOP
immediately terminates the collection of high frequency sampling data. Data for
the current interval is lost.
SAMPLE START
activates sample data collection. Only those domains and their elements that
have been enabled shall be monitored. At startup, system configuration records
from the monitor domain are generated. These records include information
concerning the memory, processor, paging and real I/O configurations, as well as
the initial profile settings. High frequency sampling data collection, if enabled,
as well as single sample data collection will be started.
SAMPLE STOP
deactivates creation and collection of sample data. This also stops the collection
of high frequency sampling data, if it is active. All data collected for the current
interval are purged. The monitor sample profile is not affected by this
command.
Usage Notes
1. The following must be done before sample monitoring can be started:
• A saved segment must be defined and saved for MONITOR.
• An application program running in a virtual machine must load the monitor
saved segment and connect to the *MONITOR CP system service via IUCV.
264
VMjXA SP2 CP Command Reference
MONITOR SAMPLE
2. Both event and sample monitoring can be active at the same time. Monitoring
of both types of data can be started by use of the MONITOR START
command, or for sample data, by issuing the MONITOR SAMPLE START
command. Similarly, monitoring can be stopped by the appropriate stop
command, MONITOR SAMPLE STOP or MONITOR STOP.
Specific Usage Notes for 1/0
1. Any overlapping of I/O devices can exist on a series of MONITOR SAMPLE
commands on the I/O domain. For example, if this command:
MONITOR SAMPLE ENABLE I/O TYPE 3380
is followed by this command:
MONITOR SAMPLE ENABLE I/O CLASS DASD
then all DASD devices will be enabled for monitoring. However, if this is
followed by this command:
MONITOR SAMPLE DISABLE I/O TYPE 3380
monitoring will cease for all 3380 devices, but will continue for all other types of
DASD devices.
2. A message will be issued for any devices which do not exist.
3. Devices which are enabled but are found to be offline, will be monitored when
varied online attached to the system.
4. A summary message will be issued indicating how many devices are enabled for
monitoring, and how many are offline.
5. The VOLUME operand can only be used for volumes attached to the system
since CP associates a volume label to a device number only at the time it is
attached. If it is desired to enable a DASD device not attached to the system, it
can be done by using the DEVICE option.
6. For a multiple-exposure device, all exposures associated with the volume are
enabled or disabled.
7. The volume to be monitored is maintained by its device address. Enabling or
disabling a volume for monitoring remains valid as long as its device address
does not change. For example, if a volume is detached and a volume with the
same label at a different address is attached, the volume must be enabled again
to be monitored and its previous device address disabled.
Specific Usage Notes for INTERVAL
1. The valid range of values for INTERVAL is 6 to 3600 for SECONDS, and 1 to
60 for MINUTES. INTERVAL values must be specified in whole numbers.
2. If this command is not issued, an initial value of 10 minutes (600 seconds) will
be used when collecting sample data.
3. If an interval is currently in effect, the new interval will not take effect until the
next sample data record is produced.
4. The SAMPLE INTERVAL value must be greater than or equal to the SAMPLE
RATE value.
5. It is possible that data may not be reported at the time the interval expires. This
will happen when it takes longer than an interval to collect the data. If this
should happen, the interval time should be adjusted to allow sufficient time to
collect and report the data.
Chapter 2. VM/XA SP CP Commands
265
MONITOR SAMPLE
Usage Notes for RATE
1. The valid range of value for RATE is 0.01 to 30.00 seconds. Up to two digits
may be specified after the decimal point. Leading zeros are not required, and
trailing zeros are not required after the decimal point.
2. If this command is not issued, an initial RATE of 5 seconds will be used.
3. If a rate is currently in effect, the new rate will not take effect until the current
high frequency rate has elapsed.
4. The SAMPLE RATE value specified must be less than or equal to the SAMPLE
INTERVAL value.
Response 1
MONITOR SAMPLE START causes sample data to be collected periodically based
on the previously specified sample profile if an application program is retrieving
sample records. The response is:
MONITOR SAMPLE STARTED
Response 2
MONITOR SAMPLE STOP deactivates all current sample data collection. The
response when sample data collection is active is:
MONITOR SAMPLE STOPPED
Response 3
The following response is issued for all other valid commands entered:
COMMAND COMPLETE
266
VMjXA SP2 CP Command Reference
MONITOR START/STOP
MONITOR START/STOP
Privilege Class: A,E
Use the MONITOR START command to activate event and sample monitoring
based on the profiles established by the preceding MONITOR EVENT and
MONITOR SAMPLE commands. Use the MONITOR STOP command to
deactivate all monitoring.
MONitor
STArt
[BLock m ] [PARTition n] }
{ STOP
where:
START
activates event and sample monitoring based on the profiles established by the
MONITOR EVENT and MONITOR SAMPLE commands. Event monitoring
will be started first.
STOP
deactivates the event and sample monitoring. The monitor event and sample
profiles are not affected by this command, except for PARTITION which is set
to zero. Event monitoring will be stopped first.
BLOCKm
specifies the number of 4Kb shared-segment frames (m) that will be accumulated
before the virtual machine is notified that the event data is available for data
collection. The BLOCK value may be modified via the MONITOR EVENT
BLOCK command while event monitoring is active.
PARTITION n
specifies the number of 4Kb shared-segment frames (n) that are reserved for
event data. The rest of the shared segment shall then be used for sample data.
Usage Notes
1. Specific usage notes for BLOCK:
a. If BLOCK is not specified, the default is four 4Kb frames.
b. The minimum value for BLOCK is four 4Kb frames.
c. The maximum value for BLOCK is half the size of the PARTITION value.
d. The value of BLOCK will be saved when monitoring is stopped.
2. Specific usage notes for PARTITION:
a. If PARTITION is not specified, the default value is half the size of the
saved segment.
b. The minimum PARTITION size is eight 4Kb frames.
c. The maximum PARTITION size is the size of the saved segment. If sample
monitoring is active, the maximum PARTITION size is the size of the saved
segment, minus one 4Kb frame.
d. The value of PARTITION will not be saved when monitoring is stopped.
Chapter 2. VM/XA SP CP Commands
267
MONITOR START/STOP
Response 1
For MONITOR START, either one line or both lines may appear:
MONITOR EVENT STARTED
MONITOR SAMPLE STARTED
Response 2
For MONITOR STOP, either one line or both lines may appear:
MONITOR EVENT STOPPED
MONITOR SAMPLE STOPPED
268
VM/XA SP2 CP Command Reference
MSGNOH
MSGNOH
Privilege Class: B
Use of the MSGNOH command provides the ability for a service virtual machine to
send messages to specified users without the standard header associated with the
MESSAGE command.
MSGNOH
1
userid
*
ALL
OPerator
{ msgtext }
I
where:
userid
*
is the identification of the user to whom the message is being sent. If you wish
to send a message to your own userid, you may specify that with an asterisk (*).
ALL
transmits the message to all logged on users.
OPerator
transmits the message to the operator.
msgtext
is the text of the message that is being sent. The length of the message is limited
by the number of characters remaining on the input line after the command and
appropriate operand are entered.
Usage Notes
1. If a message is issued from a CMS environment, the command and the message
text cannot be longer than 240 characters.
If the message is issued from a CP environment, the command and message
length is limited by the input area of the terminal.
2. See "General Usage Notes for MESSAGE" on page 248.
Response
msgtext
is the response received by the specified user or users.
where:
msgtext
is the message text.
Chapter 2. VMjXA SP CP Commands
269
NOT READY
NOTREADY
Privilege Class: G
Use the NOT READY command to make a virtual spooling device appear as if it
had changed from "ready" to "not ready" status.
I
NOTReady
vdev
where:
vdev
is the virtual device number of the device to be made "not ready."
Usage Notes
1. Use this command to change the status of spooled unit record devices and
virtual consoles only.
2. Any I/O operation in progress to the specified device at the time the command is
issued will be completed. The "not ready" condition will be in effect for the
next I/O operation.
Responses
None.
270
VM/XA SP2 CP Command Reference
ORDER
ORDER
Privilege Class: D, G
Use the ORDER command to change the order of closed spool files on a specified
queue. The order of the files determines the sequence in which they will be selected
for output on real printers or punches, or read on virtual readers.
The class G user can issue the ORDER command to order any spool files that the
user originated or currently owns.
The class D user can issue the ORDER command to order any spool files in the
system or files belonging to any user on the system.
ORDer
[SYSTEM] {Reader '}' {CLass cl [CLass c2 ••• ]
Pri nter FORM forml FORM form2 •..
PUnch
}{CLass cl
[ useridJ{Reader
~
Printer FORM forml
PUnch
spoolidl
}
~CLass
c2 •.• ] }
FORM form2 ••.
spoolid2 ..•
Note: You may enter a combination of CLASS, FORM, and spoolid on the same
command line.
where:
SYSTEM
is restricted to class D users. Use the SYSTEM operand to order any file or
group of files on the system queue that you specify without indicating the
owner's userid. This is not valid with the "spoolid" option.
userid
*
is the user identification of the user whose spool files are to be ordered. If you
are ordering your own files, you may specify userid as an asterisk (*).
The userid option allows a class D user to order any file, or group of files,
owned by a particular user. The files are repositioned only with respect to other
spool files owned by the userid that you specified.
The userid option allows a class G user to order any file that he or she
originated, and that is now owned by, the user whose userid is specified on the
command line. The files will be ordered only in relation to any other files that
the class G user originated which are owned by the userid specified in the
command line.
READER
RDR
PRINTER
PRT
PUNCH
PCH
indicates the spool file queue that you want to order.
Chapter 2. VM/XA SP CP Commands
271
ORDER
CLASS cl
CLASS c2 ...
are the file classes that you want to rearrange, and the sequence in which they
are to be processed. You must enter the keyword CLASS for each class that
you want to order. cl, c2, ... are one character alphanumeric fields (from A to
Z or from 0 to 9) that represent spooling classes.
FORM forml
FORMform2 •••
are the forms to be rearranged, and the sequences in which they are to be
processed. 'formI' and 'form2' are specified as I-to-8 characters. For the class
G user, the form is the user form name. For the class D user, the form is the
user form name when you specify "*,, or default to your userid. Otherwise, the
form is the operator form number.
spooJidl
spooJid2 ••.
are the spool identifications of the files that you want to order. This is not valid
with the SYSTEM keyword.
Usage Notes
1. Class G users can order only their own files and any files that they originated.
The order that you specify will not affect the position of any other files that are
in the same system queue as your files, but will only reposition your files with
respect to any other files that you may own.
For example, suppose the system printer queue contains the following files:
SpooJid
Owning user
I
22
USERI
USER2
USER2
USER2
333
4444
Assume further that USER2 issues the following ORDER command:
ORDER PRT 4444
The following queue order will result:
SpooJid
Owning user
1
USER 1
USER2
USER2
USER2
4444
22
333
The class G user may order files that he or she originated and that another
userid now owns. If so, the user will only change the order of the files in
relation to any other files that he or she originated and are now owned by the
other userid. For example, assume there are two users, USERI and USER2,
and USER2' s printer queue is as follows:
SpooJid
123
456
789
9101
272
VMjXA SP2 CP Command Reference
Owning User
Originator
USER2
USER2
USER2
USER2
USER2
USER 1
USER 1
USER2
ORDER
Assume further that USER 1 issues the following ORDER command:
ORDER USER2 PRT 789
The following print queue order will result for USER2:
Spoolid
123
789
456
9101
Owning User
Originator
USER2
USER2
USER2
USER2
USER2
USER 1
USERI
USER2
2. The class D user can reorder any files in the system by specifying the SYSTEM
or userid option.
For example, if you issue the following command:
ORDER SYSTEM PRINTER CLASS C
all class C printer files are placed ahead of any other printer files in the system,
regardless of who owns them or originated them.
The ORDER command is also useful to the class D user who wants to place
files owned by a particular user ahead of all other files on a specified queue.
For example, if you issued the following command:
ORDER USER2 PUNCH CLASS B
you place all of USER2's class B punch files ahead of all other punch files on
the system.
3. Use the QUERY READER/PRINTER/PUNCH command to determine spool
file attributes, such as class and spoolid, for the files that you want to rearrange.
The display produced by the command will show the current order of the spool
files on the queue that you specify.
4. You can use a combination of class, forms, and spoolid specifications to
rearrange files. For example:
ORDER PRINTER CLASS A 1963 CLASS C FORM LISTING
orders the command issuer's printer queue files in the following order: all class A
files, the file with spoolid 1963, all class C files, and all files with the form
"LISTING." They will be followed by any other printer spool files not specified
in the ORDER command line.
5. A file cannot be ordered more than once in a given command. For example,
assume the following is a user's spool print queue.
Spoolid
Class
1234
4567
7890
5555
8888
A
B
A
A
B
Chapter 2. VMjXA SP CP Commands
273
ORDER
If the user issued "ORDER PRT 8888 CLASS A CLASS B," the following
order would result:
Spoolid
Class
8888
1234
7890
5555
4567
B
A
A
A
B
Note that the spoolid 8888 was only ordered once.
Responses
{nnnnnnn} FILE(S) ORDERED
{
NO}
indicates the number of files ordered.
Note: This response is suppressed if you have issued the CP SET IMSG OFF
command.
Migration Notes
VMISP HPO
1. VM/XA SP does not allow users to specify SYSTEM and spoolid on the same
command line. VM/SP HPO (Release 5) users do not see this difference.
2. VM/XA SP does not support the DEST option.
3. VM/XA SP allows room for a 7-digit response.
VMIXA SF: VM/XA SP does not allow users to specify SYSTEM and spoolid on
the same command line.
274
VM/XA SP2 CP Command Reference
PER
PER
Privilege Class: G
Within VM/XA SP, the TRACE command is used to monitor events that occur in
your virtual machine. Please refer to the TRACE command in this reference book
for this information.
Migration Notes
VMISP HPO
1. VM/XA SP will accept the PER command as a synonym for TRACE.
2. VM/XA SP provides equivalent function differently for the following:
SAVE - provided by GOTO and APPEND
GET - provided by GOTO and APPEND
END CURRENT - provided by applying CLEAR to the active trace set
END ident - provided by DELETE
END set - provided by CLEAR
END traptype - same result by deleting each trap separately
GUEST R - provided by NODAT
GUEST V - provided by DAT.
3. VM/XA SP has no equivalent for MASK without DATA.
Chapter 2. VM/XA SP CP Commands
275
PURGE
PURGE
Use the PURGE command described in this section to remove closed spool files and
system data files from the system.
Complete Format for PURGE
The format box below shows all the operands available with the PURGE command.
Complete descriptions of the operands appear on the following pages, in the same
sequence as the operands appear here.
PURge
[SYSTEM] reader
. Printer
PUnch
UR
lfU
Class
CLass cl
[CLass c2 ...
]
FORM forml FORM form2 •..
[useridJ reader HALL
Printer
PUnch
UR
~
IMG
CLass cl
rCLass c2
spoolidl
spoolid2 ...
FORM forml i....FORM form2 •.•
000
fU
}
]I
0
D,G
A,B,C,D,E
spoolidl [SPOOlid2
NAME fnl NAME fn2
...
000]
}
0
}
NLS
B
fLL
spoolidl epOOlid2
.. ]
NAME fnl NAME fn2 ..•
NSS [ASSOCi ates] {ALL
spool idl [SPOOl id2
}
E
o]} ]
A,C,D,E,G
000 ]
NAME fnl NAME fn2 ...
[SYSTEM]
[TRFiles eLL
NAME fnl [NAME fn2
[US;ridJ
UCR
rRFiles fLL
NAME fnl
NAME fn2
spoolidl [SPOOlid2
{ALL
spool idl [SPOOl id2
NAME fnl NAME fn2
}
oJ
...
00
:::]} ]
A,B,C
00
General Usage Notes for PURGE
• If you specify more than one file selection criteria, processing of the PURGE
command stops upon encountering an invalid option. None of the remaining
options are processed.
276
VMjXA SP2 CP Command Reference
PURGE
Migration Notes
VMISP HPO
1. VMjXA SP has no default for selection criteria, unlike HPO which uses a
default of ALL.
2. VMjXA SP uses DR to specify all device types instead of ALL in VMjSP HPO.
3. VMjXA SP does not allow you to specify SYSTEM and spoolid on the
command line. VMjSP HPO (Release 5) users will not see this difference.
4. VMjXA SP does not support the DEST and FORCE options.
5. VMjXA SP allows room for a 7-digit response.
VMIXA SF: VMjXA SP does not allow you to specify SYSTEM and spoolid on the
command line.
Chapter 2. VMjXA SP CP Commands
277
PURGE
PURGE
Privilege Class: D, G
Use the PURGE command to remove closed spool files from the system before they
are selected for output on a real printer or punch, or before they are read by a
virtual card reader. The PURGE by spoolid command can be used to purge a file
after it has begun printing or punching on a real device; this causes printing or
punching of the file to cease, and causes the file to be purged.
Class G users can purge any spool files that they own or originate.
The class D user can purge any spool file in the system, or any files that belong to a
particular user on the system.
PURge
[SYSTEM]
l
Reader
Printer {ALL
CLass cl
CLass c2 .. .
PUnch
FORM forml [ FORM form2 .. .
l UR
dJ lReader
[ useri
~.
PrinterjlALL
CLass cl
CLass c2 ... ]
PUnch
spoolidl
spoolid2 .. .
[
. UR
FORM forml FORM form2 .. .
1
Note: You may enter a combination of classes, spoolids, and forms on the
command line.
where:
SYSTEM
allows the class D user to manipulate all files in the system, regardless of
ownership. This is not allowed with spooUd.
userid
*
is the user identification for the user whose files are to be purged.
The userid option allows the class D user to purge files that belong to any user
on the system. If you are a class G user, you can purge your own files or files
owned by another userid that you originated.
Any user, class D or class G, can purge their own files using the asterisk (*)
option. If you do not specify userid or *, the default is to purge your own files.
READER
RDR
PRINTER
PRT
PUNCH
PCH
UR
indicates which spool file queue contains the files that you want to purge. UR
indicates that all reader, printer, and punch files are to be purged.
278
VM/XA SP2 CP Command Reference
PURGE
ALL
specifies that ALL files on the queue of the device type specified (READER,
PRINTER, PUNCH, UR) are to be purged.
CLASS cl CLASS c2
designates a spool file class where cl and c2 are one-character alphanumeric
fields from A to Z or 0 to 9. All the files of the specified class or classes for the
specified device type or types will be purged.
spoolidl
purges the files of the specified spool identification, for the specified device type.
This is not valid with the SYSTEM keyword.
FORM forml FORM form2
purges all files with the specified form names or form numbers. forml and
form2 are specified as 1- to 8-characters. For the class G user, the form is the
user form name. For the class D user, the form is the user form name when you
specify * or default to your userid. Otherwise, the form is the operator form
number.
Usage Notes
1. The class D user can use the PURGE command to purge any file in the system
by specifying the SYSTEM or userid option. For example, if you issue the
following command:
PURGE SYSTEM PRINTER CLASS C
you purge all class C printer files in the system, regardless of who owns them or
who originated them.
The class D user can use the userid option to purge any file or files that are
owned by a particular user. For example, if you issue the following command:
PURGE GENUSER READER ALL
you purge all reader files owned by the userid GENUSER.
2. You can purge files using a combination of CLASS and spoolid on the same
command line. For example:
PURGE PRINTER CLASS A 1932 FORM DOCUMENT CLASS D 619
specifies that CP should purge all the command user's class A and class D
printer files, all the command user's files with form DOCUMENT, and the
command user's printer files having spoolids 1932 and 619.
3. If a command syntax error occurs when purging closed spool files from the
system, only the files encountered prior to the error are processed.
4. An active spool file (one which is being printed or punched) may only be purged
by specifying its spoolid. Printing or punching of the file will stop, and the file
will be purged.
Responses
{nnnnn~~} FILE(S) PU~ED
indicates the number of files purged.
Note: This response is suppressed if you have issued the CP SET IMSG OFF
command.
Chapter 2. VM/XA SP CP Commands
279
PURGE
Migration Notes
VMISP HPO
1. VMjXA SP has no default for selection criteria, unlike HPO which uses a
default of ALL.
2. VMjXA SP uses UR to specify all device types instead of ALL in VMjSP HPO.
3. VMjXA SP does not allow you to specify SYSTEM and spoolid on the
command line. VMjSP HPO (Release 5) users will not see this difference.
VMIXA SF: VMjXA SP does not allow you to specify SYSTEM and spoolid on the
command line.
280
VM/XA SP2 CP Command Reference
PURGEIMG
PURGE IMG
Privilege Class: A,B,C,D,E
Use the PURGE IMG command to remove system data files that contain image
libraries.
PURge
IMG
ALL
{
spoolid1 [SPOOlid2 •••
NAME fn1 NAME fn2 •••
J
}
Note: You may enter a combination of spool identification numbers and names on
the command line.
where:
IMG
specifies that image library files should be purged.
ALL
allows you to purge all image library files.
spoolid (spoolid2 •.• )
is the number used to identify the file. It specifies the file to be purged.
NAME Cn (NAME Cn2 ••• )
specifies the filename that identifies the files to be purged.
Usage Notes
1. In response to the PURGE command, CP purges the designated files unless the
files are currently in use. If a file is currently in use, CP places it in a "pending
purge" state (class P), and purges it as soon as it is no longer being used or the
system is shut down or re-IPLed.
2. To determine if a file is in a pending purge state, issue the QUERY IMG
command. If the file is in a pending purge state, CP's response will show that
the file is class "P."
3. Any combination of spoolid and NAME may be specified on the PURGE IMG
command line. For example:
PURGE IMG 1234 NAME IMAG3800 3421
will purge IMG files 1234 and 3421, and any IMG files with the filename
"IMAG3800. "
Response 1
The response from the PURGE IMG command displays the count of files purged.
{nn~~} FI lE (S) PURGED
where:
nnnn
indicates the number of files purged.
Note: This response is suppressed if you have issued the CP SET IMSG OFF
command.
Chapter 2. VM/XA SP CP Commands
281
PURGEIMG
Response 2
This response displays the count of files pending a purge and is issued· only when
pending purge files result.
{nnnn}
FILE(S) PENDING PURGE
where:
nnnn
indicates the number of the files which are purged when they are no longer in
use.
For example, in the situation where five image files exist, of which two are in use,
issue the command:
PURGE IMG ALL
The responses will be:
0003 FILES PURGED
0002 FILES PENDING PURGE
Migration Notes
VMISP HPO: This function is not provided in VMjSP HPO.
282
VM/XA SP2 CP Command Reference
PURGENLS
PURGE NLS
Privilege Class: B
Use the PURGE NLS command to purge message repository files.
PURge
NLS {ALL
}
J
NAME fn2 .•. ,
spoolid1 [SPOOlid2 .••
NAME fn1
where:
NLS
specifies that message repository files should be purged.
ALL
specifies that all message repository files should be purged.
spoolid
specifies the spool identification number of the file to be purged.
NAMEfn
specifies the name of the file to be purged.
Usage Notes
Any combination of spoolid and NAME may be specified on the PURGE NLS
command line. For example:
PURGE NLS 1234 NAME NLS101 3421
purges message repository files 1234 and 3421, and any message repository files with
the filename NLS 10 1.
Response 1
The response from the PURGE NLS command displays the count of files purged.
{nn~~} FILE(5) PURGED
where:
nonn
indicates the number of files purged.
Note: This response is suppressed if you have issued the CP SET IMSG OFF
command.
Response 2
This response displays the count of files pending a purge and is issued only when
pending purge files result.
{nnnn} FILE(S) PENDING PURGE
where:
nnnn
indicates the number of files that are purged when they are no longer in use.
Chapter 2. VM/XA SP CP Commands
283
PURGENLS
For example, say that out of five existing NLS files two are in use, and you issue the
command:
PURGE NLS ALL
The responses will be:
GGe3 FILES PURGED
GGe2 FILES PENDING PURGE
284
VM/XA SP2 CP Command Reference
PURGE NSS
PURGE NSS
Privilege Class: E
Use the PURGE NSS command to remove system data files that contain named
saved systems (NSS) and saved segments.
PURge
NSS
[ASSOCi ates] { ALL
spoolidl [SPOOlid2
NAME fnl NAME fn2
Note: You may enter a combination of spool identification numbers and names on
the command line.
where:
NSS
specifies that named saved systems (NSS) and saved segments should be purged.
ASSOCiates
specifies that the files associated with a segment space or member segment will
be purged. If you purge a segment space, its associated members are also
purged or set to pending purge or their segment space entries are compressed. If
you purge a member segment, it is purged or set to pending purge and its
associated segment spaces are purged or set to pending purge or their member
entries are compressed.
ALL
allows you to purge all NSS and saved segment files.
spoolid
is the number used to identify the file. It specifies the file to be purged. It can
be an NSS, a DCSS, a segment space, or a member saved segment.
NAMEfn
specifies the filename that identifies the file to be purged. The file can be an
NSS, a DCSS, a segment space, or a member saved segment.
Usage Notes
1. In response to the PURGE command, CP purges the designated files unless the
files are currently in use. If a file is currently in use, CP places it in a "pending
purge" state (class P), and purges it as soon as it is no longer being used or the
system is shut down or re-IPLed. If the file being purged is a member of a
segment space, the system places it in pending purge status if any user is
accessing any member of the segment space. The system purges the member
when the segment space is no longer in use.
2. If you do not specify ASSOCIATES and the target of the PURGE command is
a member saved segment, CP purges only that member. It does not purge any
other file and it does not update any segment space descriptions. If the target of
the PURGE command is a DCSS, CP purges only the DCSS. If the target of
the PURGE command is a segment space, CP purges only that segment space. It
does' not purge any other file and it does not update members of that segment
space.
Chapter 2. VM/XA SP CP Commands
285
PURGE NSS
3. To determine if a file is in a pending purge state, issue the QUERY NSS
command. If the file is in a pending purge state, CP's response will show that
the file is class "P."
4. Any combination of spoolid and NAME may be specified on the PURGE NSS
command line. For example:
PURGE NSS 1234 NAME eMS 3421
will purge NSS and saved segment files 1234 and 3421, and any NSS and saved
segment files with the filename "CMS."
Response 1
The response from the PURGE NSS command displays the count of files purged.
{nn~~} FILE (S) PURGED
where:
nnnn
indicates the number of files purged.
Note: This response is suppressed if you have issued the CP SET IMSG OFF
command.
Response 2
This response displays the count of files pending a purge and is issued only when
pending purge files result.
{nnnn}
FILE(S) PENDING PURGE
where:
nnnn
indicates the number of files which are purged when they are no longer in use.
For example, in the situation where five NSS or saved segment files exist, of which
two are in use, issue the command:
PURGE NSS ALL
The responses will be:
0003 FILES PURGED
0002 FILES PENDING PURGE
Migration Notes
VMISP HPO: This function is not provided in VM/SP HPO.
286
VM/XA SP2 CP Command Reference
PURGE TRFILES
PURGE TRFILES
Privilege Class: A,C,D,E,G
Use the PURGE TRFILES command to remove users' system trace files from the
system. System trace files are system data files created by the TRSAVE command
for CP or virtual machine tracing.
PURge
[SYSTEM] [TRFil es {ALL
NAME fn1 [NAME fn2
[
useri d:J [TRFi 1es {ALL
*
NAME fn1 [NAME fn2
spoolid1 spoolid2
...dJ
:::J1 ]
where:
SYSTEM
specifies that files should be purged regardless of who owns or originated them.
Class G users cannot use the SYSTEM option. It is invalid with the spoolid
option.
userid
*
specifies the owner of the files to be purged. System trace files cannot be purged
while they are in use. Class G users may purge only files that they own or that
they originate, and that are not in use. Class A, C, D, and E users may purge
any system trace files that are not in use.
You can specify
* to purge your own system trace files.
TRFiles
specifies that system trace files should be purged.
ALL
specifies that all system trace files should be purged.
spoolid
specifies the spool file identification number of the file to be purged. This
option is invalid with the SYSTEM option.
NAME fn
specifies the name of the file to be purged. This is the file name specified on the
command TRSAVE ... ON DASD NAMEfname ... when the trace was started.
More than one file can exist with the same filename for a given owner.
Usage Notes
1. Any combination of spoolid and NAME may be specified on the PURGE
TRFILES command line. For example:
PURGE TRF 1234 NAME GTRACE 3421
purges system trace files 1234 and 3421, and any trace files with the filename
GTRACE.
2. If you specify spoolid to purge files, the file you purge may be part of a group of
files with the same file name as that created by the TRSAVE .. ON DASD
NAMEfname .. command. If this is the case, some system trace data
information is purged.
Chapter 2. VM/XA SP CP Commands
287
PURGE TRFILES
3. If you specify the NAME option to purge files and there are multiple groups of
trace files with the same name, you may accidentally purge files you do not want
to purge. Use the QUERY TRFILES command to display all of the trace files
and determine which files you want to discard. If more than one file exists with
the same name, use spoo/id to specify the correct file to be purged and to avoid
losing data.
4. If you are authorized to use the SYSTEM option and you use it with the
NAME option, you purge all trace files in the system with the filename specified.
5. If a system trace file has a class of W (meaning the file is being written to), it is
not purged. You must issue the TRSAVE OFF, TRSAVE CANCEL, or
TRSOURCE DISABLE command to purge the class W file.
Responses
{nnnnn~~} FILE(S) PURGED
indicates the number of files purged.
Note: This response is suppressed if you have issued the CP SET IMSG OFF
command.
288
VMjXA SP2 CP Command Reference
PURGEUCR
PURGE UCR
Privilege Class: A,B,C
Use the PURGE UCR command to purge a UCR file created by the system
programmer.
PURge
UCR
ALL
NAME fnl NAME fn2
{ spoolidl [SPOOlid2 •••
000
}
J
VCR
specifies that UCR files should be purged.
ALL
allows you to purge all UCR files.
spoolid
is the numbers used to identify the file to be purged.
NAME Cn
specifies the filenames of the file to be purged.
Usage Notes
You may specify any combination of spoolid and NAME on the PURGE UCR
command line. F or example:
PURGE UCR 1234 NAME UCR101 3421
will purge UCR files 1234 and 3421, and any UCR files with the filename UCRI01.
Responses
{nn~:} FILE(S) PURGED
displays the count of files purged by the PURGE UCR command.
nnnn
indicates the number of files purged.
Note: This response is suppressed if you have issued the CP SET IMSG OFF
command.
Migration Notes
VMISP HPO: This function is not provided in VM/SP HPO.
Chapter 2. VM/XA SP CP Commands
289
QUERY
QUERY
Use the QUERY command described in this section to determine your system status
and machine configuration.
The format box below shows all of the operands available with the QUERY
command. Complete descriptions of the operands appear on the following pages, in
the same sequence as the operands appear here.
Class
Query
ABEND
B
ACCount
G
ALLOC [ ALL
]
volid! [volid2 ... ]
D
CACHE
rdev
}
rdev ...
{ rdev-rdev
CHPID yy
CMDLIMit
X. AUTO Log ]
[ AUTO Log
COMMands [cmd! cmd2 cmd3 •.. ]
CPLANGLIST
CPLANGuage
CPLEVEL
CPT Race
CPUid
DAsd RESERVE [userid]
290
VM/XA SP2 CP Command Reference
\
l
{FOR NONSPECIFIC} ] [ [ALLcodes
] ... ]
FOR \ SPECI FIC
code! code2 ...
SYSTEM
ALL
[
userid
QUERY
Query
I
'
type - ACTive
FREe
OFFline
ATTach [userid]
SYStem
ALL
....
.II(
rdev
,
-
;.
[STATUS]
rdev
rdev-rdev
[rdev rdev '"
rdev-rdev rdev-rdev •••
OAsd RESERVE [userid]
, [DAsd] volid
B
]
J
DUMP
Files
B
[SYSTEM] [[CLaSS c] [FORM form]][HOl d
'J.[XFER{USerid.}] [AVAI L]
ALL
NOHol d ,"
. ALL
,,
SYShold '
.
.
USERhold, .
D
. useri dJ [[CLaSS c] [FORM fOrm]] ~HOl d
][XFER{. useri d}'] [AVAI L]
[
*
spoolid
. NOHold.
ALL.
ALL
SYSho 1d .
USERhold:
D,G
FRames
Hold
A,B,E
[LOG]
IMG [SPOOl id ]
NAME fn
Class c
ALL
B,D
[COUNT]
A,B,C,
D,E
Chapter 2. VM/XA SP CP Commands
291
QUERY
Query
B
IOAssist
Links
G
vdev
LOGICAL {ldev
ldev-ldev
[ldev
... ] }
ldev-ldev •••
B
Any
LOGmsg
MAXSPOOL
[SYST~M]
D,G
userld
*
MAXUsers
A
MITime
A,B
MONData
C
MONitor
-
~ALL
BLock
EVent
INTerval
PARTition
RATE
....SAMPle
A,E
Any
Names
NLS [ALL
] [COUNT]
E
NAME fn
spoolid
CLass c
1dJ
NSTSPOO
i
NAME fn
[MAP]
[COUNT]
Class c
ALL
[USERS filename]
292
VM/XA SP2 CP Command Reference
E
QUERY
Query
PASSWORD
tNK
LOGON
XAUTOLOG
AUTO LOG
I
G
PATHS [TO] rdev
A,B
PF[nn]
G
PROCessors
A,B,C,E
QUICKDSP userid
Reader [SYSTEM][[CLass c][FORM form]]
[AVAIL]
Printer
PUnch
r
A,E
OLd
rxprFER {USerid}]
NOHold
ALL
ALL:
SYSho 1d TBL:
USERhol d .
D
11
D,G
Reader [userid][[CLaSS c][FORM fOrm]] [AVAIL] [HOLd
][EXPJFER {userid
Printer ~ . spoolid
.
NOHold
ALL
ALL JJ
PUnch
SYShold TBL.
.
USERhold
RECording
A,B,C,E,F
SCReen
G
SDF
A,B,C,D
E,G
SECuser
G
Set
G
SHARE userid
A,E
Chapter 2. VM/XA 8P CP Commands
293
QUERY
Query
SRM
tALL
a IABias
J DSPSlice
LDUBuf
STORBuf
DSPBuf
A,E
,
•
•
l
"
STORage
B
SYStem
TAG
[DEV]
~
f FILE
!
Printer
PUnch
CONsole
vdev
spoolid
G
l ()
I
TDisk
TDsk
B
TERMinal
G
Time
G
TRace
G
ACTiVe]
ALL
name
[ SETS
RETurns
TRFi 1es [SYSTEM]
[
294
B
[TDiSk ]
TDsk
rdev ]
[ ALL
[ALL
.] [COUNT]
NAME fn,
user; d:] [ALL
.] [COUNT]
* "
NAME fn
spool i d~
VMjXA SP2 CP Command Reference
A,C,D,E,G
QUERY
Query
TRSAVE [FOR] [CP
[10]
tracei d
]
A,C,E,G
ALL
..
TRSOurce ~ALL
A,C,E,G
tracei d
SET traceset
TYPE 10 1
GT I
DATA'
NONE
'10
..USER
UCR [ALL
NAME fn
spoolid
'us~rid
]
•
[COUNT]
A,B,C
USER~D }
{ userld
G
Users [userid]
Any
VECtor
A,B,C,E
[users]
Vi rtua 1
[Virtual]
G
CONsole
G
[Vi rtua 1] CPUS
G
[Vi rtua 1] CTCa
G
[Virtual] DAsd [DETAILS]
G
[Vi rtua 1]
vdev
} [DETAILS]
{ vdev-vdev
G
[Virtual]
{GRaf}
G
dhapter
2. VMjXA SP CP Commands
I
295
QUERY
Query
Virtual
Vi rtual
{printer'}
Prt
{punCh}
PCh
Ii
Virtual
{Reader}
Rdr
Ii
[Vi rtua1]
STORage
Ii
[Vi rtual]
TApes
Ii
[Vi rtua 1]
UR
Ii
[Vi rtua1]
VECtor
Ii
[Vi rtua 1] rSTore }
XSTorage,
Ii
V=R
B
{XSTore }[USER [USeridl]
XSTorage MAP
296
Ii
VM/XA SP2 CP Command Reference
B
QUERY ADEN))
QUERY ABEND
Privilege Class: B
Use QUERY ABEND to display the current status of the SOFT ABEND function.
Using QUERY ABEND, you can determine whether soft abends will cause full
system termination, or whether soft abends will be processed normally.
I
ABEND
Query
where:
ABEND
requests the display of the current status of the SOFT ABEND function.
Usage Notes
None.
Responses
SOFT
ABEND HARD
{ HARD
.}
aaannn
where:
SOFT
indicates that soft abends will not force full system termination; normal system
processing will continue after recovery action has been taken.
HARD
indicates that no soft abends are to attempt recovery action; all soft abends will
cause full system termination as if they were hard abends.
HARD aaannn
specifies the soft abends that you have selected to be treated as hard abends;
they will cause full system termination. The code aaannn is made up of a 3
character module name and a 3 character abend code.
Note: ABEND HARD aaannn can display up to five entries on a single output
response line.
Chapter 2. VM/XA SP CP Commands
297
QUERY ACCOUNT
QUERY ACCOUNT
Privilege Class: G
Use QUERY ACCOUNT to display the account number currently being used for
your session charges.
I
Query
ACCount
where:
ACCOUNT
requests the display of your current session account number.
Usage Notes
None.
Responses
ACCOUNT acntnum
where:
acntnum
is your current session account number.
298
VMjXA SP2 CP Command Reference
QUERY ALLOC
QUERY ALLoe
Privilege Class: D
Use QUERY ALLOC to display the number of allocated, in use, and available
cylinders for DASD volumes attached to the system.
I Query
ALLOC [ ALL
]
volidl [volid2 .•• }
where:
ALLOC
requests the display of the number of allocated, in-use, and available cylinders.
ALL
specifies that you want allocation information for all system volumes. This is
the default.
volidl (volid2 •.. )
specifies a list of one or more specific volume identifier or identifiers for which
you want information displayed.
Usage Notes
Examples of QUERY ALLOC:
QUERY ALLOC - displays information about all system volumes
QUERY ALLOC ALL - displays information about all system volumes
QUERY ALLOC VOL001 - displays information about a single system
volume whose volid is VOL001
QUERY ALLOC VOL001 DASD99 - displays information about two system
volumes whose vol ids are VOL001 and
DASD99.
Responses
DASD rdev volid type TDISK
PAGE
SPOOL
DRCT
TOTAL=nnnn
TOTAL=nnnn
TOTAL=nnnn
TOTAL=nnnn
INUSE=nnnn
INUSE=nnnn
INUSE=nnnn
INUSE=nnnn
AVAIL=nnnn
AVAIL=nnnn
AVAIL=nnnn
AVAIL=nnnn <,ACTIVE>
is displayed for each system volume.
where:
rdev
is the real device number of the CP-owned volume.
volid
is the volume identification of the
CP~owned
volume.
Chapter 2. VM/XA SP CP Commands
299
QUERY ALLOC
type
shows the DASD device type (for example, 3380).
nnnn
shows the number of cylinders allocated in each category.
<,ACTIVE>
appears on the DRCT response line if that volume contains the currently active
user directory.
Migration Notes
VMISP HPO: This function is not provided by HPO.
VMI XA SF: The < ,ACTIVE> option which appears with the volume containing
the active user directory is new.
300
VM/XA SP2 CP Command Reference
QUERY CACHE
QUERY CACHE
Privilege Class: B
Use the QUERY CACHE command to display caching status for 3880 Model 11,
13, 21 and 23 subsystems.
I Query
CACHE { rdev
}
rdev ...
rdev-rdev
where:
rdev
is the real device number of one of the devices in the subsystem.
rdev ...
is a list of real device numbers.
rdev-rdev
is a range of real device numbers.
Usage Notes
For a multiple-exposure device (3880 models 11 and 21), only the base address can
be queried. For example, to display the caching status for the cache associated with
device 340, issue:
QUERY CACHE 340
Response 1
rdev SUBSYSTEM STORAGE
ccccccccK BYTES CONFIGURED
aaaaaaaaK BYTES AVAILABLE
ooooooooK BYTES OFFLINE
ppppppppK BYTES UNAVAILABLE
is the response returned for each specified real device attached to a 3880 Model 11
subsystem.
.
where:
rdev
is the real device number of one of the devices in the subsystem.
cccccccc
is the configured size of subsystem storage in kilobytes.
aaaaaaaa
is the size in kilobytes of subsystem storage available to the storage director for
allocation.
00000000
is the size in kilobytes of subsystem storage that is not available to the storage
director for allocation. The storage space is not available because of storage
failures that occurred during attempts to transfer data from subsystem storage.
Chapter 2. VM/XA SP CP Commands
301
QUERY CACHE
PPPPPPPP
is the size in kilobytes of subsystem storage that is not available to the storage
director for allocation due to DASD exception conditions that prevent successful
completion of a transfer from subsystem storage to DASD.
Note: cccccccc, aaaaaaaa,
00000000,
and pppppppp are decimal
numbers.
Response 2
rdev CACHE {AVAILABLE } FOR SUBSYSTEM
UNAVAILABLE
ccccccccK BYTES CONFIGURED
aaaaaaaaK BYTES AVAILABLE
ooooooooK BYTES OFFLINE
ppppppppK BYTES UNAVAILABLE
is the response returned for each real device attached to a 3880 Model 21 subsystem.
where:
rdev
is the real device number of one of the devices in the subsystem.
cccccccc
is the configured size of subsystem storage in kilobytes.
aaaaaaaa
is the size in kilobytes of subsystem storage available to the storage director for
allocation.
00000000
is the size in kilobytes of subsystem storage that is not available to the storage
director for allocation. The storage space is not available because of storage
failures that occurred during attempts to transfer data from subsystem storage.
pppppppp
is the size in kilobytes of subsystem storage that is not available to the storage
director for allocation due to DASD exception conditions that prevent successful
completion of a transfer from subsystem storage to DASD.
Note: cccccccc, aaaaaaaa,
00000000,
and pppppppp are decimal numbers.
Response 3
rdev CACHE .{AVAILABLE . } FOR SUBSYSTEM
UNAVAILABL~
ccccccccK
aaaaaaaaK
ooooooooK
ppppppppK
BYTES
BYTES
BYTES
BYTES
CONFIGURED
AVAILABLE
OFFLINE
BOUND
is the response returned for each real device attached to a 3880 Model 13 subsystem.
302
VM/XA't SP2 CP Command Reference
QUERY CACHE
rdev CACHE {ACTIVATED }' FOR DEVICE
DEACTIVATED
is the response to be repeated for each device specified in the QUERY CACHE
command.
where:
rdev
is the real device number of one of the devices in the subsystem.
cccccccc
is the configured size of subsystem storage in kilobytes.
aaaaaaaa
is the size in kilobytes of subsystem storage available to the storage director for
allocation.
00000000
is the size in kilobytes of subsystem storage that is not available to the storage
director for allocation. The storage space is not available because of storage
failures that occurred during attempts to transfer data from subsystem storage.
PPPPPPPP
is the size in kilobytes of subsystem storage currently occupied by tracks that are
bound to the cache within one or more high-performance storage areas.
Note: cccccccc, aaaaaaaa,
00000000,
and pppppppp are decimal numbers.
Response 4
rdev CACHE {AVAILABLE '} FOR SUBSYSTEM
UNAVAILABLE
ccccccccK BYTES CONFIGURED
aaaaaaaaK BYTES AVAILABLE
ooooooooK BYTES OFFLINE
is the response returned for each real device attached to a 3880 Model 23 subsystem.
rdev CACHE {' ACTIVATED } FOR DEVICE
DEACTIVATED
is the response to be repeated for each device specified in the QUERY CACHE
command.
where:
rdev
is the real device number of one of the devices in the subsystem.
cccccccc
is the configured size of subsystem storage in kilobytes.
aaaaaaaa
is the size in kilobytes of subsystem storage available to the storage director for
allocation.
Chapter 2. VMjXA SP CP Commands
303
QUERY CACHE
00000000
is the size in kilobytes of subsystem storage that is not available to the storage
director for allocation. The storage space is not available because of storage
failures that occurred during attempts to transfer data from subsystem storage.
Note:
cccccccc, aaaaaaaa, and
304
VM/XA SP2 CP Command Reference
00000000
are decimal numbers.
QUERYCHPID
QUERY CHPID
Privilege Class: A, B
Use the QUERY CHPID command to display all the devices which have channel
path yy installed to them. It also displays the current status of the path as it
pertains to that device (online or offiine) .
I
Query
.I
CHPID yy
where:
yy
is the path whose device allocation information is requested.
Examples
To display all the devices on path lA type:
QUERY CHPID 1A
A typical response may be:
PATH 1A ONLINE TO DEVICES 0190, 0191, 0193
PATH 1A OFFLINE TO DEVICES 0192
Usage Notes
The QUERY CHPID command shows all devices associated with a specific channel
path. For information about which channel paths are associated with a specific
device, see the QUERY PATHS command.
Response 1
Path Status:
PATH yy {ONLINE } TO DEVICES xxxx(l)
PATH yy {OFFLINE} TO DEVICES zzzz(l)
xxxx(n)
zzzz(n)
indicates that path yy to device xxxx(1) through device xxxx(n) is logically available
(online) and path yy to device zzzz(l) through device zzzz(n) is logically unavailable
(offline).
where:
yy
is the logical path.
xxxx
zzzz
are the real device numbers.
Chapter 2. VM/XA SP CP Commands
305.
QUERYCHPID
Response 2
No Devices on Path
NO DEVICES ON PATH
yy
indicates there are no devices on the specified channel path.
where:
yy
is the path.
Response 3
Nonexistent CHPID
INVALID CHPID
yy
indicates that a nonexisting channel path ID was specified.
where:
yy
is the nonexisting channel path ID that was entered.
Response 4
Path Status:
PATH STATUS FOR DEVICE rdev: ONLINE - yl,yn OFFLINE - xl,xn
indicates the online or offline status for each channel path ID to the specified device.
where:
rdev
is the real device number.
yl,yn
are the logically online channel paths to the device.
xl,xn
are the logically offline channel paths to the device.
306
VMjXA SP2 CP Command Reference
QUERY CMDLIMIT
QUERY CMDLIMIT
Privilege Class: A, B
Use QUERY CMDLIMIT to determine the system limit value that disables the
AUTO LOG and XAUTOLOG commands. If you enter more incorrect passwords
than this system limit value, the AUTOLOG and the XAUTOLOG commands are
disabled for the remainder of your logon session.
I Query
CMDLIMit
XAUTOLog ]
[ AUTO log
where:
AUTO LOG
XAUTOLOG
requests a display showing the system limit value for the AUTOLOG and
XAUTOLOG commands. This parameter is optional.
Usage Notes
1. The SET CMDLIMIT command is used to change the system limit value for the
number of incorrect passwords for the AUTO LOG and XAUTOLOG
commands.
2. For security reasons, CP limits the number of incorrect passwords allowed in
your logon session. Each invalid password entered for an AUTOLOG or
XAUTOLOG command is counted. Once you have exceeded the limit, you
must log off and log on again to enter more AUTOLOG or XAUTOLOG
commands.
3. AUTOLOG is an accepted synonym for XAUTOLOG. The minimum
abbreviation is AUTOL.
Responses
XAUTOlOG/AUTOlOG incorrect password limit is nnn.
where:
nnn
indicates the number of incorrect passwords that can be entered before the
AUTO LOG and XAUTOLOG commands are disabled for the rest of your
logon session.
Chapter 2. VM/XA SP CP Commands
307
QUERY COMMANDS
QUERY COMMANDS
Privilege Class: Any
Use the QUERY COMMANDS command to display the commands and
DIAGNOSE codes which you are authorized to use.
I
COMMands [cmdl cmd2 cmd3 .•. ]
Query
where:
cmdl cmd2 cmd3 .•.
are the names of specific commands which you are trying to find out if you have
authorization to use.
Usage Notes
1. The same function is available via the CP COMMANDS command.
2. Some commands have more than one version, but the user may not be
authorized to use all th-:- versions of a particular command. If the system rejects
a command that is listed in the response, it is probably because the user is not
authorized to use the version that includes the operand or operands that were
entered.
3. For an indication of which versions of a command you are authorized to issue,
use "QUERY COMMANDS cmd ... ," where "cmd" is the name of the
command or commands you are interested in. You will be shown the default
IBM privilege classes of the command which you are authorized to issue.
4. You may specify any number of commands on the "QUERY COMMANDS
cmd ... " command. If a command name is entered twice, it will be displayed
twice in the response. No checking is made for duplicate entries.
Respo{lse 1
comml
comm2
comm3
comm4
comm5
comm6
diag2
diag3
diag4
diag5
diag6
comm7
diagl
diag7
indicates the commands and DIAGNOSE codes that the user is authorized to issue.
where:
CODlDlX
is the name of a command you are authorized to use.
diagx
identifies a DIAGNOSE code you are authorized to use.
308
VM/XA SP2 CP Command Reference
QUERY COMMANDS
Response 2
cmdl
cmd2
cmd3
IBMCLASS=cl,c2,c3
IBMCLASS=ANY
IBMCLASS=NONE
is the response when you specifically enter commands to check authorization for
them. The response includes one line of output for each command listed.
where:
cmdx
is the name of the command you entered on the command line.
mMCLASS = cl,c2,c3
are the IBM -defined privilege classes of this command. .
mMCLASS = ANY
indica tes that the command is a class ANY command, and all users may issue
the command.
mMCLASS = NONE
indicates that you are not authorized to issue any version of the command.
Migration Notes
VMISP HPO
1. VMjSP HPO has COMMANDS, not QUERY COMMANDS.
2. VMjXA SP allows specification of a particular command.
3. VMjXA SP commands can be up to 12 characters in length; HPO commands
can be up to 8 characters.
4. VMjXA SP does not include the
* (asterisk) in the list of commands.
Chapter 2. VM/XA SP CP Commands
309
QUERY CPLANGLIST
QUERY CPLANGLIST
Privilege Class: G
Use the QUERY CPLANGLIST command to display all the language identifiers
(langids) that can be set for CP in your virtual machine. You can use this command
to determine whether or not a certain language is valid for your virtual machine.
I Query
CPLANGLIST
where:
CPLANGLIST
specifies that information should be displayed about the system CP default
language, the issuing user's current CP language, and all other CP languages
available to the user.
Usage Notes
None.
Responses
System default language: xxxxx
User's current language: xxxxx
Other available languages: xxx xx
where:
System default language:
is the language identifier of the default language for CPo
User's current language:
is the language identifier of the language that is currently active for CP in your
virtual machine.
Other available languages:
are other available CP languages (or NONE).
310
VMjXA SP2 CP Command Reference
QUERY CPLANGUAGE
QUERY CPLANGUAGE
Privilege Class: G
Use the QUERY CPLANGUAGE command to display the language CP is currently
using to display CP messages for the virtual machine session.
I
Query
CPLANGuage
where:
CPLANGUAGE
specifies that information should be displayed about the current CP language
being used by the virtual machine.
Usage Notes
None.
Responses
language
where:
language
is the CP language currently being used by the virtual machine.
Chapter 2. VMjXA SP CP Commands
311
QUERY CPLEVEL
QUERY CPLEVEL
Privilege Class: G
Use the QUERY CPLEVEL command to determine the following CP attributes:
• Software release number
• Software service level number
• Date and time the CP system software was written to the nucleus
• Date and time the CP was last started.
I
Query
CPLEVEL
where:
CPLEVEL
displays the software release number, service level, generation date and time, and
IPL date and time.
Usage Notes
None.
Responses
VM/XA SP RELEASE r, SERVICE LEVEL ssss
GENERATED AT mm/dd/yy hh:mm:ss timezone
IPL AT mm/dd/yy hh:mm:ss timezone
where:
r
is the software release number.
SERVICE LEVEL ssss
is the software service level number. The number indicates which service tape
has been applied to the CP software; it cannot identify which individual updates
have been incorporated into CP.
GENERATED AT mm/dd/yy hh:mm:ss timezone
indicates the date and time the CP system software was written to the nucleus.
IPL mm/dd/yy hh:mm:ss timezone
indicates the date and time the CP system software was last started.
312
VMjXA SP2 CP Command Reference
QUERY CPTRACE
QUERY CPTRACE
Privilege Class: A, C, E
Use QUERY CPTRACE to display the current setting of the tracing of real system
events in the CP trace tables. This setting is specified by the SET CPTRACE
command.
Query
CPTRace [FOR rNSPECIFIC
SPECIFIC
1-
[ [ ALLcodes
] ..• ]
. _ code! code2 ...
SYSTEM
.
ALL
userid
-
where:
CPTRACE
displays'the current setting of the tracing of real system events in the CP trace
tables.
FOR NONSPECIFIC
FOR specifies which categories of trace settings are to be displayed.
NONSPECIFIC indicates the specified tracing applies to all virtual machines not
specifically set or named by a previous SET CPT RACE command.
NONSPECIFIC is the default. All virtual machines begin in the
NONSPECIFIC group. All members of the NONSPECIFIC group have the
same codes traced.
FOR
I I
SPECIFIC
SYSTEM
ALL.
userid
SPECIFIC indicates the specified tracing applies only to those virtual machines
specifically set or named by a previous SET CPT RACE command. Members of
the SPECIFIC group may each have a unique set of codes traced.
SYSTEM indicates the specified tracing applies to system work. SYSTEM
becomes a member of the SPECIFIC group even though the specified tracing
may not match the virtual machines already in the group. Therefore, SYSTEM
is similar to "userid" in that it names the work for which tracing applies, and
SYSTEM can also be a part of either the SPECIFIC or NONSPECIFIC groups.
ALL indicates the specified tracing applies to both the SPECIFIC and
NONSPECIFIC groups of virtual machines and SYSTEM.
userid indicates the specified tracing applies only to this specific virtual machine.
userid becomes a member of the SPECIFIC group, even though the specified
tracing may not match others in the group.
ALLCODES
displays the setting of all CPTRACE categories.
code! code2 .•.
is either a single 4-digit trace code or the name of a category of codes. Only the
setting of this code or category of codes is displayed.
Chapter 2. VM/XA SP CP Commands
313
QUERY CPTRACE
Usage Notes
1. The CP SET CPT RACE command determines which events are recorded.
Using QUERY CPT RACE will let you know what tracing events have been set
on or off. To check for only NONSPECIFIC categories, issue the command:
QUERY CPTRACE
To check for only SPECIFIC categories, issue the command:
QUERY CPTRACE FOR SPECIFIC
2. You can use the QUERY CPT RACE response to recreate the CPT RACE
setting at some later point. For each response line, in the order displayed, the
indicated code or category is set to ON if ENABLED or ENABLED EXCEPT,
and is set to OFF if DISABLED or DISABLED EXCEPT. In the case of
Example 4 (see "Example 4" on page 315) the CPT RACE setting can be
recreated by issuing:
SET
SET
SET
SET
SET
SET
CPTRACE
CPTRACE
CPTRACE
CPTRACE
CPTRACE
CPTRACE
FOR
FOR
FOR
FOR
FOR
FOR
NONSPECIFIC
NONSPECIFIC
NONSPECIFIC
NONSPECIFIC
NONSPECIFIC
NONSPECIFIC
OFF
ON
OFF
OFF
ON
OFF
ALLCODES
SVC
0200
3600
REALIOS
SSCH
Response 1
The QUERY CPT RACE response shows an indented hierarchy of trace categories
describing, as concisely as possible, the current CPTRACE setting. The output takes
the form:
FOR qualifier
category ENABLED/DISABLED EXCEPT
subcategory DISABLED/ENABLED EXCEPT
subcategory ENABLED/DISABLED
subcategory DISABLED/ENABLED
Response 2
For categories not specifically traced, the output is:
FOR qualifier NO SPECIFIC TRACE SET
Response 3
For a query on the SPECIFIC qualifier, when no specific tracing is in effect, the
output is:
NO SPECIFIC TRACE SET
This response is repeated for each qualifier the trace setting is to be displayed for.
In the following examples, no specific tracing is assumed unless otherwise indicated.
Examples
CPT RACE ON (or all CP TRACE entires were disabled via the command SET
CPT RACE OFF), you receive the following response for the QUERY CPT RACE
command:
FOR NONSPECIFIC
ALLCODES ENABLED (or DISABLED)
314
VMjXA SP2 CP Command Reference
QUERY CPTRACE
Example 2: All CP TRACE entries were enabled via the command SET CPTRACE
ON. If you wanted to display the setting of the REALIOS trace category after
deactivating trace for CLEAR SUBCHANNEL (X I lOOO I and X I l003 I ) via the
command SET CPT RACE OFF CSCH, you would issue the command QUERY
CPT RACE REALIOS. You would receive the following response:
FOR NONSPECIFIC
REALIOS ENABLED EXCEPT
CSCH
DISABLED
Example 3: If all CP TRACE entries were enabled via the command SET
CPT RACE ON and you wanted to disable the CP TRACE entries for
CALL-WITH -SAVE AREA (X I 2800 I ), RETURN-WITH -SAVE AREA (X I 2COO I ) ,
RUN USER (X'OAOO'), and IUCV (X'1500 ' - X ' 1511 1) via the command "SET
CPT RACE OFF CALL RET OAOO IUCV," you receive the following response for
the QUERY CPT RACE command:
FOR NONSPECIFIC
ALLCODES ENABLED EXCEPT
CALLRET DISABLED
0A00
DISABLED
IUCV
DISABLED
Example 4: All CP TRACE entries were disabled via the command SET
CPT RACE OFF. Perhaps you want to enable all the CP TRACE entries in
category SVC and REALIOS except for SVC INTERRUPTION (X 10200 I), EXIT
TO THE DISPATCHER (X'3600 ' ), and START SUBCHANNEL
(X'l030 ' - ' l033 1). You would then issue the command SET CPT RACE ON SVC
REALIOS OFF 0200 3600 SSCH. You will then receive the following responses for
the QUERY CPT RACE command:
FOR NONSPECIFIC
ALLCODES DISABLED EXCEPT
SVC
ENABLED EXCEPT
0200
DISABLED
3600
DISABLED
REALIOS ENABLED EXCEPT
SSCH
DISABLED
Example 5: All tracing is enabled for the nonspecific and disabled for BATCHl by
issuing SET CPT RACE ON and SET CPT RACE FOR BATCHl OFF. You will
receive the following response for QUERY CPT RACE for all codes:
FOR NONSPECIFIC
ALLCODES ENABLED
FOR BATCH!
ALLCODES DISABLED
Chapter 2. VMjXA SP CP Commands
315
QUERY CPTRAP
QUERY CPTRAP
VMfXA SP does not support the QUERY CPT RAP command. Equivalent
functions are provided by the following CP commands:
• QUERY TRSAVE - Displays the destination of traces defined by TRSOURCE
or displays the current status of recording for CP system tracing (traces
controlled by the SET CPTRACE command).
• QUERY TRSOURCE - Displays the current status of the various traces that
have been defined using the TRSOURCE command.
• QUERY CPT RACE - Displays the current setting of the tracing of real system
events in the CP trace tables.
In addition, the following commands may be helpful:
• TRSOURCE - Supports definitions and control of I/O, data, and guest tracing.
• TRSAVE - Specifies where CP trace data or data from traces defined by the
TRSOURCE command are to be saved. CP trace data may be saved either in
system trace files or on tape. Data from traces defined by the TRSOURCE
command may be saved only in system trace files.
• SET CPTRACE - Activates or deactivates CPT RACE entry recording of real
machine events in the CP TRACE tables.
Migration Notes
VMISP HPO: Using any abbreviation for the QUERY CPT RAP command may
result in the QUERY CPTRACE command being invoked. This results in syntax
errors on the CPT RACE command.
316
VMjXA SP2 CP Command Reference
QUERY CPUID
QUERY CPUID
Privilege Class: G
Use QUERY CPUID to display the 16-digit processor identification that is in use by
your virtual machine.
I
Query
CPUid
where:
CPUID
requests the display of the processor identification that is in use by your virtual
machine.
Usage Notes
None.
Responses
CPUID= aassssssccccdddd
where:
aa
is the version code. These two digits are set to X FF to identify that your
virtual machine is running under VM/XA SP.
I
I
ssssss
is the processor identification number. This field contains six hexadecimal digits.
This is the only part of the CPUID that can be modified by means of the CP
SET CPUID command or set by the system directory's OPTION control
statement.
eeee
is the model number. This field is set to the model number of the real machine.
dddd
is the machine check extended logout length. This field is set to X 0000
I
I •
Chapter 2. VMjXA SP CP Commands
317
QUERY DASD RESERVE
QUERY DASD RESERVE
Privilege Class: B
Use the CP QUERY DASD RESERVE command to display the status of all
reserved DASD devices that are defined as full pack mini-disks.
I Query
DAsd RESERVE [userid]
where:
userid
indicates that only DASD reserved to this user should be displayed. If this
operand is not specified, then all reserved DASD devices will be displayed. If
the userid is specified as '*', then the issuing user's ID will be used.
Usage Notes
1. Only DASD defined as full-pack minidisks with the SHARED option and an
active or pending reserve are displayed.
2. This command may be used to determine the reserve status of system DASD.
3. If either the "RESERVED BY SYSTEM" response or the "RESERVE
PENDING FOR SYSTEM" response consistently appear for the same device
over a period of time, this may indicate a problem.
Responses
DASD rdev INT REQUIRED (if the device requires intervention)
DASD rdev {CP SYSTEM} nnnn volid {RESERVED BY
}{USER USerid}
CP OWNED
RESERVE PENDING FOR SYSTEM
are the responses you receive upon the successful completion of the command. If
intervention is required, you will receive both responses.
where:
rdev
specifies the real device number of the device.
CP SYSTEM
indicates that this is a system DASD device.
CPOWNED
indicates that this is a CP-owned volume.
nnnn
specifies the number of links to this pack.
volid
is the volume ID of the DASD device. This field may be blank.
RESERVED BY
indicates that there is currently a reserve on the DASD device.
RESERVE PENDING FOR
indicates that a user (or the system) is waiting for a reserve on the DASD device.
318
VM/XA SP2 CP Command Reference
QUERY DASD RESERVE
USER userid
indicates that the real reserve is held by the system for this user.
SYSTEM
indicates that the real reserve is held by the system.
Chapter 2. VM/XA SP CP Commands
319
QUERY (REAL DEVICE)
QUERY (real device)
Privilege Class: B
Use QUERY (real device) to display the status of real devices.
Query
ACTive
FREe
OFFline
ATTach [userid]
SYStem
ALL
[STATUS]
rdev rdev
]
[ rdev-rdev rdev-rdev •.•
where:
type
is one of the following:
Type
Meaning
DAsd
TApes
UR
GRaf
Direct access storage device
Magnetic tape
Unit record devices
Display device
Channel-to-channel adapter
Requests a display of all devices and the status of real
storage.
eTCa
ALL
Note: If you want to display the status of real storage
(from the QUERY ALL command), refer to the
QUERY STORAGE command.
ACTIVE
indicates the active devices of the type specified. An active device is one that is
in use by a user or the system and is neither a FREE nor an OFFLINE device.
FREE
indicates the free devices of the type specified. A free device is one that is not
currently in use by a user or the system, and is neither an ACTIVE nor an
OFFLINE device.
OFFLINE
indicates the offline devices 'of the type specified. An offline device is neither an
ACTIVE nor a FREE device.
ATTACH (userid)
indicates the devices that are dedicated to a user on the system. If you specify a
userid, only devices attached to that user's virtual machine are indicated. If you
do not specify a userid, you receive the status of all devices dedicated to any user
on the system. Attached devices are always active.
320
VMjXA SP2 CP Command Reference
QUERY (REAL DEVICE)
SYSTEM
indicates the devices in use by the system. A system device is always active.
ALL
indicates all devices of the type specified. The status is displayed in "active,"
"free," and "offline" order, and is equivalent to the response you would receive
if you entered:
QUERY type ACTIVE
QUERY type FREE
QUERY type OFFLINE
rdev (STATUS)
displays the status of a real DASD device. The status presented indicates
whether the device is operational, nonoperational, has an equipment check, has
a channel error, or is offline.
rdev
rdev-rdev
indicates the real device address or range of real devices that are defined.
DASD volid
is the volume identification of a DASD device whose status is to be displayed.
If a volume has a nonstandard label, the reported volid is unpredictable.
Usage Notes
1. If you want to display the status of real storage, refer to the QUERY
STORAGE command.
2. SYSTEM is not a valid option for the QUERY GRAF and QUERY CTCA
commands.
3. STATUS is a valid option only for the DASD type devices.
QUERY (REAL) ACTIVE Responses
Note: If you issue the QUERY DASD volid or the QUERY UR ACTIVE
command when there are no active devices of this type, you receive one of
the following responses:
UR ACTIVE NOT FOUND
- or DASD volid NOT FOUND
where:
volid
is the volume identification specified.
If the system is using any device that is in an intervention required state when you
issue QUERY (real), you receive the following response:
type rdev INT REQ
where:
type
is the real device type.
Chapter 2. VM/XA SP CP Commands
321
QUERY (REAL DEVICE)
rdev
is the real device number.
In the previous response, "type" can be any of the following:
Type
Meaning
DASD
TAPE
RDR
PRT
PUN
Direct access storage device
Magnetic tape
Card reader
Printer
Card punch
Display device
Channel-to-channel adapter
3704 or 3705 Communications Controller
Mass Storage Controller
Any other device.
GRAF
CTCA
CTLR
MSC
DEV
The intervention required response is preceded by one of the following responses:
ACTIVE DASD Responses
DASD rdev ATTACHED TO userid vdev {R/O} val id
R/W
is displayed if the real device is dedicated to a user.
DASD rdev CP {SYSTEM} valid nnnnn •••
OWNED
- orDASD rdev CP {SYSTEM} va 1i d nnnnn {SHARED
}
OWNED
RESERVE PENDING FOR {USER USerid}
RESERVED BY
SYSTEM
is displayed if the real device is attached to the system for access as user minidisks
and/or for system paging, spooling,or temporary disk space. The difference between
the two responses is that, in the longer response, the device may be reserved (the
SHARED option is on), the device has a reserve pending, or the device is currently
reserved.
In these responses:
rdev
is the real device number.
ATTACHED
indicates the device is dedicated to a user.
userid
is the owner's virtual machine user identification.
vdev
is the virtual machine's virtual device number.
322
VM/XA SP2 CPCommand Reference
QUERY (REAL DEVICE)
RIO
RIW
is the access status for the device. R/O means read-only access, while RjW
means read-write access.
volid
is the volume label of the device.
00000
is the number of links to minidisks contained on the volume.
includes additional response information for shared and/or reserved DASD.
SYSTEM
indicates that the device is allocated to the system for use as user's minidisks.
OWNED
indicates that the device is used by the system for paging and spooling activity.
SHARED
indicates that the device is shared between multiple real and virtual systems.
RESERVE PENDING FOR
indicates that a user (or the system) is waiting for a reserve on the DASD device.
RESERVED BY
indicates that a reserve is active on the DASD device.
USER userid
indicates that the real reserve is held by the system for this user.
SYSTEM
indicates that the real reserve is held by the system.
If the device is a multiple-exposure paging subsystem, the following response is also
displayed:
rdev rdev rdev ATTACHED userid vdev vdev vdev
{RIO'} vol id
R/W
where:
rdev
is the real device number of each of the three page-mode exposures.
vdev
is the virtual device number of each of the three page-mode exposures.
volid
is the volume label of the device.
ACTIVE TAPE Responses
TAPE rdev ATTACHED userid vdev'{R/O}
R/W
is displayed if the tape drive is dedicated to a user.
- or TAPE rdev ASSIGNED SYSTEM DUMP
is displayed if the tape drive is assigned to receive system dumps.
Chapter 2. VM/XA SP CP Commands
323
QUERY (REAL DEVICE)
- or -
TAPE rdev ASSIGNED SYSTEM SPTAPE
is displayed if the tape is currently being used by the SPTAPE command for
dumping, loading, or scanning.
TAPE rdev ASSIGNED SYSTEM TRSAVE
where:
..dev
is the real device number.
userid
is the owner's virtual machine identification.
vdev
is the virtual machine's virtual device number.
RIO
R/W
is the access status for the device. RIO means read-only access, R/W means
read-write access.
SYSTEM DUMP
indicates that the tape is assigned to receive system dumps.
SYSTEM SPTAPE
indicates that the tape is currently being used by the SPTAPE command for
dumping, loading, or scanning.
SYSTEM TRSAVE
indicates that the tape is in use by the TRSAVE function.
ACTIVE READER Responses
RDR rdev ATTACHED userid vdev
indicates that the card reader is dedicated to a user.
where:
rdev
is the real device number.
userid
is the device owner's virtual machine identification.
vdev
is the virtual machine's virtual device number.
- or-
RDR rdev (STARTED) JSYSTEM'l
DRAINING~ luserid J
DRAINED
INT REQ
~
is displayed for each card reader assigned to the system for spooling activity.
324
VMjXA SP2 CP Command Reference
QUERY (REAL DEVICE)
where:
rdev
is the real device number.
STARTED
indicates that the device is available for spooling activity.
DRAINING
indicates that the device is processing a file, but upon completion the device is
drained.
DRAINED
indicates that the device is not available for spooling activity. Issue the CP
START command to activate the device.
INT REQ
indicates that the device is not ready and requires manual intervention before
spool file processing can resume.
SYSTEM
indicates that the device is available for input with user identification cards.
userid
indicates that the device is available for input and that no user identification
cards are required. All input decks are assigned to the user identified as userid.
If the card reader is currently active with a spool file, the following response is also
displayed:
RDR rdev READING userid FILE spid
where:
rdev
is the real device number.
userid
is the name of the virtual machine spool file owner.
spid
is the spool file number.
ACTIVE PRINTER Responses
{PRT} rdev ATTACHED userid vdev
indicates that the printer is dedicated to a user.
where:
rdev
is the real device number.
ATTACHED
indicates that the device is dedicated to a user.
userid
is the device owner's virtual machine identification.
vdev
is the virtual machine's virtual device number.
Chapter 2. VMjXA SP CP Commands
325
QUERY (REAL DEVICE)
PRT rdev STARTED
DRAINING
DRAINED
INT REQ
SETUP REQ
MOUNT REQ
SYST~M} CLASS
{userld
c1 ass
- or -
PRT rdev FORM form {MANUAL} {NOSEP} {N03800 }
AUTO
SEP
BEG3800
SETUP
ANY3800.
For 3800 printers only:
{PRT} rdev FLASH name IMAGE image1ib CHARS char FCB name {HOLD}
PURGE
For impact printers only (except for a 1403 without UCS feature):
{PRT} rdev {NOFOLD} IMAGE image1 i b CHARS chars [FCB {name}] [INDEX nn]
FOLD
is the response when the printer is in use as a system spooling device.
where:
rdev
is the real device number.
STARTED
indicates that the device is available for spooling activity.
DRAINING
indicates that the device is processing a file, but upon completion the device is
drained.
DRAINED
indicates that the device is not available for spooling activity. Issue the CP
START command to activate the device.
INT REQ
indicates that the device is not ready, and requires manual intervention before
spool file processing can resume.
SETUPREQ
indicates that the printer is ready to print an alignment page to allow the
operator to properiy aiign ihe forms on an impaci prinier. The operator must
hit the STOP and START buttons to print another alignment page, or enter the
START command to begin printing the entire file.
MOUNTREQ
indicates that the printer is waiting for the operator to mount a new form.
SYSTEM
indicates that the devices process files for any userid.
326
VMjXA SP2 CP Command Reference
QUERY (REAL DEVICE)
userid
indicates that the device process files only for the specified userid.
CLASS class
specifies the classes serviced by the device. An output device can service up to
eight output classes.
rdev
is the real device number.
FORM form
specifies the form that an output device can service. "form" is a 1- to 8-character
operator form number. This operand is ignored when the printer is in AUTO
mode.
MANUAL
indicates that the operator schedules output forms. Only spool files with the
form currently active on the device are processed. When the last spool file with
the current form is printed or punched, the output device stops.
AUTO
indic~tes
that the operator wants CP to schedule forms output. The currently
active form is processed first. When all files with the current form have been
printed or punched, CP automatically selects a new form for the device.
SETUP
indicates that the operator wants CP to print a page so that forms alignment can
be verified. (This option is valid only for impact printers.) The operator gets a
message indicating that the form should be set up. When the form has been set
up, the operator should press the STOP button, then the ST ART button. An
alignment page is then printed. It is the first page of the file, with letters
replaced with XIS and numbers replaced by 9's.
Each time the operator presses the STOP and START buttons after a full
alignment page is printed, another alignment page is printed. When the forms
are aligned, the operator can then issue the START command for the device.
The printer then returns to its previous mode (AUTO or MANUAL), and the
file prints in its entirety.
If neither MANUAL, AUTO, nor SETUP is specified and the printer is currently in
SETUP mode, it returns to the previous mode, AUTO or MANUAL. If no START
command has been issued with the MANUAL, AUTO, or SETUP options since a
system cold start, the default is MANUAL.
SEP
NOSEP
indicates whether you want a file separator for output files. This option is
invalid for readers.
N03800
specifies that no spool files that contain 3800 load CCWs are printed. Since
load CCWs issued to 3800 printers can take a great deal of time, this option
insures a fast output queue.
BEG3800
specifies that only spool files without 3800 load CCWs, or that contain 3800
load CCWs only at the beginning of the file, are printed on this device. This
allows the user an initial setup with which the entire file can be printed.
Chapter 2. VMjXA SP CP Commands
327
QUERY (REAL DEVICE)
ANY3800
places no restrictions on the presence or absence of 3800 load CCWs within
spool files. This option can potentially cause a slower output queue, depending
on the number of 3800 load CCWs issued by the selected spool files.
FLASH name
specifies the forms overlay negative loaded into the device.
IMAGE imageJih
specifies the name of the system image library file that contains the load images
(character sets, FCBs, graphic character modifications, or copy modifications)
that are used for printing files and separators.
CHARS chars
specifies the name of the character set or sets used when printing the separator
page.
FCB name
is the name of the forms control buffer (FCB) being used when printing the file
or the separator page.
Note:
This does not appear for 1403-type printers.
HOLD
indicates that spool files causing 3800 load checks are put in system HOLD
status.
PURGE
indicates that spool files causing 3800 load checks are deleted.
NOFOLD
FOLD
indicates whether lowercase characters are being translated (folded) in to
uppercase for printing.
INDEX nn
indicates the character position on the page at which to begin printing.
Note: This only appears for 3211 type printers.
If the device is currently active with a spool file, the following response is also
displayed:
PRT rdev PRINTING user; d FI LE spi d RECS {.~~~~l COpy [*] nnn SEQ sss
nnRM)
where:
rdev
is the real device number.
PRINTING
indicates that the device is printing a file.
userid
is the name of the virtual machine spool file owner.
FILE spid
is the spool file number.
328
VMjXA SP2 CP Command Reference
QUERY (REAL DEVICE)
RECS {nnnn }
nnnK
nnnM
is the number of records remaining for output in the file. If the number of
records is greater than 9999, this is shown as nnnK, where K is the number of
records rounded to the nearest 1000. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy (*)non
is the number of copies remaining for output, where 001 indicates the last copy.
The asterisk (*) is for the 3800 printer and indicates that the printer prints each
page nnn times before going on to the next page.
SEQ sss
is the sequence for the file on the printer.
ACTIVE PUNCH Responses
PUN rdev ATTACHED userid vdev
indicates that the punch is dedicated to a user.
where:
rdev
is the real device number.
ATTACHED
indicates that the device is dedicated to the user.
userid
is the device owner's virtual machine identification.
vdev
is the virtual machine's virtual device number.
- or -
PUN rdev STARTED
DRAINING
DRAINED
INT REQ
SETUP REQ
MOUNT REQ
CLASS
{ SYST~M:}
userld.
c1 ass
PUN rdev FORM form {MANUAL}{ NO~EP}
AUTO - SEP
indicates that the printer or punch device is attached to a user.
where:
rdev
is the real device number.
STARTED
indicates that the device is available for spooling activity.
Chapter 2. VMjXA SP CP Commands
329
QUERY (REAL DEVICE)
DRAINING
indicates that the device is processing a file, but upon completion the device will
be drained.
DRAINED
indicates that the device is not available for spooling activity. Issue the CP
START command to activate the device.
INT REQ
indicates that the device is not ready, and requires manual intervention before
spool file processing can resume.
SETUPREQ
indicates that the punch is ready to generate an alignment page to allow the
operator to properly align the forms on an impact printer. The operator must
hit the STOP or START buttons to print another alignment page, or enter the
START command to begin printing the entire file.
MOUNTREQ
indicates that the device is waiting for the operator to mount a new form.
SYSTEM
indicates that the devices process files for any userid.
userid
indicates that the device process files only for the specified userid.
CLASS class
specifies the classes serviced by the device. An output device can service up to
eight output classes.
If the device is currently active with a spool file, the following response is also
displayed:
PUN rdev PUNCHING userid FILE spid RECS{~~~~lCOPY [*]nnn SEQ sss
nnnM f
where:
rdev
is the real device number.
PUNCHING
indicates that the device is punching a file.
userid
is the name of the spool file owner.
FILE spid
is the spool file number.
RECS (nnnn )
~::!S
is the number of records remaining for output in the file. If the number of
records is greater than 9999, this is shown as nnnK, where K is the number of
records rounded to the nearest 1000. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
330
VMjXA SP2 CP Command Reference
QUERY (REAL DEVICE)
COpy (*)000
is the number of copies remaining for output, where 001 indicates the last copy.
The asterisk (*) is for the 3800 printer and indicates that the printer prints each
page nnn times before going on to the next page.
SEQ sss
is the sequence for the file on the punch.
ACTIVE GRAF Responses
GRAF rdev ATTACHED TO userid vdev
indicates that the real device is dedicated to a user.
GRAF rdev LOGON AS userid vdev
GRAF rdev DIALED TO userid vdev
indicates that a virtual machine user is logged on at the device or dialed through the
device.
where:
rdev
is the real device number.
userid
is the owner's virtual machine user identification.
vdev
is the virtual machine's virtual device number.
Note: The status of any 328x display printer may be shown in the response to the
QUERY (REAL) GRAF command.
ACTIVE GRAF/DISPLAV Responses (SNA/CCS Terminals)
vvvvvvvv CONTROLS THE FOLLOWING LUIS
luname LOGON AS userid vdev
luname DIALED TO userid vdev
where:
vvvvvvvv
identifies a VTAM service machine that is recognized by CPo Any logical units
controlled by this VTAM service machine that are logged on to or dialed in to
the system are described in the luname response lines following this line.
luoame
identifies a SNA/CCS terminal controlled by a VTAM service machine. It is the
name from the VTAM definition of the terminal as an SNA logical unit.
userid
identifies the userid of the user logged on through the SNA/CCS terminal or the
userid of the virtual machine to which the SNAjCCS terminal is dialed.
vdev
is the virtual device number of the terminal.
Chapter 2. VM/XA SP CP Commands
331
QUERY (REAL DEVICE)
1
QUERY (REAL) FREE Responses
type rdev FREE
~'... up to 4 responses per 1i ne
ENABLED
DISABLED
DRAINED
volid
.
is displayed if the real device is not in use by a user or the system.
where:
type
is the real device type.
rdev
is the real device number.
FREE
indicates that the device is available.
ENABLED
indicates that a display device is enabled for user access, but is not currently in
use.
DISABLED
indicates that a display device is disabled for user access.
DRAINED
indicates that a unit record device has been drained of system spooling activity.
volid
indicates that a DASD device is available and has the volume identified as volid
mounted.
In the above response, type is one of the following;
Type
Meaning
DASD
TAPE
RDR
PRT
PUN
Direct access storage device
Magnetic tape
Card reader
Printer
Card punch
Display device
Channel-to-channel adapter
3704 or 3705 Communications Controller
Mass storage controller
Any other device.
GRAF
CTCA
CTLR
MSC
DEV
QUERY (REAL) OFFLINE Response
type rdev OFFLINE, . . . up to 4 responses per line
is displayed for each offline device.
where:
type
is the real device type.
332
VM/XA SP2 CP Command Reference
QUERY (REAL DEVICE)
rdev
is the real device number.
OFFLINE
shows the offline status of the device.
In the above response, type is one of the following:
Type
Meaning
DASD
TAPE
RDR
PRT
PUN
GRAF
CTCA
CTLR
MSC
Direct access storage device
Magnetic tape
Card reader
Printer
Card punch
Display device
Channel-to-channel adapter ..
3704 or 3705 Communications Controller
Mass Storage Controller
Any other device.
DEV
QUERY (REAL) Miscellaneous Devices Responses
type rdev ATTACHED userid vdev
is displayed if the real device is dedicated to a user.
where:
type
is the real device type.
rdev
is the real device number.
userid
is the owner's virtual machine user identification.
vdev
is the virtual machine's virtual device number.
In the above response, type is one of the following:
Type
Meaning
CTCA
CTLR
MSC
Channel-to-channel adapter
3704 or 3705 Communications Controller
Mass Storage Controller
Any other device.
DEV
QUERY rdev STATUS Responses
In all of the following responses, rdev is the real device number by which the user
refers to the device.
When the device is ready and available, the system responds with:
DEVICE rdev OPERATIONAL
Chapter 2~ VMjXA SP CP Commands
333
QUERY (REAL DEVICE)
When the device is either disabled or not connected to the channel subsystem, the
system responds with:
DEVICE rdev NOT OPERATIONAL
When the device sense data indicates an equipment check, the system responds with:
DEVICE rdev EQUPMENT CHECK
When the device has indicated it has hardware problems, the system responds with:
rdev CHANNEL ERROR
When the device is unavailable to CP, the system responds with:
DASD rdev OFFLINE
Migration Notes
VM/SP HPO: VM/XA SP provides real device information in numerical order by
device address.
VMIXA SF
1. VM/XA SP uses GRAF rather than DISP in its response.
2. The third line in the response for impact printers is new for VM/XA SP.
334
VM/XA SP2 CP Command Reference
QUERY DUMP
QUERY DUMP
Privilege Class: B
Use QUERY DUMP to display the device number and type of the device assigned
to receive CP abnormal termination dumps, and to display the current settings of the
DUMP options.
I
Query
DUMP
where:
DUMP
requests the display of the device number and type of the device assigned to
receive system ABEND dumps, and the setting of the DUMP options.
Usage Notes
If you have assigned a device to receive CP dumps, VMjXA SP responds with the
device type and the real device number. If you have not assigned a device to receive
CP dumps, the response depends on the dump assignment made by VMjXA SP
during initialization. If VMjXA SP was able to find enough contiguous DASD
storage to assign a DASD dump, it responds to QUERY DUMP with DASD and
the real device number. If VMjXA SP was unable to find enough contiguous DASD
storage, it responds with PRINTER. PRINTER indicates that, at the time it is
ready to create the dump, VM/XA SP will assign the dump to the first printer
available in the order in which the printers were defined at initialization. If no
printers are available when VMjXA SP is ready to create the dump, the dump is not
created.
Responses
type rdev} DUMP UNIT
{
PRINTER
V=R}{IPL } [CYL
CP
NOIPL
{ ALL
nnn]
where:
type rdev
indicates the device type and the real device number of the dump device. type
can be DASD, TAPE, or PRINTER.
PRINTER
indicates that no dump device has been assigned and that VMjXA SP was
unable to find enough contiguous DASD space at initialization to assign a
DASD dump receiver. By default, when VMjXA SP is ready to create the
dump, it assigns the dump to the first printer available in the order in which the
printers were defined at initialization. If no printer is available when VM/XA
SP is ready to create the dump, no dump is created.
V=R
CP
ALL
indicates whether the entire V = R area, CP-owned pages and free storage, or all
pages in real storage will be included in your dump.
Chapter 2. VM/XA SP CP Commands
335
QUERY DUMP
IPL
NOIPL
indicates whether the system will automatically restart when the dump is
completed. NOIPL indicates that the system will enter a wait state upon
completion of the dump.
CYL non
is the number cylinders of spooling space allocated for system dumps. This
value is displayed for DASD dumps only.
Migration Notes
VMISP HPO:
1. In VM/XA SP, the response does not indicate TEMP or DUMP.
2. VM/XA SP indicates PRINTER if no dump device has been assigned.
3. The VM/XA SP response provides additional information regarding restart after
a dump and spooling space cylinders for DASD dumps.
336 VM/XA SP2 CP Command Reference
QUERY FILES
QUERY FILES
Privilege Class: D, G
Use QUERY FILES to obtain a count of reader, printer, and punch spool files. The
file counts include files that are open on virtual devices or are being processed on
real printers or punches.
Cla;:;s G users can issue QUERY FILES to'display the number of reader, printer, or
punch files that they currently own or have originated.
A class D user can issue QUERY FILES to obtain a count of all spool files in the
system, or files that belong to a particular user on the system.
Query
Files
1
[SYSTEM] r[CLass c] [FORM forml1,[HOl d
[XFER{useri d2}] [AVAIL]
llli
,NOHold
ALL,
,SYShol d
USERhold
[
useri d] [[CLaSS c] [FORM form]]'[HOl d
][XFER{useri d2},'] [AVAI L]
*,
spoolid
NOHold
ALL,
ALL
' SYShold
USERhold
where:
SYSTEM
obtains a count of all spool files in the system. The SYSTEM option is for class
D users only. It is invalid with the spoo/id option.
userid
*
is the user identification for the user whose spool files are to be queried. You
can specify userid as an asterisk (*) for information on your own files. For a
class G user, the * (asterisk) is the default. Class G users cannot specify userids
other than their own.
ALL
queries all of your files and is the default.
CLASS c
designates an existing spool file class. c is a I-character alphanumeric field from
A to Z, or 0 to 9.
spoolid
is the system-assigned spoolid number of the file that is to be queried. This
option is not valid with the SYSTEM keyword, nor can it be used if a class D
user is defaulting to SYSTEM. Class D must be used with a userid or an
asterisk (*).
FORM form
indicates that you want to count the number of spool files with the specified
form. form is I-to-8 characters. For the class G user,form is the user form
name. For the class D operator,jorm is the user form name when * is specified.
Otherwise, the form is the operator form number.
AVAIL
displays only a count of available files, not those files that are open or in use.
Chapter 2. VM/XA SP CP Commands
337
QUERY FILES
HOLD
NOHOLD
SYSHOLD
USERHOLD
indicates that you want to query about files that are in a particular HOLD
status. Specify HOLD to query files that are in user or system hold. Specify
USERHOLD to query files that only have user hold in effect; specify
SYSHOLD to query files that only have system hold in effect. Specify
NOH OLD to query files that are not in user or system hold.
A file that is in hold status can not be processed by a spooling device; you can
use the CP CHANGE command to alter the file's hold status.
XFER
{~~~d2
}
XFER userid2 allows you to query the number of spool files that you originated,
and which are currently owned by the user specified by the userid. XFER ALL
allows you to query the total number of spool files originated by you.
Usage Notes
If the userid option is used with the XFER option by a class D user, then the userid
option is treated as the origin id of the files. The result will be a count of the files
originated by the first user, and will include those files currently owned by the user
but specified after the XFER option.
For example, if a class D user issues the command:
QUERY FILES USERl
a count is returned of the files that USERl currently owns.
If a class D user issues the command:
QUERY FILES XFER USER2
a count is returned of the files that USER2 currently owns, but which USER2 did
not originate.
If a class D user issues the command:
QUERY FILES USERl XFER USER2
a count is returned of the files that USERl originated, but which are currently
owned by USER2.
Responses
F or the class D user:
FI LES: {nnnnn~~} RDR, {"nnnn~~} PRT, {nnnnn~~} PUN
where nnnnnnn is the number of spool files of each type.
F or the class G user:
FILES:
{nn~~}
RDR,
{nn~~}
PRT,
{nn~~} PUN
where nnnn is the number of spool files of each type.
338
VMjXA SP2 CP Command Reference
QUERY FILES
Migration Notes
VMISP HPO
1. VM/XA SP does not allow users to specify SYSTEM and spoolid on the same
command line. VM/SP HPO (Release 5) users do not see this difference.
2. VM/XA SP does not support the DEST option.
3. VMjXA SP allows room for a 7-digit response.
VMIXA SF: VM/XA SP does not allow users to specify SYSTEM and spoolid on
the same command line.
Chapter 2. VM/XA SP CP Commands
339
QUERY FRAMES
QUERY FRAMES
Privilege Class: A,B,E
Use QUERY FRAMES to display the status of real storage.
I Query
FRames
where:
FRAMES
displays the status of real storage.
Usage Notes
None.
Responses
SYSGEN
nnnnn
REAL
nnnnn
USABLE
nnnnn
OFFLINE
nnnnn
V=R
nnnnn
RESNUC PAGING
nnnnn nnnnn
TRACE
nnnnn
RI0370
AVAIL
nnnnn
PAGNUC LOCKRS
nnnnn nnnnn
LOCKCP
nnnnn
SAVE
nnnnn
nnnnn
FREE LOCKRIO
nnnnn nnnnn
where:
nnnnn
is the number of 4K (4096 byte) frames.
SYSGEN
is the number of frames specified at system generation.
REAL
is the number of 4K frames of storage within the addressing capability of the
processor.
USABLE
is the number of frames of usable storage.
OFFLINE
is the number of frames not configured and frames taken offline because of
error.
Note: If SYSGEN < REAL and SYSGEN = USABLE + OFFLINE, it is
because pages below SYSGEN have been assigned to the hardware.
The second line of the response provides a breakdown of usable storage.
V=R
is the number of frames of virtual = real
0' = R) area allocated, if any.
RESNUC
is the number of frames in the resident CP nucleus.
PAGING
is the number of frames available for paging.
340
VMjXA SP2 CP Command Reference
QUERY FRAMES
FREE
is the number of frames currently in use by the free storage management
routines.
TRACE
is the number of frames in the internal CP trace table.
RI0370
is the number of frames allocated for the RI0370 area, if any were requested at
system generation. These frames are reserved for use by the DIAGNOSE XI 98 1
page lock function for virtual machines running in 24-bit addressing mode. If
this value is 0, programs funning in 24-bit addressing mode may not use
DIAGNOSE XI 98 1 • If you issue the UNLOCK RI0370 command, this area is
deallocated and its frames are added to the AVAILABLE list.
The third line of the response provides the current breakdown of the use of storage
in the PAGING area.
AVAIL
is the number of frames available for use; that is, frames that are not any of the
following types:
PAGNUC
is the number of frames currently in use by the pageable portion of the CP
nucleus.
LOCKRS
is the number of frames currently locked for I/O operations.
LOCKCP
is the number of frames currently locked using the CP LOCK command.
EXTEND
is the number of frames allocated as an extension of the FREE storage area.
SAVE
is the number of frames currently in use by the save area manager for
dynamic save areas or CPEBKs.
LOCKRIO
is the number of frames in the RI0370 area currently in use by DIAGNOSE
XI 98 1 • If an RI0370 area exists with no frames in use, you may deallocate
the area by issuing the UNLOCK RI0370 command. The difference
between RI0370 and LOCKRIO is the number of frames still available to
satisfy additional lock requests.
The following relationships hold:
USABLE
USABLE
PAGING
RI0370
+ OFFLINE
= REAL (or SYSGEN, whichever is less)
= V=R + RESNUC + PAGING + TRACE + RI0370
= AVAIL + PAGNUC + LOCKRS + LOCKCP + SAVE + FREE
= LOCKRIO + (RI0370 area frames that are not in use)
Note that frames used to satisfy DIAGNOSE X 198 1 lock requests for 370-XA
mode virtual machines are part of the normal PAGING area and are counted as
LOCKRS frames.
Chapter 2. VM/XA SP CP Commands
341
QUERY FRAMES
Migration Notes
VMIXA SF: This information was previously given by the QUERY STORAGE
command.
342
VM/XA SP2 CP Command Reference
QUERY HOLD
QUERY HOLD
Privilege Class: B, D
Use the QUERY HOLD command to display a list of users whose output has been
placed in system HOLD status, or who have been placed in logon HOLD status.
If you are a class B user, you can display logon HOLD information. If you are a
class D user, you can display output HOLD data. If you have both privilege classes,
you can display either logon HOLD or output HOLD information.
I
Hold
Query
[LOG]
where:
HOLD
requests a display of a list of all users whose output or logon has been placed in
system HOLD status. If you are a class B user and specify LOG, you will see
the logon HOLD information. If you are a class D user (and therefore cannot
specify LOG), you will see the output HOLD information. If you have both
privilege classes, you must specify :LOG to see the logon HOLD information.
LOG
requests a display of logon HOLD information. This option is restricted to
users with class B privileges. The logon HOLD information is displayed.
Usage Notes
Users in logon HOLD status can also have output files in HOLD status.
Response 1
HOLD:
{nnnnn~~}
PRT.
{nnnnn~~} PUN
where:
nnnnnnn
NO
is the number of files of the type indicated (PRT or PUN), or NO (if none) in
HOLD status. For the class B user, this is the number of files belonging to users
in logon HOLD status. For the class D user, this is the number of files in
system HOLD status. For a user with both class Band D, it is the combined
total.
This response is always the first of two responses issued.
Response 2
NO USERS HELD
For the command QUERY HOLD (class D), this means there are no users currently
in the output HOLD status. For the command QUERY HOLD LOG (class B), this
means there are no users currently in the logon HOLD status.
Chapter 2. VM/XA SP CP Commands
343
QUERY HOLD
Response 3
useri d - {ALL}' •••
(up to four users per line)
PRT
PUN
is displayed in response to the QUERY HOLD (class D) command for each user in
output HOLD status.
where:
userid
is the identification of the user in output HOLD status.
ALL
PRT
PUN
indicates which type of output is being held for the user. PRT for printer files
only, PUN for punch files only, and ALL for both printer and punch files.
Response 4
userid - LOG, •••
(up to four users per line)
is displayed in response to the QUERY HOLD LOG (class B) command for each
user in logon HOLD status.
where:
userid
is the identification of the user logon HOLD status.
If you have class D privileges also, any user in both logon and output HOLD status
will receive a response as follows:
useri d - LOG {ALL.}'
PRT
RUN
where:
ALL
PRT
PUN
indicates in which type of output HOLD the user may be.
Migration Notes
VMISP HPO: VM/XA SP allows for a 7-digit response.
VMIXA SF: In VM/XA SP, you must specify the LOG operand to display users
whose logon has been placed in HOLD status.
344
VM/XA SP2 CP Command Reference
QUERYIMG
QUERY IMG
Privilege Class: A,B,C,D,E
Use the QUERY IMG command to display information about image library (1M G)
files. It is equivalent to the QUERY RDR/PRT/PUN command for spool files.
Query
IMG [SPOOl id ]
NAME fn
CLass c
,ALL
[COUNT]
where:
IMG
specifies that information should be displayed on image library files. This
operand is valid only for a class A, B, C, D, or E user.
spooJid
is the system-assigned spoolid number of the file to be queried.
COUNT
displays only the number of image library files that match the criteria specified
on the command. No other information is provided.
NAMEfn
specifies the filename of the file for which information is displayed.
CLASS c
specifies the class of files to be queried. c is a I-character alphanumeric field.
The classes for these files are A and P where A indicates that the file is in the
available state and P indicates that the file is in the pending purge state.
ALL
allows you to display information on all files of the specified type. This is the
default.
Usage Notes
None
Response 1
OWNERID FILE TYPE CL RECS DATE TIME
FILENAME FI~£TYPE ORIGINID
*IMG
spid typ c nnnn mmjdd hh:mm:ss filenamefiletype originid
where:
*IMG
indicates that the file is an IMG file owned by the system. *IMG is not a
userid; it is used to indicate on what queue the file resides.
spid
is the file identification number.
typ
indicates the type of system data file. This is IMG for image library files.
Chapter 2. VM/XA SP CP Commands
345
QUERYIMG
c
is the file class. For the list of these classes, refer to the class listings on page
371.
nnnn
is the number of logical records in the spool file. If the number is greater than
9999, then the number is shown as nnnK, where K represents the number of
lines rounded to the nearest 1000. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
mm/dd
is the month and day that the file was closed. If the file has not yet been closed,
this is the date the file was opened.
hh:mm:ss
is the time the file was closed in hours:minutes:seconds. If the file has not yet
been closed, this is the time the file was opened.
filename
is the filename assigned to the file.
filetype
is the filetype (1M G) assigned to the file.
originid
is the userid of the originator of the IMG file.
Response 2
If no files as specified by the command line exist, the following response is given:
FI LES:
NO IMG
Response 3
If the COUNT option is specified on the QUERY IMG command, only the number
of image library files that match the criteria specified is displayed. The following is
the response:
FILES: {nn~~} IMG
where:
nnnn
is the number of image library files. If no files are found that match the
selection criteria, then NO replaces nnnn.
Migration Notes
VMISP HPO: This function is not provided in HPO.
VMIXA SF: The format of this response has changed.
346
VM/XA SP2 CP Command Reference
QUERY IOASSIST
QUERY IOASSIST
Privilege Class: B
Use QUERY IOASSIST to determine the status of the interpretive execution assist
for the V = R and V = F users. Class G users should use the QUERY SET command
to determine the status.
I
IOAssist
Query
where:
IOASSIST
requests a display of the status of the interpretive execution assist for all V = R
and V = F users.
Usage Notes
None.
Responses
ALL USERS SET - {ON }
OFF
IOASSIST SETTING ACTIVE
userid
ON }
{ OFF
{YNOES.}
where:
ALL USERS SET - {ON "}
" OFF
indicates the status of the interpretive execution assist for all users. When this is
set OFF, no users will use the assist. When this is set ON, the individual userid
setting determines whether the user can use the assist.
userid
indicates the userid of a V = R or V = F virtual machine.
IOASSIST SETIING { ~~ }
indicates the current status of the interpretive execution assist for this userid.
ON means that the user is eligible to use the assist if the ALL USERS SET
value is also ON. OFF means that the user is not using the assist.
The value given for "ALL USERS SET" determines what the status is for all
users, regardless of the individual userid setting. It is changed via the SET
IOASSIST ON/OFF FOR ALL command.
ACTIVE g~}
indicates whether the user was actually using the start interpretive execution
assist at the time the command was issued. It is only an instantaneous look at
the user's status.
Chapter 2. VM/XA SP CP Commands
347
QUERY LINKS
QUERY LINKS
Privilege Class: G
Use QUERY LINKS to display information about existing links to a virtual device.
I
Query
Links
vdev
where:
LINKS vdev
requests the display of information about links to the virtual device located at
virtual device number vdev.
Usage Notes
None.
Responses
userid vdev {R/W}' • . . up to four responses per line
RIO
where:
userid
is the userid of the user who has a link to the specified virtual device.
vdev
is the virtual device number by which the user (userid) refers to the device.
RIO
R/W
is the type of access the user (userid) has to the virtual device. RIO is read-only
and RjW is read-write access.
348
VM/XA SP2 CP Command Reference
QUERY LOGICAL
QUERY LOGICAL
Privilege Class: B
Use QUERY LOGICAL to display the status of logical devices.
Query
ldev
[ldev ••.
] }
{ ldev-ldev ldev-ldev .•.
ldev
ldev ...
ldev-Idev
ldev-Idev ldev-Idev .•.
requests the display of the status of the logical device at address ldev, or the
range of logical devices specified as ldev-Idev. Specify a logical device number
as an L followed by four hexadecimal digits.
Response 1
If the system is using any logical device that is in an intervention required state when
you issue QUERY LOGICAL, you receive the following response:
PRT } ldev INT REQ
{, GRAF
DEV
Response 2
If the logical device is dedicated to a user when you issue QUERY LOGICAL, you
receive the following response:
PRT } ldev ATTACHED userid vdev
{ GRAF
Response 3
If a virtual machine user is logged on at the device when you issue QUERY
LOGICAL, you receive the following response:
GRAF ldev LOGON AS userid vdev
Response 4
If the device is free when you issue QUERY LOGICAL, you receive the following
response:
GRAF} 1dey {ENABLED } .•. up to three
PRT
DISABLED
responses per line
{, DEV
Note: In the above responses, PRT refers to a printer, GRAF refers to a display
station, and DEV refers to any other device.
Migration Notes
VMIXA SF: References to DISP changed to GRAF in VM/XA SP.
Chapter 2. VM/XA SP CP Commands
349
QUERY LOGMSG
QUERY LOGMSG
Privilege Class: A,B,C,D,E,F ,0
Use QUERY LOOMSO to display the daily system log message.
I
Query
LOGmsg
where:
LOGMSG
displays the system log message.
Usage Notes
See the SET LOOMSO command for information on how to change the current
system log message.
Response 1
[nn] logmsg text
(one line is displayed for each non-nulliogmsg line)
where:
nn
is the log message line number. This value can range from 01 to 50. A line
number is displayed only if the user has class "B" privileges.
logmsg text
is the message text that has been assigned to the indicated log message line
number.
Response 2
THERE IS NO LOGMSG DATA
is displayed when no message text has been assigned to a specified log message line
number.
Migration Notes
VMISP HPO
1. The VM/XA SP response provides an initial line of header information.
2. The VM/XA SP response for class B users includes the log message line number.
350
VMjXA SP2 CP Command Reference
QUERY MAXSPOOL
QUERY MAXSPOOL
Privilege Class D, G
Use the QUERY MAXSPOOL command to display the spool file limit for the
system or for any individual user. The general user can display his own spool file
limit.
I Query
MAXSPOOL
[SYST~M'J
userld
*
where:
SYSTEM
allows the class D user to query the maximum number of files allowed in the
system.
userid
allows the class D user to query the maximum number of files allowed for the
user. Class G users can only specify their own userids.
*
allows either the class D user or the class G users to query the maximum
number of files allowed for themselves. This is the default.
Usage Notes
The user maximum spool file count is set through the SPOOLFILE directory
statement.
Responses
MAXIMUM SPOOL FILE COUNT FOR {SYST~M..} IS number
userld
indicates the maximum number of files allowed for either the system or the user,
depending on which was requested on the command.
where:
SYSTEM
userid
is the system or userid specified on the QUERY MAXSPOOL command.
number
is the maximum number of spool files allowed. If you specify SYSTEM, then
the number is the total number of files allowed in the system. If you specify a
userid, then this is the total number of files that this user is allowed to maintain.
Chapter 2. VM/XA SP CP Commands
351
QUERY MAXUSERS
QUERY MAXUSERS
Privilege Class: A
Use the QUERY MAXUSERS command to display the current limit of logged on
users.
I Query
MAXUsers
where:
MAXUSERS
requests a display of the current user logon limit.
Usage Notes
The number of users actually logged on may be greater than the maximum value
displayed. This can happen when the user logon limit is lowered to a point below
the current number of users logged on. Also, the total users could be one more than
the maximum user limit when the operator logs on and the maximum number of
users is already logged on.
Response 1
MAXUSERS = nnnnn
is the response to display the current user logon limit.
where:
nnnnn
is the maximum number of users allowed to be logged on to the system at any
one time.
Response 2
NO MAXUSERS LIMIT IS SET
is the response if no user logon limit is set.
352
VM/XA SP2 CP Command Reference
QUERY MITIME
QUERY MITIME
Privilege Class: A, B
Use QUERY MITIME to determine the current time interval settings for the
missing interrupt detector.
I
MITime
Query
where:
MITIME
requests the display of the current time interval settings for the missing interrupt
detector.
Usage Notes
1. When you issue QUERY MITIME, each current MITIME setting will be
displayed in a form similar to the one you used when you issued the SET
MITIME command to invoke the specifications.
2. When multiple responses are displayed for specific devices because of the overlap
in their range and class, the first response will take precedence, since the
command displays previous SET MITIME settings in a last-in, first-out
sequence.
Example of Multiple Responses:
Assume the valid range of DASD devices addresses is 190-400 and several SET
MITIME commands have been previously entered. If you wished to determine the
current missing interrupt time interval for DASD devices 251 and 291, you would
issue the command, QUERY MITIME. If the response was as follows:
MITIME ON
MITIME ON
MITIME ON
250-252
190-255
DASD
00:10
01:40
00:30
then the current time interval for device 251 is 10 seconds, and the current time
interval for device 291 is 30 seconds.
Responses
MITIME
ON
{ OFF
}l
devcl ass
rdev
rdev-rdev
ALL
l
[mm: 55]
where:
ON
OFF
indicates whether time intervals for the specified devices have been set on. ON
specifies that the intervals have been set; OFF specifies that time intervals have
been set off and that no monitoring for missing interrupts is being done for the
specified devices.
Chapter 2. VM/XA SP CP Commands
353
QUERY MITIME
devclass
indic'ates the device class for which you want to display the missing interrupt
detector settings. "devclass" includes DASD, TAPE, GRAF, UR, or MISC.
GRAF does not include the 328X, and UR does not include the 3800. MISC
includes 328X, 3800, and any DASD defined as a mass storage subsystem
device.
rdev
rdev-rdev
is a real device number or range or real device numbers for which you want to
display the missing interrupt detector settings.
ALL
indicates that the missing interrupt detector setting is in effect for all of your
devices.
mm:ss
indicates the time interval in minutes and seconds. The maximum value for mm
is 99, while the maximum value for ss is 59. This is only displayed if MITIME is
set ON.
Migration Notes
VMISP HPO: The VMjXA SP response provides interval settings on a single line for
each device or class of devices.
354
VM/XA SP2 CP Command Reference
QUERY MONDATA
QUERY MONDATA
Privilege Class: C
Use the QUERY MONDATA command to determine if terminal event records for
monitor include input and output from the user display device.
I
MONData
Query
where:
MONDATA
requests a display of whether the user display data is being included with the
terminal event records for monitor.
Usage Notes
To change the MONDATA option, issue the SET MONDATA command.
Responses
MONDATA {ON .}
OFF
ON indicates that input from and output to user display stations is being included
with the terminal event records. It is the responsibility of the installation to protect
the security of this data.
OFF indicates that input from and output to user display stations is not being
included with the terminal event records.
Chapter 2. VM/XA SP CP Commands
355
QUERY MONITOR
QUERY MONITOR
Privilege Class: A,E
Use the QUERY MONITOR command to display the current profile information
for monitor.
Query
MONitor
~AlL
.i-
BLock
EVent
INTerval
PARTition
RATE
SAMPle
.
-
where:
ALL
requests a display of the domain specifications for both event and sample data.
This is the default value.
BLOCK
requests a display of the current monitor block value.
EVENT
requests a display of all current settings established by the MONITOR EVENT
commands. This display will show all MONITOR EVENT controls in effect and
will show all active monitor event domain specifications. If an application
program is connected for receiving monitor records, the userid of that machine is
displayed and an indication is given if the IUCV path has been quiesced.
INTERVAL
requests a display of the current monitor sample interval value.
PARTITION
. requests a display of the current monitor partition value.
RATE
requests a display of the current monitor high frequency rate value.
SAMPLE
requests a display of all current settings established by MONITOR SAMPLE
commands. This display will show all sampling controls in effect and will show
all active monitor sample domain specifications. If an application program is
.s;onnected for receiving monitor records, the userid of that machine is displayed
and an indication is given if the IUCV path has been quiesced.
Usage Notes
1. If QUERY MONITOR or QUERY MONITOR ALL is issued, data on EVENT
monitoring is displayed first, followed by SAMPLE data.
2. Regarding the responses:
• Any leading zeros are converted to blanks
• Multiple blanks and indenting are intentional and are included for
reada bili ty.
356
VM/XA SP2 CP Command Reference
QUERY MONITOR
Examples:
For QUERY MONITOR SAMPLE:
MONITOR SAMPLE ACTIVE
INTERVAL
30 SECONDS PENDING INTERVAL 20 SECONDS
RATE
11.21 SECONDS
MONITOR DCSS NAME - MONDCSS
USER CONNECTED TO *MONITOR - USER45
MONITOR DOMAIN ENABLED
SYSTEM
DOMAIN ENABLED
PROCESSOR DOMAIN DISABLED
STORAGE DOMAIN DISABLED
USER
DOMAIN ENABLED
THE FOLLOWING USERIDS ARE ENABLED:
ABLEFOX MAINT USER01 USER02 USER03 USER04 USER05
WI LLIAMS WI LSON
I/O
DOMAIN ENABLED
THE FOLLOWING DEVICES ARE ENABLED:
01A0-01AF 08C0-08FF 0900
0934-093F 0999-1010 1030-104F
2222
3000-32FF 3400-3404
where:
SAMPLE
describes the monitor sample domain.
ACTIVE
indicates that SAMPLE monitoring is being performed.
INTERVAL 30 SECONDS
indicates that the current monitor sampling interval is set to 30 seconds.
PENDING INTERVAL 20 SECONDS
indicates that a new sampling interval of 20 seconds will take effect after the
current sampling interval has occurred.
RATE 11.21 SECONDS
indicates that high-frequency sampling is active, with a current rate of 11.21
seconds.
The first leading zero in the RATE value is converted to a blank, if applicable
(for example, 8.21 rather than 08.21).
MONITOR DCSS NAME - MONDCSS
indicates that the name of the DCSS used to collect monitor data is MONDCSS.
USER CONNECTED TO *MONITOR - USER45
indicates that USER45 is the virtual machine lD that is receiving lUCY
notification of the monitor records.
MONITOR DOMAIN ENABLED
indicates that the monitor domain is enabled.
SYSTEM DOMAIN ENABLED
indicates that the system domain is enabled.
PROCESSOR DOMAIN DISABLED
indicates that the processor domain is disabled.
STORAGE DOMAIN DISABLED
indicates that the storage domain is disabled.
Chapter 2. VM/XA SP CP Commands
357
QUERY MONITOR
USER
DOMAIN ENABLED
indicates that the user domain is enabled.
ABLEFOX MAINT USEROI USER02 USER03 USER04 USER05
WILLIAMS WILSON
indicates that there are nine users currently being monitored: ABLEFOX,
MAINT, USER01, USER02, USER03, USER04, USER05, WILLIAMS, and
WILSON.
Userids are displayed in alphabetical order.
1/0
DOMAIN ENABLED
indicates that the I/O domain is enabled.
0IAO-OIAF OSCO-OSFF 0900
0934-093F 0999-1010 1030-104F
2222 3000-32FF
3400-3404
indicates that device 0900 and device 2222 are being monitored. In addition, all
devices in the following ranges are being monitored:
01AO-01AF
OSCO-OSFF
0934-093F
0999-1010
1030-104F
3000-32FF
3400-3404
Devices are shown in ascending order.
All leading zeros, if applicable, are shown. For example, device number 3 would
be displayed as 0003.
Responses
To make it easier to find the various responses, every response is listed by option
(EVENT, SAMPLE, BLOCK, INTERVAL, PARTITION, RATE and ALL).
Response 1 (QUERY MONITOR EVENT)
If QUERY MONITOR EVENT is specified, the response is as follows:
Note: If QUERY MONITOR ALL is specified, this response is issued first,
followed by Response 2:
MONITOR EVENT {ACTIVE } BLOCK m PARTITION n
INACTIVE
MONITOR DCSS NAME - [dcssname]
USER CONNECTED TO *MONITOR - {userid}
[IUCV PATH QUIESCED]
where:
EVENT
describes the status of event monitoring.
ACTIVE
indicates that EVENT monitoring is being performed.
INACTIVE
indicates that EVENT monitoring is not being performed.
358
VMjXA SP2 CP Command Reference
QUERY MONITOR
BLOCKm
indicates the number of 4K blocks that will be accumulated before an lUCY
message is sent to the virtual machine, indicating there is event data to be read .
•
Leading zeros, if any, are removed.
PARTITION n
indicates the number of 4K blocks reserved to hold event data.
Leading zeros, if any, are removed.
dcssname
indicates the name of the DCSS that is being used. If there is no DCSS name
defined, the dcssname is specified as "NO DCSSNAME DEFINED."
userid
is the userid of the user connected to monitor.
IUCV PATH QUIESCED
indicates that monitor data collection has been temporarily suspended for both
sample and event. However, high frequency sample data continues to be
updated.
The following response lines are given based on the specifications in the event
profile:
MONITOR
DOMAIN ENABLED
PROCESSOR DOMAIN {DISABLED}
ENABLED
STORAGE
DOMAIN {DISABLED}
ENABLED
SCHEDULER DOMAIN {DISABLED}
ENABLED
Note: The following additional responses are issued only if the SCHEDULER
domain is enabled, based on the specifications for the SCHEDULER domain
in the event profile:
ALL USERS ENABLED
- or -
ALL USERS EXCEPT:
userid [userid .•. J
- or -
THE FOLLOWING USERIDS ARE ENABLED:
userid [userid ••• J
Userids are displayed in alphabetical order.
SEEKS
DOMAIN {.DISABLED}
ENABLED
Note: The following additional responses may be issued only if the SEEKS domain
is enabled, based on the specifications for the SEEKS domain in the event
profile:
ALL DEVICES ENABLED
Chapter 2. VM/XA SP CPCommands
359
QUERY MONITOR
- or -
ALL DEVICES EXCEPT:
rdev[-rdev]
- or-
THE FOLLOWING DEVICES ARE ENABLED:
rdev[-rdev]
USER
DOMAIN {DISABLED}
ENABLED
Note: The following additional responses may be issued only if the USER domain
is enabled, based on the specifications for the USER domain in the event
profile:
ALL USERS ENABLED
- or -
ALL USERS EXCEPT:
userid [userid .•• ]
- or -
THE FOLLOWING USERIDS ARE ENABLED:
userid [userid ••. ]
I/O
DOMAIN {DISABLED}
ENABLED
Note: The following additional responses may be issued only if the I/O domain is
enabled, based on the specifications for the I/O domain in the event profile:
ALL DEVICES ENABLED
- or -
ALL DEVICES EXCEPT:
rdev[-rdev]
- or -
THE FOLLOWING DEVICES ARE ENABLED:
rdev[-rdev]
Response 2 (QUERY MONITOR SAMPLE)
If QUERY MONITOR SAMPLE is specified, the response is as follows:
Note: If QUERY MONITOR ALL is specified, this response follows Response 1.
MONITOR SAMPLE {ACTIVE }
INACTIVE
INTERVAL {m MINUTES} [PENDING INTERVAL '{m MINUTES}]
n SECONDS
n SECONDS •
RATE
SECONDS} [PENDING RATE
SECONDS},]
STOP
STOP
{m
{n
MONITOR DCSS NAME - [dcssname]
USER CONNECTED to *MONITOR - {userid} [IUCV PATH QUIESCED]
360
VM/XA SP2 CP Command Reference
QUERY MONITOR
where:
SAMPLE
describes the monitor sample domain.
ACTIVE
indicates that SAMPLE monitoring is being performed.
INACTIVE
indicates that SAMPLE monitoring is not being performed.
INTERVAL {m MINUTES }
mSECONDS
describes the current monitor sampling interval, where m is the current interval
value (1-60 for MINUTES, 6-3600 for SECONDS). If an INTERVAL value
does not fall on a whole minute, the suffix SECONDS is displayed.
PENDING INTERVAL {n MINUTES}
. nSECONDS
indicates that a new sampling interval is to take effect after the current sampling
interval has occurred. If the new INTERVAL value does not fall on a whole
minute, the suffix SECONDS is displayed.
RATE {m SECONDS .}
STOP
describes the current monitor high frequency sampling rate, where m is a value
between 0.01 and 30 seconds. STOP indicates that high frequency sampling is
inactive.
PENDING RATE {n SECONDS}
STOP
indicates that a new high frequency sampling rate is to take effect after the
current high frequency sampling rate has occurred. n is a value between 0.01
and 30 seconds. STOP indicates that high frequency sampling will be inactive
when the current RATE expires.
dcssname
indicates the name of the DCSS that is being used. If there is no DCSS name
defined, the dcssname is specified as "NO DCSSNAME DEFINED."
IUCV PATH QUIESCED
indicates that monitor data collection has been temporarily suspended for
sample. However, high frequency sample data continues to be updated.
The following additional response lines are given based on the specifications in the
sample profile:
MONITOR
DOMAIN ENABLED
SYSTEM
DOMAIN ENABLED
PROCESSOR DOMAIN {DISABLED}
ENABLED
STORAGE
DOMAIN {DISABLED}
ENABLED
USER
DOMAIN {DISABLED}
ENABLED
Chapter 2. VM/XA SP CP Commands
361
QUERY MONITOR
Note: The following additional responses may be issued only if the USER domain
is enabled, based on the specifications for the USER domain in the sample
profile:
ALL USERS ENABLED
- or -
ALL USERS EXCEPT:
userid [userid ••• J
- or -
THE FOLLOWING USERIDS ARE ENABLED:
userid [userid ••• J
I/O
DOMAIN {DISABLED}
ENABLED
Note: The following additional responses may be issued only if the I/O domain is
enabled, based on the specifications for the I/O domain in the sample profile:
ALL DEVICES ENABLED
- or -
ALL DEVICES EXCEPT:
rdev[-J
- or -
THE FOLLOWING DEVICES ARE ENABLED:
rdev [-rdevJ
Response 3 (QUERY MONITOR BLOCK)
If QUERY MONITOR BLOCK is specified, the response is as follows:
MONITOR BLOCK m
where:
BLOCKm
shows the number of 4Kb blocks of event records that accumulate before an
IUCV message is sent to the virtual machine to indicate that there is event data
to be read.
Response 4 (QUERY MONITOR INTERVAL)
If QUERY MONITOR INTERVAL is specified, the response is as follows:
MONITOR INTERVAL
{m MINUTES} PENDING
n
SECONDS
INTERVAL
[m MINUTES]
n
SECONDS
where:
INTERVAL {m MINUTES }
n SECONDS
describes the current monitor sampling rate. where m is the current interval·
value (1-60 for MINUTES, 6-3600 for SECONDS). If an INTERVAL value
does not fall on a whole minute, the suffix SECONDS is displayed.
362
VM/XA SP2 CP Command Reference
QUERY MONITOR
PENDING INTERVAL
{mn SECONDS'
MINUTES}
indicates that a new sampling interval is to take effect after the current sampling
interval has occurred. If the new INTERVAL value does not fall on a whole
minute, the suffix SECONDS is displayed.
Response 5 (QUERY MONITOR PARTITION)
If QUERY MONITOR PARTITION is specified, the response is as follows:
MONITOR PARTITION
n
where:
PARTITION n
indicates the number of 4K blocks reserved to hold event data.
Response 6 (QUERY MONITOR RATE)
If QUERY MONITOR RATE is specified, the response is as follows:
MONITOR RATE
{m
SECONDS} [PENDING RATE
STOP
n SECONDS]
SECONDS
where:
RATE
{mSTOP
SECONDS}
describes the current monitor high frequency sampling rate, m is a value between
0.01 and 30 seconds. STOP indicates that high frequency sampling is inactive.
PENDING RATE
{nSTOP
SECONDS}
indicates that a new high frequency sampling rate is to take effect after the
current high frequency sampling rate has occurred, where n is a value between
0.01 and 30 seconds. STOP indicates that high frequency sampling will be
inactive when the current RATE expires.
Response 7 (QUERY MONITOR ALL)
When you issue QUERY MONITOR ALL, Response 1 and Response 2 are issued.
Chapter 2. VM/XA SP CP Commands
363
QUERY NAMES
QUERY NAMES
Privilege Class: A, B, C, D, E, F, G
Use QUERY NAMES to display a list of all the users logged on and the real or
logical device number of the display to which each user is connected.
I
Query
Names
where:
NAMES
requests a display of a list of all logged on users and the real or logical device
number of the display where the user is connected.
Usage Notes
Multiple, concurrent VTAM service machines are supported; therefore, multiple
listings of logical unit names (lunames) owned by VTAM service machines may be
displayed in the response. This portion of the QUERY NAMES response follows
the rdev /ldev listings of users connected to the system; it is only displayed if there is
an active VTAM service machine connected to the system.
Responses
userid } - {rdeV}. . •. up to four responses per line.
LOGNxxxx
DSC .
{ LOGLxxxx
ldev
VSM
- userid
userid - luname, userid -luname,
userid - luname, userid -luname, ••.
where:
userid
LOGNxxxx
LOGLxxxx
is the user identification of the virtual machine. If a user has not completed
logon processing to a real device, userid is displayed in the form LOGNxxxx,
where xxxx is the real device number of the display that being used. If a user
has not completed logon processing to a logical device, userid is displayed in the
form LOGLxxxx, where xxxx is the logical device number of the display being
used.
rdev
DSC
ldev
is the device number where the user is logged on. The device may be real (rdev)
or logical (ldev). DSC is displayed if the user is disconnected and does not have
a real display.
VSM - userid
identifies the userid of the VTAM service machine managing the following users.
364
VM/XA SP2 CP Command Reference
QUERY NAMES
userid - luname
identifies the userids and the SNA logical unit names (lunames) of their
terminals for all users accessing the system from an SNA/CCS terminal managed
by that VTAM service machine.
Migration Notes
VMISP HPO
1. The VM/XA SP response uses LOGN instead of LOGO as in VM/SP HPO.
2. The VM/XA SP response uses LOGL instead of LOGOL as in VM/SP HPO.
VMIXA SF: The VM/XA SP response uses DSC instead of DISC as in VM/XA SF.
Chapter 2. VM/XA SP CP Commands
365
QUERYNLS
QUERY NLS
Privilege Class: E
Use the QUERY NLS command to display detailed information about one or more
message repository files or to display the count of message repository files. Message
repository files are created by the system programmer.
Query
NLS [.ALL
] [COUNT]
NAME fn
spoolid
CLass c
where:
NLS
specifies that information should be displayed about message repository files.
ALL
queries all message repository files. This is the default.
spoolid
specifies the system-assigned number of the file to be queried.
NAMEfn
specifies the filename of the file or files to be queried. This is the filename
specified when the file was created. More than one file can exist with the same
filename, although only one may be class A.
CLASS c
specifies the class of files to be queried. c is a I-character alphanumeric field.
The classes for these files are A or P where A indicates that the repository file is
in the available state and P indicates that the file is in the pending purge state.
COUNT
displays only the number of message repository files that match the criteria
specified on the command.
Usage Notes
None.
Response 1
OWNERID FILE TYPE CL RECS DATE TIME
FILENAME FILETYPE ORIGINID
*NLS
1234 NLS A 0001 08/28 11:21:05 FRNCH
NLS
NLSMAINT
*NLS
9012 NLS P 0001 09/28 06:22:10 ENGLS
NLS
NLSMAINT
where:
OWNERID
indicates that the file is an NLS file owned by the system. *NLS is not a userid.
It indicates the queue on which the file resides.
FILE
is the spool file identification number.
TYPE
is always NLS and indicates a message repository file.
366
VM/XA SP2 CP Command Reference
QUERYNLS
CL
is either A or P. Class A indicates that the file is available. Class P indicates
that this file is in the pending purge state.
RECS
is the number of 4Kb pages in the file.
DATE
is the month and day that the file was closed.
TIME
is the time the file was closed in hours:minutes:seconds.
FILENAME
is the filename associated with the file.
FILETYPE
is the filetype associated with the file.
ORIGINID
is the userid of the originator of the file.
Response 2
FILES:
NO NLS
appears if none of the specified files exist.
Response 3
FILES: {""~~} NLS
appears if the COUNT option is specified on the QUERY NLS command. Only the
number of repository files that match the specified criteria is displayed.
where:
nnnn
is the number of repository files. If no files are found that match the selection
criteria, then NO replaces nnnn.
Chapter 2. VM/XA SP CP Commands
367
QUERYNSS
QUERY NSS
Privilege Class: E
Use the QUERY NSS command to display information about named saved systems
(NSS), and saved segments. It is equivalent to the QUERY RDR/PRT/PUN
command for spool files.
The format of the QUERY NSS command is:
Query
NSS[SPOOlidl
[MAP]
.NAME fn
COUNT
CLass r
ALL
[USERS fi 1ename]
where:
NSS
specifies that information should be displayed for NSS and saved segment files.
spoolid
is the spool file identification number of the file to be queried.
NAME Cn
specifies the filename of the file for which information is displayed.
CLASS c
specifies the class of files to be queried. 'c' is a I-character alphanumeric field.
The classes for these files are A, P, S, or R.
ALL
allows you to display information on all NSS and saved segment files. This is
the default.
MAP
indicates that information specific to NSS and saved segment files should be
displayed, such as beginning and ending page numbers of the saved NSS and
saved segments.
COUNT
displays only the number of files that match the criteria specified on the
command. No other information is provided.
USERS filename
displays the use rids that are actively using the NSS or saved segment.
Response 1
OWNERID FILE TYPE CL RECS DATE TIME
FILENAME FILETYPE ORIGINID
*NSS
spid type c nnnn mm/dd hh:mm:ss filename filetype originid
where:
OWNERID
indicates that the file is an NSS or saved segment file owned by the system.
*NSS is not a userid; it indicates the queue on which the file resides.
·368
VM/XA SP2CP Command Reference
QUERYNSS
FILE
is the file identification number.
TYPE
indicates the type of system data file. This is NSS for named saved system or
saved segment files.
CL
is the file class. F or the list of these classes, refer to the class listings on page
371.
RECS
is the number of logical records in the spool file. If the number is greater than
9999, then the number is shown as nnnK, where K represents the number of
lines rounded to the nearest thousandth. If the number is greater than 999 499,
then the number is shown as nnnM, where M represents the number of lines
rounded to the nearest million.
DATE
is the month and day that the file was closed. If the file has not yet been closed,
this is the date the file was opened.
TIME
is the time the file was closed in hours:minutes:seconds. If the file has not yet
been closed, this is the time the file was opened.
FILENAME
is the filename assigned to the file.
FILETYPE
is the filetype assigned to the file.
ORIGINID
is the userid of the last user to write to the file.
Response 2
If no files as specified by the command line exist, the following response is given:
FI LES :
NO NSS
Response 3 (QUERY NSS ALL MAP)
Query output with the ALL and MAP options is as follows:
Chapter 2. VM/XA SP CP Commands
369
QUERYNSS
FILE FILENAME FILETYPE MINSIZE BEGPAG ENDPAG TYPE CL HUSERS PARMREGS VMGROUP
1001 CMS
NSS
1002 USERSEG DCSS
1003 USERSEG DCSS
1004 SEG1
DCSS
1006 GCS
NSS
1009 CPSYSTM CPNSS
1010 MONSEG CPDCSS
2006 SYSTEM1 NSS
2007 SYSTEM1 NSS
2008 SYSTEM2 NSS
2009 SYSTEM3 NSS
3001 BIGSEG
3014 SEGE
DCSS-S
DCSS-M
000256K 00000
0000E
00E00
00100
N/A
00100
N/A
00100
N/A
00200
000004M 00000
00300
00600
000004M 00000
00100
N/A
000300K 00000
00300
000300K 00000
00300
000300K 00000
00300
000300K 00000
00300
00700
N/A
00700
N/A
00780
00004
00021
00FFF
001FF
001FF
001FF
002FF
00008
005FF
00FFF
00900
001FF
00008
005FF
00008
005FF
00008
005FF
00008
005FF
009FF
0077F
008FF
EW
EW
SR
SR
SR
EN
SR
EW
SW
SN
EW
SC
EW
SW
EW
SW
EW
SW
EW
SW
A 00015
00-15
NO
P 00001
R 00000
S 00000
N/A
N/A
N/A
R 00004
00-15
N/A
N/A
N/A
NO
YES
R 00000
R 00001
R 00000
NONE
N/A
OMITTED
N/A
N/A
NO
S 00000
NONE
NO
R 00000
03-08
NO
R 00000
10-10
NO
N/A
N/A
N/A
N/A
A 00000
SR A 00001
SW
where:
FILE
is the file identification number of the NSS or saved segment.
FILENAME
indicates the name of the NSS or saved segment.
FILETYPE
indicates the type of system data file. "NSS" is for a named saved system,
"CPNSS" is for a CP syste service NSS, "CPDCSS" is for a CP system service
DCSS, "DCSS" is for a segment defined without the SPACE operand,
"DCSS-S" is for a segment space for which members were defined, and
"DCSS-M" is for a member of a segment space.
MINSIZE
indicates the minimum storage size of the virtual machine into which an NSS
can be loaded. This field does not apply to a saved segment, for which "N/A" is
displayed.
nnnnnnK
000nnnM
=
=
storage size in decimal kilobytes
storage size in decimal megabytes
BEGPAG
indicates the beginning page number of one page range in the NSS or saved
segment. For a segment space, this is the beginning page number of the entire
segment space.
ENDPAG
indicates the ending page number of one page range in the NSS or saved
segment. For a segment space, this is the ending page number of the entire
segment space.
370
VMjXA SP2 CP Command Reference
QUERYNSS
TYPE
is the page descriptor code of the page range in the NSS or saved segment. It
indicates the type of virtual machine access permitted to pages in the range. See
the DEFSEG or DEFSYS commands for a more detailed discussion of page
descriptor codes. Valid codes are:
EW
EN
ER
SW
SN
SR
SC
-
exclusive read/write access
exclusive read/write access, no data saved
exclusive read-only access
shared read/write access
shared read/write access, no data saved
shared read-only access.
CP writeable pages, shared read-only access by
virtual machine, no data saved
The page range type may not apply to the entire range of a segment space;
therefore "-" is used when describing these files.
CL
indica tes the file class.
The file classes are:
Class Definition
A
indicating this system data file is in the available state. This means that the
system data file has been defined and saved. To determine whether the system
data file is in use, examine the #USERS field in the response from the
QUERY NSS command with the MAP option.
P
indicating this system data file is in the pending purge state. It will be purged
when the last virtual machine releases the NSS or saved segment, or during the
next system IPL or RESTART.
R
indicating this system data file has restricted access and is in the available
state. To determine whether it is in use, examine the #USERS field in the
response from the QUERY NSS command with the MAP option. Access to an
NSS, DCSS, or segment space name with this class requires a NAMESAVE
directory entry for the NSS, DCSS, or segment space name.
S
indicating this system data file is in the skeleton state. This means that a
DEFSEG or DEFSYS command has been executed for the system data file.
The SAVESEG or SAVESYS can now be executed to complete this system
data file.
#USERS
indicates the number of users attached to the NSS or saved segment.
PARMREGS
indicates a range of registers in which parameters are passed to the virtual
machine at IPL time. Possible values are:
m-n
displays the range of registers, where m and n are decimal integers
between 00 and 15 (inclusive) and m is less than or equal to n.
NONE
displayed when P ARM REGS = NONE was specified on the
DEFSYS command.
OMITTED indicates that the PARMREGS option was not specified on the
DEFSYS command.
N/A
displayed for a saved segment. Registers are not saved for saved
segments; therefore, this field does not apply.
Chapter 2. VMjXA SP CP Commands
371
QUERYNSS
VMGROUP
indicates, for NSS files only, whether the VMGROUP attribute was specified on
the DEFSYS command when the named saved system was created. For DCSS
files, this field is not applicable (N/ A).
Response 4 (QUERY NSS NAME MAP)
QUERY NSS NAME output with the MAP option is as follows when the named
system data file is a segment space:
FILE FILENAME FILETYPE MINSIZE BEGPAG ENDPAG TYPE CL #USERS PARMREGS VMGROUP
4111
4212
4513
3614
STUFF
PIECE1
PIECE2
PIECE3
DCSS-S
DCSS-M
DCSS-M
DCSS-M
N/A
N/A
N/A
N/A
00600
00600
00680
00700
008FF
0067F
006FF
0077F
A 00001
SR A 00000
SR A 00001
SR A 00001
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
Response 5 (QUERY NSS NAME MAP)
QUERY NSS NAME output with the MAP option is as follows when the named
system data file is a member saved segment:
FILE FILENAME FILETYPE MINSIZE BEGPAG ENDPAG TYPE CL #USERS PARMREGS VMGROUP
6513
9835
3435
7545
ITEM7
BIG
BIGGEST
BIGGER
DCSS-M
DCSS-S
DCSS-S
DCSS-S
N/A
N/A
N/A
N/A
00680
00600
00300
00600
006FF
008FF
007FF
009FF
SR A
A
A
A
00002
00000
00001
00000
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
Note that the number of users indicates only users associated with that filename.
Response 6 (QUERY NSS COUNT)
If the COUNT option is specified on the QUERY NSS command, only the number
of named saved systems that match the criteria specified is displayed. The following
is the response:
FILES: {nn~:} NSS
where:
nnnn
is the number of named saved systems. If no files are found that match the
selection criteria, then NO replaces nnnn.
Response 7 (QUERY NSS USERS SEGSPACE)
If the USERS option is specified on the QUERY NSS command for a segment space
with active users, this response follows:
372
VM/XA SP2 CP Command Reference
QUERYNSS
FILE FILENAME FILETYPE CLASS
0011 SEGSPACE DCSS-S A
USER0001 USER0002 USER0003 USER0004 USER0005 USER0006 USER0007
FILE FILENAME FILETYPE CLASS
0012 MEMSEG0 DCSS-M A
USER0011 USER0012 USER0013 USER0014 USER0015 USER0016 USER0017
USER0021 USER0022 USER0023 USER0024 USER0025 USER0026 USER0027
FILE FILENAME FILETYPE CLASS
0013 MEMSEG1 DCSS-M A
NONE
where:
FILE
is the spool ID of.the file.
FILENAME
indicates the name of the NSS or DCSS.
FILETYPE
indicates the type of system data file. NSS is for a named saved system, DCSS
is for a discontiguous saved segment, CPNSS is for CP NSS, and CPDCSS is for
a CP DCSS, DCSS-S is for a segment space, and DCSS-M is for a member
segment.
CLASS
indicates the file class. For a list of the class descriptions that apply to this
command, see page 371.
Response 8 (QUERY NSS USERS MEMSEG2)
If the USERS option is specified on the QUERY NSS command for a member
segment with active users, this response follows:
FILE FILENAME FILETYPE CLASS
1111 MEMSEG2 DCSS-M A
USER1001 USER0222 USER2203 USER2224 USER6605 USER7006 USER9097
USER2001 USER2222 USER0223 USER0224 USER6005 USER0706 USER0907
USER3001 USER8022 USER0023 USER0024 USER8065 USER0876 USER9097
FILE FILENAME FILETYPE CLASS
0011 SEGSPACE DCSS-S A
USER0081 USER8002 USER0003 USER0004 USER0005 USER0006 USER0007
Response 9 (QUERY NSS USERS PPDCSS)
If the USERS option is specified on the QUERY NSS command for a DCSS with
active users, this response follows:
FILE FILENAME FILETYPE CLASS
2222 PPDCSS DCSS
A
USER1001 USER8222 USER2203 USER2224 USER6605 USER7806 USER9097
USER2001 USER2222
Chapter 2. VM/XA SP CP Commands
373
QUERY NSS
Response 10 (QUERY NSS USERS CMSNSS)
If the USERS option is specified on the QUERY NSS command for an NSS with
active users, this response follows:
FILE FILENAME FILETYPE CLASS
3333 CMSNSS NSS
A
USER1001 USER0222 USER2203 USER2224 USER6605 USER7006 USER9097
USER2001 USER2222
Response 11 (QUERY NSS USERS XYZABC)
If the USERS option is specified on the QUERY NSS command for a nonexisting
NSS/DCSS or the NSS/DCSS is not active, this response follows:
XYZABC
NOT IN USE OR AN INVALID NSS/DCSS NAME
Migration Notes
VMISP HPO: This function is not provided by VM/SP HPO.
374
VMjXA SP2 CP Command Reference
QUERY PASSWORD
QUERY PASSWORD
Privilege Class: G
Use QUERY PASSWORD to determine whether you can include a password on the
command line of the LINK, LOGON, AUTOLOG, or XAUTOLOG commands.
PASSWORD
Query
UNK
LOGON
XAUTOLOG
AUTO LOG
J
l
where:
PASSWORD
requests a display to show whether you can include a password on a command
line for a command that requires a password.
LINK
displays whether you can include a password on a command line for the LINK
command.
LOGON
displays whether you can include a password on a command line for the
LOGON command.
AUTOLOG
XAUTOLOG
displays whether you can include a password on a command line for the
AUTOLOG or the XAUTOLOG command.
Usage Notes
1. See the SET PASSWORD command for an explanation of how to set password
suppression. The commands affected by SET PASSWORD are LINK,
LOGON, AUTO LOG, and XAUTOLOG.
2. For security reasons, the password suppression facility permits your installation
to require that issuers of the CP LINK command do not put the LINK access
mode password in the command when they issue it. Instead, the user is
prompted to enter the password, and the input field is masked.
3. If you issue QUERY PASSWORD using DIAGNOSE code X I 08 1 , you receive
one of the following return codes in your R Y register:
RC
Meaning
o
Indicates that you may enter a password on a command line.
4
Indicates that you cannot enter a password on a command line.
8
Error - invalid operands following on the command line.
Responses
LINK
} PASSWORD MUST BE ENTERED SEPARATELY
LOGON
{ XAUTOLOG/AUTOLOG
indicates that you cannot enter the access mode password on the command line.
Chapter 2. VM/XA SP CP Commands
375
QUERY PASSWORD
'LINK
.}PASSWORD MAY BE INCLUDED ON THE COMMAND LINE
LOGON
{ XAUTOLOG/AUTOLOG
indicates that you can enter the access mode password on the command line.
Migration Notes
VMISP HPO: This function is not provided in VMjSP or VMjSP HPO.
VMIXA SF: The syntax for this command is NOT upwardly compatible with the
previous release. The user must indicate specific3:11y which password suppression
facility setting is to be displayed.
376
VM/XA SP2 CP Command Reference
QUERY PATHS
QUERY PATHS
Privilege Class: A,B
Use the QUERY PATHS command to display all the paths installed to a specified
device and to display their current status, either logically online or offline.
I Query
PATHS [TO] rdev
where:
rdev
is the real device number whose path allocation information is desired.
Usage Notes
The QUERY PATHS command shows all the paths installed to a specific device.
For information about the devices associated with a specific channel path, see the
QUERY CHPID command.
Examples:
QUERY PATHS TO 192
A typical response to the above example command may be:
PATH STATUS FOR DEVICE 0192: ONLINE - 1A,30,22,10,60,40,12 OFFLINE - 11
Responses
PATH STATUS FOR DEVICE rdev: ONLINE - y1,yn OFFLINE - x1,xn
is the response for the QUERY PATHS command showing the logical online or
offline status for each channel path id to the specified device.
where:
rdev
is the real device number.
yl,yn
are the online channel paths to the device.
xl,xn
are the offline channel paths to the device.
Chapter 2. VMjXA SP CP Commands
377
QUERY PER
QUERY PER
Privilege Class: G
In VM/XA SP, the QUERY TRACE command displays the current TRACE
settings. QUERY PER is recognized as a synonym for QUERY TRACE. For
further information, please refer to QUERY TRACE.
Migration Notes
VMISP HPO
1. QUERY PER is accepted as a synonym for QUERY TRACE.
2. The VM/XA SP response returns the setting of all TRACE options instead of
those explicitly entered as HPO.
378
VM/XA SP2 CP Command Reference
QUERY PFnn
QUERY PFnn
Privilege Class: G
Use QUERY PF to display the program function key command lines associated with
a specified 3270 display device program function key.
I
Query
PF[nn]
where:
PF(nn)
requests a display of the program function command lines associated with the
program function key you designate by the value nn. The value nn is a number
from 1 (or 01) to 24. If you do not specify a value for nn, all program function
keys and their associated data lines are displayed.
Usage Notes
See the CP SET command for an explanation of how to define and use program
function keys.
Response 1
PFnn [SUBSTITU]{DELAY } pfdata
IMMED
NODISP
where:
PFnn
is the program function key number.
SUBSTITU
indicates that tokens from the input are substituted in the pfdata. Otherwise, no
substitution takes place.
DELAY
IMMED
NODISP
indicates when the program function is executed. IMMED means that the
program function is executed when you press the PF key. DELAY means that
the program function is displayed in the input area when you press the PF key.
NODISP means that the program function is executed when you press the PF
key but the function is not redisplayed on the terminal.
pfdata
is the program function command line associated with the key.
Response 2
If there is no function defined for the program function key, you receive the
following response:
PFnn UNDEFINED
Chapter 2. VM/XA SP CP Commands
379
QUERY PFnn
Migration Notes
VMIXA SF
1. The VM/XA SP response does not display saved lines under a PF key set to
RETRIEVE.
2. If QUERY PFnn is issued when all the PF keys are undefined, VM/XA SF gives
a one-line response; VM/XA SP provides one line per PF key.
380
VMjXA SP2 CP Command Reference
QUERY PROCESSORS
QUERY PROCESSORS
Privilege Class: A,B,C,E
Use the QUERY PROCESSORS command to display a list of all real processors
indicating how each real processor is being used on the system.
I
Query
PROCessors
where:
PROCESSORS
displays a list of real processors on the system.
Usage Notes
None.
Responses
PROC nn MASTER
PROC nn ALTERNATE
PROC nn DEDICATED TO userid CPU mm
where:
nn
is the real processor address.
MASTER
indicates the master processor.
ALTERNATE
indicates an alternate processor (a nondedicated processor other than the
master).
DEDICATED TO userid CPU mm
indicates the virtual CPU to which real processor nn has been dedicated. The
"userid" indicates the user who owns the virtual CPU. "mm" is the virtual
address of that CPU.
Migration Notes
VMISP HPO
1. VMjXA SP allows you to spell out the entire operand PROCESSORS.
2. The VMjXA SP response indicates whether a processor is the MASTER, an
ALTERNATE, or a DEDICATED processor.
Chapter 2 .. VM/XA SP CP Commands
381
QUERY QUICKDSP
QUERY QUICKDSP
Privilege Class: A,E
Use the QUERY QUICKDSP command to indicate whether a user has the
QUICKDSP attribute.
I Query
QUICKDSP userid
where:
userid
is the identifier of the virtual machine whose QUICKDSP setting is to be
displayed.
Usage Notes
None.
Responses
USER userid: QUICKDSP={ON}
OFF
appears to the QUERY QUICKDSP command issuer.
382
VMjXA SP2 CP Command Reference
QUERY READER/PRINTER/PUNCH
QUERY READER/PRINTER/PUNCH
Privilege Class: D, G
Use QUERY READER/PRINTER/PUNCH to display detailed information about
one or more spool files of the specified type. The display includes files that are open
on virtual devices, that are closed and on the device queue, or that are being
processed on the real printers, punches, or readers. The list of spooLfiles is displayed
in the order that they will be processed.
Class G users can obtain information about reader, printer, or punch files that they
own or originate.
The class D user can obtain information about all spool files in the system, or spool
files belonging to any user on the system.
Query
Reader [SYSTEM] [[CLass c][FORM form]] [AVAIL] [HOLd
]'[EXP]fXFER {useridlJ'
Printer
NOHold
TBL L
ALL (
PUnch
SYShold
ALL
USERhold
Reader [USeri dl,[ [CLass c] [FORM form] J [AVAI L] [HOLd
][EXP'][XFER {useri d}]
J' spool i d
NOHo 1d
TBL
ALL, ,
Pri nter ~
PUnch
SYSholdAL~
USERhold
Note: The options userid and system are permitted for class D users only.
where:
READER
RDR
PRINTER
PRT
PUNCH
PCH
displays the following information about your reader, printer, or punch files:
• Userid (of user who created the file)
• Spool file identification
• Class and originating device type
• Number of logical records in the file
• Number of copies specified for the file
• File HOLD, KEEP, and MSG status
• FORM name.
SYSTEM
allows the class D user to obtain information about all files in the system,
regardless of ownership. This is not allowed with the "spoolid" option.
Chapter 2. VM/XA SP CP Commands
383
QUERY READER/PRINTER/PUNCH
userid
*
is the user identification for the user whose spool files are to be queried. You
can specify an asterisk (*) if you are querying about your own files.
The class D user can obtain information about reader, printer, or punch spool
files that are owned by any user of the system by specifying that user's userid. If
class D users want to obtain a display about their own spool files, they must
enter their own userid or an asterisk on the command line.
CLASS c
designates an existing spool file class. "c" is a one-character alphanumeric field
from A to Z, or 0 to 9.
FORM form
indicates that you want to obtain spool file information for files with the
specified form. "form" is one to eight characters. For the class G user, "form"
is the user form name. For the class D operator, "form" is the user form name
___
1.._~
WllCll
_____
____ !C'__ "ok
yuu
<)!-'C\.iUY
0_"
(X,.
" ..1.. _____=__
Vl.UCJ. WJ.<)C,
"C' _ _ _ "
J.UJ.J.U
=_ ..1.. _____
n
.. _ _
C'_ _ _ .. _1- __
HI l.U~ U!-,~J.'I.l.UJ. J.UJ.UJ. UUJ.J.J.lIl•.-J.•
AVAIL
displays only available files, not those files which are open or in use.
spoolid
is the system-assigned number of the spool file that is to be queried. This option
is not valid with the SYSTEM keyword.
HOLD
NOHOLD
SYSHOLD
USERHOLD
indicates that you want to query about files that are in a particular hold status.
• Specify hold to query files that are in user or system hold. A file that is in
hold status cannot be processed by the spooling device. If you are a class G
user, you can change a file's user hold status by using the CP CHANGE
command; if you are a class D user, you can change the system hold status
also by using the CP CHANGE command.
• Specify NOH OLD to query files that are not in user or system HOLD.
• Specify SYSHOLD to query files that only have system HOLD in effect.
• Specify USERHOLD to query files that only have user HOLD in effect.
EXP
TBL
displays expanded information for spool files.
The information displayed is:
•
•
•
•
•
•
•
User form name and operator form number
Forms control buffer (FCB)
Name and number of the copy modification module
Flash name
Number of copies to be flashed (flash count)·
Where the 3800 LOAD CCWs are positioned within the spool file
N arne of the character set or sets.
TBL is accepted as a substitute for the EXP option.
384
VMjXA SP2 CP Command Reference
QUERY READER/PRINTER/PUNCH
ALL
displays additional information for spool files. In addition to the information
normally displayed for the reader, printer, or punch files, the following is also
displayed:
• Date and time the file was created
• Filename and file type of file (if any)
• Distribution code of the file.
Note: The form name is not displayed when you use the ALL option.
XFER {userid }
: ALL
allows you to query the number of spool files currently owned by other users
that you originated. XFER userid displays information about the spool files that
you originated, and which are currently owned by the user specified by the
userid. XFER ALL displays information about all the spool files originated by
you.
For both the class G and class D users, issuing the XFER ALL or the userid
operands in a QUERY will not change the response header, but will change the
information listed underneath the header.
Usage Notes
I. If the userid option is used with the XFER option, then the userid option is
treated as the origin id of the files. The result will be information about the files
originated by the first user and which are currently owned by the user specified
after the XFER option.
For example:
If a class D user issues the command:
QUERY PRT USER I
he will receive information about the files which USER 1 currently owns.
If a class D user issues the command:
QUERY PRT XFER USER2
he will receive information about the files which USER2 currently owns but did
not originate.
If a class D user issues the command:
QUERY PRT USERI XFER USER2
he will receive information about the files which USERI originated, but which
USER2 currently owns.
Response 1
The following response is issued when you specify QUERY RDRjPRTjPUN without
the ALL option:
For a class G user:
ORIGINID FILE CLASS RECORDS CPY HOLD FORM
userid spid a typ nnnnnnnn nnn NONE form
*nnn USER
SYS
USYS
KEEP MSG
ON ON
OFF OFF
Chapter 2. VMjXA SP CP Commands
385
QUERY READER/PRINTER/PUNCH
For a class D user:
OWNERID FILE CLASS RECORDS CPY HOLD USERFORM OPERFORM KEEP MSG
userid spid a typ nnnnnnnn nnn NONE userform operform ON ON
*nnn USER
OFF OFF
SYS
USYS
Response 2
The following response is issued when you specify QUERY RDRjPRTjPUN with
the ALL option:
ORIGINID FILE CLASS RECORDS CPY HOLD DATE TIME
NAME
TYPE
DIST
userid spid e typ nnnnnnnn nnn NONE mm/dd hh:mm:ss filename fi.letype disteode
*nnn USER
SYS
USYS
If you use the EXP option, then you receive the following response:
ORIGINID FILE CLASS RECORDS FLASH FCB MDFY FLSHC LOAD CHARS
userid spid e typ nnnnnnnn name feb mod n eee NO name name name name
BEG
ANY
Response 4
If the file is open (being created or read) on a virtual device, then the OPEN status
and the virtual device address (vdev) are displayed in place of the DATE and TIME
fields:
ORIGINID FILE CLASS RECORDS CPY HOLD DATE TIME
userid spid e typ nnnnnnnn nnn NONE OPEN- vdev
*nnn USER
SYS
USYS
NAME
TYPE
DIST
filename filetype disteode
Response 5
If the file is open (being read or created) for the SPTAPE command, then the OPEN
status and SYS are displayed in place of the DATE and TIME fields:
ORIGINID FILE CLASS RECORDS CPY HOLD DATE TIME
userid spid e typ nnnnnnnn nnn NONE OPEN- SYS
*nnn USER
SYS
USYS
NAME
TYPE
DIST
filename filetype disteode
Response 6
If a closed spool file is in the process of being printed or punched on a real output
device, then the PRT or PUN status and the number of records remaining to be
printed in the current copy are displayed in the DATE and TIME fields:
ORIGINID FILE CLASS RECORDS CPY HOLD DATE TIME
userid spid e typ nnnnnnnn nnn NONE PRT- (nnnn)
*nnn USER PUN- (nnnK)
SYS
(nnnM)
USYS
NAME
TYPE
DIST
filename filetype disteode
Note: If the number of records remaining to be printed is greater than 9999, then
nnnK will be shown, and if the number of records remaining is greater than
999499 then nnnM is shown.
386
VM/XA SP2 CP Command Reference
QUERY READER/PRINTER/PUNCH
Response 7
If a spool file is open (being read) on a real card reader, then the OPEN status and
the real device number (rdev) are displayed in place of the DATE and TIME fields:
ORIGINID FILE CLASS RECORDS CPY HOLD DATE TIME
userid spid c typ nnnnnnnn nnn NONE OPEN- rdev
*nnn USER
SYS
USYS
NAME
TYPE
DIST
filename filetype distcode
Response 8
If no files of the specified type exist, one of the following responses is given,
corresponding to the specified file type:
NO RDR FILES
- or -
NO PRT FILES
- or -
NO PUN FILES
where:
ORIGINID
OWNERID
ORIGINID heading the title line for the spool file data is altered to OWNERID
when the userid or XFER operand is used, or when a class D user is defaulting
to or specifying SYSTEM. In that event, OWNERID represents the owner of
the file.
userid
is the identification of the user who owns the file.
spid
is a system-assigned number which is used by the system to identify the file.
c
is the spool file class.
typ
shows the device type that originally produced the spool file. The type can be
RDR, PRT, PUN, CON, DMP or SYS.
nnnnnnnn
is the number of logical records contained in the file.
nnn
*nnn
is the number of copies requested for the spool file. This is shown as a 3-digit
number (nnn). The asterisk (*) indicates that the 3800 printer should print each
page from the spooled output files nnn times before going on to the next page.
NONE
USER
SYS
USYS
represents the file's HOLD status. NONE indicates there are no holds on the
file, USER indicates the file is in user hold status, SYS indicates the file is in
system hold, and USYS indicates the file is in both user and system hold.
Chapter 2. VM/XA SP CP Commands
387
QUERY READER/PRINTER/PUNCH
FORM form
is the name of the paper type as understood by the user (displayed for a class G
user).
userform
is the name of the paper type as understood by the user (displayed for a class D
user).
operform
is the name of the paper type as understood by the operator (displayed for a
class D user).
KEEP {ON }
OFF
indicates whether or not the file is retained after being processed. ON indicates
that KEEP is in effect and the file will be retained after processing, and OFF
indicates that KEEP is not in effect.
MSG {ON }
OFF
indicates whether or not messages about the file printing or punching will be
displayed. ON indicates these messages will be displayed; OFF indicates they
will not be displayed.
mm/dd
is the month and day that the file was created.
hh:mm:ss
is the time when the file was created in hours:minutes:seconds.
filename
is the filename assigned to the file (if any).
filetype
is the filetype assigned to the file (if any).
distcode
is the distribution code of the file.
FLASH name
is the name of the forms overlay frame to be superimposed on the output if
printed on a 3800 printer.
FeB name
is the name of the FCB module used in the vertical formatting of a page.
MDFYname
is the name of the copy modification module used to alter output text if printed
on a 3800 printer.
n
is the copy modification character set number.
FLSHC ccc
is the number of copies that are printed while the forms overlay frame is in place
if printed on a 3800 printer.
LOAD load
is where the 3800 LOAD CCWs are positioned within the spool file - not at all
(NO), at the beginning (BEG), or interspersed throughout the spool file (ANY).
388
VM/XA SP2 CP Command Reference
QUERY READER/PRINTER/PUNCH
CHARS char
is the name of the character set or sets used to generate output if printed on a
3800 printer.
Migration Notes
VMISP HPO
1. The VM/XA SP response provides information about open spool files.
2. The VM/XA SP response. to QUERY READER/PRINTER/PUNCH provides
additional information regarding the KEEP and MSG settings.
3. VM/XA SP supports additional options: EXP, XFER, and AVAIL.
4. VM/XA SP does not allow users to specify SYSTEM and spoolid on the same
command line. VM/SP HPO (Release 5) users do not see this difference.
5. VM/XA SP indicates page copies by an * (asterisk) in the copy count, rather
than with the FLASH name as in HPO.
6. VM/XA SP does not support the DEST and PSF options.
VMIXA SF: VMjXA SP does not allow users to specify SYSTEM and spoolid on
the same command line.
Chapter 2. VM/XA SP CP Commands
389
QUERY RECORDING
QUERY RECORDING
Privilege Class: A, B, C, E, F
Use QUERY RECORDING to determine the status of CP data collection for
ACCOUNTING and EREP records, and to determine if record retrieval is in
progress.
I
Query
RECording
where:
RECORDING
requests the status of data collection for ACCOUNTING and EREP records.
Usage Notes
1. If the PENDING indication is ON and the record count has not decreased, then
an error has probably occurred and data retrieval is not proceeding normally.
The virtual machine retrieving the records should issue a SYSTEM RESET
command and reinitiate data retrieval.
2. Class A and B users receive the status of all recording functions. Other users
will receive the status of the recording functions for which they are eligible to
retrieve data records.
Responses
RECORDING
COUNT
function {ON} nnnnn
OFF
LMT
mmm
USERID
userid
COMMUN I CA TI ON
INACTIVE
}
{ ACTIVE [PENDING]
where:
function
is the name of the recording function. ACCOUNT is the name used for
accounting records; EREP is used for error recording records.
ON
OFF
indicates whether records are being generated.
nnnnn
is the number of records pending in storage.
mmm
is the threshold limit used to calculate when the system operator and retrieving
virtual machine will be notified that uncollected records are accumulating.
userid
is the user identification of the virtual machine that is eligible to retrieve the
associated records. This user can alter selected fields in the CP recording table
by using the RECORDING command.
390
VM/XA SP2 CP Command Reference
QUERY RECORDING
COMMUNICATION
is the status of the virtual machine's communication with CP for record
retrieval. INACTIVE means that the user must initiate communication with CP
to begin record retrieval. ACTIVE means that the user has already initiated the
communication. PENDING means that CP to virtual machine communication
has been initiated and that CP has sent a record to the virtual machine for
retrieval.
Chapter 2. VMjXA SP CP Commands
391
QUERY SCREEN
QUERY SCREEN
Privilege Class: G
Use the QUERY SCREEN command to display the extended color and extended
highlighting values in effect for the virtual machine console.
SCReen
Query
Usage Notes
1. The extended color and highlighting values are set either by the SCREEN
statement in your directory entry or are set when you issue the SCREEN
command.
2. If you do not have a SCREEN directory statement in your directory entry and
you have not issued the SCREEN command during the current session, the
response to the QUERY SCREEN command is DEFAULT for the color value
and NONE for the extended highlight value.
Responses
CPOUT
INREDISP
STATAREA
color
color
color
exthilight
exthilight
exthilight
VMOUT
INAREA
color
color
exthilight
exthilight
where:
color
is the color value currently in effect for your virtual console.
exthilight
is the extended highlight value currently in effect for your virtual console.
392
VMjXA SP2 CP Command Reference
QUERYSDF
QUERY SDF
Privilege Class: A,B,C,D,E,G
Use QUERY SDF to allow a user to obtain a count of all system data files.
Query
SDF
Usage Notes
1. The count of IMG files is displayed only for class A, B, C, D, and E users.
2. The count of NSS files is displayed only for class E users.
3. The count of UCR files is displayed only for class A, B, and C users.
4. The count of NLS files is displayed only for class E users.
5. The count of TRF files is displayed only for class A, C, D, E, and G users.
6. For a class G user, only the number of TRF files that the class G user owns is
displayed.
7. QUERY SDF ALL returns the same information as QUERY SDF.
Responses
The response from the QUERY SDF command indicates the count of the different
types of system data files. The response is as follows:
where:
nnnn
is the number of system data files of this type.
Chapter 2. VM/XA SP CP Commands
393
QUERY SECUSER
QUERY SECUSER
Privilege Class: G
Use the QUERY SECUSER command to determine the identity and status of the
secondary user specified in your CONSOLE directory statement.
I
Query
SECuser
where:
SECUSER
requests a display of the identity and status of the secondary user for your
userid.
Usage Notes
None.
Response 1
SECONDARY USER userid IS DISCONNECTED
is the response if your directory entry has a secondary userid specified on the
CONSOLE statement, and that user is disconnected. If you disconnect from the
system, the result is the same as if no secondary userid were designated in your
directory entry, unless the secondary user's virtual machine handles console I/O
through the message system service, in which case secondary console support is
provided to your disconnected virtual machine. If the secondary user reconnects,
they can provide secondary console functions for your virtual machine.
Response 2
SECONDARY USER userid IS NOT LOGGED ON
is the response if your directory entry has a secondary userid specified on the
CONSOLE statement, and that user is not logged on. If you disconnect from the
system, the result is the same as if no secondary userid were designated in your
directory entry. If the secondary user logs on, they can provide secondary console
functions for your virtual machine.
Response 3
SECONDARY USER userid IS LOGGED ON
is the response if your directory entry has a secondary userid specified on the
CONSOLE statement, and that user is capable of providing secondary console
support for you. If you, the primary user, disconnect from the system, that
secondary user receives your console output until you reconnect or log off. The
secondary user may provide console input to your virtual machine or to CP on your
behalf by using the SEND command.
394
VM/XA SP2 CP Command Reference
QUERY SECUSER
Response 4
SECONDARY USER IS UNDEFINED
is the response if your directory entry has no secondary userid specified on the
CONSOLE statement. If you disconnect from the system, your console output will
be lost until you reconnect. If you have spooled your console output, it is retained in
your console spool file.
If your virtual machine requests console input while disconnected and you do not
have a functional secondary user, CP waits 15 minutes for you to reconnect. If you
do not reconnect within that time, CP logs you off the system.
Chapter 2. VMjXA SP CP Commands
395
QUERY SET
QUERY SET
Privilege Class: G
Use QUERY SET to display the status of many SET command functions.
I
Set
Query
where:
SET
requests a display of the status of the SET command functions.
Usage Notes
None.
Responses
MSG {ON }' WNG {ON }' EMSG JON (' ACNT OFF, RUN {ON }.
OFF
OFF.
CODE
OFF.
IUCV
IUCV
TEXT
OFF (
IUCV)
LINEDIT {ON }, TIMER (ON \' ISAM OFF, ECMODE ON
OFF
-
{mm:ss}
OFF
J
{OFF}
494
VM/XA SP2 CP Command Reference
~ASD
TAPE
GRAF {rom: ss} ...
UR
OFF
MISC
A,B
]
SET
SET
MODE [RETRY] {QUi et }
Record
A,F
MONData
C
G
MSG {ON
OFF }
IUCV
NOPDATA
{~~F }
G
NOTRANS {ON }
OFF
G
PAGEX {ON}
OFF
G
PASSWORD JLINK
B
{SEPARATE}.!
INCLUDE
LOGON
XAUTOLOG
AUTO LOG
PFnn [SUBSTITU][IMMed] [pfdatal#pfdata2# ... pfdatan]
DELay
NODisp
G
PFnn COpy [rdeV ]
ldev
luname
G
PFnn
RETrieve {CLEAR}
G
PFnn TAB nl [n2 ... ]
G
QUICKDsp useri d [ON .]
OFF
A
RECord
{~~F} rdev
LIMIT nn BYTE nn BIT n
[{~~D} BYTE
nn BIT
nJ
F
Chapter 2. VM/XA SP CP Commands
495
SET
SET
REServed {US;ri d}
{~~F}
A
G
RUN {ON}
OFF
SHARE userid {ABSolute
nnn%}
A
RELative nnnnn,
INITial
B
}
SHARED {ON } [FOR] { rdev
OFF
rdev-rdev
SMsg
fNOFF }
G
IUCV
SRM
IABi as
[nnn [%]
90
INITial
,
~']
A
DSPSlice minslice
}
fff[%]
}
STORBuf {aaa [%] bbb [%] ccc[%]
INITi a1
,~
LDUBuf
{ddd[%] eee[%]
INITial
,
SVC76
DSPBuf
>
{iiiii jjjjj kkkkk}
INITi a1
{~:}
G
TIMER {ON }
G
VMCONIo {IUCV}
OFF
G
OFF
REAL,
WNGtOFFN}
IUCV
496
VM/XA SP2 CP Command Reference
G
SET
General Usage Notes for SET
Use the CP QUERY SET command to determine the current settings of the
following SET command functions:
SET AUTOPOLL
SETCCWTRAN
SET CONCEAL
SET CPCONIO
SET ECMODE
SETEMSG
SET IMSG
SET IOASSIST
SET LINED IT
SET MACHINE
SET MIH
SET MSG
SET NOPDATA
SET NOTRANS
SET PAGEX
SET RUN
SET SMSG
SET SVC76
SET TIMER
SETVMCONIO
SETWNG
Use the CP QUERY command with the proper operand to determine the settings of
the following SET command functions:
SET ABEND
SET ACCOUNT
SET ACNT
SET CACHE
SET CMDLIMIT
SET CPTRACE
SET CPUID
SET DUMP
SET LOGMSG
SET MAXUSERS
SET MITIME
SET MONDATA
SET PASSWORD
SETPF
SET QUICKDSP
SET SHARE
SET SRM (DSPBUF)
SET SRM (DSPSLICE)
SET SRM (IABIAS)
SET SRM (LDUBUF)
SET SRM (STORBUF)
Chapter 2. VM/XA SP CP Commands
497
SET ABEND
SET ABEND
Privilege Class: B
Use SET ABEND to force specific soft abend codes, or all soft abend codes, to
cause full system termination.
ABEND {HARD
}
HARD aaannn •••
SOFT
where:
ABEND
indicates that you want to change system processing for soft abends.
HARD
specifies that. any soft abend will cause full system termination without
attempting system recovery.
HARD aaannn
specifies the soft abend with abend code aaannn will cause full system
termination, but other soft abends will continue to be processed normally.
You can specify up to 10 unique soft abend codes with one or more invocations
of the SET ABEND command. The codes will be inspected for format validity,
that is, three letters followed by three numbers. The nnn portion of the code is
required to be less than or equal to decimal 255. The code will not be inspected
to determine whether it corresponds to a soft abend that is actually present in
the system.
SOFT
cancels all previous specifications of HARD and HARD aaannn. All soft
abends operate normally as established during system initialization.
Usage Notes
If any invalid abend code is encountered in SET ABEND HARD aaannn aaannn ... ,
no soft abend settings are changed.
Responses
None.
498
VM/XA SP2 CP Command Reference
SET ACCOUNT
seT ACCOUNT
Privilege Class: G
Use SET ACCOUNT to change the current session account number.
I
SET
ACCount nnnnnnnn
where:
nnnnnnnn
is the 1- to 8-character account number that will replace the current session
account number.
Usage Notes
1. The account number you specify on the command line must be the same as one
contained in your entry in the system directory.
2. If the account number you specify is valid, an accounting record will be created
for your session under the current accounting number.
Responses
None.
Chapter 2. VM/XA SP CP Commands
499
SET AUTOPOLL
SET AUTOPOLL
Privilege Class: G
SET AUTOPOLL specifies how CP detects changes to virtual autopolling channel
programs: whether VM/XA SP itself tests for the change or whether your virtual
machine notifies VM/XA SP of the change. In general, the guest operating system
that notifies CP of changes to virtual autopolling channel programs issues this
command without the need for any action or intervention on your part.
I SET
where:
AUTOPOLL
AUTOPo 11 [ON:]
OFF,
[ON]
OFF
controls whether CP tests for changes to virtual autopolling channel programs.
ON indicates that your virtual machine must notify CP when a change is made
to a virtual autopolling channel program. OFF indicates that CP tests for
changes to virtual autopolling channel programs.
Usage Notes
1. In general, do not issue this command yourself. Guest operating systems that
notify CP of changes to virtual autopolling channel programs usually issue this
command themselves internally. If you do issue the command while a guest
operating system is running, you may cause the system to stop or to terminate
abnormally.
2. If SET AUTOPOLL ON is specified for your virtual machine, the operating
system running in your virtual machine must use DIAGNOSE code XI 28 1 to
notify VM/XA SP whenever a virtual autopolling channel program has been
modified. If the operating system does not issue a DIAGNOSE code X 128 1
instruction after the modification, results are unpredictable.
3. If SET AUTOPOLL OFF is specified and the operating system running in your
virtual machine uses the DIAGNOSE code XI 28 1 interface, VM/XA SP and
your virtual machine are duplicating a function. In this case, VM/XA SP is
testing for virtual autopolling channel program modification and at the same
time the virtual machine is notifying VM/XA SP whenever modification occurs.
Therefore, IBM recommends the combined use of the SET AUTOPOLL ON
command and DIAGNOSE code XI 28 to eliminate this unnecessary
duplication.
1
Responses
None.
500
VM/XA SP2 CP Command Reference
SET CACHE
SET CACHE
Privilege Class: B
Use the SET CACHE command to activate or deactivate caching by device or by
subsystem for 3880 Model 13 and 23 subsystems.
SET
CACHE {DEVICE }{ON.} [FOR] {rdev
}
SUBSYStem OFF
rdev •.•
rdev-rdev,
where:
rdev
rdev .•.
rdev-rdev
is the real device number, a list of real device numbers, or a range of real device
numbers of devices in the subsystem.
DEVICE {. ON }
OFF
DEVICE ON indicates that caching is to be activated for the specified devices.
DEVICE OFF indicates that caching is to be deactivated for the specified
devices. Any user to whom the device was attached will bypass the cache.
SUBSYSTEM {ON }
OFF
SUBSYSTEM ON indicates that caching is to be made available for the entire
subsystem to which the device is attached. SUBSYSTEM OFF indicates that
caching is to be made unavailable for the entire subsystem to which the device is
attached.
Usage Notes
1. If SET CACHE DEVICE ON is issued for a device, all minidisks that were
defined on that device in the user's directory entry with the DASDOPT or
MINIOPT statement then have access to the cache. This means that CP allows
virtual I/O to these mini disks to pass through the cache.
If SET CACHE DEVICE OFF is issued for a device, all minidisks that were
defined on that device in the user's directory entry with the MINIOPT or
DASDOPT statement no longer have access to the cache. This means that CP
forces virtual I/O to these minidisks to bypass the cache.
Example
To activate device 340 for caching, enter:
SET CACHE DEVICE ON 340
Response 1
rdev CACHE ACTIVATED FOR DEVICE
This response will be repeated for each specified device when you issue the SET
CACHE DEVICE ON rdev command.
Chapter 2. VMjXA SP CP Commands
501
SET CACHE
where:
rdev
is the real device number of the device that has been given access to the cache.
Response 2
rdev CACHE DEACTIVATED FOR DEVICE
This response will be repeated for each specified device when you issue the SET
CACHE DEVICE OFF rdev command.
where:
rdev
is the real device number of the device that has been given access to the cache.
Response 3
rdev CACHE UNAVAILABLE FOR SUBSYSTEM
This response will be repeated for each specified device when you issue the SET
CACHE SUBSYSTEM OFF rdev command.
where:
rdev
is the real device number of the device whose subsystem's cache has been
deactivated.
Response 4
rdev CACHE AVAILABLE FOR SUBSYSTEM
This response will be repeated for each specified device when you issue the SET
CACHE SUBSYSTEM ON rdev command.
where:
rdev
is the real device number of the device whose subsystem's cache has been
activated.
502
VM/XA SP2 CP Command Reference
SETCCWTRAN
SETCCWTRAN
Privilege Class: G
Use SET CCWTRAN to control CCW translation for CPo
I SET
where:
CCWTRAN {
g:}
controls CCW translation for CPo If you specify OFF, all virtual I/O from your
virtual machine bypasses CP CCW translation except under the following
conditions, which force CCW translation:
• Tracing I/O to a device.
• Tracing CCWs for a device.
• CP has sense data pending for a device.
• The I/O device is not dedicated to the preferred virtual machine unless it is a
full-pack minidisk and the channel program begins with valid SEEK,
SET-FILE-MASK CCWs.
• CP has delayed response messages pending for the device.
• CP is expecting a global CCW to be issued, which must be translated.
When a preferred virtual machine is logged on, the CCWTRAN option is set
OFF to bypass CCW translation. Note, however, that if you run VM/XA SP in
a virtual machine, a preferred virtual machine guest who logs on to your
second-level system will have the CCWTRAN option set ON.
Usage Notes
You can use this command only if your preferred virtual machine runs in the V = R
area.
Responses
None.
Chapter 2. VMjXA SP CP Commands
503
SET CMDLIMIT
SET CMDLIMIT
Privilege Class: B
Use SET CMDLIMIT to define a system limit for the number of incorrect
passwords a user can enter on the AUTOLOG and XAUTOLOG commands. If a
user exceeds this limit, CP disables the AUTO LOG and XAUTOLOG commands
for the remainder of the user's logon session.
I SET CMDLIMit
XAUTOLog
AUTO Log
where:
XAUTOLOG DOD
AUTOLOG DOD
sets the system limit for incorrect passwords entered on the AUTO LOG and
XAUTOLOG commands. The maximum limit is 255; the minimum limit is 1.
The limit is set to 4 (the initial system setting) if nnn is omitted.
Usage Notes
1. For security reasons, CP limits the number of incorrect passwords allowed on
the AUTO LOG and XAUTOLOG commands in each user's logon session. The
SET CMDLIMIT lets you raise or lower that limit.
2. Use the QUERY CMDLIMIT command to determine the current system limit
value.
3. AUTOLOG is an accepted synonym for XAUTOLOG. The minimum
abbreviation is AUTOL.
Responses
None.
Migration Notes
See the XAUTOLOG and AUTO LOG commands.
504
VM/XA SP2 CP Command Reference
SET CONCEAL
SET CONCEAL
Privilege Class: G
Use the SET CONCEAL command to activate and to deactivate the protected
application environment for a virtual machine, thus protecting a session from
unexpectedly entering CP READ.
I
SET
CONCea 1 {ON }
OFF
where:
ON
specifies that the virtual machine is to operate in the protected application
environment. This environment is intended for the application end user who
does not want to interact with CPo Instead of presenting the user with an
unexpected CP READ on occurrence of certain error conditions (for example,
paging error, soft abend, disabled wait PSW loaded), the protected application
facility forces an automatic re-IPL of the virtual machine without issuing any
error messages to the user. The IPL is initiated using the IPL command last
used for the virtual machine.
To prevent a re-IPL loop, CP does not force re-IPL if a previous automatic
re-IPL has occurred less than a minute before. No more than 10 automatic
re-IPLs are attempted between activation and deactivation of the protected
application environment. If a re-IPL is not attempted or if the attempt fails, CP
issues the same message as when the protected application environment is not
active and puts the terminal into CP READ state.
When you SET CONCEAL ON, the terminal break key is disabled. If you
subsequently deactivate the protected application environment using the SET
CONCEAL OFF command, the break key is reenabled. You may also enable
the break key by issuing a TERMINAL BRKKEY command while in the
protected application environment.
OFF
specifies that the virtual machine should no longer operate in the protected
application environment. Certain error conditions (such as a paging error, a soft
abend, or a disabled wait PSW in the virtual processor) cause CP to take control
of the virtual machine and display CP READ on the terminal. No re-IPL is
initiated. The terminal break key is reenabled when you issue SET CONCEAL
OFF.
Usage Notes
1. With your break key disabled, you cannot enter the CP READ state while
running in full screen mode unless your guest (operating system or application)
provides a way. The guest can use DIAGNOSE code X ' 08 1 to pass either the
CP command or no command at all to enter CP READ. In addition, the
TERMINAL MODE CP command allows entry to CP on a console attention
interrupt when in line mode.
2. An application can establish the protected application environment for itself by
issuing a SET CONCEAL ON command using DIAGNOSE code X I 08 I •
Chapter 2. VM/XA SP CP Commands
505
SET CONCEAL
3. You may not specify SET CONCEAL ON if you have defined a multiprocessor
configuration. The protected application facility only supports virtual
uniprocessor systems.
4. If you use an application which runs with the protected application environment
active, be aware that an automatic re~IPL will reset your virtual machine. If you
IPL a named saved system, storage is also cleared; therefore, data in virtual
machine storage is lost.
5. If the protected application environment is already active, the SET CONCEAL
ON command has no effect. Thus, if the break key has been reenabled via the
TERMINAL BRKKEY command, this second SET CONCEAL ON command
does not disable the break key.
Responses
None.
Migration Notes
VMISP HPO: For SET CONCEAL OFF, VMjXA SP resets the break key to the
last key specified on the TERMINAL BRKKEY command, rather than
unconditionally resetting it to the PAl key as in HPO.
506
VMjXA SP2 CP Command Reference
SET CPCONIO
SET CPCONIO
Privilege Class: G
Use the SET CPCONIO command to control the destination of all CP output to the
virtual machine console. At LOGON, CPCONIO is set OFF.
I SET
CPConi 0 {IUCV}
OFF
where:
IUCV
specifies that responses are to be passed to the virtual machine via lUCY if a
connection to the message system service exists. If the console is being spooled,
the responses are also placed in the console spool file as well as being sent via
IUCV. If no IUCV connection exists, data will be handled as if SET CPCONIO
OFF had been issued.
OFF
specifies that responses are to be displayed at the terminal.
Usage Notes
None.
Responses
None.
Chapter 2. VM/XA SP CP Commands
507
SET CPLANGUAGE
SET CPLANGUAGE
Privilege Class: G
Use the SET CPLANGUAGE command to change the current language of your
virtual machine.
I
SET
CPLANGuage langid
where:
langid
is the language identifier of the language to which the virtual machine is to be
set. langid may be I-to-5 characters in length and must consist of CMS file
system characters only.
Usage Notes
1. Be aware of the language-related terminal restrictions when you specify a
language. For example, you may have your terminal set to display the German
character set; if you then set your language to Spanish while using the same
terminal, you may get unexpected characters on your screen or, in the worst
case, CP may disconnect you. If you are not sure what characters your terminal
can display, check with your system administrator.
2. The QUERY CPLANGLIST command displays all the valid language ids that
you can set in CPo To display the language that is currently active in your
virtual machine, issue the QUERY CPLANGUAGE command. Contact your
system administrator if you have any questions about the languages available on
your VMjXA SP system.
Responses
None.
Examples
If your virtual machine is set to American English and you want to change your
language to French, issue the command:
SET CPLANGuage FRANC
To change it back to American English, issue the command:
SET CPLANGuage AMENG
508
VM/XA SP2 CP Command Reference
SET CPTRACE
SETCPTRACE
Privilege Class: A, C
Use SET CPTRACE to activate or deactivate CPTRACE entry recording of real
machine events in the CP TRACE tables.
SET
CPTRace
FOR lNONSPECIFIC
SPECIFIC
SYSTEM
ALL
[[
userid
FOR
[
{~;~~i~IC}
~]
[illLJ
[ALLcodes
"'J [more]]
OFF codel code2 •••
RESET ]
userid
where [more] ;s:
ON } [ ALLcodes
] ]
[ { OFF
codel code2 •••
[more]
where:
CPTRACE
enables or disables tracing of real machine events in the CP trace tables.
FOR NONSPECIFIC
specifies the target for the subsequent tracing changes.
NONSPECIFIC indicates the specified tracing applies to all virtual machines not
specifically set or named by a previous SET CPT RACE command.
NONSPECIFIC is the default. All virtual machines begin in the
NONSPECIFIC group. All members of the NONSPECIFIC group have the
same codes traced.
FOR
!
SPECIFIC
SYSTEM
I
ALL
userid
specifies the target for the subsequent tracing changes.
SPECIFIC indicates the specified tracing applies only to those virtual machines
specifically set or named by a previous SET CPT RACE command. Members of
the SPECIFIC group may each have a unique set of codes traced.
SYSTEM indicates the specified tracing applies to system work. SYSTEM
becomes a member of the SPECIFIC group, even though the specified tracing
may not match the virtual machines already in the group. Therefore, SYSTEM
is similar to "userid" in that it names the work for which tracing applies, and
SYSTEM can also be a part of either the SPECIFIC or NONSPECIFIC groups
but not both.
ALL indicates the specified tracing applies to both the SPECIFIC and
NONSPECIFIC groups of virtual machines and to system work.
userid indicates the specified tracing applies only to this specific virtual machine.
userid becomes a member of the SPECIFIC group, even though the specified
tracing may not match others in the group.
Chapter 2. VMjXA SP CP Commands
509
SET CPTRACE
RESET
RESET ends specific tracing for the indicated virtual machine, system work, or
the entire SPECIFIC group. The virtual machine or machines (and/or
SYSTEM) become members of the NONSPECIFIC group. SET CPTRACE
FOR SPECIFIC RESET, therefore, ensures that all virtual machines and
SYSTEM are in the NONSPECIFIC group.
ON
OFF
ON, the default, enables tracing of the specified categories. OFF disables
tracing of the specified trace categories. ON and OFF may be intermixed in the
same trace category list to enable and disable trace categories in the same
command. The trace category list is processed from left to right.
ALLCODES
ALLCODES, the default, specifies all trace codes.
code! code2 ..•
is either a single 4-digit trace code or the name of a category of codes. The
system displays only the setting of this code or category of codes.
The following list describes the major (second-level) code category names in the
system hierarchical order:
EXT
SVC
PRG
MCH
I/O
STOR
SCH
lOS
lOR
CPX
RUNU
VINT
VCSW
IUCV
CCS
External interruption activities
Supervisor call interruption related activities
Program interruption entries
Machine check interruption related activities
Input/output interruption related activities
Real storage maintenance related activities
Adding/dropping users to or from a scheduler queue
I/O instructions (including real, logical device, and I/O assist)
Stacking/unstacking of IORBKs or TRQBKs
Stacking/unstacking of CPEBKs and related activity
Virtual machine dispatching activity
Simulated I/O interruptions
Simulated I/O instructions
IUCVactivities
SNA/CCS activities.
The following lists the code category names and the trace events within these
categories also in system hierarchical order (for a full numerical list regardless of
category, refer to VM/XA SP Diagnosis Reference).
ALLCODES
Sets or resets tracing of all events and is the default option.
EXT
Sets or resets tracing of external interruption related activities:
0100
External interruption
PCDIAG
Processor controller (P. C.) diagnose
3COO
3C55
PCSERVC
Processor controller (P.C.) service call
3CI0
3C65
510
VMjXA SP2 CP Command Reference
P.C. diagnose request started
P.C. diagnose request returned
P.C. service call request started
P. C. service call request returned
SET CPTRACE
3CFF
Unsolicited processor controller interrupt received
AEOO
SIGP instruction
SVC
Sets or resets tracing of supervisor call interruption related activities:
0200
SVC interruption
2200
Add or stack a COMBK
2301
Execute CP command
CALLRET
(Trace Codes 2800 and 2COO)
2800 - Call-with-save-area
2COO - Return-with-save-area
3600
Exit to the dispatcher
ABEND
(Trace Codes FFEE and FFFF)
FFEE - Resume trace after soft abend
FFFF - Suspend trace during soft abend
PRG
Sets or resets tracing of program interruption entries:
0300
Program interruption
MCH
Sets or resets tracing of machine check interruption related activities:
0400
Machine check interruption
F400
CPU IS check stopped
F401
Check stop CPU recovery
1/0
Sets or resets tracing of input/output interruption related activities:
0500
I/O interruption
10FO
I/O sense data received
STOR
Sets or resets tracing of storage maintenance related activities:
FRE
FREE and FRET
0600 - Obtain free storage (FREE)
0700 - Return free storage (FRET)
PFRE
Pageable free storage requests
0610- Obtain pageable free storage
0710 - Return pageable free storage
4000
Page translation results
FRAMEREP
Available list replenishment
4001 - Demand scan pass 1
4002 - Demand scan pass 2
VMSTOR
4010 - Virtual machine lock storage
4011 - Virtual machine unlock storage
Chapter 2. VMjXA SP CP Commands
511
SET CPTRACE
EXTEND
Extended free storage
F700 - Return free storage page
F701 - Obtain free storage scan
SCH
Sets or resets tracing of adding and or dropping users to or from a scheduler
queue:
3200
Add user to dispatch list
3210
Drop user from dispatch list
lOS
Sets or resets tracing of all I/O instructions:
REALIOS - Real I/O
CSCH
Clear subchannel
1000 - CC 0
1003 - CC 3
HSCH
Halt subchannel.
1010 - CC 0
1011 - CC 1
1013 - CC 3
MSCH
Modify subchannel
1020 - CC 0
1021 - CC 1
1023 - CC 3
SSCH
Start subchannel
1030 - CC 0
1031 - CC 1
1033 - CC 3
SSCHSNS
Start subchannel (sense)
1038 - CC 0
1039 - CC 1
103B - CC 3
TSCH
Test subchannel
1050 - CC 0
1051 - CC 1
1053 - CC 3
RSCH
Resume subchannel
1080
1081
1082
1083
512
-
CC
CC
CC
CC
0
1
2
3
lCOI
Unit check
lC02
Valid code for unit exception
IDOl
I/O related machine check
VMjXA SP2 CP Command Reference
SET CPTRACE
CHLCHEK
Channel check
1002 - Channel check
1003 - Channel check at termination
LDIOS - Logical Device I/O
LOCSCH
Clear logical subchannel
8000 - CC 0
8003 - CC 3
LOHSCH
Halt logical subchannel
8010 - CC 0
8011 - CC 1
8013 - CC 3
LOMSCH
Modify logical subchannel
8020 - CC 0
8021 - CC 1
8023 - CC 3
LOSSCH
Start logical subchannel
8030 - CC 0
8031 - CC 1
8033 - CC 3
LOSSCHS
Start logical subchannel (sense)
8038 - CC 0
8039 - CC 1
803B - CC 3
LDTSCH
Test logical subchannel
8050 - CC 0
8051 - CC 1
8053 - CC 3
80FO
Logical I/O sense data received
8500
Logical I/O interruption
10AIOS - I/O Assist
10ACSCH
I/O Assist clear subchannel
5000 - CC 0
5003 - CC 3
10AHSCH
I/O assist halt subchannel
5010
5011
5012
5013
-
CC
CC
CC
CC
0
1
2
3
Chapter 2. VM/XA SP CP Commands
513
SET CPTRACE
IOAMSCH
I/O assist modify subchannel
5020
5021
5022
5023
IOASSCH
CC
CC
CC
CC
0
1
2
3
I/O assist start subchannel
5030
5031
5032
5033
IOATSCH
-
-
CC
CC
CC
CC
0
1
2
3
I/O assist test subchannel
5050 - CC 0
5051 - CC 1
5053 - CC 3
IOATPI
I/O assist test pending interrupt
5060 - CC 0
5061 - CC 1
IOARSCH
I/O assist resume subchannel
5080
5081
5082
5083
5500
-
CC
CC
CC
CC
0
1
2
3
I/O assist I/O interruption
lOR
Sets or resets tracing of stacking/unstacking of IORBKS or TRQBKS:
3000
Stack IORBK/TRQBK
3010
Unstack IORBK/TRQBK
CPX
Sets or resets tracing of stacking/unstacking of CPEBKS and related activity:
3300
Stack CPEBK
3310
Unstack CPEBK
3700
Stack work bits
RUNU
Sets or resets tracing of virtual machine dispatching activity:
OAOO
Run user
OAIO
Load/store Vector Facility
VSIE
Virtual SIE
I AOO - Run user in virtual SIE
lA11 - Virtual SIE interception
514
3500
Interruption, not instruction
3504
Instruction/interception
VM/XA SP2 CP Command Reference
SET CPTRACE
VINT
Sets or resets tracing of simulated I/O interruptions:
OCOO
Virtual 370-XA I/O interruption
ODOO
Virtual CSW stored
2500
Guest I/O untranslation
VCSW
Sets or resets tracing of simulated I/O instruction:
OC32
Virtual modify subchannel
OC33
Virtual start subchannel
OC35
Virtual test subchanne1
OC36
Virtual test pending interruption
OD90
Virtual start I/O
OD91
Virtual start I/O fast
IUCV
Sets or resets tracing of inter-user communication vehicle activities.
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
150A
150B
150C
150D
150E
150F
1510
1511
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
IUCV
Query function
Test message function
Retrieve buffer function
Describe function
Send function
Receive function
Reply function
Test completion function
Reject function
Purge function
Accept function
Connect function
Declare buffer function
Quiesce function
Resume function
Sever function
Set mask function
Set control mask function
CCS
Sets or resets tracing of SNA/CCS activities.
CCSN
CCS normal events
1600
1603
1604
1606
1608
1609
160A
160B
160C
160E
1610
1611
CCS
CCS
CCS
CCS
CCS
CCS
CCS
CCS
CCS
CCS
CCS
CCS
ACCEPT
PURGE
RECEIVE
REPLY
SEND one way
SEND two ways
SEVER
Logic error in CCS interface CB
REPLY from VSM
CONNECT from VSM
SEVER from VSM
Message complete from VSM, one-way SEND
Chapter 2. VM/XA SP CP Commands
515
SET CPTRACE
1612
1613
1614
1615
CCSE
CCS
CCS
CCS
CCS
Connect from VSM for LU
Logic error in VSM interface CB
Error in user environment, SEVER user
SNA control block chain invalid
CCS error events.
1680
1684
1686
1688
1689
CCS
CCS
CCS
CCS
CCS
ACCEPT error
RECEIVE error
REPLY error
SEND one-way error
SEND two-way error.
Usage Notes
1. You may combine several commands into one command as long as the FOR
qualifier is the same. For example:
SET CPTRACE FOR NONSPECIFIC ON SVC OFF EXT
Note: FOR NONSPECIFIC is the default value. The following command
would have the same result:
SET CPTRACE ON SVC OFF EXT
2. If you start a SPECIFIC trace, you must be aware of the initial state of the
trace. The NONSPECIFIC trace only modifies a trace that has already been
started. To find out the initial trace state, issue the following two commands:
QUERY CPTRACE FOR SPECIFIC
After checking the response, then issue:
QUERY CPTRACE
This will give you the NONSPECIFIC state.
3. You cannot disable tracing for entries that can occur at the time of a CP trace
table full condition. The two entry conditions that can occur are "PROGRAM
INTERRUPTION" (0300) for Trace Table Page Full, program interruption
X ' 16 1 , and "TRACE TABLE PAGE FULL DURING MACHINE CHECK
HANDLING" (F40F).
4. The SET CPT RACE command processes categories sequentially from left to
right; tracing for the first category begins before the second category is
processed. Therefore, it may be possible to have trace settings in effect during
command processing that are different from the trace settings before and after
command processing.
The NONSPECIFIC trace setting, modified by the command initially creating
the SPECIFIC trace is the initial state of a SPECIFIC trace setting.
To get an initial state of ALLCODES enabled, issue:
SET CPTRACE FOR user ON ALLCODES
Combined with or followed by the desired trace settings.
Examples
To disable the trace for IUCV instructions, issue:
SET CPTRACE OFF IUCV
516
VM/XA SP2 CP Command Reference
SET CPTRACE
As an example, assume that when your system is IPLed, all users are in the
NONSPECIFIC category. If you want to put all users in the NONSPECIFIC
category and you want to trace all trace codes, issue the command:
SET CPTRACE FOR NONSPECIFIC ON ALLCODES
Issuing the command with all its defaults and abbreviations specified, the command
would look like this:
SET CPTR
If you want to put some users in the SPECIFIC category, issue the following
commands:
SET CPTRACE FOR NONSPECIFIC OFF ALL
This turns off all trace codes for users in the NONSPECIFIC category.
Now, perhaps you want to set a SPECIFIC trace for users CMSOOO and SYSTEM;
for CMSOOO you want to set ON code categories I/O and IUCV, and for SYSTEM
you want to set ON only code categories SVC and IUCV. (See trace code category
listings beginning on page 510.) To do this, issue the following commands:
SET CPTRACE FOR CMS000 OFF ON I/O
SET CPTRACE FOR SYSTEM OFF ON SVC
SET CPTRACE FOR SPECIFIC ON IUCV
If you now want to put the user CMSOOO back into the NONSPECIFIC group, issue
the following command:
SET CPTRACE FOR CMS000 RESET
The system now would be tracing SYSTEM for SVC and IUCV trace code
categories.
Note: RESET can only be used to set users or SYSTEM back into the
NONSPECIFIC group. In order to set off codes for a NONSPECIFIC user,
issue the command:
SET CPTRACE FOR userid OFF {code or code category}
If you want to trace ALLCODES for one SPECIFIC user (a userid) only, issue the
following commands:
SET CPTRACE FOR ALL
OFF ALLCODES
SET CPTRACE FOR userid ON ALLCODES
Responses
None.
Chapter 2. VM/XA SP CP Commands
517
SET CPUID
SET CPUID
Privilege Class: G
Use SET CPUID to change the processor identification for the virtual processor on
which the command is issued.
I
SET
CPUid ssssss
where:
CPUID ssssss
changes the virtual processor identification. The six hexadecimal digits you
specify in ssssss become the new processor identification number or processor
serial number.
Usage Notes
The SET CPUID command changes bits 8-31 of the CPU ID that is returned by the
STIOP instruction to the value you specify in the SET CPUID command line.
Responses
None.
518
VMjXA SP2 CP Command Reference
SET DUMP
SET DUMP
Privilege Class: B
Use SET DUMP to designate the unit that is to receive a VMjXA SP system abend
dump.
SET
where:
DUMP
indicates that you are designating the unit that will receive CP ABEND dumps.
DASD
specifies that the system dump unit is a disk. The DASD dump space will be
released when the dump setting is changed. Spooling cylinders will be allocated
for the dump on the first CP-owned DASD device that has enough contiguous
spooling cylinders to hold a complete dump of real storage. The CP-owned
DASD are searched in the following order:
•
•
•
•
•
•
3340
3330
3350
3375
3380
2305
rdev
is the real device number of a real printer, a fully supported tape device, or a
CP-owned DASD device.
IPL
NOIPL
indicates whether the system is to be automatically restarted after a failure. At
system initialization, the value is IPL; if you don't want your system
automatically restarted, you must explicitly change the setting to NOIPL.
CP
ALL
V=R
indicates which pages of storage are to be dumped. Specify CP if only storage
locations occupied by the control program are to be dumped. Specify ALL if
you want all real storage dumped. At system initialization, the value is CPo
Specify V = R if you also want to dump V = R storage. V = F storage is part of
the V = R region generated at system generation time when the V = R operand is
specified.
Usage Notes
1. The basic format of the dump to tape is the same as the DASD format.
Multiple volume tapes are allowed as dump tapes.
2. Dumps produced by VMjXA SP have a different format than and are
incompatible with dumps produced by VMjSP.
Chapter 2: VMjXA SP CP Commands
519
SET DUMP
3. Your installation's system security can be compromised if you use the SET
DUMP ALL command, because user pages will be included in your dumps.
4. You can specify the operands in any order in the SET DUMP command.
5. If you do not specify a dump device on the command line, the dump device
setting will not be changed.
6. Whenever you issue the SET DUMP command, the CP and IPL defaul~s are in
effect unless you explicitly change them. For example, if the current dump
options are ALL and NOIPL, and you issue:
SET DUMP 000E
the dump options will be set to CP and IPL.
7. When the system is initialized, the dump device is set to DASD if there is
enough spooling space on a CP-owned DASD to hold it, and if your VM/XA
SP system is not running in a virtual machine. Upon initialization, the dump
options will be set to CP and IPL.
8. If you want to preserve a preferred virtual machine's environment if VMjXA SP
terminates because of a system incident:
• DO NOT specify the ALL or NOIPL operand on the SET DUMP
command
• Select either a DASD or a tape drive as your system dump device. If you
specify a tape drive you must keep that drive ready at all times.
Responses
type rde~} DUMP UNIT {CP }{IPL .} [CYL nnn]
{ PRINTER
ALL NOIPL
V=R
where:
type rdev
is the device type and the real device number of your dump device. The type
can be DASD, TAPE, or PRINTER.
PRINTER
indicates that no dump device has been assigned and that there is insufficient
spool space on the assigned DASD device. The dump device defaults to the first
printer available in the order in which printers were defined at SYSGEN.
CP
ALL
V=R
indicates whether CP-owned pages and free storage or all pages of real storage
will be dumped.
IPL
NOIPL
indicates whether the system will automatically restart when the dump is
completed.
CYL non
is the number of cylinders of spooling space allocated for system dumps. This
will be displayed for DASD dumps only.
520
VM/XA SP2 CP Command Reference
SET DUMP
Migration Notes
VMISP HPO
1. In VMjXA SP, use the DASD operand instead of the AUTO operand as in
VMjSP HPO.
2. VMjXA SP provides a response to this command whereas VMjSP HPO does
not.
3. Dumps produced by VMjXA SP have a different format than and are
incompatible with dumps produced by VMjSP.
Chapter 2. VM/XA SP CP Commands
521
SETEMSG
SET EMSG
Privilege Class: G
!
Use SET EMSG to control error message handling.
SET
EMSG
CODE
ION
TEXT
OFF
IUCV
where:
EMSG
Ig~DEl
TEXT
OFF
controls error message handling. If you specify ON, both error code and error
message text are displayed on your display screen. When you log on, EMSG is
set to ON.
If you specify CODE, only the error code is displayed.
If you specify TEXT, only the message text is displayed.
If you specify OFF, no error messages are displayed.
EMSG {IUCV}
specifies that both the error code and text are to be passed to the virtual
machine via IUCV if a connection to the message system service exists. If no
IUCV connection exists, the message is handled as if SET EMSG ON had been
issued.
Usage Notes
1. If you specify the TEXT option, the number of the message is not displayed.
The lack of a message number makes it difficult to locate the message in the
VMjXA SP System Messages and Codes Reference. Therefore, use the TEXT
option with caution.
2. If your console is being spooled, the full error message (both code and text)
appears in the spooled output regardless of the setting.
3. CMS recognizes EMSG settings for all error (E) and information (I) messages,
but ignores the EMSG setting and displays the complete message (error code
and text) for all other system messages.
Responses
None.
Migration Notes
VMISP HPO: In VMjXA SP, the default value when you log on is different. In
VMjXA SP, the default is ON; in VMjSP HPO the default is TEXT.
522
VMjXA SP2 CP Command Reference
SET IMSG
SET IMSG
Privilege Class: G
Use SET IMSG to control whether certain informational responses issued by the CP
CHANGE, CLOSE, DEFINE, DETACH, IPL, ORDER, PURGE, SPOOL and
TRANSFER commands are displayed on your display screen. The descriptions of
these CP commands tell which responses are affected.
IMSG {ON }
OFF
IUCV
where:
IMSG
{g~
}
controls whether the informational responses are displayed. If you specify ON,
the responses will be displayed; if you specify OFF, the responses will not be
displayed.
IUCV
specifies that informational messages are to be passed to the virtual machine via
IUCV if a connection to the message system service exists. If no IUCV
connection exists, the message will be handled as if SET IMSG ON had been
issued.
Usage Notes
The SET IMSG ON or OFF command has no effect on the handling of error
messages set by the SET EMSG command. When you log on, IMSG is set ON.
Responses
None.
Chapter 2. VM/XA SP CP Commands
523
SET IOASSIST
SET IOASSIST
Privilege Class: B,G
Use SET IOASSIST to either allow or prevent CP from using the start interpretive
execution assist for a preferred virtual machine guest.
SET
IOAss; st {ON } [[FOR] ALL .
OFF
userld
J
*
where:
.
IOASSIST {ON }
OFF
turns on or off CP's capability to use the start interpretive-execution assist for a
preferred virtual machine guest.
ALL
. enables or disables the start interpretive-execution assist eligibility for all V = R
and V = F users, independent of the local setting for these individual users. The
local setting is not changed.
When ALL is specified by a class B user, access to the start interpretiveexecution assist is allowed or disallowed for all V = R and V = F guests. These
include any new V = R or V = F guests who may log on. When this global
setting is OFF, it overrides any individual userid setting.
userid
*
enables or disables the individual user's local IOASSIST passthrough value.
* is the default and specifies the issuer of this command.
Usage Notes
1. If you set IOASSIST either ON or OFF while the preferred guest is running, you
may cause CP to reflect error status to the guest for some of the guest's devices.
2. If IOASSIST is set ON for all users, an individual user can set IOASSIST OFF
without changing the setting for other users.
Note: The reverse is not true; the ALL setting of OFF overrides local user
settings.
Responses
None.
524
VMjXA SP2 CP Command Reference
SET LINEDIT
SET LINEDIT
Privilege Class: G
Use SET LINEDIT to control logical line editing functions.
I SET
LINEDi t {ON }
OFF
where:
LINEDIT {ON }
OFF
controls the logical line editing functions for your virtual machine. If you
specify ON, the system line editing functions and symbols will be used to edit
virtual console input requests. If you specify OFF, no character or line editing
will be used for the virtual machine operating system. When you log on,
LINEDIT is set ON.
Usage Notes
None.
Responses
None.
Chapter 2. VM/XA SP CP Commands
525
SET LOGMSG
SET LOGMSG
Privilege Class: B
Use SET LOGMSG to set the log message line that you specify to the text you enter
on the command line, to delete a specified line from the log message, or to delete the
entire existing log message.
SET
LOGmsg
where:
nn
is the number of the line in the log message to be changed. nn can be a value
from 1-50.
[*)text
is the text that you want to have at line nn of the log message. If you want the
line to be automatically displayed on each user's console when that user logs on
to VM/XA SP, the text must be preceded by an * (asterisk). The maximum
number of characters that you can include in a line is 76, including blank spaces
and the asterisk, if specified.
If line nn already has text, it is replaced. Otherwise, the text is inserted for line
nn.
NULL
indicates that the current text for line nn is to be deleted from the log message.
If NULL is not preceded by a line number, the entire log message is deleted.
Usage Notes
1. If you do not specify any options following SET LOGMSG, the system prompts
you to enter a line of text. This line of text is inserted into the log message after
the last line that already has text. For example, if the highest line number in the
log message to have text is 37, the new line of text will be inserted at line 38. If
line 50 already has text defined, you receive an error message and the text is not
inserted. If you want the text to be displayed to users when they log on, the first
character must be an * (asterisk).
2. The maximum number of lines you can include in your log message is 50,
including blank lines, and thus the highest line number in the log message is 50.
3. If you specify a line number with nothing following it (for instance, SET
LOGMSG nn), the system prompts you to enter a line of text. The text entered
is placed in the log message at the line specified in the command. If you press
ENTER without entering any text, the line is deleted from the log message. If
you want the text to be displayed to users when they log on, the first character
must be an * (asterisk).
4. If the text of a line in the log message does not start with an * (asterisk), the
user must issue the CP QUERY LOGMSG command to see the text. (The text
is not displayed automatically when the user logs on to the system.)
5. If more than 76 characters of text are entered for a line, the text is truncated
after the 76th character without any message being issued.
526
VM/XA SP2 CP Command Reference
SET LOGMSG
6. The LOGMSG area is checkpointed at system termination.
Resppnses
LOGMSG:
is the prompt to enter a line of text when either SET LOGMSG or SET LOGMSG
nn is entered. Type the desired line of text in response to the prompt and press the
ENTER key. If you want the text displayed when users log on, the first character
must be an * (asterisk).
Migration Notes
VMISP HPO: VM/XA SP limits you to 50 lines of log message data.
Chapter 2. VMjXA SP CP Commands
527
SET MACHINE
SET MACHINE
Privilege Class: G
Use SET MACHINE to change the type of virtual processor configuration defined
for your virtual machine.
I SET
where:
MACIDNE
{~O
}
changes the type of virtual processor configuration for your virtual machine. If
you specify 370, your virtual configuration must obey the conventions of
Systemj370 architecture. If you specify XA, your virtual configuration must
obey 370-XA mode architecture conventions.
Usage Notes
1. The SET MACHINE command terminates all IUCV connections and releases
the IUCV buffer. Of course, if you issue the command but it does not change
your machine setting from what is used to be, then the IUCV connections and
buffer remain as they are.
2. When you change your machine type, your virtual machine is reset as if you had
issued a CP SYSTEM CLEAR command. All virtual storage and all registers
except control registers are cleared to binary zeros; control registers are reset to
their initial values. Therefore, you must repeat your IPL procedure to continue
operation.
3. A default architectural type can be specified on the user directory MACHINE
statement.
Response 1
STORAGE CLEARED - SYSTEM RESET
indica tes that the virtual machine has been cleared.
Response 2
SYSTEM
=
XA
indicates that the virtual processor is now simulating 370-XA architecture.
Response 3
SYSTEM
=
370
indicates that the virtual processor is now simulating Systemj370 architecture.
528
VM/XA SP2 CP Command Reference
SET MAXUSERS
SET MAXUSERS
Privilege Class: A
Use the SET MAXUSERS command to adjust or to remove the limit set on the
number of users who can log on.
I SET
MAXUsers {nnnnn}
OFF
where:
nnnnn
is the maximum number of users allowed to log on. The range is from I to
99999.
OFF
indicates that an unlimited number of users can log on.
Usage Notes
If the maximum number of users is set to a number lower than the current number
of logged on users, the system will allow the users to log off, to be forced off the
system, and to disconnect and reconnect, but it will not allow any users to log on
until the current number of logged on users is lower than the number specified by
MAXUSERS.
Response 1
MAXUSERS
= nnnnn
is the normal response for this command.
Response 2
REQUEST ACCEPTED. MAXIMUM USERS VALUE IS CURRENTLY EXCEEDED
is the response if the number of users already logged on exceeds the limit just set.
Response 3
NO MAXUSERS LIMIT IS SET
is the response when SET MAXUSERS OFF is entered or if no user limit is set.
Chapter 2. VM/XA SP CP Commands
529
SETMIH
SET MIH
Privilege Class: G
Use SET MIH to specify whether or not missing interrupt conditions should be
handled for I/O operations to the virtual machine's dedicated devices.
I SET
MIH
where:
MIH .{ON }
OFF
ON indicates that missing interrupt conditions to the virtual machine's dedicated
devices will be handled automatically by CPo OFF indicates that the missing
interrupt conditions to the virtual machine's dedicated devices will be detected
but will not be handled.
Usage Notes
1. SET MITIME OFF will invalidate any setting of the MIH. Missing interrupts
can be handled only if they are detected.
2. The default, which is not to handle missing interrupt conditions detected for the
virtual machine's dedicated devices, is in effect if MIH is not specified on the
user directory OPTION statement or if the SET command is not issued.
Responses
None.
530
VM/XA SP2 CP Command Reference
SETMITIME
SET MITIME
Privilege Class: A, B
Use the SET MITIME command to alter the time interval at which the specified
device is checked for missing interrupts.
SET
'DASD
TAPE
MITime
GRAF
where:
IABIAS [ mmm[%) nnn]
90
2
specifies the new "interactive bias" to take effect. An interactive bias with a
nonzero "mmm" causes users doing trivial transactions to receive better service
than their scheduling share would otherwise entitle them to receive. Interactive
bias causes a user's share of the system to be momentarily larger than normal at
the start of a new transaction. Then the user's boosted share fades back to the
normal share as the transaction progresses. If the transaction lasts even longer,
then the user's share sinks below what it would normally be until the extra
service received earlier can be made up. The effect of this is to give good
response time to trivial transactions that only require a small fraction of a
second of processing to complete.
The value "mmm" is a percentage of the distance from the user's normal
position to the topmost user. The value "mmm" controls the "intensity" of the
interactive bias. It may range from 0 to 100, with the IPL value and the default
value being 90. The intensity determines where in the dispatch list the user is
inserted for the first minor timeslice at the start of a new transaction. The insert
point is somewhere between the normal (unbiased) insert point and the topmost
user in the list. A setting of 100 gives a very strong interactive bias, while a
setting of 0 eliminates the interactive bias.
The value "nnn" controls the "duration" of the interactive bias. It may range
from 1 to 100; the initial value at IPL time and the default value is 2. The
duration specifies the number of minor timeslices it takes for a user to fade back
to his or her normal position in the dispatch list after the initial interactive
boost. For example, a setting of 3 means the boost to the user lasts for 3 minor
timeslices. The effect is strongest on the first timeslice and fades away until on
the third timeslice the user receives only a small boost in the dispatch list. On
the fourth timeslice the user receives no interactive boost at all and on the fifth
timeslice the user begins to sag below their normal position in an effort to
compensate for the larger-than-normal share the user received on the first few
timeslices.
Chapter 2. VM/XA SP CP Commands
559
SETSRM
If "mmm" is specified without "nnn," then the current interactive bias duration
is not changed.
IABIAS INITIAL
sets the intensity (mmm) and duration (nnn) back to the initial values, 90 and 2.
DSPSLICE minslice
is the new size, in milliseconds, of the dispatching minor timeslice. This is the
amount of CPU time a virtual machine may consume before re-examination by
the scheduler. The value "minslice" must be in the range of 1 to 100.
STORBUF {aaa[%) bbb[%) ccc[%)}
partitions the scheduler's view of main storage when choosing users to move
from the eligible to dispatch lists. The result is a buffering mechanism based on
the "transaction class" of a user, defined as:
El, Ql - users with short-running transactions
E2, Q2 - users with medium-running transactions
E3, Q3 - users with long-running transactions
where Ex is the class assigned to a user in the eligible list, and Qx is the
designation after moving to the dispatch list. An E1 user in the eligible list
.becomes a Q1 user in the dispatch list, and so on. An additional "transaction
class" is QO, which are users who never wait in the eligible list to contend for
resources in the dispatch list (users with the QUICKDSP attribute, for example).
The SET SRM STORBUF parameters partition the storage as follows:
aaa[%) - is the fraction of main storage the scheduler should view when
considering adding an E1, E2, or E3 user to the dispatch list. If the
total working sets of all users currently in the dispatch list plus the Ex
user under consideration exceeds the aaa percentage of main storage,
the user may not be added immediately and is delayed further.
bbb[%) - is the fraction of main storage the scheduler should view when
considering adding an E2 or E3 user to the dispatch list.
ccc[%) - is the fraction of main storage the scheduler should view when
considering adding an E3 user to the dispatch list.
In each case, the STORBUF values must be in the range 0-999, and aaa > =
bbb > = ccc.
The result of this partitioning is that storage buffers are carved out for
short-running work, which should include interactive work. Only QO and QI
users may occupy the percentage of main storage represented by (aaa - bbb).
Similarly, medium-running transactions can have a larger view of storage than
long-running ones.
STORBUF INITIAL
sets the percentage parameters back to their initial values, 100%, 85%, and
75%.
LDUBUF {ddd[%) eee(%) fffl%J}
partitions the commitment of the system's paging resources when choosing users
to move from the eligible to dispatch lists. The result is a paging capacity
buffering mechanism based on the "transaction class" of a user. (See the
description of the STORBUF parameter on page 560 for a definition of
transaction classes.)
560
VM/XA SP2 CP Command Reference
SETSRM
During system initialization, the number of exposures to paging DASD is
determined. Users expected to have high paging rates in the dispatch list are
termed "loading users." They are identified by recent paging activity or with the
knowledge that their working sets do not reside in main storage. One loading
user is expected to keep one paging exposure busy. The LDUBUF (Loading
User Buffer) percentages, then, determine the number of loading users allowed in
the dispatch list by transaction class.
The SET SRM LDUBUF parameters partition the paging capacity as follows:
dddi%] - is the fraction of paging exposures the scheduler should view when
considering adding a loading E1, E2, or E3 user to the dispatch list.
If the total number of loading users currently in the dispatch list plus
the loading Ex user under consideration exceeds the ddd percentage of
paging exposures, the user may not be added immediately and is
delayed further.
eeel%] -
is the fraction of paging exposures the scheduler should view when
considering adding a loading E2 or E3 user to the dispatch list.
fff(%] -
is the fraction of paging exposures the scheduler should view when
considering adding a loading E3 user to the dispatch list.
In each case, the LDUBUF values must be in the range 0-999, and ddd > = eee
> = fff.
LDUBUF INITIAL
sets the percentage parameters back to their initial values, 100 0/0, 75%, and
60%.
DSPBUF {iiiii iliii kkkkk}
affects the scheduler's policy for admitting users to the dispatch list in cases of
users who are not prevented from entering by the more resource-specific barriers
established by STORBUF and LDUBUF. DSPBUF stands for "dispatch
buffer" and refers to the total number of users (by class) that are allowed in the
dispatch list.
iiiii refers to the number of openings in the dispatch list made available to users
with short-running (E1) transactions. A subset, jjjjj, of the iiiii openings is also
made available to users with medium-length transactions; the E1 and E2 users
compete for these slots. Another subset, kkkkk, of the jjjjj openings is also
made available to users with long-running transactions; the E1, E2, and E3 users
all compete for these slots. QUICKDSP and other EO users are not limited by
these numbers and may enter the dispatch list without limit.
The valid range of values are 1 to 32767 where:
iiiii >= j j j j j >= kkkkk
Example:
DSPBUF 35 30 18
Thirty-five openings are available to E1 users, but only five of them (5 = 35 30) are exclusively available to E1 and are guaranteed not to be already
occupied by E2 and E3 users.
Thirty openings are available to E2 users, but only twelve of them (12 = 30 18) are guaranteed not to be already occupied by E3 users. None of the 30
openings are guaranteed against occupation by E1 users; however, E1 users
generally get out of the way quickly.
Chapter 2. VMjXA SP CP Commands
561
SETSRM
Eighteen openings are available to E3 users, but none of the openings are
guaranteed against occupation by El and E2 users. When El and E2 users do
occupy these openings, you can expect them to get out of the way relatively
quickly compared to the time scale of an E3 transaction.
DSPBUF {INITIAL}
sets the parameters back to their initial values which, for practical purposes, are
infinity.
Usage Notes
1. In using SET SRM DSPSLICE, the initial value of the dispatching minor
timeslice is determined by the model of the real machine that VMjSP is IPLed
on. Making the timeslice smaller increases the system overhead, but it also gives
better sorting of the dispatch list and more accurate share control by the
scheduler. Making the timeslice larger decreases system overhead, but at the
expense of the accuracy of the scheduler share controls. If the timeslice is made
very large, response times and throughput rates may vary widely across users
with similar shares.
Remember that when the dispatch slice gets changed, the IABIAS "duration" no
longer represents the same amount of processing as before. If the size of the
DSPLICE is changed significantly, you may want to adjust the lAB lAS
"duration" to compensate so that it still represents roughly the same amount of
processing as before.
2. The scheduler's use of the STORBUF percentages is best described by example.
Assume the values are 100%, 85% and 75%. When the scheduler is determining
whether or not to put an El user in the dispatch list, it first ensures that this
user's storage requirement (working set size, or WSS) plus the working set sizes
of all users already in the dispatch list is not greater than 100% of the available
storage. When determining whether or not to put an E2 user in the dispatch list,
the E2 user's WSS plus total WSS's in the dispatch list must not be greater than
850/0 of available memory, regardless of the mix of QO, Ql, Q2 and Q3 users
already in the dispatch list.
An installation may use the SET SRM STORBUF command to undercommit or
overcommit storage. Note that QO users are not restricted by their storage
requirement. By setting the the first percentage value (aaa) less than 1000/0, a
storage buffer may be reserved for QO users. The SET RESERVED command,
however, is a better method for a small number of QO users with predictable
storage needs.
By increasing or decreasing the differences in the three percentage values, an
installation can effect the response times and expansion factors for short-running
(generally interactive), medium-running, and long-running work.
3. The SET SRM LDUBUF is very similar to SET SRM STORBUF, except that
the resource buffered is the paging configuration capacity, rather than storage.
An installation may use SET SRM LDUBUF to undercommit or overcommit
the access to paging, or to change the emphasis on transaction length. In short,
whenever SET SRM STORBUF is used, SET SRM LDUBUF should also be
considered.
One difference to keep in mind, however, is that short-running transactions are
likely to require more paging activity than longer-running ones. This probably
is not true for the relative storage requirement. Short-running work is dormant
more often for longer periods, thus have their working sets moved to paging
DASD. For this reason, the difference between the first (ddd) and second (eee)
562
VM/XA SP2 CP Command Reference
SETSRM
percentage values should perhaps be greater than that of SET SRM STORBUF
(aaa and bbb).
Response 1
IABIAS : INTENSITY=nnn; DURATION=mmm
shows the results of a valid SET SRM IABIAS command.
Response 2
DISPATCHING MINOR TIMESLICE = xxx MS
HCPxxxxI DSPSLICE AFFECTS THE IABIAS "DURATION". SEE "SET SRM IABIAS"
shows the results of a valid SET SRM DSPSLICE command.
Response 3
STORBUF: Ql=aaa% Q2=bbb% Q3=ccc%
shows the results of a valid SET SRM STORBUF command.
Response 4
LDUBUF : Ql=ddd% Q2=eee% Q3=fff%
shows the results of a valid SET SRM LDUBUF command.
Response 5
DSPBUF : Ql=iiiii Q2=jjjjj Q3=kkkkk
shows the results of a valid SET SRM DSPBUF command.
Migration Notes
VMIXA SF: The SHARE option of the SET SRM command is no longer accepted.
Use the SET SHARE command instead.
Chapter 2. VM/XA SP CP Commands
563
SET SVC76
SET SVC76
Privilege Class: G
Use SET SVC76 to specify whether the control program (CP) or your virtual
machine will handle the SVC76 instruction.
I SET
where:
SVC76
{~~}
controls whether SVC76 instructions issued by your virtual machine are
processed by CP for recording of virtual device errors. Specify CP if guest error
records are to be recorded by CP when your virtual machine is running in
supervisor state. Specify VM if you do not want errors recorded and if you
want all guest SVC76 operations to be processed by your virtual machine. At
logon, SVC76 is set to CPo
Usage Notes
1. If your virtual machine has SET SVC76 set to CP, and:
• Issues an SVC76 from problem state, or
• Uses an invalid SVC76 interface, or
• Presents an unrecognizable EREP record, or
• Presents an EREP record that cannot be translated,
the SVC76 is reflected to the user.
2. Unless you are intentionally simulating hardware errors in your virtual machine
(for example, in order to test error recovery procedures), you should let CP
record all error records. When CP maintains the hardware error log, your
installation has the most accurate information about equipment errors.
Responses
None.
564
VM/XA SP2 CP Command Reference
SET TIMER
SET TIMER
Privilege Class: G
Use SET TIMER to control the virtual interval timer. This command is valid only
for System/370 mode virtual machines.
TIMER {ON }
OFF
REAL
where:
TIMER .{
~~F
'}
REAL
controls the virtual interval timer. If you specify ON, the virtual timer is to be
updated only when the virtual processor is running. If you specify OFF, the
timer is not to be updated. If you specify REAL, the timer is updated during
the virtual processor run time and also during virtual wait time. The initial
setting when you log on is ON.
Usage Notes
None.
Responses
None.
Chapter 2. VMjXA SP CP Commands
565
SETVMCONIO
SETVMCONIO
Privilege Class: G
Use the SET VMCONIO command to control the destination of virtual machine
generated responses. This includes any linemode I/O done by the virtual machine to
the virtual machine console. When you logon, VMCONIO is set OFF.
I SET
VMConi 0 {IUCV}
OFF
where:
IUCV
specifies that responses are to be passed to the virtual machine via lUCY if a
connection to the message system service exists. If no lUCY connection exists,
data will be handled as if SET VMCONIO OFF had been issued.
OFF
specifies that responses are to be displayed at the terminal.
Usage Notes
None.
Responses
None.
566
VM/XA SP2 CP Command Reference
SETWNG
SETWNG
Privilege Class: G
Use SET WNG to control whether warning messages sent using the WARNING
command are to be displayed. The initial setting for WARNING is ON.
WNG {ON
}
OFF
IUCV
where:
ON
OFF
controls whether warning messages are displayed on your display screen. If you
specify ON, all messages sent using the WARNING command will be displayed.
If you specify OFF, no warning messages will be received. When you log on,
WNG is set ON.
IUCV
specifies that warnings are to be passed to the virtual machine via IUCV if a
connection to the message system service exists. If no IUCV connection exists,
the message will be handled as if SET WNG ON had been issued.
Usage Notes
None.
Responses
None.
Chapter 2. VM/XA SP CP Commands
567
SHUTDOWN
SHUTDOWN
Privilege Class: A
Use the SHUTDOWN command to systematically end all system functions and to
checkpoint the system for an eventual warm start. This is the normal method that
you will use to shut down your system.
SHUTDOWN
Usage Notes
1. Because the SHUTDOWN command stops all virtual machine operations, you
should warn all users of an impending shutdown as early as possible so they may
quiesce their systems in an orderly manner.
You can use the SET LOGMSG, MESSAGE, and WARNING commands to
inform the affected users.
Response 1
SYSTEM SHUTDOWN STARTED
indicates that the command is accepted and termination processing is in progress. If
a class A user other than the primary system operator issues the SHUTDOWN
command, this response is sent to both the command issuer and the primary system
operator.
Response 2
SYSTEM SHUTDOWN COMPLETE
indicates that the shutdown has been successfully completed.
Migration Notes
VMISP HPO
1. VMjXA SP does not support the REIPL operand, which is supported in VMjSP
HPO.
2. VMjXA SP provides an additional response to indicate that SHUTDOWN has
started.
VMIXA SF
1. VMjXA SP allows a class A user other than the primary system operator to
issue the SHUTDOWN command.
2. If a class A user other than the primary system opera tor issues the command,
the response SYSTEM SHUTDOWN STARTED is sent to that user as well as
to the primary system opera tor.
568
VMjXA SP2 CP Command Reference
SLEEP
SLEEP
Privilege Class: Any
Use the SLEEP command to stop your virtual machine for a specified period of
time. When the time period elapses, your virtual machine will automatically resume
execution.
I SLeep
where:
nn
[~~~]
HRS
indicates the number of seconds, minutes, or hours, measured by the time-of-day
clock, that your virtual machine is to remain stopped. The value nn can be any
decimal number from 00 through 99. If you specify no time unit, CP assumes
that nn indicates minutes.
ATTN
indicates that if the SLEEP command with a time interval was issued via a
DIAGNOSE Code X 08 instruction, the return code should indicate whether
the SLEEP command ended because the time interval expired (RC = 0), the
ENTER key pressed (RC = 2) or because an attention was signalled (RC = 1457).
I
I
Usage Notes
1. During the dormant period, the virtual machine does not run but connection
time is still counted.
2. Messages continue to be displayed even though your virtual machine is in the
dormant state.
3. You can start your virtual machine at any time by pressing the ENTER key. If
you specify a sleep interval in the command line, your virtual machine awakens
automatically when the specified interval has elapsed ..
4. If you do not specify an interval, your virtual machine remains dormant until
you press the ENTER key.
5. If you issue the SLEEP command from a CP environment, you will return to the
CP environment when the time interval has elapsed, or when you press the
ENTER key.
6. If you issue the SLEEP command while in virtual machine environment, the end
of the time interval or pressing ENTER returns your display to virtual machine
mode without entering the CP environment.
7. The SLEEP command, with the time interval, is a convenient way to delay or
schedule the execution of certain jobs that could be run more efficiently at a
later time (for example, second shift).
8. If the SLEEP command with a time interval was entered using a DIAGNOSE
instruction, the return code indicates whether the interval has expired (RC = 0);
whether the ENTER key was pressed (RC = 2), or an ATTENTION was
signaled (RC = 1457).
Chapter 2. VM/XA SP CP Commands
569
SLEEP
Responses
None.
Migration Notes
VMISP HPO
1. VMjXA SP does not terminate SLEEP when you reconnect.
2. VMjXA SP supports the ATTN operand which allows you to be notified if
attention terminates the SLEEP.
VMIXA SF: Unless you specify ATTN, VMjXA SP always provides return code 0
from a valid SLEEP command even if attention terminates the SLEEP.
570
VM/XA SP2 CP Command Reference
SMSG
SMSG
Privilege Class: G
Use the SMSG command to send a special message to a virtual machine
programmed to accept and process the message.
I
SMsg
userid
msgtext
where:
userid
is the identification of the virtual machine to whom the special message is to be
sent. If you specify userid as '*', it indicates that the message is to be sent to
yourself.
msgtext
is the text of the message that you are sending.
Usage Notes
1. Special messages do not appear on the receiving user's console because the
messages are expected to be instructions or commands that are processed by the
receiving virtual machine.
2. Virtual machines can only receive special messages under the following
conditions:
• The receiving virtual machine has issued the SET SMSG ON command, or
set the VMCPSMSG flag at AUTHORIZE time
• The user wishing to receive special messages has issued an AUTHORIZE
with the Virtual Machine Communication Facility (VMCF)
• You can also receive special messages via IUCV by issuing the SET SMSG
IUCV command.
Responses
None.
Chapter 2. VM/XA SP CP Commands
571
SPACE
SPACE
Privilege Class: D
Use the SPACE command to force the current output file of a real printer to be
single spaced, regardless of the carriage control commands contained in the actual
file.
,I
SPAce
rdev
where:
rdev
is the real device number of the printer whose output file is to be single spaced.
Usage Notes
None.
Responses
PRT rdev SPACING
userid
FILE spoolid RECS{nnnn} COPY [*]nnn SEQ sss
nnnK
nnnM
where:
rdev
is the real device number of the printer.
userid
is the identification of the user whose file was active and single spaced.
FILE spoolid
spoolid is a file currently being processed.
RECS { : : : }
oooM
is the number of logical records in the spool file. If the number is greater than
9999, then the number is shown as nnnK, where K represents the number of
lines rounded to the nearest 1000. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy [*)000
is the remaining number of copies of the file to be created. The asterisk (*)
indicates that the 3800 printer is to copy each page nnn times before going on to
the next page.
SEQ sss
is the sequence number for the file on the printer.
572
VM/XA SP2 CP Command Reference
SPACE
Migration Notes
VMISP HPO: VMjXA SP provides a response concerning the file being spaced as
opposed to no response as in VMjSP HPO.
Chapter 2. VM/XA SP CP Commands
573
SPOOL
SPOOL
Use the SPOOL command described in this section to set the spooling control
options for one or more of your virtual spooling devices. The options that you
select modify operational functions associated with your virtual reader, printer,
punch, or console and control the disposition of files after they have been processed.
General Usage Notes for SPOOL
1. A spool file is created when the first record for a printer or punch is processed
by the virtual unit record simulation routines in CPo CP associates this spool
file with the virtual unit record device and assigns it a number called the spoolid
(spool file identification). You can use the spoolid to identify the file that you
have produced, and to manipulate the file using the VM/XA System Product
CP spooling commands, such as ORDER, CHANGE, and PURGE.
When you print or punch a file, CP displays its spoolid. You can use the
spoolid to find out various kinds of information about the file using the CP
QUERY command.
2. It is important that you remember that the SPOOL command controls both
operational characteristics of your virtual spooling devices and the disposition of
files after they have been processed.
For example, you use the SPOOL command to select which files you want to
process on your virtual readers. The SPOOL READER command does not
change any of the characteristics associated with the files in your reader queue,
but simply indicates whether a file will be purged or retained after it has been
read, and if it is to be retained, whether the file remains eligible for immediate
reprocessing.
The files in your reader queue are controlled using a combination of file
characteristics and the options in effect for the virtual reader on which they are
to be processed. Input files do not derive their characteristics from the reader,
except for HOLD status, which is set as a function of the KEEP option.
Figure 1 on page 575 summarizes the disposition of a reader file once it has
been processed, depending on the HOLD/KEEP settings specified for the reader,
and the KEEP setting of the file.
For output devices (virtual printers, punches, and consoles) use the SPOOL
command to define the characteristics of the spool files that you are creating.
You can use the SPOOL command to indicate whether files will be held from
further processing, and whether they will be retained after they have been
processed. This information is associated with the spool file itself, regardless of
the characteristics of the device on which the file is to be processed. In addition,
you can use the SPOOL command to direct the output files that you are creating
to unit record devices (readers, printers, and punches) associated with other
virtual machines.
574
VM/XA SP2 CP Command Reference
SPOOL
File
Status
Device Options
Disposition
NOKEEP
NOHOLD/NOKEEP
The file is purged.
NOKEEP
NOHOLD/KEEP
The file is retained in user HOLD status.
KEEP is not set on the file.
NOKEEP
HOLD/NOKEEP
The file is retained and remains eligible
for processing on your virtual reader.
NOKEEP
HOLD/KEEP
The file is retained in user HOLD status.
KEEP is not set on the file.
KEEP
Any setting
The file is retained in user HOLD status.
KEEP status remains on the file.
Figure 1. Disposition of Reader Files Depending Upon HOLD/KEEP Settings
All of your output files derive their characteristics from the virtual device on
which they were created. If the output device is spooled with the KEEP and
NOHOLD options, the file will be printed or punched, and then be placed in
HOLD status, retaining its KEEP characteristics. If you change the file status
to NOHOLD, the file is processed at the real device one more time and once
again is placed in HOLD status. If you do not want to retain the file, you must
change both its NOH OLD status and NO KEEP characteristic, or purge it using
the CP PURGE command.
3. Unless you reset these values, the following options are the default values for
your spool files:
Device
Default Options
Reader
NOHOLD NOKEEP NOCONT EOF CLASS Al
Punch
NOHOLD NOKEEP NOCONT CLASS Al OFF COpy 001
NOMSG NONAME NOEOF
Printer
NOH OLD NOKEEP NOCONT CLASS Al OFF COpy 001
NOMSG NONAME NOEOF
Console
NOHOLD NOKEEP NOCONT CLASS TI OFF COpy 001
TERM TO * PRINTER NOMSG STOP NONAME
NOEOF
IThese are default classes only if a specific class is not part of your entry in the
system directory.
4. You can transfer a spool file to another VM/XA SP user by issuing the CP
SPOOL, CHANGE, CLOSE, or TRANSFER commands. Use the CHANGE
and TRANSFER commands to transfer already existing files. Use the SPOOL
or CLOSE commands to transfer files which you are in the process of creating,
or files which you will create in the future. For example, if you want to transfer
the printer or punch files that you are creating to another user's virtual reader,
issue the SPOOL command with the TO option:
SPOOL vdev TO userid RDR
where vdev is the virtual device number or the virtual device "type" of your
virtual machine output device and userid is the user identification of the other
user's virtual machine. Designating either a reader, printer, or punch is
Chapter 2. VM/XA SP CP Commands
575
SPOOL
optional; the default is to the reader. The command defines the user's queue to
which you are directing the file.
If you want to print or punch a file for someone else, you can also issue the
SPOOL command with the FOR option:
SPOOL vdev FOR userid
where vdev is the virtual device number or the virtual device type of your virtual
machine output device and userid is the user identification of the other user's
virtual machine.
5. When a file changes ownership, as when it is changed to or from another user,
the spool file ID number also changes. The new number is obtained from the
pool of available ids of the recipient of the file.
Thus, if user SAM changes his file #3 to user HARRY, he would get the
response:
RDR 0003 SENT TO HARRY RDR AS 0018
Harry would now have a file #18.
576
VM/XA SP2 CP Command Reference
SPOOL READER/PRINTER/PUNCH/CONSOLE
SPOOL READER/PRINTER/PUNCH/CONSOLE
Privilege Class: G
Use SPOOL READER/PRINTER/PUNCH/CONSOLE to modify the spooling
control options in effect for your virtual machine.
SPool
{Reader} {option A }l
printer} { [option A] [option B] }l
{ PUnch
{CONsole} {[option A] [option B] [option C] }l
{vdev
1
}
You must specify at least one option of the indicated options. These are described
in "SPOOLING: Options" on page 579.
where:
READER
RDR
PRINTER
PRT
PUNCH
PCH
CONSOLE
modifies the options for all of your virtual readers, printers, punches, or console
spooling devices, including the STARTing or STOPping of spooling operations.
vdev
specifies the virtual device number of the virtual spooling device whose options
you want to modify.
options••.
see "SPOOLING: Options" on page 579.
Migration Notes
VMISP HPO
1. If a reader file is in KEEP status, VM/XA SP changes the file to HOLD after it
has been read.
2. In VM/XA SP a reader file will not be put into user HOLD if the virtual reader
is spooled CONT and HOLD.
3. VM/XA SP truncates a name identification for MVS data set names to 16
characters (if longer than 16).
4. VM/XA SP allows you to specify additional operands: KEEP /NOKEEP and
MSG/NOMSG.
5. VM/XA SP does not support the DEST option.
6. VM/XA SP sets DIST to what is in the directory for DIST *.
7. VM/XA SP has a minimum truncation of NOT for NOTERM.
Chapter 2. VM/XA SP CP Commands
577
SPOOL READER/PRINTER/PUNCH/CONSOLE
8. VM/XA SP accepts SPOOL PRT CLOSE PURGE and then closes. and purges
the file.
9. VM/XA SP always gives responses whenever a file is closed.
10. If the DIST option is specified for a device, VMfXA SP sets the distribution
code for all files created on the device to what was specified.
11. The VM/XA SP response includes the number of records and KEEP setting.
578
VMjXA SP2 CP Command Reference
SPOOLING: Options
SPOOLING: Options
option A:
HOl d .] [KEep ] [CONt ] [EOF ] [CLass c]
[ NOHold NOKeep NOCont NOEof
option B:
- [To] {use:id} [Reader J":- [CLOSE]
Pri nter . PUrge
SYSTEM
PUnch
For
{use~id}
SYSTEM
[FORM {6~~
}]
[FLaSh {~~: [~~~J
[MOdifY
}]
{~~~e [nl ] ]
--FeB , na~e -
: '8
.
< 10
J 1~
{ OFF
I.-
~,
-
fCHars {n~~~a Enamel [name2 [name3lll }
]
bHars namea [CHars namel [CHars name2 [CHars name3lll
NAme {fname [ftype]}·
dsname
[
NOName
option C:
]
STArt] [NOTerm]
[ STOp
TErm
Chapter 2. VM/XA SP CP Commands
579
SPOOLING: Options
where:
HOLD
NOHOLD
indicates whether you want to HOLD files.
If you specify HOLD for an output device, all the files created by the device are
placed in USER HOLD status. When a spool file is in USER HOLD status, it
is not processed at its destination device (the real printer, punch, or virtual
reader) until you remove the HOLD status by issuing the CP CHANGE
command with the NOHOLD option.
If you specify HOLD for an input device, files are retained after they have been
read. Unless you specify the KEEP operand for the file or for the device, the
file remains in the reader queue and is the next file eligible for processing. This
is in contrast to the HOLD status on a spool file, which makes the file ineligible
for processing.
Specify NOHOLD to allow files to be purged after processing.
KEEP
NOKEEP
indicates whether you want to retain a spool file after it has been processed.
Specify KEEP if you want to retain files after they have been processed.
F or a virtual printer or punch directed to a real device, after the file has been
printed or punched, it is placed in USER HOLD status, while retaining its
KEEP status.
For a reader, KEEP also places your spool file in user HOLD status after it has
been read, but KEEP status is not set on the file. Note that the reader DEVICE
hold option does not affect FILE hold status.
Specify NOKEEP to reset the KEEP status so that files are not retained in the
system once processing has been completed.
CONT
NOCONT
controls the continuous spooling option.
For output devices, CONT causes all CLOSE requests to be ignored unless
specified with EOF override option. NOCONT resets the option.
For readers, CONT specifies that reading will continue without end-of-file
indications at the end of each virtual spool file, until the virtual device is empty.
NOCONT specifies that end-of-file is signaled after each spool file is read, and
then the reader resets at the next logical file.
EOF
NOEOF
For a printer or punch, EOF causes the device to be automatically closed when
50,000 records are placed into the active spool file. Punches are closed
immediately at 50,000 records. If page controls are found in a print file within
the next 100 records, the file is closed at the end of the page. If no page
controls are found by then, it is presumed there are none, and the file is closed
after 50,100 records.
For a reader, the EOF/NOEOF option specifies the reflection given when
end-of-file is reached (as defined by the CONT /NOCONT option). EOF
specifies that a unit exception is reflected on the first read past the end of the
file. Further reads result in a normal read of the next file, if any, or with a unit
580
VMjXA SP2 CP Command Reference
SPOOLING: Uptions
check if the device is empty. NOEOF specifies that unit check is reflected on the
first read past end-of-file, or any subsequent read to an empty reader.
CLASS c
specifies the spool class of the device. c is a I-character alphanumeric field
whose values can be A through Z, 0 through 9, or * (asterisk). The CLASS
option determines which destination devices can process the spool file. If you
print or punch a file from one of your virtual devices, the file is assigned the
class that is associated with the device. The file is then printed or punched on a
real device which also has this class associated with it. The operator sets this
class.
The class associated with a virtual reader determines which files it recognizes for
processing. If you specify a specific class, the reader processes only files of the
same class. If you specify *, the reader processes all files regardless of class.
MSG
NOMSG
indicates whether you want to be informed about file printing and punching. If
you specify MSG, you are informed of file printing and punching if the file is
printed or punched on the same system as your user ID. The message is sent to
you when the file begins printing or punching on a real device. This message is
not sent if you have issued CP SET IMSG OFF. Specify NOMSG if you do not
want messages sent to you when the file begins printing or punching on a real
device.
COpy (*]000
indicates the number of copies that are to be printed or punched when the file is
spooled to the real unit record device. Note that regardless of what number you
specify for COPY, only one spool file is actually created. However, VM/XA SP
continues to associate the COpy number with the spool file until the spool file is
processed by a real printer or punch. At that time, VM/XA SP produces the
specified number of real printed or punched copies. If the real printer ia a 3800
device, an asterisk (*) indicates that the printer is to print each page nnn times
before going on to the next page.
(TO] { us:rid
}
SYSTEM
sends the output of the virtual device to the virtual reader, virtual printer, or
virtual punch of the specified userid. The distribution code on the spool files
becomes the distribution code specified for userid in the system directory.
When you specify TO, you retain control of the spool file. For example, you
can use the TRANSFER command to retrieve the file from the specified userid.
TO SYSTEM is equivalent to specifying OFF and resets the transferred spool
option.
READER
PRINTER
PUNCH
indicates the spool file queue to which your file is directed. If you do not
specify a queue, the file is transferred to the other user's reader queue.
Chapter 2. VM/XA SP CP Commands
581
SPOOLING: Options
FOR
}
{U~erid
SYSTEM
except for console output, transfers the spool file from the virtual device to the
corresponding virtual device of the specified userid. VMjSP transfers console
output to the receiver's virtual printer. The distribution code on the spool files
becomes the distribution code specified for userid in the system directory.
You can specify FOR * to change the spool file ownership and destination code
to those of your own virtual machine. Specifying FOR * is equivalent to
specifying the OFF operand for the device.
FOR SYSTEM is equivalent to specifying OFF and resets the transferred spool
option.
If you specify FOR userid, you cannot specify either the TO or the OFF
operand.
OFF
resets the TO or FOR option from the previous spooling command.
FORM form
specifies the form name for the resulting spool file(s). "form" is 1 to 8
characters.
FORM OFF
resets the form to the system default as specified by the installation.
FLASH name
[ALL]
nnn
signifies that a form overlay contained in the 3800 printer is to be superimposed
(or flashed) onto the specified number of copies of the output. The name, to be
I to 4 characters in length, identifies the forms overlay to be used in the
projection. The number, nnn, must be in the range from 0 to 255. The number
specifies that the first nnn copies of output are to be flashed.
For example, if you specify COpy 4 and FLASH name 2, the first two copies of
your file are flashed, while the last two copies remain unflashed. If "ALL" is
specified, the flash count always matches the copy count. "ALL" is the default.
FLASH OFF
resets the flash parameters. Blanks are inserted into the flash name field of the
specified spool file or files, and the count is set to O.
MODIFY name (n)
assigns a copy modification module to be used when printing the spool file or
files on the 3800. This function makes it possible to alter text by either
preventing printing of certain information or adding labels to output. The name
must be 1 to 4 characters.
"n" selects one of the character sets specified by the CHARS operand to be used
for the copy modification text. The values 0, 1, 2, and 3 correspond to the order
in which the table names have been specified. If no "n" is specified, the first
character set ("0") is assumed.
MODIFY OFF
resets the modify parameters. Blanks are inserted into the modify name field of
the spool file or files and, when printed, no modification will occur. The modify
number ("n") is set to O.
582
VM/XA SP2 CP Command Reference
SPOOLING: Options
FeB
rre!
specifies the forms control buffer to be used when printing the spool file or files
on the 3800 printer. name is the 1- to 4-character name of an FCB image, or
the number 6, 8, 10, or 12. This number tells the 3800 to print the entire spool
file at 6, 8, 10, or 12 lines per inch, regardless of the size of the paper that is
currently loaded. An FCB specified at 10 will print only on a 3800 Model 3
printer.
FCB OFF
resets the FCB parameter. Blanks are inserted into the FCB name field of the
spool file or files and, when printed, a default FCB will control the vertical
spacing of the output text.
CHARS nameO (namel [name2(name311J
CHARS nameO (CHARS namel [CHARS name2 (CHARS name311J
specifies the name of the character set or sets used when printing the spool file
or files on the 3800 printer. Each name must be from 1- to 4-characters with a
maximum of four names specified. The multiple use of "CHars" need only be
used if "nameN" would conflict with an option name (for example, "FORM")
or with a userid. If more than one name is specified, along with modification,
the order in which the names appear determines which table will be used for
copy modification text.
CHARS OFF
resets the "CHARS" parameters. Blanks are inserted into the name fields of
character sets to be used for output generation. The resulting spool file or files,
therefore, will use a default character set when actually printed on a 3800
printer.
DIST {distcode}
OFF
*
specifies the distribution code to be assigned to spool files created on this virtual
device. 'distcode' is 1 to 8 characters. You can override this distcode using the
DIST option on the CP CLOSE or CP CHANGE commands.
"DIST OFF" and "DIST *" reset the distribution code of the spool file(s) to the
default specified in your entry in the system directory.
NAME {. fname (ftype) 1.
dsname
J
specifies the file name and optional filetype, or the data set name that will be
given to each spool file the virtual device creates. The fname and ftype must be
8 characters or less. The data set name may be up to 24 characters; however, if
the name has more than 16 characters, it is truncated to 16 characters.
NONAME
resets the NAME option. Blanks are inserted into the name field for spool files
the virtual device creates.
CLOSE
closes the spool file on the specified device regardless of the CONT setting for
the device. CLOSE is equivalent to issuing CLOSE with the EOF option. If
PURGE is specified, CLOSE is not necessary.
Chapter 2. VM/XA SP CP Commands
583
SPOOLING: Options
PURGE
closes and purges the spool file on the specified device regardless of the CONT
setting for the device. If PURGE is specified, the CLOSE option is not
necessary. PURGE is equivalent to issuing CLOSE with the PURGE option.
START
commences placing input and output from your display station into a spool file.
Full-screen data output operations are not placed in the spool file. After the
console is closed, the file becomes a printer spool file. START applies only to
consoles.
STOP
terminates the spooling of display station input and output. STOP does not
CLOSE the console spool file. STOP applies only to consoles.
TERM
displays the display station input and output on your display screen in addition
to placing it in a spool file. The TERM operand has no effect unless the
START function is also in effect. TERM applies only to consoles.
NO TERM
suppresses the display of input and output on your display screen while placing
it in a spool file. Full screen output is not suppressed and is not placed in the
spool file. The display of console input and output is not suppressed if:
• It is the result of CP commands entered from CP mode
• The output line immediately precedes a virtual machine read to the console.
The NOTERM operand has no effect unless the START function is in effect.
NOTERM applies only to consoles.
Usage Notes
Refer to "General Usage Notes for SPOOL" on page 574.
When specifying "[TO] userid," if you omit the keyword TO, the userid cannot be
"T" or "TO." If you are transferring your output to your own virtual machine, you
may specify userid as an asterisk (*). If you specify TO userid, you cannot specify
either the OFF or FOR operand.
Responses
If the SPOOL command is used to close an output device, the message:
!
RDR! FI LE spdl SENT {TO } user; d {RDR'}' AS spd2 RECS {nnnn} COpy [*] nnn C {HOLD } {KEEP .}
PRT
' FROM
PRT
nnnK
NOHOLD NOKEEP
PUN,
PUN
nnnM
CON
ij the response you receive unless you have issued the CP SET IMSG OFF
command.
584
VMjXA SP2 CP Command Reference
SPOOLING: Options
where:
RDR
PRT
PUN
CON
indicates the spool file queue. If you are transferring a file to another user's
virtual machine, this field indicates the queue from which the file originated. If
you are receiving a file from another user, this field indicates the file queue in
which the file has been added.
spdl
is the spool identification number of the file at the time the command is issued.
TO userid
indicates to whom the file has been sent.
FROM userid
indicates from whom the file came.
RDR
PRT
PUN
indicates the spool file queue. If you are transferring a file to another user's
virtual machine, this field indicates the queue in which the file has been added.
If you are receiving a file from another user, this field indicates the file queue in
which the file originated.
spd2
is the spool identification number of the file after the command is complete.
RECS {nnnn }
nnnK
nnnM·
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy (*]nnn
specifies the number of copies of the file you want printed or punched when the
file is produced.
The asterisk (*) indicates that the 3800 printer is to copy each page nnn times
before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
c
is the spool file class assigned to the file.
HOLD
NOHOLD
is the user HOLD status associated with the file.
KEEP
NOKEEP
is the KEEP status associated with the file.
Chapter 2. VM/XA SP CP Commands
585
SPTAPE
SPTAPE
The format box below shows all the operands available with the SPTAPE command.
Complete descriptions of the operands appear on the following pages in the same
sequence as the operands appear here.
SPTape
CANCEL rdev
printer} spool id1 [SPOOl id2] , ~
PUnch
END
{
. Reader
• CLass {abCd;fQh}
,
DUMP rdev [userid]
FORM {f~nn
,.
,
!
l
IMG
NSS
, UCR
NLS
TRFiles
}
,ALL
spoolidl
I'
>
[~~~Olid2] .1
CLass {abCd;fQh}
l ALL
800
LEAVE]
REWind
1600
MODE
[ RUN
6250
[
I' 1]
38K
[[SYSHold] [USERHold] [NOHold]] [PUrge]
,
LOAD rdev [userid]
[S
printer} 'spoolid1
POOlid2]
PUnch
END
{
Reader • CLass {abCd;f9h}
FORM {f~rm}
,ALL
~
UCR
NLS
TRFiles
,LEAVE]
REWind
[ RUN ,
SCAN rdev [userid]
STOP rdev
586
VMjXA SP2 CP Command Reference
CLass {abCdefgh}
.
*
ALL
[[SYSHold] [USERHold] [NOHold]]
LEAVE]
REWind
[ RUN
-r
J
SPTAPE
Notes:
1. Form and class may be specified on the same command line.
2. If you have only class E command privileges, you cannot process reader, printer,
or punch files.
The SPT APE command supports the migrating of spool files between different VM
systems. However, this migration is supported between the following systems only:
VM/SP
VM/HPO
VM/HPO
VM/HPO
VM/HPO
VM/XA SF
VM/XA SF
VM/XA SP
Release
Release
Release
Release
Release
Release
Release
5
5
4.2
3.8
3.6
1
2
Any references to VMjSP in the following SPT APE pages refer to these releases
only. For more information, refer to When to Use the SPTAPE Command on
page 589.
This function allows spool files and system data files to be saved on tape. Also, it
allows the files to be loaded from the tape to the spool file system.
General Usage Notes for the SPTAPE Command
1. You may issue as many SPTAPE commands as you wish and load from or
dump to multiple tape drives. However, if loading and dumping requests are
active simultaneously, caution should be exercised since the two functions may
overlap.
For example, if a LOAD request has loaded a file whose attributes match the
specifications on a "dump purge" request, the file is dumped and purged from
the system.
2. Tape handling options are provided on the LOAD, SCAN, and DUMP options
and should be used for tape positioning for subsequent commands. The STOP
option positions the tape. This allows the user to continue with a new command
at the current position. The CANCEL option assumes that the user is done and
unloads the tape. If you do not wish to continue, do not mount a new tape and
issue the SPTAPE CANCEL or SPTAPE STOP command.
3. When files being dumped do not fit on a single tape reel, the current tape is
rewound and unloaded, a command response is given that asks for a new tape to
be mounted and that identifies the last complete file, if any, dumped. After the
next tape is mounted and readied, dumping of the remaining files continues. If a
file is only partially dumped when the end of a tape is reached, the entire file is
dumped onto the new tape.
4. If the message "TAPE WAS NOT REWOUND" appears after you issue the
SPT APE SCAN REWIND command, you must issue another REWIND
request.
5. While the SPT APE command is processing a file in the spooling subsystem, that
file can -be queried, but it cannot be manipulated or changed in any way.
6. Both 3420 9-track tape drives and 3480 tape drives are supported.
Chapter 2. VM/XA SP CP Commands
587
SPTAPE
7. A file loaded into the system from a tape retains the same characteristics as the
original file, but is assigned a new spoolid in the spooling system. A message is
issued that correlates the old and new spoolids.
8. Open files cannot be dumped.
9. Only the user who issues an SPTAPE DUMP, SCAN, or LOAD command may
STOP or CANCEL that command.
10. If the user does not wish to receive SPTAPE responses, the CP command SET
IMSG OFF may be used to suppress them. (This does NOT suppress the
request to mount a new tape when the current one is full.)
11. On a 3420, if the mode selected is not consistent with the tape attributes supplied
at system generation time or if the tape drive was generated as a 7-track drive, a
message is displayed asking the SPTAPE user if SPTAPE processing should
continue. If the user answers "yes," SPTAPE attempts to write at that mode. If
the user answers "no," SPTAPE processing halts. For a 3480, if the mode is not
38K, an error message is issued.
12. If a spool file originated in a VMjSP system migrates to VMjXA SP, it loses
those file attributes which do not have a VMjSP equivalent. Therefore, if the
file is migrated back to the VMjSP system, it will not be identical to the original
file.
For example, if a VMjSP 3211-type file has imbedded UNFOLD (X 123 1),
FOLD (X 143 1), or LOAD FCB (X 163 1) CCWs and is loaded into a VMjSP
system, those CCWs are removed because they are not supported in VM/XA SP.
13. When transporting files from VM/XA SP to VM/SP, do not dump system type
files on tape. These files are: CP ABEND DUMPs (usually class D),
VMDUMPs (usually class V), NSS, IMG, UCR, NLS, and TRF files. VM/SP
SPTAPE detects an error and ends processing if it encounters one of these files
on tape.
14. If files are being transported to the VM/XA system and the file owner's userid
does not exist on the VM/XA system, the file is assigned to the SPTAPE
command issuer's userid.
15. When loading NSS, IMG, UCR, NLS, or TRF files, the user may be loading
files with the same filename and filetype as other NSS, IMG, UCR, NLS, or
TRF files currently active on the system. If this should happen, check these files
to determine which should be kept. The unnecessary files should be purged.
16. SPTAPE does not dump class W system trace files.
17. When files are being loaded back into a VM/XA SP system, if the owner of the
file runs out of spoolids, the file is assigned to the SPTAPE command issuer and
a message is sent to both users.
18. When a file is loaded from tape, the spool file id number changes. The new
number is obtained from the pool of available ids of the recipient of the file.
Thus, if user SAM changes his file #3 to user HARRY, he would get the
response:
RDR 0003 SENT TO HARRY RDR AS 0018 RECS 1000 COpy 001 A NOHOLD NOKEEP
Harry would now have a file #18.
588
VM/XA SP2 CP Command Reference
SPTAPE
Action Taken on Tape Overflow
If the output tape fills before all files specified by the command are dumped, you
can either continue or end the command:
• Mount and ready a new tape on the same tape drive. The command will
continue.
• Issue SPTAPE rdev CANCEL or SPTAPE rdev STOP to end the command.
• If you take no action, the command remains dormant and the tape is not
available for other users.
Action Taken on 1/0 Error Conditions
When an I/O error condition occurs during a DUMP operation (such as an error
reading the file from disk or writing the file to tape), the following happens:
• The system issues a message.
• The tape is rewound to the last complete file.
• A second tapemark is written to indicate end-of-tape.
• The tape is positioned as specified by the user.
• The command is halted.
If the PURGE option was specified, all files successfully dumped to tape will be
purged. All other files remain in the spool file system.
When loading or scanning, an I/O error can occur when reading a file from tape, or
writing a file to DASD. Also, spool space can become full or there may be no more
spool file id's available when loading files back into the system.
If either an I/O error occurs or spool space does become full, the following happens:
• The system issues a message.
• The tape is rewound to the last tapemark, then positioned as specified by the
user.
• The command is halted.
Files that have been successfully read remain in the spooling system, but any partial
file is purged.
When to Use the SPTAPE Command
When the spool file operator determines that the spooling system is overloaded, the
operator can use the SPTAPE command to temporarily store files on tape.
The SPTAPE command enables the spooling operator to store to, and retrieve from
tape, those spool and system data files that he or she wants to schedule later on
VM/XA SP. The files can be read back into the VM/XA SP system selectively so as
not to overload the spooling system. An option is provided to scan the tape for
priority files.
Transferring spool files from the VM/XA SP spool file system to the VM/SP spool
file system, or back again, can be accomplished using the SPTAPE command. Use
the SPTAPE DUMP option to write the files of one system to tape. The files may
then be loaded into the other system's spool file queues by using the SPT APE
LOAD 'option.
Chapter 2. VMjXA SP CP Commands
589
SPTAPE
Note: System data files and other system-type files (for example, CP ABEND,
VMDUMP, CPTRAP, ACNT, and MONITOR) files are not transportable
between systems if both are not either VMjSP or VMfXA systems.
Finally, SPTAPE can be used to back up named saved system (NSS) files, image file
libraries (IMG), saved ~egments, user class override files (UCR), system trace files
(TRF), and message repository files (NLS).
Response 1
When spool or system data files are being loaded, dumped, or scanned on tape, the
user is informed of each file processed through the following response:
DUMPING}
LOADING. rdev
{ SCANNING
'PRT'
PUN userid spoolidl class form stat [NOW spoolid2]
RDR:
NSS
JMG
UCR.
NLS
~
: \ TRrJ
where:
DUMPING
LOADING
SCANNING
indicate which SPTAPE functions are active.
rdev
is the real device number of the tape drive on which the SPTAPE operation
(dumping, loading, or scanning) is taking place.
PRT
PUN
RDR
NSS
Il\1G
UCR
NLS
TRF
indicate the types of files being processed.
userid
is the userid of the file owner.
spoolidl
is the spoolid first given to the spool file.
class
is the spool class of the file.
form
is the operator form number of the file. The form field is blank for system data
files.
590
VM/XA SP2 CP Command Reference
SPTAPE
stat
is the hold status of the files: USER (for user HOLD), SYS (for system HOLD),
and USYS (for both user and system HOLDs). The status field is blank for
system data files.
NOW spoolid2
the new spoolid given to the restored file.
Response 2
When loading or scanning from a tape that was created by the VMjSP SPTAPE
DUMP command, the following response is sent when a VMjSP system-type file is
encountered. VMjSP system-type files that are skipped include files created by the
VMjSP commands CPTRAP, MONITOR, ACNT, or VMDUMP, and files that
contain VMjSP CP abend dumps.
SKIPPING VMjSP SYSTEM-TYPE FILE ON DRIVE rdev
where:
rdev
is the real device number of the tape drive on which the SPTAPE operation
(loading, or scanning) is taking place.
Response 3
If files are being transported to the VMjXA system and the file owner's userid does
not exist on the VMjXA system, the following response is sent:
USERID useridl DOES NOT EXIST; FILE spoolid ASSIGNED TO userid2
where:
useridl
was the file owner on the old system.
spoolid
is the new spoolid given to the restored file.
userid2
is the SPTAPE command user's userid.
Note: You will not receive any of the responses listed above if you have issued the
SET IMSG OFF command.
Response 4
When a user issues SPTAPE with the STOP or CANCEL option or SPTAPE
processing is complete, the following response is issued to the command issuer:
SPTAPE '{DUMP} FUNCTION ON DRIVE rdev {COMPLETE }
LOAD
STOPPED
SCAN
CANCELLED
where:
DUMP
LOAD
SCAN
is the SPTAPE function which was active.
Chapter 2. VM/XA SP CP Commands
591
SPTAPE
rdev
is the real device number of the tape drive on which the SPTAPE function is
taking place.
COMPLETE
STOPPED
CANCELLED
is the current status of the SPTAPE function.
Response 5
When a file is dumped with the PURGE option, or when a file is loaded, the file
owner is sent the following response:
{
RDR} FILE spdl SENT {TO } userid {RDR}, AS spd2 RECS {nnnn} COpy [*]nnn
PRT
FROM
PRT
nnnK
PUN
PUN
nnnM
where:
C
{HOLD } {KEEP }
NOHOLD
NOKEEP
RDR
PRT
PUN
is the virtual device on which the file is being created or read.
spdl
is the spool identification of the file when it is associated with the command
user.
TO userid
indicates to whom the file has been sent.
FROM userid
indicates from whom the file came.
RDR
PRT
PUN
indicates the spool file queue that now contains the file.
spd2
is the spool identification of the file when it is associated with the "userid" in the
response.
RECSnnnn
nnnK
nnnM
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy [*)oon
specifies the number of file copies you want printed or punched when the file is
produced.
When the optional asterisk (*) is specified, the 3800 printer prints each page
from the spooled output files nnn times before going on to the next page.
592
VMjXA SP2 CP Command Reference
SPTAPE
c
is the spool file class assigned to the file.
HOLD
NOHOLD
is the user HOLD status associated with the file.
KEEP
NOKEEP
is the KEEP status associated with the file.
This response is suppressed if the virtual machine user has issued the SET IMSG
OFF command.
Response 6
If the end-of-reel is reached before all the selected files have been dumped, the
following response is sent:
END OF VOLUME ON TAPE rdev, MOUNT NEXT TAPE
LAST FILE DUMPED userid SPOOlid}
{ NO FILES DUMPED
where:
rdev
is the real device number of the tape drive on which the SPT APE dumping
operation is taking place.
userid
is the userid of the last file that was dumped.
spoolid
identifies the last spoolid, if any, that was dumped.
The SPT APE user should mount and ready another tape. If the user does not wish
to continue dumping to another tape, the user should issue the SPTAPE CANCEL
or the SPTAPE STOP command.
Migration Notes
VMISP HPO
1. In VMjXA SP you may dump and load files using up to eight classes as
selection criteria.
2. In VMjXA SP you may also dump and load NSS, VCR, IMG, NLS, and TRF
files.
3. In VMjXA SP if you wish to specify one or more spoolids you must also specify
a userid. VMjSP HPO (Release 5) users do not see this difference.
4. VMjXA SP gives a final COMPLETE response when the total operation is
complete.
5. VMjXA SP does not support the DEST option.
6. VMjXA SP has no extended attribute buffer support.
7. VMjXA SP does not support the convert setting or the X I 5A I CCW content.
VMIXA SF: In VMjXA SP if you wish to specify one or more spoolids you must
also specify a userid.
Chapter 2. VM/XA SP CP Commands
593
SPTAPE CANCEL
SPTAPE CANCEL
Privilege Class: D, E
Use the SPTAPE CANCEL command to immediately terminate dumping, loading,
or scanning of files on or to tape.
I
SPTape
CANCEL rdev
where:
CANCEL
specifies that the operation should terminate immediately. The tape will then be
rewound and unloaded, regardless of the previous tape positioning options. The
tape (rdev) should be scanned from the current point to the first double tape
mark encountered.
rdev
is the real device number of the tape drive used by SPTAPE.
Usage Notes
For more information, see "General Usage Notes for SPTAPE."
Responses
For more information, see "General Responses for SPTAPE."
594
VM/XA SP2 CP Command Reference
SPTAPEDUMP
SPTAPE DUMP
Privilege Class: D, E
Use the 8PTAPE DUMP command to dump files to tape for backup storage or for
migration.
SPTape
DUMP rdev [userid] , { printer}
,
PUnch
Reader
spoolidl
[SPOOlid2]"
END
CLass {abCd;f9h}
~
~
FORM {f~rm
!
, ALL
•
}
I
>
IMG
NSS
UCR
NLS
, , TRFi 1es
1
LEAVE]
REWind
[ RUN
!
ODE 1600
8001' ]
[
6250
38K
[[SYSHold] [USERHold] [NOHold]] [PUrge]
where:
DUMP
specifies designated spool or system data files are to be written from the spool
file system to tape.
rdev
is the real device number of the tape drive used by 8PTAPE.
userid
indicates that only those files owned by the specified userid are to be processed.
If no userid is specified, files are processed regardless of userid. A userid must
be specified if selecting files by spoolid.
PRINTER
PRT
indicates that printer-type spool files are to be written. This option may be used
by class D users only.
PUNCH
PCH
indicates that punch-type spool files are to be written. This option may be used
by class D users only.
READER
RDR
indicates that reader-type spool files are to be written. This option may be used
by class D users only.
Chapter 2. VMjXA SP CP Commands
595
SPTAPEDUMP
spoolid
indicates a spool file (spoolidl), or the start of a range of spool files ending with
spoolid2, to be written.
END
indicates that all spool files on the selected queue with a spoolid greater than
spoolidl are to be written.
CLASS { :bcdefgh }
indicates that only those files with one or more of the specified classes are to be
written to tape. From one to eight classes (single alphanumeric characters with
no intervening blanks) may be specified. * indicates files are to be processed
regardless of class.
FORM
{!orm}
indicates that only those files with the specified operator form number are to be
written to tape. The form must be no more than 8 characters. Form may not
be specified on NSS, IMG, or VCR files. * indicates files are to be processed
regardless of form.
ALL
indicates that all files on the selected queue with the selected hold status are to
be written to tape, regardless of the file's spoolid, class, or form.
NSS
indicates that named saved system (NSS) and saved segment files are to be
written to tape.
IMG
indicates that image library files are to be written to tape.
VCR
indicates that user class override files are to be written to tape.
NLS
indicates that message repository files are to be written to tape.
TRFiles
indicates that system trace files are to be written to tape.
LEAVE
specifies that no tape movement occurs after the SPT APE operation is
performed. This is the default.
REWIND
specifies that the tape be rewound after the SPTAPE operation is performed.
RUN
specifies that the tape be rewound and unloaded after the SPTAPE operation is
performed.
MODE
specifies the tape density. Mode values of 800, 1600, 6250, or 38K may be
specified. 38K may only be specified when a 3480 tape drive is being used, and
is the default for a 3480 tape drive. 1600 is the default for all other drives.
SYSHOLD
specifies that system-held files should be included in the SPTAPE operation.
This option cannot be used with the NSS, IMG, VCR, NLS, or TRF options.
596
VMjXA SP2 CP Command Reference
SPTAPEDUMP
USERHOLD
specifies that user-held files should be included in the SPTAPE operation. This
option cannot be used with the NSS, IMG, UCR, NLS, or TRF options.
NOHOLD
specifies that files that are not held should be included in the SPTAPE
operation. This is the default. This option cannot be used with the NSS, IMG,
UCR, NLS, or TRF options.
PURGE
specifies that the spool files are to be deleted from the spooling system after
being successfully written to tape. This option cannot be used with the NSS,
IMG, UCR, NLS, or TRF options; it is valid only for DUMP. '
Usage Notes
1. Users who are class E and not class D may process only NSS, IMG, UCR,
NLS, or TRF files.
2. Refer to the "General Usage Notes for SPTAPE."
Responses
Refer to the "General Responses for SPTAPE."
Chapter 2. VMjXA SP CP Commands
597
SPTAPE LOAD
SPTAPE LOAD
Privilege Class: D, E
Use the SPTAPE LOAD command to load files from tape.
SPTape
LOAD rdev [userid]
{ printer} 'spoolidl
PUnch
Reader
[S POOlid2J"
END
CLass {abCd:f9h}
~
FORM {f~rm}
,ALL
s
!SPOOlidl [~~~Olid2J
CLass {abCd;f9h}
r!
IMG
UCR
NLS
TRFiles
[LEAVE]
REWind
!
>
ALL
[[SYSHold] [USERHold] [NOHold]]
RUN
where:
LOAD
specifies that designated spool or system data files are to be read from tape to
the spool file system.
rdev
is the real device number of the tape drive used by SPTAPE.
userid
indicates that only those files owned by the specified userid are to be processed.
If no userid is specified, files are processed regardless of userid.
PRINTER
PRT
indicates that printer-type spool files are to be read. This option may be used by
class D users only.
PUNCH
PCH
indicates that punch-type spool files are to be read. This option may be used by
class D users only.
READER
RDR
indicates that reader-type spool files are to be read. This option may be used by
class D users only.
spoolid
indicates a spool file (spoolidl), or the start of a range of spool files ending with
spoolid2, to be read.
END
indicates that all spool files on the selected queue with a spoolid greater than
spoolidl are to be read.
598
VM/XA SP2 CP Command Reference
SPTAPE LOAD
CLASS {:bcdefgh }
indicates that only those files with one or more of the specified classes are to be
loaded from tape. From one to eight classes (single alphanumeric characters
with no intervening blanks) may be specified. * indicates files are to be
processed regardless of class.
FORM {~orm }
indicates that only those files with the specified operator form number are to be
loaded. The form must be no more than 8 characters. Form may not be
specified on NSS, IMG, or UCR files. * indicates files are to be processed
regardless of form.
ALL
indicates that all files on the selected queue with the selected hold status are to
be read from tape, regardless of the file's spoolid, class, or form.
NSS
indicates that named saved system (NSS) and saved segment files are to be read
from tape.
IMG
indicates that image library files are to be read from tape.
UCR
indicates that user class override files are to be read from tape.
NLS
indicates that message repository files are to be read from tape.
TRFiles
indicates that system trace files are to be read from tape.
LEAVE
specifies that no tape movement occurs after the SPTAPE operation is
performed. This is the default.
REWIND
specifies that the tape be rewound after the SPTAPE
op~ration
is performed.
RUN
specifies that the tape be rewound and unloaded after the SPTAPE operation is
performed.
SYSHOLD
specifies that system-held files should be included in the SPTAPE operation.
This option cannot be used with the NSS, IMG, UCR, NLS, or TRF options.
USERHOLD
specifies that user-held files should be included in the SPTAPE operation. This
option cannot be used with the NSS, IMG, UCR, NLS, or TRF options.
NOH OLD
specifies that files that are not held should be included in the SPTAPE
operation. This is the default. This option cannot be used with the NSS, IMG,
UCR, NLS, or TRF options.
Chapter 2. VM/XA SP CP Commands
599
SPTAPE LOAD
Usage Notes
For more information, check under "General Usage Notes for SPTAPE."
Responses
For responses, check under "General Responses for SPTAPE."
600
VM/XA SP2 CP Command Reference
SPTAPE SCAN
SPTAPE SCAN
Privilege Class: D, E
Use the SPTAPE SCAN command to determine what files exist on the tape.
SPTape
SCAN rdev [userid] [LEAVE ]
REWind
RUN
where:
SCAN
specifies that the tape should be scanned from the current point to the first
double tape mark encountered.
rdev
is the real device number of the tape drive used by SPTAPE.
userid
indicates that only those files owned by the specified userid are to be processed.
If no userid is specified, files are processed regardless of userid.
LEAVE
specifies that no tape movement occurs after the SPTAPE operation is
performed. This is the default.
REWIND
specifies that the tape be rewound after the SPTAPE operation is performed.
RUN
specifies that the tape be rewound and unloaded after the SPTAPE operation is
performed.
Usage Notes
Refer to "General Usage Notes for SPTAPE."
Responses
Refer to "General Responses for SPTAPE."
Chapter 2. VM/XA SP CP Commands
601
SPTAPESTOP
SPTAPE STOP
Privilege Class: D, E
Use the SPTAPE STOP command to terminate processing after the current file.
I
SPTape
STOP rdev
where:
STOP
specifies that the operation should terminate after completing the current file.
The tape will then be positioned at the beginning of the next file.
rdev
is the real device number of the tape drive used by SPTAPE.
Usage Notes
Issuing SPT APE STOP between tape reel mounts during a multireel spool file dump
has the same affect as issuing SPTAPE CANCEL.
Responses
Refer to "General Responses for SPTAPE."
602
VM/XA SP2 CP Command Reference
START
START
Privilege Class: D
Use the START command to restart a spooling device after it has been drained. It
can also be used to change the processing options currently in effect for the device.
STArt
[
[
rdev
[options]
Reader
Printer
PUnch
ALL
]
]
where:
rdev ••.
is the real device number of a particular spooling device that you want to start.
You can specify more than one real device, each with its own set of options.
options
See "START: Options" on page 604.
READER
RDR
PRINTER
PRT
PUNCH
PUN
ALL
starts your readers, printers, or punches. Specify ALL to start all of your
readers, printers, and punches.
Migration Notes
VMISP HPO
1. VMjXA SP does not support the FILEFCB and CFILEFCB options, which are
supported in VMjSP HPO.
2. VMjXA SP does not support imbedded LOAD FCB CCWs, which are
supported in VMjSP HPO.
3. The VMJXA SP response does not indicate processor addresses.
4. VMjXA SP has a SEP option as well as NOSEP.
5. VMjXA SP does not support the DEST option.
6. VMjXA SP does not support logical printers.
7. Information in the VMjXA SP response has been reordered or changed: FORM
information appears on a different line; the response indicates whether the device
was started for the system or for a specific userid; the response provides
additional information about impact printers.
VMIXA SF: NOSEP must be specified on each START command if no separator
pages are to be printed. (In the past, if NOSEP was specified, it remained in effect
until another START command with SEP was specified.)
Chapter 2. VM/XA SP CP Commands
603
START: Options
START: Options
Option
A:
[
Option B:
USER {useri d} ]
SYSTEM
[CLass {abc~efgh} ] [FORM {f~nn}] [~~~~al] [~~:epJ
SEtup
Option C:
[
-
N03800 ] [IMage imagel ib] [CHars name] [FCB name]
BEG3800
6
ANY3800
8
10
12
Option D:
FOLD ]
[ NOFOLD
Option E:
[
[INDEX nn]
FLash {name} ]
OFF
[HOLD]
PUrge
where:
OptionA
valid for all real spooling devices.
OptionB
valid for printer and punch devices only, except for SETUP, which is only valid
for impact printers.
OptionC
valid for both impact and 3800 printers.
Note: CHARS is not valid for 1403 printers without the Universal Character
Set feature installed, 4245 or 4248 printers. FCB is not valid for a 1403
type printer.
OptionD
valid for impact printers only.
Note: INDEX is valid for 3211 printers only.
OptionE
valid for 3800 printers only.
Whenever a start command is issued with option(s), only the device settings
which correspond to those options are changed. The other device settings
remain unchanged from the previous START command.
Device settings are saved across system warm starts. Cold start defaults are
indicated under each option.
USER {' userid
}
SYSTEM
specifies which virtual machines this device may service. If you specify a userid,
the spooling device prints or punches only that user's files. If the device is a
printer or punch, the class designation must still match the class of the spool
files that it will service. If the device is a reader, no ID card is required.
If you specify SYSTEM, the spooling device will be available to service spool
files belonging to any user, which is the normal operation.
604
VMjXA SP2 CP Command Reference
START: Options
If no START command with the USER option has been issued since the last
cold start, SYSTEM is the default.
CLASS { :bcdefgh }
specifies the output classes that the device can service. You can specify from
one to eight classes (each a single character, with no intervening blanks). If you
are specifying multiple classes for your device, your files will be serviced in the
same order as the classes that you have specified. For example, if you specify
the following for your printer:
CLASS AD!
all class A files are processed before class D files, and all class D files before
class 1 files.
The CLASS operand is invalid for a reader.
Specify a class of * for printers or punches so that they can service any spool file
class.
If no START command with the CLASS option has been issued since the last
cold start, the default classes specified in the RDEVICE macro (during system
generation) are used.
FORM {~orm}
specify the form that an output device can service. 'form' is a 1- to 8-character
operator form number. This operand is ignored when the printer is in AUTO
mode.
Specify '*' for printers or punches so that files can be printed or punched
regardless of form.
If no START command with the FORM option has been issued since the last
cold start, the default form specified in the SYSFORM macro (during system
generation) is used. If the SYSFORM macro was not specified, the default is
STANDARD.
MANUAL
indicates that the operator will schedule output forms. Only spool files with the
form currently active on the device are processed. When the last spool file with
the current form is printed or punched, the output device stops. The operator
can then schedule a new form by issuing a START command with the FORM
option.
If 'form *' is specified, spool files are printed or punched regardless of the form,
and the output device will not stop between spool files with different forms.
AUTO
indicates that the operator wants CP to schedule forms output. The currently
active form is processed first. When all files with the current form have been
printed or punched, CP automatically selects a new form for the device. The
operator will receive a message to change forms, and the output device will be
idle. The operator can then put in the new form and press the START button
(or issue the START command) to print files with the new form.
SETUP
indicates that the operator wants CP to print a page so that forms alignment can
be verified. (This option is only valid for impact printers). The operator will get
a message indicating that he or she should set up the forms. When the form has
been set up, the operator should press the STOP button, then the START
Chapter 2. VM/XA SP CP Commands
605
START: Options
button. An alignment page will then be printed. It is the first page of the file,
with letters replaced with X's and numbers replaced by 9's. Each time the
operator presses the STOP, START buttons after a full alignment page has been
printed, another alignment page will be printed. When the forms are aligned,
you should issue the 'START' command for the device. The printer will then
return to its previous mode (AUTO or MANUAL), and the file will print in its
entirety.
If neither MANUAL, AUTO, nor SETUP is specified and the printer is currently in
SETUP mode, it will return to the previous mode, AUTO or MANUAL. If no
START command has been issued with the MANUAL, AUTO, or SETUP options
since a system cold start, the default is MANUAL.
SEP
NOSEP
indicates whether you want a file separator for output files. This option is
invalid for readers.
If you do not want separator pages to be printed, you must always say NOSEP.
If no START command with the SEP or NOSEP option has been issued since
the last cold start, the default is specified in the RDEVICE macro.
N03800
specifies that no spool files will be printed that contain 3800 load CCWs. Since
load CCWs issued to 3800 printers can take a great deal of time, this option
insures a fast output queue.
BEG3800
specifies that only spool files without 3800 load CCWs, or that contain 3800
load CCWs only at the beginning of the file, will be printed on this device. This
allows the user an initial setup with which the entire file will be printed.
ANY3800
places no restrictions on the presence or absence of 3800 load CCWs within
spool files. This option can potentially cause a slower oU,tput queue, depending
on the number of 3800 load CCWs issued by the selected spool files.
If no START command with the N03800, BEG3800, or ANY3800 options has been
issued since the last cold start, the default is N03800.
IMAGE imagelib
specifies the name of the system image library file which will contain the load
images (character sets, FCBs, graphic character modifications, or copy
modifications) that will be used for printing files and separators. 'imagelib'may
be from I to 8 characters in length, and must be an existing image library file.
If no START command with the image option has been issued since the last
cold start, the default imagelib specified on the RDEVICE macro (at installation
time) is used.
CHARS name
specifies the character set to be used by the printer when printing both the
separator pages and the file. For 3800 printers, the character set specified is
used for the separator pages and only those spool files which do not request a
specific character set. 'name' is I to 4 characters long. This character set name
must reside in the image library specified for this device.
For impact printers that support a character set the CHARS specified is used for
the entire file.
606
VM/XA SP2 CP Command Reference
START: Options
If no ST ART command with the CHARS option has been issued since the last
cold start, the default CHARS specified on the RDEVICE macro (at installation
time) is used.
Note: This option is not valid for 1403 printers without the Universal Character
Set feature installed, 4245, or 4248 printers.
FeB
l~me~
specifies the forms control buffer used by the printer when printing both the
separator pages and the file. For 3800 printers, the FCB specified is used for
separator pages and only those spool files which do not request a specific FCB.
For impact printers (except the 1403 which does not support the FCB), the FCB
specified is used for the entire file.
'name' is either a 1- to 4-character name of an FCB image in the image library
specified for this device, or the number 6, 8, 10, or 12. This number tells the
3800 to print the entire spool file at 6, 8, 10, or 12 lines per inch, regardless of
the size of the paper that is currently loaded.
Note: The number lOis only supplied for 3800 model 3 printers.
Specifying an FCB of 6, 8, 10, or 12 are only special cases on 3800 printers. If
an FCB of 6, 8, 10, or 12 is specified for an impact printer, the START
command will try to find an image library member with the corresponding name
(for example, "32036" if "FCB 6" is specified for a 3203 printer).
If no START command with an FCB option has been issued since the last cold
start, the default FCB specified on the RDEVICE macro (at installation time) is
used.
FOLD
NOFOLD
specifies the need to load the universal character set (UCS) buffer with an
operation code that permits printing of uppercase and lowercase bit
configurations. If FOLD is specified, all characters will be printed in uppercase.
This is used when lowercase is specified in a file, but no lowercase exists in the
UCS specified. If NOFOLD is specified, the characters are not translated into
uppercase.
Note: If you specify the FOLD option, the control unit ignores bit positions 0
and 1 of the EBCDIC code when comparing the character codes from the
UCS buffer and the print line buffer. Only uppercase characters will be
printed from either uppercase or lowercase data codes. Warning: Misuse
of the FOLD option can cause multiple characters to be printed for the
same EBCDIC bit configuration.
INDEX nn
specifies the position at which to begin printing. nn is a number from 1 to 31; a
leading zero need not be specified. (This option is valid only for 3211 type
printers.)
Chapter 2. VM/XA SP CP Commands
607
START: Options
FLASH
{name}
OFF
specifies the forms overlay negative loaded into the device. Spool files
designated to be FLASHed with 'name', and spool files with no flash name
associated with them, will be selected for printing. "name" is 1 to 4
alphanumeric characters.
If 'OFF' is specified, it indicates that no flash will be used.
If no START command with the FLASH option has been issued since the last
cold start, the default FLASH name specified on the RDEVICE macro (at
installation time) is used.
HOLD
PURGE
specifies the system action to be taken on files with 3800 load errors. If HOLD
is specified, all files with load errors will be placed in system hold status. If
PURGE is specified, all files with load errors will be purged.
If no START command with the HOLD or PURGE option has been issued
since the last cold start, the default is HOLD.
Usage Notes
1. If a device is busy when you issue the START command, the changes that you
specify will take effect after the current file is complete.
2. If you specify the "NOSEP" operand for a punch, separator cards will not be
punched. Instead, for each file the operator will receive the message:
PUN rdev START FOR OUTPUT
The punch can be started for the next file by pressing the START/STOP key on
the device.
3. If a real spooling printer that is not a 3800 is STARTed with the BEG3800 or
ANY3800 options, all 3800 load CCWs contained in selected spool files will be
removed, and the file will be printed with the available setup.
4. IBM does not recommend that you use spool file class to determine the output
form (paper) for 3800 operation. If you change the paper on the 3800 printer
without specifying a new form name with the FORM operand. of the START
command, 3800 errors win result.
Accordingly, when you change the paper on a 3800 printer, IBM recommends
that you start the printer with the FORM operand and a new form name. But if
you prefer, you may instead drain the printer (with the DRAIN command) and
issue the START command without the FORM operand.
5. If you are working within CMS and you want to issue a CP START command,
use #CP START.
6. The DEFFCB option (which allows a user to specify that the default FCB that
was loaded in the printer should be used) will be accepted as a parameter on the
START command for a 3211 type printer only, for compatibility, but will be
ignored because VM/SP currently uses the default FCBs loaded in by the
LOADBUF command.
608
VM/XA SP2 CP Command Reference
START: Options
Responses
Responses For a Real Reader
RDR rdev STARTED .{SYST~M}
userld
Responses For a Real Printer
PRT rdev STARTED {SYST~M} CLASS abcdefgh
userld
PRT ~dev FORM operform {MANUAL} {SEP
AUTO
NOSEP
SETUP
}fBEG38ee
N03See}
ANY3See
In addition, when a 3800 printer is started, the following response is also generated.
PRT rdev FLASH name IMAGE imagel ib CHARS name FCB inamel {HOLD }
6
PURGE
8
Ie
12
Responses For Impact Printers Only
When an impact printer is started, the following response appears for all impact
printers except the 1403 printers which do not have the universal character set
feature installed.
PRT rdev {NOFOLD} IMAGE imagelib CHARS chars [FCB name] [INDEX nn]
FOLD
appears for all impact printers except for 1403 printers which do not have the
universal character set feature installed.
where:
NOFOLD
FOLD
indicates whether lowercase characters are being translated (folded) into upper
case for printing.
IMAGE imagelib
indicates the image library,being used by the printer.
CHARS chars
indicates the character set being used by the printer.
FCB {name}
indicates the FCB being used by the printer.
Chapter 2. VMjXA SP CP Commands
609
START: Options
INDEX nn
indicates the character position on the page at which to begin printing.
Note: This only appears for 3211 type printers.
Responses For A Real Punch
PUN rdev STARTED {SYST~M} CLASS abcdefgh
userld
PUN rdev FORM operform{MANUAL} {SEP }
AUTO
NOSEP
where:
rdev
is the real device number of the device.
FORM operform
is the current form number processed on the device.
SYSTEM
userid
indicates which virtual machine's files the device may service.
CLASS abcdefgh
indicates which output classes the device can service.
MANUAL
AUTO
SETUP
indicates the mode of forms processing for the printer or the punch.
SEP
NOSEP
indicates whether file separators will be produced between output files.
N03800
BEG3800
ANY3800
specifies the restriction placed on 3800 load CCWs for spool files processed on a
real printer. N03800 - no load CCWs in file. BEG3800 - only spool files
without 3800 load CCWs, or with them at the beginning of the spool file will be
processed. ANY3800 - will process any spool file, regardless of the occurrence
of 3800 load CCWs.
FLASH name
specifies the name of the forms overlay within the 3800 device.
IMAGE imagelib
indicates the image library containing load images (character sets, FCBs, graphic
character modifications, or copy modifications) that will be used for printing
files and separators.
CHARS name
specifies the CHARS which is used to print the file.
610
VM/XA SP2 CP Command Reference
ST ART: Options
FeB
rrel
indicates the FCB which is used to print the file.
HOLD
PURGE
indicates the system action taken towards spool files which cause 3800 load
errors.
Responses For Currently Active Devices
PRT} rdev {PRINTING} userid FILE spoolid RECS {nnnn.:.} COpy [*]nnn SEQ sss
{ PUN
PUNCHING
nnnK
nnnM.
is the message you receive when the system begins processing a spool file that has
the MSG attribute.
where:
PRT
PUN
indicate the type of device on which the file is being processed.
rdev
is the real device number.
userid
is the name of the spool file owner.
FILE spoolid
is the spool file spoolid number.
RECS {nnnn }
nnnK
nnnM
is the number of logical records in the spool file. If the number is greater than
9999, the number is shown as nnnK, where K represents the number of lines
rounded to the nearest 1000 records. If the number is greater than 999499, then
the number is shown as nnnM, where M represents the number of lines rounded
to the nearest million.
COpy [*)nnn
specifies the number of file copies you want printed or punched when the file is
produced.
An asterisk (*) indicates that the 3800 printer will print each page from the
spooled output files nnn times before going on to the next page.
If a file is not spooled to the 3800 printer, the function performed by specifying
the asterisk (*) is ignored and duplication occurs normally.
SEQ sss
is the sequence number for the file on the printer or punch.
Chapter 2. VM/XA SP CP Commands
611
STOP
STOP
Privilege Class: G
Use the STOP command to place all your virtual processors into soft-stop, or to
place selected processors into hard-stop.
STOP
CPU lcpuaddr
[
I
where:
CPU
cpuaddrl cpuaddr •..
.cpuaddrl-cpuaddrn
ALL •••
I
IJ
cpuaddr
cpuaddrl cpuaddr•.•.
cpuaddrl-cpuaddrn
ALL
specifies the processor or processors you want to place in hard-stop. You can
specify a single processor address, a list of processor addresses delimited by
blanks, a nonwrapping pair of addresses separated by a "-" with no blanks, or
ALL. If you omit this operand, all of your virtual processors are placed into
soft-stop.
Usage Notes
1. If you issue the STOP command without operands, all of your virtual processors
are placed into soft-stop.
2. This command is useful with a TRACE command to suspend execution when a
certain condition is reached.
3. Execution of the virtual processor or processors is suspended until a BEGIN,
SYSTEM RESTART, ATTN, IPL, EXTERNAL, or REQUEST command is
entered.
4. The STOP command causes suspension of virtual machine execution regardless
of the setting of SET RUN.
Responses
None.
612
VMjXA SP2 CP Command Reference
STORE
STORE
Use the STORE command described in this section to alter any of the following
locations in your real or virtual machine:
•
•
•
•
•
•
•
•
•
•
•
First-level storage
Second-level storage
Third-level storage
General registers
Floating-point registers
Control registers
Storage keys
The current program status word (CURRENT PSW)
Channel address words (CAWs)
Channel status words (CSWs)
Vector Facility registers.
Complete Format for STORE
The format box shows all of the operands available with the STORE command.
Complete descriptions of the operands appear on the following pages, in the same
sequence as the operands appear here.
STore
[n [D
H
[~~.J
tW}
CAW
CSW
G
hexloc data
C
hexloc data
hexwordl
hexwordl
hexwordl
[hexword2]
G
[hexword2]
... ]
{Gregl} hexwordl
Xregl
[hexword2
{Yregl} hexdwordl
[hexdword2 ..• ]
G
STATUS
G
VR [[~g ]
[,e~t ]
hexwordl [hexword2 •.• J
] ]
G
[ VP [[r~g ] [,e~tJ hexdwordl [hexdword2 .•• J ]
VSR
hexwordl
[hexword2]
G
VMR
hexwordl
[hexword2 ... ]
G
VAC
hexdword
G
Chapter 2. VM/XA SP CP Commands
613
STORE
Migration Notes
VMISP HPO: VM/XA SP does not support storing into odd-numbered floating
point registers.
VMIXA SF: In VM/XA SP, the default option is N.
614
VM/XA SP2 CP Command Reference
STORE GUEST STORAGE
STORE GUEST STORAGE
Privilege Class: G
Use STORE GUEST STORAGE to store data in second-level or third-level storage.
I STore
I
[~U]
hexloc data
Note: Do not put blanks between the operands and the address specified by hexloc.
However, at least one blank must precede the data that you want to insert
into storage.
where:
R
stores your data in second-level storage.
L
stores into second-level storage if the guest virtual machine is in DAT OFF
mode, stores into third-level storage if the guest virtual machine is in DAT ON
mode.
v
stores into third-level storage using the standard STD as indicated by control
register 1.
w
stores into third-level storage using the alternate working segment table
designation (STD) as indicated by control register 7.
N
stores the specified data (hexadecimal) in successive fullword locations starting at
the address specified by hexloc. The smallest group of hexadecimal values that
can be stored is one fullword. This is the default.
If hexloc is not on a fullword boundary, the store operation will begin on the
next lower fullword boundary. If the value being stored is less than one
filllword (eight hexadecimal digits) in length, it is right-adjusted in the word and
is filled in with zeros. If two or more hexadecimal words are specified, they
must be separated with one or more blanks.
s
stores the specified data (hexadecimal) without word alignment starting at the
address specified in hexloc. The shortest string that can be stored is one byte (2
hexadecimal digits).
If the string contains an odd number of characters, the last character is not
stored, an error message is issued, and the function terminates. If you specify
the S operand, the data you enter must be a string of two or more hexadecimal
digits with no embedded blanks.
K
stores the data in the storage key for the 4Kb page in which hexloc is located.
Two hexadecimal digits are used to form the key for the page. If one digit is
provided, it becomes the lower digit and the upper digit is O.
Chapter 2. VM/XA SP CP Commands
615
STORE GUEST STORAGE
u
stores the specified data (EBCDIC characters) starting at the address specified
by hexloc. The data is stored in byte segments with no word alignment.
hexloc
is the starting storage location that is to be altered. The address hexloc may be
one to eight hexadecimal digits; leading zeros are optional. The hexloc
parameter has no defaults; you must always specify the starting address that you
want to alter.
data
is the data you want to insert into storage. data takes on different meanings,
depending on the type of STORE you are performing (N, S, K, or U). See the
descriptions of each of these operands for the meaning of data.
Usage Notes
An attempt to store at an address in a protected page, or to change the key at an
address in a protected page, will result in an error message. A protected page is a
page of read-only storage.
Responses
STORE COMPLETE
indicates that the data has been stored.
616
VMjXA SP2 CP Command Reference
STORE HOST STORAGE
STORE HOST STORAGE
Privilege Class: C
Use STORE HOST STORAGE to store data in first level storage.
I STore
I {!}eX10C data
Note: Do not put blanks between the operands and the address specified by hexloc.
However, at least one blank must precede the data that you want to insert
into storage.
where:
H
indicates that first level storage is to be altered.
N
stores the specified data (hexadecimal) in successive fullword locations starting at
the address specified by hexloc. The smallest group of hexadecimal values that
can be stored is one fullword. This is the default.
If hexloc is not on a fullword boundary, the store operation will begin on the
next lower fullword boundary. If the value being stored is less than one
fullword (four bytes) in length, it is right-adjusted in the word and is filled in
with zeros. If two or more hexadecimal words are specified, they must be
separated with one or more blanks.
s
stores the specified data (hexadecimal) without word alignment starting at the
address specified in hexloc. The shortest string that can be stored is one byte (2
hexadecimal digits). If the string contains an odd number of characters, the last
character is not stored, an error message is issued, and the function terminates.
If you specify the S operand, the data you enter must be a string of two or more
hexadecimal digits with no embedded blanks.
K
stores the data in the storage key for the 4Kb page in which hexloc is located.
Two hexadecimal digits are used to form the key for the page. If one digit is
provided, it becomes the lower digit and the upper digit is O.
u
stores the specified data (EBCDIC characters) starting at the address specified
by hexloc. The data is stored in byte segments with no word alignment.
hexloc
is the starting storage location that is to be altered. The address hexloc may be
one to eight hexadecimal digits with optional leading zeros. The hexloc
parameter has no defaults; you must always specify the starting address that you
want to alter.
data
is the data you want to insert into storage. Data take on different meanings,
depending on the type of STORE you are performing (N, S, K, or U). See the
descriptions of each of these operands for the meaning of data.
Chapter 2. VM/XA SP CP Commands
617
STORE HOST STORAGE
Warning: Exercise extreme caution in issuing the STORE HOST STORAGE
command. Careless storage alterations can cause abnormal terminations of your
system as well as security and integrity problems.
Usage Notes
You can only alter CP owned pages with STORE HOST STORAGE.
Responses
STORE COMPLETE
indicates that the data has been stored.
618
VM/XA SP2 CP Command Reference
STORE PSW/CAW/CSW
STORE PSW/CAW/CSW
Privilege Class: G
Use STORE PSW/CAW/CSW to store data in the current virtual machine program
status word (PSW), channel address word (CAW), or channel status word (CSW).
STore
psw.}. hexwordl [hexword2]
CAW hexwordl
{ CSW hexwordl [hexword2]
where:
PSW
alters all or part of the PSW with the data you specify in hexwordl and
hexword2. If you specify only hexwordl, it is stored into the address portion of
your virtual machine's current PSW. If you specify both hexword 1 and
hexword2, hexwordl is stored into the first word of your virtual machine's
current PSW and hexword2 is stored into the address portion of the PSW.
CAW
alters the channel address word (CAW). This operand is valid for System/370
mode virtual machines only; the 370-XA architecture equivalent, the operation
request block (ORB), has no fixed location and cannot be located.
CSW
alters the channel status word (CSW). The value you specify in hexwordl is
stored into the address portion of your virtual machine's channel status word,
and the value you specify in hexword2 (if given) will be stored into the status
word portion of your virtual machine's channel status word. This operand is
valid for System/370 mode virtual machines only; the 370-XA architecture
equivalent, the interruption response block (lRB), has no fixed location and
cannot be located.
hexwordl [hexword2)
is the data you want to store in the PSW, CAW, or CSW. If the data is less
than 8 digits (4 bytes), it will be right adjusted and padded with leading zeros.
Usage Notes
None.
Responses
STORE COMPLETE
is the response at the successful completion of the command.
Chapter 2. VM/XA SP CP Commands
619
STORE REGISTERS
STORE REGISTERS
Privilege Class: G
Use STORE REGISTERS to store data into general purpose registers, floating-point
registers, or control registers.
STore
Gregl} hexwordl
{ Xregl
[hexword2
..• J
{Yregl} hexdwordl [hexdword2 ... J
where:
Gregl
is a decimal number from 0 to 15 or a hexadecimal number from 0 to F
representing the first, or only, general register whose contents are to be assigned
a value. You must prefix the value with the letter G.
Xregl
is a decimal number from 0 to 15 or a hexadecimal number from 0 to F
representing the first, or only, control register that is to be assigned a value.
You must prefix the value with the letter X.
Yregl
is an integer (0, 2, 4, or 6) representing the first, or only, floating-point register
whose contents are to be assigned a value. You must prefix the value with the
letter Y.
hexwordl
hexword2...
each represents up to eight hexadecimal digits for G and X register stores. If the
value being stored is less than the eight digits, it is right-adjusted in the register
and the high-order bytes of the register are filled with zeros. If two or more
values are specified, they must be separated by one or more blanks. The data is
stored in successive registers.
hexdwordl
hexdword2
each represents up to 16 hexadecimal digits for Y register stores. If the value
being stored is less than 16 digits, it is left-adjusted in the register and the
low-order bytes of the register are filled with zeros. If two or more values are
specified, they must be separated by one or more blanks. The data is stored in
successive registers.
Responses
STORE COMPLETE
indicates that the data has been stored.
620
VMjXA SP2 CP Command Reference
STORE STATUS
STORE STATUS
Privilege Class: G
Use STORE STATUS to store selected virtual machine data in certain low storage
locations.
I
STATUS
STore
where:
STATUS
stores selected virtual machine data in certain low storage locations of the virtual
machine, simulating the hardware store status facility. These locations are
permanently assigned locations in guest absolute storage.
The STORE STATUS operand causes the following data to be stored in low
storage:
Decimal
Address
Hexadecimal
Address
Length
in Bytes
216
224
256
264
352
384
448
D8
E0
100
108
160
180
1C0
8
8
8
4
32
64
64
Data
CPU Timer
Clock Comparator
Current PSW
Prefix register
Floating-point registers 0-6
General registers 0-15
Control registers 0-15
Usage Notes
1. The STORE STATUS command stores data in the logout area.
2. The STORE STATUS command stores CPU timer and clock comparator values
that may then be displayed on your console via the DISPLAY command. This
procedure is one way to get timer information on your display.
Responses
STORE COMPLETE
is the response at the successful completion of the command.
Chapter 2. VM/XA SP CP Commands
621
STORE VECTOR
STORE VECTOR
Privilege Class: G
Use STORE VECTOR to alter the contents of one or more vector register elements
or vector register pair elements, vector activity count, vector status register, or vector
mask register.
STore
VSR
hexwordl
[hexword2]
VMR
hexwordl
[hexword2 ... ]
VAC
hexdword
where:
VR
allows you to store into one or more elements of one vector register.
VP
allows you to store into one or more elements of one vector register pair.
reg
If you use VR, reg is a decimal number from 0 to 15 or a hexadecimal number
from 0 to F indicating the vector register whose elements you want to store a
new value.
If you use VP, reg is a decimal number from 0 to 14 or a hexadecimal number
from 0 to E indicating the even number of the vector register pair into whose
elements you want to store a new value.
If you specify VR or VP without a register number, the system will store in
vector register 0 or vector register pair 0-1.
elt
elt is a hexadecimal number from 0 to one less than the section size representing
the first, or only, element whose content is to be altered.
hexword 1 (hexword2 .••)
is the data you wish to store in consecutive elements of the vector register you
specified. The hexword operands may each be up to eight hexadecimal digits. If
the value is less than a fullword, it is right-adjusted in the register element and
its high-order bytes are filled with zeros. If you specify two or more hexwords,
they must be separated by one or more blanks. If the number of hexwords listed
plus the starting element number exceeds the section size, then the valid hexword
is stored and an error message is issued.
hexdwordl (hexdword 2.•.)
is the data you wish to store in consecutive elements of the vector register pair
you specified. The hexdword operands may each be up to 16 hexadecimal digits.
If the value is less than a doubleword, it is left-adjusted in the register element
and its low-order bytes are filled with zeros. If you specify two or more
hexdwords, they must be separated by one or more blanks. If the number of
622
VMjXA SP2 CP Command Reference
STORE VECTOR
hexdwords listed plus the starting element number is larger than the section size,
then the system stores the valid hexdwords and ignores the excess hexdwords.
VSR hexwordl (hexword2)
stores the data in hexwordl (and hexword2 if you specify hexword2) in the
virtual machine's vector status register. The hexword may each be up to eight
hexadecimal digits. If the value is less than a fullword, it is right-adjusted in the
register word being altered and its high-order bytes are filled with zeros. If you
specify two or more hexwords, they must be separated by one or more blanks.
This fullword value is then checked to conform to the architecture of the vector
status register. The system corrects any inconsistencies.
VMR hexwordl [hexword2 ••• J
stores the data in hexwordl and the other specified hexwords in the virtual
machine's vector mask register. The hexword operands may each have up to
eight hexadecimal digits. If the value is less than a fullword, it is left-adjusted in
the word and its low-order bytes are filled with zeros. If you specify two or
more hexwords, they must be separated by one or more blanks. The number of
bytes which can be stored in the VMR is limited to the section size. If the
combined operand is longer than the length of the vector mask register, the
system ignores the excess digits.
VAC hexdword
stores the data in hexdword in the virtual machine's vector activity count. The
operand may represent up to 16 hexadecimal digits. If the value stored is less
than a doubleword, it is right-adjusted in the word and the leftmost bits are
filled with zeros. This hexdword value is then checked to conform to the
architecture of the vector activity count. The system corrects any
inconsistencies.
Usage Notes
STORE VR and STORE VP will turn on the vector in-use and change bits
corresponding to the register or pair being changed. If the in-use bit were off
previously, then the elements of that register pair will be zero as nothing will be
stored into them.
Examples
To store hexadecimal values 4E5400005E450000 and 4E5500005E550000 into the
vector register pair 6 and 7, enter:
ST VP6 4E5400005E450000 4E5500005E550000
To store hexadecimal value 0000000200000000 into the virtual machine's vector
activity count, enter:
ST VAC 0000000200000000
To store hexadecimal value 00000001 OOOOOOFF into the virtual machine's vector
status register, enter:
STORE VSR 00000001 000000FF
To store hexadecimal value FFFFFFFF FFFFOOOO 00000000 00000000 into the
virtual machine's vector mask register, enter:
ST VMR FFFFFFFF FFFF0000 00000000 00000000
Chapter 2. VM/XA SP CP Commands
623
STORE VECTOR
Responses
STORE COMPLETE
indicates that the data has been stored.
Migration Notes
VMISP HPO: VM/XA SP evaluates the command for proper syntax prior to
checking whether the Vector Facility is available.
624
VMjXA SP2 CP Command Reference
SYSTEM
SYSTEM
Privilege Class: G
Use the SYSTEM command to clear storage and simulate the action of RESET and
RESTART on a real computer console.
I
I
SYStem
CLEAR
RESET
RESTART
STORE STATUS
where:
CLEAR
clears virtual storage, virtual storage keys, floating and general purpose registers
in all processors, and resets the I/O configuration. All processors are reset and
placed in hard-stop.
RESET
resets the processors and the I/O configuration. All processors in the user's
configuration are placed in hard-stop.
RESTART
simulates the hardware system RESTART function by storing the current PSW
at second level location eight and loading, as the new PSW, the doubleword
from virtual location zero. Interrupt conditions and storage remain unaffected.
STORE STATUS
stores selected virtual machine data in certain low storage locations of the virtual
machine, simulating the hardware store status facility. These locations are
permanently assigned locations in guest absolute storage.
The STORE STATUS operand causes the following data to be stored in low
storage:
Decimal
Address
Hexadecimal Length in
Address
Bytes
Data
216
224
256
264
352
384
448
D8
EO
100
108
160
180
1CO
CPU Timer
Clock Comparator
Current PSW
Prefix register
Floating-point registers 0-6
General registers 0-15
Control registers 0-15
8
8
8
4
32
64
64
Usage Notes
1. The RESET function and the CLEAR function leave the virtual machine in a
stopped state.
2. To resume operation after issuing the SYSTEM command with RESET
specified, either STORE a PSW and issue BEGIN or issue BEGIN with a
hexadecimal storage location specified. When doing either of these, be sure the
wait state bit in the PSW is turned off before issuing BEGIN. The virtual
machine automatically restarts at the location specified in the new PSW (which
Chapter 2. VMjXA SP CP Commands
625
SYSTEM
is loaded from the doubleword at location zero) after the SYSTEM RESTART
command is processed.
3. The SYSTEM CLEAR or SYSTEM RESET commands will clear a virtual
check-stop condition on the virtual processors.
4. The SYSTEM CLEAR and SYSTEM RESET commands terminate all IUCV
connections and release the IUCV buffer.
5. The SYSTEM STORE STATUS command stores data in the logout area. The
SYSTEM STORE STATUS command stores CPU Timer and Clock
Comparator values that may then be displayed on your display via the
DISPLAY command. This procedure is one way to get timer information on
your display.
6. The SYSTEM CLEAR and the SYSTEM RESET commands cause the virtual
machine to be reset. If the virtual machine was a member of a virtual machine
group (from a prior IPL of a VMGROUP NSS), that group membership is
canceled. The virtual machine's IUCV connection to the signal system service is
severed and a signal-out message is broadcast by the signal system service to all
other members of the group enabled for signal-out notification.
7. If your virtual machin~ uses the DIAGNOSE X 198 1 facilities for locking virtual
machine pages in real storage, issuing SYSTEM CLEAR unlocks those pages in
certain cases. If you have locked pages in private virtual machine storage,
SYSTEM CLEAR unlocks those pages. SYSTEM CLEAR also releases all
NSSs and saved segments from your virtual machine. Locked shared pages are
unlocked only by DIAGNOSE XI 98 1 or by the release of the shared segment by
the last user.
Responses
STORAGE CLEARED - SYSTEM RESET
is the response given if you enter the SYSTEM CLEAR command.
SYSTEM RESET
is the response given if you enter the SYSTEM RESET command.
STORE COMPLETE
is the response given if you enter the SYSTEM STORE STATUS command.
If you enter the command SYSTEM RESTART, no response is given; the virtual
machine resumes execution at the address in the virtual PSW loaded from virtual
storage location zero.
Migration Notes
VMISP HPO
1. In VM/XA SP if you specify SYSTEM CLEAR, the system clears the registers
and resets the I/O configuration;
2. VM/XA SP supports an additional operand: STORE STATUS.
3. In VM/XA SP, SYSTEM STORE STATUS is the same as the VM/SP HPO
STORE STATUS.
VMIXA SF: During a system reset, VM/XA SP does not reset the CONMODE
setting of a virtual console.
626
VM/XA SP2 CP Command Reference
TAG
TAG
Privilege Class: G
Use the TAG command to associate descriptive information with VMjXA SP spool
files or spooled devices.
I
TAg
[QUery]
.
[DEV]
rinter
PUnch
CONsole
vdev
, FIle spoolid
I
,
[tagtext]
J
where:
QUERY
requests the display of the tag information that is associated with a particular
virtual spooled device or spool file.
DEV
specifies a device is to be tagged or the tag information for a device will be
displayed.
PRINTER
PRT
PUNCH
PCH
CONSOLE
vdev
specifies a spooling device whose output is to be assigned the tag information. If
you enter a generic device name, such as PRINTER or CONSOLE, all current
virtual devices of that type are affected.
FILE spoolid
indicates a closed spool file that you want to assign tag information. You can
use this form of the TAG command only for spool files that are queued on your
reader, printer, or punch queues.
spoolid is the spool file identification that CP assigned when the spool file was
closed.
tagtext
is the information that you want to associate with the specified spool device or
spool file. The contents and format of this data are flexible; they are the
responsibility of the file originator and the end user.
Usage Notes
1. If you enter the TAG command without tagtext information and without the
QUERY option, the tag area associated with the device or file is set to all
blanks.
2. Even though you have created a spool file, once you spool it to another virtual
machine, the other user owns it as soon as the file is closed. If you want to
query or change the tag data, you must first reclaim the file by issuing the CP
CHANGE or CP TRANSFER command.
Chapter 2. VM/XA SP CP Commands
627
TAG
3. The buffer that contains TAG information is 136 characters long, including
blanks. However, because specific terminals may allow fewer than 136
characters, a user may not be able to type in that many characters on the
command line.
Response 1
type vdev TAG:
tag text
displays the tag information associated with a virtual spooling device.
where:
type
is PRT, PUN, or CON
vdev
is the virtual device number,
tagtext
is the tag information 3.ssociated with the device. This tag information may be
up to 136 characters long.
Response 2
tagtext
- or (TAG BLANK)
displays the tag information associated with a specified spool file.
where:
tagtext
is the tag information associated with the file. This tag information may be up
to 136 characters long.
(TAG BLANK)
is displayed when the tag is all blanks.
Response 3
type {vdev
} TAG NOT SET
displays the tag information associated with a device if:
• You have not specified tag information
• You have explicitly set the tag fields to blanks
where:
type
is PRT, PUN, or CONS.
vdev
is the virtual device number.
628
VMjXA SP2 CP Command Reference
TAG
Migration Notes
VMISP HPO: The situation that produced the response TAG MISSING in VMjSP
HPO now produces the response TAG BLANK in VMjXA SP.
Chapter 2. VM/XA SP CP Commands
629
TERMINAL
TERMINAL
Use the TERMINAL command described in this section to control various
characteristics of your virtual console.
The format box below shows all of the operands available with the TERMINAL
command. Complete descriptions of the operands appear on the following pages, in
the same sequence as the operands appear in the format box.
TERMinal
APL
JON}
lOFf
ASCiitbl
ATtn
BREakin
IMmed }
{ GUESTctl
BRKkey
'key}
{ NONE
CHardel
ON }
{ OFf
. ~har:
t
CONmode
3215
{ 3270)
CNTL
SYS}
{ USR
EScape
HIlight
ON }
OFf
{ char
{~~f }
LINEDEL
{
LINENd
char,
ON
{
630
iON
'OFf "}
OFf
char
}
VM/XA SP2 CP Command Reference
TERMINAL
TERMinal
LINESi ze
{nnn}
OFF
MODE
{~:}
PROMpt
{~~Y}
SCROll
{nnn }
CONT
SCRNsave
OFF
TABchar
t}
OFf
char
TEXT
TYpe
{~~f}
{3101}
TTY,
General Usage Notes for The TERMINAL Command
1. You can specify more than one function in a single entry of the TERMINAL
command. For example:
TERMINAL CHARDEL OFF LINESIZE 80
specifies two terminal characteristics:
• the character delete function CHARDEL is set OFF
• the maximum line length for terminal output LINESIZE is set to 80
characters.
2. The settings you specify with the TERMINAL command are in effect only for
the duration of that session. When you initially log on, the system defaults are
in effect. However, the settings you specify for line-editing (except LINEDEL)
and MODE are still in effect when you log on after disconnecting. All other
operands (TEXT, APL and LINE SIZE) are reset if you log on after
disconnecting.
3. If an error occurs during processing of the command, all functions preceding the
one with the error are in effect.
4. You cannot use any of the letters A through Z, or the numbers 0 through 9, as a
symbol (char) in association with any 'of the CHARDEL, LINEDEL, LINEND,
T ABCHAR, and ESCAPE operands.
5. You can use the CP QUERY TERMINAL command to determine the values
for the TERMINAL command functions.
6. CP automatically masks your password on typewriter terminals; however, to
maintain compatibility with previous releases, CP accepts the MASK operand of
the TERMINAL command as valid.
Chapter 2. VM/XA SP OP Commands
631
TERMINAL
Migration Notes
VMISPHPO
1. VMjXA SP allows the user to set OFF the SCRNSAVE option; however, an
error message results whenever it is set ON.
2. In VMjXA SP the system ignores the TERMINAL BRKKEY function in line
mode.
3. VMjXA SP does not allow BREAKIN GUESTCTL for SNAjCCS termir.als.
VMIXA SF: VMjXA SP does not support the operands MSG, WNG, EMSG,
IMSG, and LINEDIT, which are supported in VMjXA SF Release 1.
632
VM/XA SP2 CP Command Reference
TERMINAL APL
TERMINAL APL
Privilege Class:
G
Use TERMINAL APL to control the use of the APL character translation tables.
I TERMi nal
APL {ON }
OFf
where:
APL {ON}
{OFF}
controls the use of the APL character translation tables. If you specify ON, CP
will use the translation tables applicable to display stations equipped with the
APL hardware feature. If you specify OFF, CP will use the normal terminal
translation tables. Unless otherwise specified, APL OFF is in effect.
Usage Notes
1. If you set APL ON, TERMINAL TEXT is forced OFF.
2. For more information, refer to the "General Usage Notes for TERMINAL."
Responses
None.
Chapter 2. VMjXA SP CP Commands
633
TERMINAL ASCIITBL
TERMINAL ASCIITBL
Privilege Class: G
Use the TERMINAL ASCIITBL command to select the translation table used by
your TTY terminal.
I
ASCiitbl
TERMinal
{VMl}
VM2
where:
ASCllTBL
{~: }
specifies the translation table to be used. VMl specifies the use of the
translation table based on the TTY ANSI X3.4 1977 Standard. VM2 specifies
the use of the translation table based on the TTY A.NSI X3.26 1980 Standard.
Usage Notes
TERMINAL ASCIITBL may be issued only from a TTY device; otherwise an error
message is issued.
Responses
None.
634
VMjXA SP2 CP Command Reference
TERMINAL ATTN
TERMINAL ATTN
Privilege Class: G
Use TERMINAL ATTN to control the signaling of an attention interruption on
keyboards and printers of ASCII terminals. This command is not valid for display
type terminals.
I TERMinal
ATtn
where:
ATTN{
g~F}
controls the signaling of an attention interruption. ON specifies that an
exclamation point (!) is displayed when an attention interruption occurs. The
OFF option suppresses the displaying of the exclamation point and carriage
return.
OFF is the default for display terminals. ON is the default for ASCII devices.
Usage Notes
TERMINAL ATTN ON controls the signaling of an attention interruption only on
the keyboards and printers or ASCII terminals. It is not valid for display type
terminals.
Responses
None.
Chapter 2. VM/XA SP CP Commands
635
TERMINAL BREAKIN
TERMINAL BREAKIN
Privilege Class: G
Use TERMINAL BREAKIN to allow the user to control break-in by CP while in
full-screen mode.
I TERMinal
BREakin
{
IMmed
}
GUESTctl
where:
IMmed
specifies that break-in by CP can take place on any full screen reads and full
screen writes that have an inactive keyboard, as well as when the user hits the
BRKKEY.
specifies that high-priority warnings from CP and user-requested CP functions
still break in, but messages only break in when the user hits the BRKKEY, or
one of the previously mentioned tasks break in.
Usage Notes
1. For the BREAKIN option, only IMMED is supported for SNAjCCS terminals.
If you issue TERMINAL BREAKIN with the GUESTCTL option from an
SNAjCCS terminal, the command is not executed and you receive a message
indicating an invalid device type error.
2. If you change the TERMINAL BREAKIN setting while logged on to a local
display and then disconnect and reconnect to an SNAjCCS terminal, your
TERMINAL BREAKIN setting is affected in the following way during the
reconnection processing:
• BREAKIN, if previously set to IMMED, is not changed.
• BREAKIN, if not previously set to IMMED, is set to IMMED and a
message is issued to inform you of the change.
Responses
None.
636
VM/XA SP2 CP Command Reference
TERMINAL BRKKEY
TERMINAL BRKKEY
Privilege Class:
G
Use TERMINAL BRKKEY to define the key to control break-in by CP for
full-screen guests.
I
TERMinal
BRKkey {key
}
NONE
where:
key
must be one of the following: PAl, PA2, PFnn, or CLEAR. PFnn can be any
PF key on your display station, from PFI to PF24.
NONE
specifies that no BRKKEY should be defined.
Usage Notes
[ The break key is in effect only in a full-screen environment.
2. When you first log on to a virtual machine, the default key to control break-in
by CP for full-screen guests is PAL However, if you intend to run an operating
system in your virtual machine that requires the PAl key for some other
function, you can use this command to define an alternate break key.
3. Once you've issued this command, the new break key remains in effect for the
duration of the session or until you reissue this command during the current
session. If you've used this command to define a new break key and then, at
some point in the session, would prefer to use the default break key again, the
PAl option allows you to do so.
4. If you use this command to define a key other than PAl as the break key,
VMjSP passes control of the PAl key to your virtual machine.
5. When NONE is specified, the full-screen guest has complete control of the
keyboard. You can to return to CP mode only if the full-screen program
provides a way for you.
6. Entry to the protected application environment disables the BRKKEY. To
reenable it within the protected application, issue the TERMINAL BRKKEY
command. Upon exit from the protected application, CP restores the break key
setting to what it was before entry into the same protected application. If the
break key was changed while in the protected application, it remains unchanged
when you exit the application.
7. For the BRKKEY option, only PAl and NONE are supported for SNAjCCS
terminals. If you issue TERMINAL BRKKEY with any other options from an
SNAjCCS terminal, the command is not executed and you receive a message
that indicates an invalid device type error.
Chapter 2. VM/XA SP CP Commands
637
TERMINAL BRKKEY
8. If you change the TERMINAL BRKKEY setting while logged on to a local
display, then disconnect and reconnect to an SNA/CCS terminal, your
TERMINAL BRKKEY setting is affected in the following way during the
reconnection processing:
• If BRKKEY was previously set to NONE or PAl, it is not changed.
• Otherwise, BRKKEY is set to PAl and an informational message is issued
to inform you of the change.
Responses
None.
638
VM/XA SP2 CP Command Reference
TERMINAL CHARDEL
TERMINAL CHARDEL
Privilege Class: G
Use TERMINAL CHARDEL to define the logical character delete symbol.
I TERMinal
CHa rde 1 {ON
}
OFf
char
where:
CHARDEL { ON }
OFF
char
defines the logical character delete function for your virtual machine. If you
specify ON, the system default symbol becomes your logical character delete
symbol. The default symbol is @, but may be changed by what is specified in
your entry in the system directory. If you specify char, that character becomes
your logical character delete symbol. The character you select should be unique
and not common to the data stream being entered. If you specify OFF, no
logical character delete symbol is used for your virtual machine.
Usage Notes
1. When you log on, CHARDEL ON is in effect. If your virtual machine is logged
on by someone else using the CP AUTOLOG or XAUTOLOG command,
CHARDEL OFF is the default.
2. For more information, see the "General Usage Notes for TERMINAL."
Responses
None.
Chapter 2. VMjXA SP CP Commands
639
TERMINAL CONMODE
TERMINAL CONMODE
Privilege Class: G
Use TERMINAL CONMODE to alter the console mode of your display. The
console mode (3215 or 3270) determines the type of virtual I/O support that VM/SP
provides.
I TERMinal
CONmode {3215}
3270
where:
CONMODE {3215.}
3270
defines the type of virtual I/O support that VM/SP provides for your display. If
you specify 3215, then 3215 CCW processing occurs. If you specify 3270, then
3270 CCW processing occurs.
Usage Notes
1. In order to use this command correctly, you need to be aware of the three
factors that affect your console mode:
a. The CONSOLE statement: The CONSOLE statement in your system
directory determines the initial console mode of your display.
h. The TERMINAL CONMODE command: You can issue the TERMINAL
CONMODE command to change your console mode.
c. The DEFINE CONSOLE command: You can also issue the DEFINE
CONSOLE command to change your console mode.
In brief, you have two commands that you can use to actively change your
console mode: TERMINAL CONMODE and DEFINE CONSOLE.
2. In order to change your console mode setting with DEFINE CONSOLE, you
first have to detach your console with the DETACH command. For various
reasons, you may not always want to detach your virtual console. TERMINAL
CONMODE provides you with a way of changing your console mode setting
without detaching your console.
3. Certain programs require a console mode that may differ from your usual or
default console mode. If you attempt to run such a program with the incorrect
console mode, results are unpredictable. In most instances, the program
terminates abnormally.
Some programs reset the console mode internally. You may not be aware that
the console mode has been changed for you automatically. Problems result if
you then invoke a program that requires the alternate console mode setting.
Therefore, you should remain aware of the significance of the console mode any
time that you invoke a program in your virtual machine.
4. If you issue TERMINAL CONMODE 3270 from an SNA/CCS terminal
controlled by a VTAM service machine that does not support CONMODE
3270, the command is not executed and you receive a message indicating an
invalid device type error. CONMODE 3270 is supported by ACF/VTAM
Version 3, Release 1.1 for VM/SP (VM/VTAM) and later releases.
640
VM/XA SP2 CP Command Reference
TERMINAL l,;UNMUlJE
5. Use the QUERY VIRTUAL CONSOLE command to determine the console
mode.
Responses
None.
Chapter 2. VM/XA SP CP Commands
641
TERMINAL CNTL
TERMINAL CNTL
Privilege Class: G
Use the TERMINAL CNTL command to allow either CP or an application
program to insert TTY line control characters into output directed to your TTY
terminal.
I TERMinal
CNTL {SYS}
USR
where:
CNTLjSYS}
t USR
determines whether CP or the application is to insert the TTY line control
characters. SYS specifies that CP is to insert TTY line control characters into
output directed to a TTY terminal. USR specifies that the application program
is to insert TTY line control characters into output directed to a TTY terminal.
Usage Notes
I. TERMINAL CNTL may be issued from a TTY device only; otherwise an error
message is issued.
2. If you specify USR, both TERMINAL TYPE and TERMINAL PROMPT must
be set to TTY. If TYPE and PROMPT are not TTY and you select USR,
TYPE and PROMPT are forced to TTY. These options may not be changed
while CNTL is set to USR or an error message is issued and the setting remains
as TTY.
3. Application programs that use the CMS WRTERM macro to write data to a
terminal must specify either the WRTERM EDIT=NO or EDIT = LONG
parameters. Otherwise, TERMINAL CNTL has no effect.
4. If you disconnect your virtual machine, TERMINAL CNTL is reset to SYS.
Responses
None.
642
VM/XA SP2 CP Command Reference
TERMINAL ESCAPE
TERMINAL ESCAPE
Privilege Class: G
Use TERMINAL ESCAPE to define the logical escape character.
I TERMinal
EScape {. ON
.}
OFf
char
where:
ESCAPE {ON .}
OFF
char .
defines the logical escape character function. If you specify ON, the default
symbol becomes the logical escape character for your virtual machine. The
default symbol is ", but may be changed by what is specified in your entry in the
system directory. If you specify char, then that character will become the logical
escape character. The character you select should be unique and not common to
the data stream being entered. If you specify OFF, no logical escape character
is allowed for your virtual machine.
Usage Notes
1. When you log on, ESCAPE ON is in effect. If your virtual machine is logged
on by someone else using the CP AUTOLOG or XAUTOLOG command,
ESCAPE OFF is the default.
2. For more information, refer to "General Usage Notes for The TERMINAL
Command" on page 631.
Responses
None.
Chapter 2. VMjXA SP CP Commands
643
TERMINAL HILIGHT
TERMINAL HILIGHT
Privilege Class: G
Use TERMINAL HILIGHT to highlight the command redisplay line on the virtual
machine console.
I TERMinal
HIl ight {ON }
OFf
where:
HILIGHT {ON }
OFF
defines whether or not the command redisplay line on a display is highlighted.
When the option is OFF, user input is displayed at normal intensity. The
HILIGHT option is set to OFF when you logon. The TERMINAL HILIGHT
command has no effect on the highlighting options specified on the CP
SCREEN command.
Usage Notes
None.
Responses
None.
644
VM/XA SP2 CP Command Reference
TERMINAL LINEDEL
TERMINAL LINEDEL
Privilege Class: G
Use TERMINAL LINEDEL to define the logical line delete symbol.
I TERMinal
LINEDEL {ON ,}
OFf '
char
where:
LINEDEL {' ON }'
OFF
char '
defines the logical line delete function for your virtual machine. If you specify
ON, the system default symbol becomes the logical line delete symbol for your
virtual machine. The default symbol is ¢, but may be changed by what is
specified in your entry in the system directory. If you specify char, then that
character will become the logical line delete symbol. The character you select
should be unique and not common to the data stream being entered. If you
specify OFF, no logical line delete symbol is allowed for your virtual machine.
Note: For ASCII devices the default character is a left bracket (D.
Usage Notes
1. If you disconnect your virtual machine after you change the LINEDEL
character, the new LINEDEL character remains in effect while you are
disconnected and after you reconnect.
2. When you log on, LINEDEL ON is in effect. If your virtual machine is logged
on by the someone else using the CP A UTOLOG or XAUTOLOG command,
LINEDEL OFF is the default.
3. For more information, refer to "General Usage Notes for The TERMINAL
Command" on page 631.
Responses
None.
Chapter 2. VMjXA SP CP Commands
645
TERMINAL LINEND
TERMINAL LINEND
Privilege Class: G
Use TERMINAL LINEND to define the logical line end symbol for your virtual
machine.
I TERMinal
LINENd {ON
OFf }.
char
where:
LINEND {ON}
OFF
. char
defines the logical line end symbol for your virtual machine. If you specify ON,
the system default symbol becomes the logical line end symbol for your virtual
machine. The default symbol is #, but may be changed by what is specified in
your entry in the system directory. If you specify char, then that character
becomes the logical line end character. The character you select should be
unique and not common to the data stream being entered. If you specify OFF,
no logical line end symbol is allowed for your virtual machine.
Usage Notes
1. When you log on, LINEND ON is in effect. If your virtual machine is logged
on by someone else using the CP AUTO LOG or XAUTOLOG command,
LINEND OFF is the default.
2. For more information, refer to "General Usage Notes for The TERMINAL
Command" on page 631.
Responses
None.
646
VM/XA SP2 CP Command Reference
TERMINAL LINESIZE
TERMINAL LINESIZE
Privilege Class: G
Use TERMINAL LINE SIZE to specify the maximum allowable line length for
display screen output.
I TERMinal
LINESi ze
nnn'}
{OFf
where:
LINESIZE
{nnn }
, OFF
specifies the maximum allowable line length. The value you specify for nnn can
be any number from 1 through 255. OFF specifies that the output line length is
not to be adjusted by CPo In other words, CP does not split a long output line
into two or more shorter ones.
If neither nnn nor OFF is specified, the default value is device dependent.
Usage Notes
1. If TERMINAL APL ON is specified, CP defines an output length of 1760 and
assumes that the APL system has inserted the appropriate carriage control
characters into the output data.
2. If a user disconnects from the system and then logs on again, the LINESIZE
specified is reset to the system defaults.
Responses
None.
Ghapter 2. VM/XA SP CP Commands
647
TERMINAL MODE
TERMINAL MODE
Privilege Class: G
Use TERMINAL MODE to control the display station attention environment.
I TERMinal
MODE {;:}
where:
MODE
{~~}
controls the display station attention environment. If you specify CP, one or
more attentions will force your virtual machine into the CP environment. If you
specify VM, one or more attentions will be reflected to your virtual machine.
VM is the default for all users except the primary system operator when the user
logs on.
Usage Notes
1. This command only has meaning in line mode.
2. For more information, refer to "General Usage Notes for The TERMINAL
Command" on page 631.
Responses
None.
648
VMjXA SP2 CP Command Reference
TERMINAL PROMPT
TERMINAL PROMPT
Privilege Class: G
Use TERMINAL PROMPT to set the prompting sequence to be used on a TTY
device.
I TERMinal
PROMpt {VM '}
TTY
where:
PROMPT{ VM }
TTY
sets the prompting sequence. The VM option causes the cursor to be positioned
in column I of the input line for a read operation. The TTY option enables the
normal TTY prompt sequence of a period in column 1 and the cursor in column
2.
Usage Notes
1. TERMINAL PROMPT can be issued from a TTY device only; otherwise, an
error message is issued.
2. If a user disconnects from the system and then logs on again, the PROMPT
options are reset to the system defaults.
Responses
None.
Chapter 2. VM/XA SP CP Commands
649
TERMINAL SCROLL
TERMINAL SCROLL
Privilege Class: G
Use TERMINAL SCROLL to specify the number of scrolled lines on a 3101 display
screen.
I TERMinal
SCROll
{nnn}
CONT
where:
SCROLL { nnn
}
CONT
controls scrolling. nnn specifies the number of lines that are scrolled up before
scrolling stops with on the bottom line of the screen. Pressing the NEW LINE
key (character mode) or the SEND key (block mode) causes another cycle of
nnn lines to be scrolled. For normal frame by frame scrolling, make nnn equal
to the number of data lines on the screen. CONT specifies continuous scrolling
to the end of the output.
Usage Notes
1. TERMINAL SCROLL may be issued from a TTY device only; otherwise, an
error message is issued.
2. If a user disconnects from the system and then logs on again, the SCROLL
options are reset to the system default.
Responses
None.
650
VM/XA SP2 CP Command Reference
TERMINAL TAB CHAR
TERMINAL TABCHAR
Privilege Class: G
Use TERMINAL TABCHAR to define logical tab characters on display devices.
The QUERY TERMINAL command displays the current logical tab character.
I TERMinal
TABchar '{.ON
OFf
}
char
where:
TAB CHAR {ON }
OFF
char
defines logical tab characters. ON sets the logical tab character to the one used
by the system, which is a broken vertical bar. OFF resets the logical tab
character to undefined. char defines the logical tab character to be used by the
system internally. It may be any valid specific graphic character (that is, a
character other than A-Z or 0-9).
Usage Notes
1. When an invalid character is specified, an error message is issued to the display
and the logical tab character remains unchanged.
2. If a user disconnects from the system and then logs on again, the T ABCHAR
specified from the previous session will be in effect.
3. For more information, refer to the "General Usage Notes for TERMINAL."
Responses
None.
Chapter 2~ VMjXA SP CP Commands
651
TERMINAL TEXT
TERM'INAL TEXT
Privilege Class: G
Use TERMINAL TEXT to control the use of text translation tables.
I TERMinal
TEXT {ON}
OFf
where:
TEXT
{~~}
controls the use of the text translation tables. If you specify ON, CP will use the
translation tables applicable to display terminals equipped with the text
hardware features. If you specify OFF, CP will use the normal translation
tables. Unless otherwise specified, TEXT OFF is in effect.
Usage Notes
1. If TEXT is set ON, TERMINAL APL is forced OFF.
2. For more information, refer to the "General Usage Notes for TERMINAL."
Responses
None.
652
VM/XA SP2 CP Command Reference
TERMINAL TYPE
TERMINAL TYPE
Privilege Class: G
Use TERMINAL TYPE to define a device as a 3101 or as a TTY.
I TERM; nal
TYpe {3101}
TTY
where:
TYPE {3101}
TTY
defines the device. When 3101 is in effect, the terminal is regarded as a display
screen and keyboard ASCII device. The 3101 operand (a) allows the use of
program function keys 1 through 24, (b) causes output to begin at column 1 of
line 24 on the display, and (c) allows editing of previously entered information
without the necessity of rekeying the entire text. When TTY is in effect, the
terminal is regarded as a typewriter terminal.
Usage Notes
1. TERMINAL TYPE may be issued from a TTY device only; otherwise, an error
message is issued.
2. If a user disconnects from the system and then logs on again, the TYPE options
are reset to the system defaults.
Responses
None.
Chapter 2. VM/XA SP CP Commands
653
TRACE
TRACE
Privilege Class: G
Use the TRACE command described in this section to monitor events that occur in
your virtual machine. VM/XA SP allows you to trace a number of events,
including:
• Instruction execution
• Storage alteration
• Register alteration
• I/O activity.
Each traced event results in a trace entry, a command response that you can have
sent to your virtual console, to a virtual printer, or to both. The trace entry is made
up of significant information about the event. You can use trace entries to analyze
the operation of your virtual machine and to debug problems.
Note that in this manual the TRACE documentation is primarily for reference. For
a full explanation of how to use the trace facility, along with examples, see VM/XA
SP Virtual Machine Operation.
How the TRACE Documentation Is Organized
Although it has a large number of operands and options, the TRACE command is
relatively easy to use. This section is organized to make using TRACE as
convenient as possible for you. There are two major parts: the overview material
that concerns the entire trace facility, followed by subsections describing individual
TRACE operands.
Following this introduction, the overview provides three format boxes showing all
the possible operands and options available with the TRACE command. Once you
become somewhat familiar with the TRACE command, you can use these format
boxes to view at a glance all of the options at your disposal. The TRACE operands
are divided into two types: primary and control operands. The primary operands
allow you to choose the kind of event you want to trace. These operands are shown
in the first format box, along with any options that are unique to a particular
primary operand. The second format box shows the options that are common to all
of the primary operands as well as to the TRAP control operand. The third format
box shows the control operands (the operands that enable you to operate the trace
facility) along with any options unique to a particular control operand.
The format boxes are followed by a brief explanation of what each contains. This
section includes lists of all the operands and gives you the page on which you can
find an operand's complete description. (Each operand is described in its own
subsection, as though it were a separate command. Note that certain related
operands are described together in a single subsection.)
Next, there are "General Usage Notes for TRACE" on page 657. These notes
provide you with a capsule explanation of how to use the trace facility. Again, for a
full explanation of how to use the trace facility, see VM/XA SP Virtual Machine
Operation. The usage notes also include some important information about how the
trace facility functions.
654
VM/XA SP2 CP Command Reference
TRACE
The next section, "TRACE: Common Options" on page 659, provides full
explanations for the options common to all of the primary operands and to the
TRAP control operand. This is followed by "TRACE: Command Responses" on
page 663, showing all of the command responses (trace entries) that you may
receive. Note that this response section provides a list of all of the response symbols
and an explanation for each. During the tracing process, you can turn to this
section to interpret the trace entries that you receive .. Because all of the responses
are gathered here~ this section can be especially helpful when you're tracing a
number of varied events simultaneously.
The overview material is followed by the subsections that document individual
TRACE operands. These subsections are in alphabetical order. Each subsection
explains the particular use of an operand (or a group of related operands), and
provides explanations for any options unique to that operand as well as usage notes
unique to that operand. If the operand is compatible with the common options, the
subsection also contains a list of the common options.
Complete Format for TRACE
The following three format boxes show all of the operands and options available
with the TRACE command.
Primary operand format:
TRace
ALL
BRAnch [INTO range]
COunt
DIAGnose [range] [SIM ]
NOSIM
EXTernal [range]
G[n[-m][, ... ]] [DATA range MASK string]
INSTruction [DATA string]
I/O [range] [INSTructi on] [CCW ] [SIM :] [INTerrupt]
NOCCW NOS 1M:
MC [range] [SIM ]
[NOS 1M]
MCH
mnemonicl SIM
[ NOSIM:
mnemonic2 [range] [SIM
NOSIM
PROGram [range]
RIO
[range] [SIM
CCW
RSCH
NOSIM [ NOCCW
SIO
SIOF
SSCH
STore [INTO .{. range
}]
hexloc [DATA string [MASK string]
SVC [range] SIM
[ NOSIM
TAble
TPI [range] SIM
[NOSIM
'J
:J
TRace
J
J
J
J
Chapter 2. VMjXA SP CP Commands
655
TRACE
Common options:
[.{
~~~~ ·}rangeJ.
' Range
RUN ]
[
,NORun.
,.
[SKIP n] [PAss n] [STOP n] [STEp n]
m~~~~ ~a1] G~~~~:~er] [~~~:~:sor] [~~bAT]
[IDentifer ident]
CMd ••. cp command •.. ]
[ NOCMD
Control operand format:
TRace
APPEND name
CALL name [SUSpend]
CLEAR [name]
DELete ident
END ·[ALL ]
COunt
GOto-name[SUSpend]
RETurn name [SUSpend]
TRAP ident [common options]
where:
primary operand
is one of the operands you use to specify the kind of event you want to trace.
(On the pages that follow, the operands are described in their own subsections,
as though they were separate commands. Certain related operands are described
together in single subsections. For your convenience, each operand is listed
below alphabetically, along with a reference to the subsection and the page
where its full description appears.) The primary operands are:
656
Operand'
Description
ALL
See "TRACE ALL" on page 672.
BRAnch
See "TRACE BRANCH" on page 674.
COunt
See "TRACE COUNT" on page 677.
DIAGnose
See "TRACE SVC/DIAGNOSE/MC" on page 697.
EXTERNAL
See "TRACE EXTERNAL/PROGRAM" on page 679.
GPRs
See "TRACE GPRs" on page 682.
INSTruction
See "TRACE INSTRUCTION" on page 684;
1/0
See "TRACE I/O" on page 686.
Me
C;;:pp
"TD Ar~
....,~ ....
------
VMjXA SP2 .CP Command Reference
-
c;;:vr/nTAnN()C;;:~/M(,," on n~op.
- . . - , - _.. _ - - " - - - , - - - - - r-Q-
(lQ7
-_ ..
TRACE
Operand
Description
MCH
See "TRACE MCH" on page 688.
mnemonic!
See "TRACE mnemonicl" on page 689.
mnemonic2
See "TRACE mnemonic2" on page 691.
PROGRAM
See "TRACE EXTERNALjPROGRAM" on page 679.
RIO
See "TRACE RIOjRSCHjSIOjSIOF jSSCH" on page 693.
RSCH
See "TRACE RIOjRSCHjSIOjSIOFjSSCH" on page 693.
SIO
See "TRACE RIOjRSCHjSIOjSIOFjSSCH" on page 693.
SIOF
See "TRACE RIOjRSCHjSIOjSIOFjSSCH" on page 693.
SSCH
See "TRACE RIOjRSCHjSIOjSIOF jSSCH" on page 693.
STore
See "TRACE STORE" on page 695.
SVC
See "TRACE SVCjDIAGNOSEjMC" on page 697.
TAble
See "TRACE TABLE" on page 699.
TPI
See "TRACE TPI" on page 700.
common options
are the options that are available to all the primary operands as well as to the
TRAP control operand. These options are fully explained in "TRACE:
Common Options" on page 659.
control operand
is one of the operands you use in controlling the operation of the trace facility
itself. (On the pages that follow, the operands are described in their own
subsections, as though they were separate commands. Certain related operands
are described together in single subsections.)
For your convenience, each operand is listed below alphabetically, along with a
reference to the subsection and the page where its full description appears.) The
control operands are:
Operand
Description
APPEND
See "TRACE APPEND" on page 673.
CALL
See "TRACE GOTOjCALLjRETURN" on page 680.
CLEAR
See "TRACE CLEAR" on page 676.
DELete
See "TRACE TRAP" on page 702.
END
See "TRACE END" on page 678.
GOto
See "TRACE GOTOjCALLjRETURN" on page 680.
RETurn
See "TRACE GOTOjCALLjRETURN" on page 680.
TRAP
See "TRACE TRAP" on page 702.
General Usage Notes for TRACE
1. All of the primary TRACE operands establish trace traps. A "trace trap" is a
programming function that, as its name implies, captures information about an
event in your virtual machine.
When you establish a trap, you can assign it any unique one-to-four character
name (with the exception of the name "ALL"). If you do not assign a name, the
Chapter 2. VMjXA SP CP Commands
657
TRACE
system assigns the trap a unique number from 1 to 9999. You use this unique
identifier (name or number) to alter a trap with the TRACE TRAP command or
to delete a trap with the TRACE DELETE command.
The options (unique and common) available with each primary operand and
with the TRAP operand allow you to specify exactly how you want the trap to
execute. For example, you might want the trap to function only when an event
occurs within a particular address range. In this case, you would specify the
common option FROM with the address range you've chosen. At the same
time, you might want to trace events only when your virtual machine is running
in supervisor state. In this case, you would also specify the common option
SUPERVISOR.
2. All trace traps must be contained in units of control called sets. A "trace set" is
a collection of one or more traps that run together.
You create a set using the TRACE GOTO command. When you create the set,
you assign it a unique 1- to 8-character name. If you do not assign the set a
name, the system assigns a unique name for you.
If you do not create a set before you establish a trap, VM/XA SP creates a set
for you named INITIAL.
y one set may be active at any given time.
The following commands exist for manipUlating sets:
• TRACE GOTO
• TRACE CALL
• TRACE RETURN
• TRACE CLEAR
• TRACE END
• TRACE APPEND
3. You can define up to 255 trace sets and trace traps in any combination during a
single trace session. (For example, you can create two trace sets with no more
than 253 traps between them, five trace sets with no more than 250 traps
between them,20 trace sets with no more than 235 traps between them, and so
on.)
4. If you have RUN set ON when you issue a TRACE command, making a
TRACE set active, RUN will be turned off.
5. For information on how to display your current trace settings, see the QUERY
TRACE command. The QUERY TRACE can be especially useful if you need
to know the identifiers that VM/XA SP has assigned to your traps or sets. The
command QUERY TRACE ALL displays the attributes of all trace traps within
all trace sets.
6. The IPL command for VM/XA SP suspends all user tracing with the TRACE
command during the IPL process. Tracing is then automatically reset as it was
and continues normally.
7. DATOFF is a synonym for NODAT. DATOFF is allowed whenever NODAT
is allowed.
8. Depending on the model, PER events for general-register alteration mayor may
n",t h;:> r;:>r-nO'nt'7;:>rl f'nr u;:>r-tnr tn(ltrnf'ttnn(l
L.L"" .., ....
658
"""""""e~""'''''~
VM/XA SP2 CP Command Reference
.. ...,................, ........u
............... " .... u.
TRACE: Common Options
TRACE: Common Options
~~~~, }range]
[{Range
[:~~un]
[SKIP n] [PAss n] [STOP n] [STEp n]
[IDentifier ident]
'CMd •.. cp command •.. ]
[ NOCMD
You can respecify all of the common options except the ID option. If you specify
any of these options without a primary trace operand, they will be applied to all
events in the current trace set. If you specify the TRAP operand, these operands will
be applied to a single event.
where:
PSWA range
FROM range
RANGE range
PSWA restricts instruction tracing to a given address range. PSWA permits a
trap to be taken if the PSWA (that is, the program status word address,
commonly known as the instruction counter) points to an instruction in the
specified range. The range may be a single address, a pair of addresses
separated by a "-," or an address followed by a period followed by a byte count.
An instruction is considered to be within the range if the first byte is within the
range.
FROM and RANGE are synonyms for PSWA used in those subcommands
where a potential for confusion exists. For example, TRACE BRANCH allows
two instruction ranges to be specified, a FROM range and an INTO range.
FROM and RANGE are allowed wherever PSWA is allowed.
For executed instructions (that is, instructions that are issued by means of the
assembler language EXECUTE instruction), the instruction is within the range if
either:
• The first byte of the EXECUTE instruction is within the range
• The first byte of the target instruction is within the range
For external interruptions, the PSW address at the time of the interruption is
inspected to see if it is within the range.
When a program event recording (PER) event is reflected to your virtual
machine, the PER event address is checked.
F or any other program exception, the old PSW instruction address is inspected if
a nullification exception occurs; for all others, the old PSW instruction address is
adjusted by the instruction length code, and then is inspected.
Chapter 2. VMjXA SP CP Commands
659
TRACE: Common Options
RUN
specifies that virtual machine execution is not to pause when the specified event
occurs. RUN is assumed if TERMINAL is not specified or assumed. RUN is
incompatible with NORUN, STEP, and STOP.
NORUN
specifies that virtual machine execution is to pause when the specified event
occurs. NORUN is assumed if TERMINAL is specified or assumed. NORUN
is incompatible with RUN, STEP, and STOP.
SKIP n
requests that the associated event be completely ignored n times. When used
with the NOSIM option, however, it specifies the number of times that an
instruction will be simulated normally.
STOPn
requests a number of displays for the command. Your virtual machine pauses
after the specified number of displays. Unless a STEP count is specified, a pause
occurs for each subsequent display.
PASSn
is a repeating SKIP specification. If you do not specify a SKIP option, PASS
takes effect immediately. If you do specify a SKIP count, PASS takes effect
after the SKIP count expires and the specified event has been recognized.
F or example:
• PASS 2 will display every third event
• PASS 8 will display every ninth event
• SKIP 2 PASS 8 will display the third event, the 12th event, and every ninth
event thereafter.
STEPn
is a repeating STOP specification. If you do not specify a STOP option, STEP
takes effect immediately. If you do specify a STOP count, STEP takes effect
after the first pause.
For example:
• STEP 3 will pause every third event
• STEP 9 will pause every ninth event
• STOP 3 STEP 9 will pause after the third and 12th displays and for every
ninth display thereafter.
TERMINAL
specifies that output for the current command is to be sent to the virtual
console. This is the default setting for newly-created tracing specifications with
neither terminal nor printer output specifications. TERMINAL and
NOTERMINAL are incompatible options.
NOTERMINAL
specifies that output for the current command is not to be sent to the virtual
console. TERMINAL and NOTERMINAL are incompatible options.
BOTH
specifies that the output for the current command is to be sent to the virtual
console and to the virtual printer.
660
VMjXA SP2 CP Command Referenc~
TRACE: Common Options
PRINTER
PRT
specifies that output for the current command is to be sent to the virtual printer
having the lowest virtual device address. PRINTER may be abbreviated as
PRT. PRINTER and NOPRINTER are incompatible options.
NOPRINTER
NOPRT
specifies that output for the current command is not to be sent to the virtual
printer. NOPRINTER may be abbreviated as NOPRT. PRINTER and
NOPRINTER are incompatible options.
SUPERVISOR
requests that the specified tracing be restricted to events occurring while the
machine is in supervisor state. If specified in addition to PROBLEM, or if
neither SUPERVISOR nor PROBLEM is specified, then both problem state and
supervisor state events will be traced.
PROBLEM
requests that the specified tracing be restricted to events occurring while the
machine is in problem state. If specified in addition to SUPERVISOR, or if
neither SUPERVISOR nor PROBLEM is specified, then both problem state and
supervisor state events will be traced.
DAT
requests that the specified tracing be restricted to events occurring while the
virtual machine has virtual dynamic address translation enabled. If you specify
DAT in addition to NODAT, or if you specify neither DAT nor NODAT,
events occurring in both DAT and non-DAT mode will be traced.
NODAT
requests that the specified tracing be restricted to events occurring while the
virtual machine has virtual dynamic address translation disabled. If you specify
NODAT in addition to DAT, or if you specify neither DAT nor NODAT,
events occurring in both DAT and non-DAT mode will be traced.
IDENTIFIER ident
specifies an identifier for a trace trap describing the event. It must be one to
four characters in length. If a trap already exists with the given identifier, it will
be replaced by the trap for the newly defined event. If you do not specify ID, a
unique number from I to 9999 will be assigned as the identifier, with leading
zeros removed. You cannot use the word "ALL" as an identifier. Also, on the
TRACE TRAP commands (TRACE TRAP and TRACE DELETE), this is an
invalid option.
CMD... cp command ...
specifies a CP command or set of CP commands to be executed when the
specified event occurs.
Multiple commands must be separated by linend characters. Actuallinend
characters will terminate the trace command.
For example, if the pound sign (#) is your logical line end character, and if" is
your logical escape character:
trace svc cmd d 20#d 30
issues a TRACE SVC command that displays location 20, and then issues the
CP command DISPLAY to display location 30.
Chapter 2. VM/XA SP CP Commands
661
TRACE: Common Options
The command:
trace svc cmd d 20"#d 30
issues one TRACE command; it displays locations 20 and 30 whenever an SVC
instruction is executed.
You can use this option with TRACE GOTO, TRACE CALL, and TRACE
RETURN to allow conditional and unconditional branching and subroutine
calls between TRACE environments.
All characters between the CMD option and the end of the TRACE command
line are considered to be part of the CMD field; thus, it must be the last option
on the line. No command syntax verification is made on the set of CP
commands to be executed until the specified event occurs. Terminal output from
the set of commands is not affected by the TERM or NOTERM specification of
the trace event.
NOCMD
specifies that no CP command is to be executed when the specified event occurs.
Use NOCMD to delete CMD fields from existing trace events.
662
VM/XA SP2 CP Command Reference
TRACE: Command Responses
TRACE: Command Responses
The following pages illustrate the command responses for each of the TRACE
command operands. These response descriptions use the following symbols:
Symbol
Meaning
aaaaaaaa
Storage address, followed by a single quote (') if OAT.
For external and I/O interruptions it is the PSW address
at the time of interruption. When a PER event is
reflected to the virtual machine, it is the program event
recorder event address. For other program exceptions, it
is the old PSW instruction address for nullification
exceptions, and for all others it is the old PSW
instruction address as adjusted by the instruction length
code.
tttttttt
Transfer address, followed by a single quote (') if OAT
xxxxxxxx
Instruction, CSW status, et al
gggggggg
Second level channel command word, CSW status, et al
hhhhhhhh
First level channel command word, CSW status, et al
0000
First level CCW offset
addressl
Address of operand 1 (for SI and SS formats only)
address2
Address of operand 2 (for RX, RS, S, and SS formats
only)
Note: addressl and address2 may be question marks if
the addresses cannot be resolved because the base
or index registers used to compute them have
been altered by the instruction.
contentl
Contents of Rl field (RRE format only)
content2
Contents of R2 field (RRE format only)
vdev
Virtual device address
vsch
Virtual subchannel number
mnem
Mnemonic for instruction
code
Interruption code number in hexadecimal
xx
Extension-exception code
nnnnnnnn
The number representing the successful trace events in
the current trace set
name
Interruption name (e.g., operation, addressing)
CCn
Condition code number (0, l, 2 or 3)
Gnn
A general register with altered contents
cccccccc
Contents of register
ss
Status byte
FSA = nnnnnnnn
The FAILING STORAGE ADDRESS if valid. If it is
invalid, then nothing will be shown.
Chapter 2. VMjXA SP CP Commands
663
TRACE: Command Responses
Symbol
Meaning
zz
Altered byte of an EXECUTE instruction, formed by
inclusive-orfing the low byte of Rl with the second byte
of the executed instruction.
***
Prefix indicating virtual machine interruption
->
As a prefix indicating transfer of control, it is present at
the beginning of a line whenever the displayed instruction
does not immediately follow the last instruction
displayed. As a suffix for a successful branch instruction,
it precedes the address being transferred to.
»
Indication of storage alteration, followed by the operand
address.
Prefix used with LOAD ADDRESS to show that the
actual data is shown rather than computing the operand
address by base and displacement.
For operation codes that represent two mnemonics, the mnemonic for fixed-point
operations is shown. The following is a list of those operation codes with the
mnemonic to be returned by CP:
Table 9. Operation Codes and Mnemonics
Number
Code
Meaning
A409
VL
Load
A40A
VLM
Load Matched
A40B
VLY
Load Expanded
A40D
VST
Store
A40E
VSTM
Store Matched
A40F
VSTK
Store Compressed
A40A
VLMR Load Matched
A50B
VLZR
Load Zero
E400
VLI
Load Indirect
E401
VSTI
Store Indirect
Basic Instruction Display
aaaaaaaa mnem xxxxxxxx address! address2 CC n
Executed Instructions
aaaaaaaa EX xxxxxxxx address! mnem xxzzxxxx address! address2 CC n
Load Address Instructions
aaaaaaaa LA xxxxxxxx
=
cccccccc CC n
RRE Format Instructions:
aaaaaaaa mnem xxx xxx xx content! content2 CC n
664
VMjXA SP2 CP Command Reference
TRACE: Command Responses
Instructions Altering Storage
aaaaaaaa mnem xxxxxxxx » addressl address2 CC n
Successful Branch Instructions (including SVC and LPSW)
aaaaaaaa mnem xxxxxxxx
->
tttttttt CC n
Instructions Satisfying GPR Alteration Tracing
aaaaaaaa mnem xxxxxxxx addressl address2 CC n Gnn=cccccccc
Gnn=cccccccc
Gnn=cccccccc
Gnn=cccccccc
External Interruptions
*** aaaaaaaa EXT code -
tttttttt
Program Interruptions
(Instruction displayed where possible)
*** aaaaaaaa PROG code -
tttttttt name
Virtual Machine Check Interruptions
(Instruction displayed where possible)
*** aaaaaaaa MCH -> tttttttt type type
(FSA=nnnnnnnn)
where:
aaaaaaaa
is the address contained in the second word of the old PSW, if valid, of
the machine check. If the PSW instruction address is marked invalid,
question marks will appear in place of the address.
tttttttt
is the address contained in the second word of the new PSW for the
machine check.
type
is one or more of the machine check codes found in the 370-XA:
Principles of Operation. The major virtual machine check codes are:
Table 10 (Page 1 of 2). Machine Check Codes
Number
Code
Meaning
0
SD
System Damage
1
PD
Instruction-processing
Damage
2
SR
System Recovery
3
TD
Interval-timer Damage
4
CD
Timing Facility Damage
5
ED
External Damage
6
VF
Vector Facility Failure
7
DG
Degradation
8
W
Warning
9
CP
Channel Report Pending
Chapter 2. VM/XA SP CP Commands
665
TRACE: Command Responses
Table 10 (Page 2 of 2). Machine Check Codes
Number
Code
Meaning
10
SP
Service Processor Damage
11
CK
Channel Subsystem Damage
12
Unused
13
VS
Vector Facility Source
14
B
Backed Up
FSA=nnnnnnnn
is the FAILING STORAGE ADDRESS if valid. If it is
invalid, then nothing will be shown.
370 110 Interruptions
*** aaaaaaaa I/O vdev
->
tttttttt CSW xxxxxxxx xxxxxxxx
370-XA 1/0 interruptions
*** aaaaaaaa I/O DEV vdev
->
tttttttt SCH vsch PARM xxxxxxxx
370 110 Instructions
aaaaaaaa
aaaaaaaa
aaaaaaaa
aaaaaaaa
aaaaaaaa
aaaaaaaa
aaaaaaaa
aaaaaaaa
SIO
SIOF
SIO
mnem
mnem
mnem
mnem
mnem
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
vdev
vdev
vdev
vdev
vdev
vdev
vdev
vdev
CC
CC
CC
CC
CC
CC
CC
CC
0
0
1
0
1
1
2
3
CAW xxxxxxxx
CAW xxxxxxxx
CAW xxxxxxxx CSW xxxx
CSW xxxx
CSW xxxxxxxx xxxxxxxx
370-XA 110 Instructions
aaaaaaaa SSCH xxxxxxxx address2 CC 0 SCH vsch DEV vdev
CPA xxxxxxxx PARM xxxxxxxx KEY x FPI xx lPM xx
where:
CPA
is the channel program address specifying the absolute
address of the first channel command word to be
executed on the device.
PARM
is the interrupt parameter to be returned with any
interrupt for the specified channel command words.
KEY
is the storage protection key to be used.
FPI
is the Format, Prefetch, Initial Status control byte.
LPM
is the Logical Path Mask
aaaaaaaa TSCH xxxxxxxx address2 CC 0 SCH vsch DEV vdev
CCWA xxxxxxxx DEV STS xx SCH STS xx CNT xxxx
KEY x FPI xx CC x CTlS xxxx
aaaaaaaa TSCH xxxxxxxx address2 CC 1 SCH vsch DEV vdev
KEY x FPI xx CC x CTlS xxxx
666
VMjXA SP2 CP Command Reference
TRACE: Command Responses
where:
CCWA
is the ending channel command word address when I/O
completed.
DEV STS
is the unit status for the device.
SCH STS
is the channel status for the subchannel.
CNT
is the residual CCW count upon I/O completion.
KEY
is the key used for storage protection.
FPI
is the format, prefetch, initial status control byte used. It
also indicates a no-path-available condition and a
confirmed I/O condition code O.
CCx
is the condition code for the requested I/O operation.
Unlike 370 I/O, this is always returned separately from
the SSCH instruction.
CTLS
are the function and activity control bytes.
aaaaaaaa TPI xxxxxxxx address2 CC 1
SCH xxxx DEV xxxx PARM xxxxxxxx
where:
SCH
is the subchannel requesting the interruption.
DEV
is the device ID for the subchannel.
PARM
is the interruption parameter supplied by the virtual
machine, zero if the interrupt is unsolicited.
Instructions/Condition Codes
aaaaaaaa mnem xxx xxx xx address2 CC n SCH vsch DEV vdev
Executed I/O Instructions
aaaaaaaa EX xxxxxxxx aaaaaaaa mnem xxzzxxxx address2 CC n
SCH vsch DEV vdev
(Followed by fields as before)
CCW Tracing Display Format:
Seek CCWs for Mini-DASDs:
CCW
aaaaaaaa 99999999 99999999
SEEK
99999999 9999
0000
hh •••••. hhhhhhhh
hhhhhhhh hhhh
Seek CCWs for Attached DASDs:
CCW
aaaaaaaa 99999999 99999999
SEEK
99999999 9999
0000
hhhhhhhh hhhhhhhh
hhhhhhhh hhhh
Chapter 2. VM/XA SP CP Commands
667
TRACE: Command Responses
CCWs with a Virtual Channel Simulator:
CCW
SEEK
0000 hh .••... hhhhhhhh
hhhhhhhh hhhh
Seek CCW - Set File Mask CCW Sequence with a Virtual Channel Simulator:
VDEV vvvv CCW 99999999 99999999 STS
CCW 99999999 99999999 STS
55
55
ss DATA STS
DATA 99 STS
5S
S5
Seek CCW - Set File Mask CCW Sequence with a Real Channel:
CCW
SEEK
CCW
0000 hh ...... hhhhhhhh
hhhhhhhh hhhhhhhh
0000 hh .....• hhhhhhhh
hh
Search CCWs for Attached DASDs:
CCW
aaaaaaaa 99999999 99999999
SEARCH
99999999 99
0000 hhhhhhhh hhhhhhhh
hhhhhhhh hh
Search CCWs for Mini-DASDs:
CCW
aaaaaaaa 99999999 99999999
SEARCH
99999999 99
0000 hh ...... hhhhhhhh
hhhhhhhh hh
TIC CCWs:
CCW
aaaaaaaa 99999999 99999999
0000 hh000000 hhhhhhhh
TIC CCWs with Virtual Channel Simulator:
CCW
99999999 99999999
TIC
aaaaaaaa
Other CCWs:
CCW
668
aaaaaaaa 99999999 99999999
VM/XA SP2 CP Command Reference
0000 hhhhhhhh hhhhhhhh
TRACE: Command Responses
CCWs with Data Crossing Page Boundaries:
CCW
aaaaaaaa 99999999 99999999
IDAl
IDAl
as many IDAls as needed
0000
hh •..••. hhhhhhhh
hhhhhhhh
hhhhhhhh
0000
hh ••.••• hhhhhhhh
hhhhhhhh
hhhhhhhh
CCWs with User IDALs:
CCW
aaaaaaaa 99999999 99999999
IDAl
99999999
IDAl
99999999
CCWs with Virtual Channel IDAWs:
CCW
IDAW 99999999 DATA 9999
Data Transfer over 8 Bytes with Virtual Channel Simulator:
hhhhhhhh hhhhhhhh
hhhhhhhh hhhh
CCW
Suspend with Virtual Channel Simulator:
CCW
99999999 99999999 ***SUSPENSION***
Define Extent CCWs for Mini-DASDs:
CCW
aaaaaaaa 99999999 99999999 0000 hh ...••. hhhhhhhh
EXTENT
hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh
Locate Record CCWs for Mini-DASDs:
CCW
aaaaaaaa 99999999 99999999 0000 hh ...••. hhhhhhhh
lOCATE
hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh
Search CCWs for Attached DASDs:
CCW
aaaaaaaa 99999999 99999999
SEARCH
99999999 99
0000
hhhhhhhh hhhhhhhh
hhhhhhhh hh
Chapter 2. VMjXA SP CP Commands
669
TRACE: Command Responses
Search CCWs for Mini-DASDs:
CCW
aaaaaaaa 99999999 99999999
SEARCH
99999999 99
0000
hh •••••• hhhhhhhh
hhhhhhhh hh
0000
hhOOoooo hhhhhhhh
TIC CCWs:
CCW
aaaaaaaa 99999999 99999999
TIC CCWs with Virtual Channel Simulator:
CCW
99999999 99999999
TIC
aaaaaaaa
Other CCWs:
CCW
aaaaaaaa 99999999 99999999
0000
hhhhhhhh hhhhhhhh
CCWs with Data Crossing Page Boundaries:
CCW
aaaaaaaa 99999999 99999999
IDAl
IDAl
as many IDAls as needed
0000
hh •••••• hhhhhhhh
hhhhhhhh
hhhhhhhh
0000
hh .••••• hhhhhhhh
hhhhhhhh
hhhhhhhh
CCWs with User IDALs:
CCW
aaaaaaaa 99999999 99999999
IDAl
99999999
IDAl
99999999
CCWs with Virtual Channel IDAWs:
CCW
IDAW gg999999 DATA 9999
Data Transfer over 8 Bytes with Virtual Channel Simulator:
CCW
Suspend with Virtual Channel Simulator:
670
VM/XA SP2 CP Command Reference
hhhhhhhh hhhhhhhh
hhhhhhhh hhhh
TRACE: Command Responses
Migration Notes
VMISP HPO
1. In VMjXA SP, TRACE stops execution after each traced instruction, instead of
before each traced instruction, as in VMjSP HPO.
2. In VMjXA SP, the traceback table shows only those branch instructions which
are in the range of branches being traced.
3. If the maximum branch count is exceeded in VMjXA SP, the traceback table
shows the maximum branch count. It is not set back to one as in VMjSP HPO.
4. VMjXA SP allows a minimum truncation of TERM for TERMINAL.
5. VMjXA SP supports additional operands and options including many of the
VMjSP HPO PER command functions.
6. VMjSP HPO accepts TERM BOTH or PRINTER BOTH; VMjXA SP considers
TERM BOTH and PRINTER BOTH conflicting options.
7. The VMjSP HPO options GUESTR, GUESTV, CURRENT, PRIV, CCW, and
CSW are not accepted in VMjXA SP.
8. VMjSP HPO accepts EN for END; YMjXA does not.
9. The VMjSP HPO PER END tracetype (like PER END BR) is not accepted in
VMjXA SP.
10. VMjSP HPO accepts PRO as a minimium truncation for PROGRAM; PROG is
the minimum truncation in VMjXA SP.
11. When VMjSP HPO does not recognize a word on the TRACE command, it
displays "003 Invalid option - word." VMjXA SP displays "002 Invalid operand
- word."
12. An attempt to modify a PER trace set when none exists results in return code
180 and the message "TRACE NOT IN EFFECT." In VMjXA SP, an attempt
to modify a trace set when none exists results in return code 47 and the message
"The current trace set does not exist."
13. In VMjSP HPO, the output for PER STORE into 20500 includes an MVCL.
VMjXA SP does not.
14. VMjXA SP does not allow the MASK operand.
15. When no trace is active, the VMjXA SP response to a QUERY PER command
is RC 0, "NO TRACE SETS DEFINED." In VMjSP HPO you receive RC
180, "DMKPEQI80E PER trace not in effect."
Chapter 2. VM/XA SP CP Commands
671
TRACE ALL
TRACE ALL
Privilege Class: G
Use TRACE ALL to trace all program, external, and I/O interruptions in addition
to all instructions executed.
I
[ALL]
TRace
[common options]
where:
ALL
causes all program, external, and I/O interruptions to be traced in addition to all
instructions executed. If you omit ALL, any options you specify are valid only
for the trace currently in effect. A new trace will not be started.
common options
Y Oti can specify any of the common options:
1
' PSWA
FRom
[{
Range
range]
[RUN
NORun
.J
[SKI P n] [PAss n] [STOP n] [STEp n]
[IDentifer ident]
CMd
[ NOCMD
000
cp command
00
oJ
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
1. Because ALL encompasses;system events in your entire address range, the
PSWA option has no function if used with TRACE ALL. If an address range is
specified by the PSWA operand, it will be ignored.
2. Each TRACE ALL command replaces an active TRACE ALL command.
Responses
See "TRACE: Command Responses" on page 663.
672
VM/XA SP2 CP Command Reference
TRACE APPEND
TRACE APPEND
Privilege Class: G
Use the TRACE APPEND command to merge the trace traps from two trace sets
in to one trace set.
I TRace
APPEND name
where:
APPEND
merges the traps from the named trace set with the current trace set.
name
specifies the trace set whose traps are to be merged into the current trace set.
Usage Notes
1. The TRACE APPEND command causes all trace traps from the named trace set
to be added to the current trace set.
If a trap exists in both trace sets with the same identifier and the trap was
named using the ID option on the TRACE command, then the trap in the
named set will replace the trap in the current trace set.
If two traps have the same identifier but were not named with the ID option (for
example, the identifier was assigned by the system), then both traps will remain,
and the trap from the named trace set will be assigned a new identifier.
2. The current trace set cannot be appended to itself.
Responses
None.
Chapter 2. VM/XA SP CP Commands
673
TRACE BRANCH
TRACE BRANCH
Privilege Class: G
Use TRACE BRANCH to trace successful branch instructions, including LPSW and
SVC instructions that do not load a wait PSW.
I
TRace
BRAnch [INTO range] [common options]
where:
BRANCH
traces successful branch instructions
INTO range
permits a trap to be taken if the destination of a successful branch instruction is
within the specified range.
You may specify the range as a single address or a pair of addresses separated
by a ".," or "-." A dash denotes a starting and ending range. A period denotes
a starting range for a byte count. A branch destination is considered to be
within the range if any byte is within the range.
The addresses are real or virtual as determined by the setting of the DAT bit in
the PSW at the time the event is detected. For BRANCH tracing, the address
or range of addresses can be odd or outside of the address space; the event will
be detected after the branch instruction but before any attempt is made to fetch
the next instruction.
common options
You can specify any of the common options:
~~~~ } range']
[{Range
RUN ]
[ NORun
[SKIP n] [PAss n] [STOP n] [STEp n]
[IDentifer ident]
CMd .•. cp command •.. ]
[ NOCMD
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
674
VM/XA SP2 CP Command Reference
TRACE BRANCH
Usage Notes
1. Your virtual machine will run very slowly after you have issued the TRACE
BRANCH instruction.
2. While TRACE BRANCH is active, a record of branch instructions is maintained
in the traceback table. You can use the TRACE TABLE command to display
this information.
Responses
See "TRACE: Command Responses" on page 663.
Chapter 2. VM/XA SP CP Commands
675
TRACE CLEAR
TRACE CLEAR
Privilege Class: G
Use TRACE CLEAR to delete all traps in a named trace set. The set itself will be
deleted if it is not active and it is not found in the RETURN list constructed by
TRACE CALL commands.
I
TRace
CLEAR [name]
where:
CLEAR (name)
deletes all traps in the named trace set. If you do not specify a name, the active
trace set is cleared.
Usage Notes
None.
Responses
See "TRACE: Command Responses" on page 663.
676
VM/XA SP2 CP Command Reference
TRACE COUNT
TRACE COUNT
Privilege Class: G
Use TRACE COUNT to count the successful trace events in your virtual machine.
I TRace
COunt
where:
COUNT
requests either the display of the current value of the TRACE COUNT, if
active, or the initiation of the TRACE COUNT.
Usage Notes
1. The TRACE COUNT function allows you to count the number of successful
trace events in the current trace set. While TRACE COUNT is active, no other
trace output is produced. The virtual machine does not stop after each event,
even if you specify NORUN.
2. When you enter a valid TRACE command, the system displays the value of the
current count and TRACE COUNT terminates.
If you enter TRACE COUNT when COUNT is already active, then the system
displays the current count and the count resumes from O.
When the TRACE COUNT reaches 16 million, the system displays that count
and resumes from O.
3. The current COUNT is also included in the QUERY TRACE response.
Responses
Trace count ;s nnnnnnnn
precedes the display of trace traps if TRACE COUNT is active.
where:
nnnnnnnn
is the number representing the successful trace events in the current trace set.
Chapter 2. VM/XA SP CP Commands
677
TRACE END
TRACE END
Privilege Class: G
Use TRACE END to delete all trace traps and all trace sets. No return list will
remain.
I TRace
END [ALL
COunt
]
where:
END [ALL)
deletes all trace traps and trace sets.
END [COUNT)
requests the display of the current value of the TRACE COUNT and the
termination of TRACE COUNT.
Usage Notes
None.
Response 1
Trace ended
is displayed if tracing was in effect and you issued TRACE END ALL. If tracing
was not in effect, the system displays no message.
Response 2
Trace count is nnnnnnnn
Trace count ended
is displayed if TRACE COUNT was active and you issued TRACE END COUNT.
where:
nnnnnnnn
is the number of successful trace events in the current trace set.
678
VM/XA SP2 CP Command Reference
TRACE EXTERNAL/PROGRAM
TRACE EXTERNAL/PROGRAM
Privilege Class: G
Use TRACE EXTERNAL/PROGRAM to trace external or program interruptions
or a range of external or program interruptions. When possible, the instruction that
caused the program interruption will also be displayed.
TRace
EXTernal} [range]
PROGram
{ PRG
[common options]
where:
EXTERNAL
PROGRAM
PRG
traces external or program interruptions, respectively.
range
is a hexadecimal range of external or program interruptions. You can express
this range as a single value, a pair of values separated by a "-," or an address
followed by a period "." and followed by a byte count. Wrap-around ranges are
not allowed.
common options
You can specify any of the common options:
[{Range
~~~~ } range]
RUN ]
[ NORun
[SKIP n] [PAss n] [STOP n] [STEp nJ
TErminal ]
NOTERMinal
[ BOth
Printer ] [SUperVisor] [OAT ]
NOPRINTer
PROBlem
NODAT
[IDentifer ident]
CMd ..• cp command ••. ]
[ NOCMD
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
None.
Responses
See "TRACE: Command Responses" on page 663.
Chapter 2. VMjXA SP CP Commands
679
TRACE GOTO/CALL/RETURN
TRACE GOTO/CALL/RETURN
Privilege Class: G
Use TRACE GOTO, TRACE CALL, and TRACE RETURN to activate TRACE
sets by name.
TRace
GOto
name} [
]
CALL
name
SUSpend
{ RETurn
where:
GOTO name
causes a trace set by the given name to become active. Specify name as a unique
I to 8 character identifier. If no trace set exists by that name, a new, empty set
is created. No program degradation occurs from an empty (null) trace set. The
previous trace set is unchanged but no longer active. If empty, it may be deleted
automatically.
You can use TRACE GOTO as the first command in a tracing session to
establish the name of an initial trace set. If traps are created without issuing a
TRACE GOTO, the initial trace set containing them will be named INITIAL.
CALL name
causes a trace set by the given name to become active. If no trace set exists by
that name, a new, empty set is created. No program degradation occurs from an
empty (null) trace set. The previous trace set is unchanged and is placed in a '
"Return" list on a last-in, first-out basis.
You can issue the CP QUERY TRACE RETURNS command to display a list
of trace sets currently in the return list; the order is from most to least recent.
Recursive calling is not allowed; it is illegal to call any trace set that has itself
called a trace set.
TRACE CALL is designed to be used with TRACE RETURN.
RETURN
causes the first trace set on the return list to be removed from the list and
become active. The previous trace set is unchanged but no longer active; if
empty, the previous trace set is deleted automatically.
SUSPEND
causes the trace set being loaded to have no effect until the next GOTO, CALL,
or RETURN occurs. You can issue TRACE commands to place traps for trace
events into the set without affecting the program that is currently in operation.
A suspended trace set will cause no program degradation.
Usage Notes
I. You can construct trace sets using a program that runs in your virtual machine.
The program will retrieve commands from storage and pass them to the control
program using DIAGNOSE instructions.
In most cases, the commands are to be applied to a subsequent program that is
not yet in operation. You can use the SUSPEND option to insure that the trace
set will have no effect until the next TRACE GOTO, TRACE CALL, or
TRACE RETURN occurs.
680
VM/XA SP2 CP Command Reference
TRACE GOTO/CALL/RETURN
Responses
See "TRACE: Command Responses" on page 663.
Chapter 2. VMjXA SP CP Commands
681
TRACE GPRs
TRACE GPRs
Privilege Class: G
Use TRACE GPRs to trace alterations to your virtual machine's general purpose
registers. You can trace all alterations to your registers, or only those that cause a
particular register or set of registers to assume a specified value.
TRace
G[n[-m][, ... ]] [DATA range MASK string]
[common options]
where:
G
is the general register or range of general registers whose alterations you want to
trace. If you are specifying a range of general registers, use the hyphen between
the first register number and last register number in the range.
You may specify the register numbers in either decimal or hexadecimal.
Wrap-around ranges (that is ranges whose ending register is less than the
starting register) are permitted. For example:
trace G10-2
is a valid range; it establishes tracing of alterations to registers 10, 11, 12, 13, 14,
15,0, 1, and 2.
DATA range
specifies a data value or range of data values to be checked to see if any of the
altered register(s) assume a value within the range. The range may be a single
value or a pair of values separated by a "." or "-." A dash denotes a starting
and ending range. A period denotes a starting range for a byte count. Range
values are viewed as unsigned 32-bit integers. If no data range is specified for
general register alteration tracing, O-FFFFFFFF is assumed. Wrap-around data
ranges are not allowed.
MASK string
specifies a hexadecimal string which forms a mask for data comparison. The
MASK string is logically applied to both the register and the data range before a
comparison is made.
common options
You can specify any of the common options:
682
VMjXA SP2 CP Command Reference
TRACE GPRs
PSWA } range]
FRom
[{ Range
l
RUN
,NORun
J
[SKI P nJ [PAss nJ [STOP nJ [STEp nJ
[IDentifer identJ
CMd
[ NOCMD
000
cp command
00
oJ
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
1. Your virtual machine will run very slowly when you have issued the TRACE
GPRs command.
Responses
See "TRACE: Command Responses" on page 663.
Chapter 2. VM/XA SP CP Commands
683
TRACE INSTRUCTION
TRACE INSTRUCTION
Privilege Class: G
Use TRACE INSTRUCTION to trace instructions in your virtual machine,
regardless of successful execution.
TRace
INSTruction [DATA string] [common options]
where:
INSTRUCTION
causes the tracing of instructions.
DATA string
specifies a string of data to be compared against the instruction data.
common options
You can specify any of the common options:
.{PSWA
FRom } range]
[ Range
[RUN
NORun '.J
[SKIP n] [PAss n] [STOP n] [STEp n]
[IDentifer ident]
CMd •.. cp command ....
[ NOCMD
J
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
1. If you use TRACE INSTRUCTION in conjunction with the PSWA option, only
instructions within the range of the address specified by PSWA are traced.
2. You may use the DATA option to limit tracing to certain instructions or
sequences of instructions. For example:
TRACE INSTR DATA 183F
will cause the tracing of all LR 3,15 instructions.
TRACE INSTR DATA 183F50
will trace all LR 3,15 instructions only if they are followed by a STORE (ST)
instruction.
684
VM/XA SP2 CP Command Reference
TRACE INSTRUCTION
Responses
See "TRACE: Command Responses" on page 663.
Chapter 2. VM/XA SP CP Commands
685
TRACE 1/0
TRACE 1/0
Privilege Class: G
Use TRACE I/O to trace input/output instructions and/or input/output interruptions
for all devices or for a range of devices.
TRace
P{~J
[rangel
'J
'J
[INSTruction] [CCW
[',S'IM
NOCCW
NOS 1M:
[INTerrupt]
[common options]
where:
1/0
10
traces I/O instructions or I/O interruptions.
range
is a range of devices. The range may be expressed as a singie device number or
pair of device numbers separated by a "-," or a starting device number followed
by a period "." and followed by a number representing the number of
consecutive device addressed to be traced. Wrap-around ranges are not allowed.
INSTRUCTION
specifies tracing of I/O instructions for a TRACE I/O command. If neither
INSTRUCTION nor CCW nor INTERRUPT are specified, INSTRUCTION
and INTERRUPT will be assumed by default.
CCW
specifies that CCW's will be displayed with RIO, SIO, SIOF, SSCH, and RSCH
instructions that successfully initiate I/O. CCW and NOCCW are incompatible
options.
NOCCW
specifies that CCW's will not be displayed. NOCCW will be assumed if CCW is
not specified. CCW and NOCCW are incompatible options.
SIM
requests normal simulation of instructions. If neither SIM nor NOSIM are
specified, SIM will be assumed by default. SIM and NOSIM are incompatible
options.
NOSIM
requests deletion of instruction simulation. Through use of the CMD option,
you can use it to define another operation for the instruction to perform. The
PSW will be left pointing to the next sequential instruction. SIM and NOSIM
are incompatible, options.
INTERRUPT
specifies tracing of I/O interruptions for a TRACE I/O command. If neither
INSTRUCTION nor CCW nor INTERRUPT are specified, INSTRUCTION
and INTERRUPT will be assumed by default.
686
VM/XA SP2 CP Command Reference
TRACE I/O
common options
You can specify any of the common options:
PSWA } range]
FRom
[{ Range
[RUN ]
NORun
[SKIP nJ [PAss nJ [STOP nJ [STEp nJ
[IDentifer identJ
CMd .•• cp command ..• ]
[ NOCMD
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
1. For 370-XA I/O, the device range applies to the device number, and not the
subchannel number.
2. I/O interruption addresses are not subject to the instruction range (if any)
specified by PSWA, FROM, or RANGE.
Responses
See "TRACE: Command Responses" on page 663.
Chapter 2. VMjXA SP CP Commands
687
TRACEMCH
TRACE MCH
Privilege Class: G
Use TRACE MCH to intercept machine check interruptions. When possible, the
instruction that caused the program interruptions will also be displayed. If you have
issued TRACE MCH and a machine check occurs, the tracing facility saves all the
necessary information prior to the machine check.
I TRace
MCH [common options]
where:
MCH
indicates that virtual machine checks are to be trapped.
common options
You can specify any of the CO!!lmOn options:
PSWA .} range] [RUN
FRom
NORun
[{, Range
J
[SKIP n] [PAss n] [STOP n] [STEp n]
[IDentifer ident]
CMd ••• cp command .••
[ NOCMD
J
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
None
Responses
See "TRACE: Command Responses" on page 663.
688
VM/XA SP2 CP Command Reference
TRACE mnemonicl
TRACE mnemonic1
Privilege Class: G
Use TRACE mnemonicl to trace the execution of specific assembler language
instructions.
TRace
mnemonicl [SIM ]
NOSIM
[common options]
where:
mnemonic!
must be one of the following standard assembler opcode mnemonics:
CONCS
DISCS
IPTE
ISK
ISKE
LCTL
LPSW
PGIN
PGOUT
PTLB
RCHP
RDD
RRB
RRBE
SAL
SCHM
SCK
SERVe
SIE
SIGP
SPX
SSK
SSKE
SSM
SSYN
STAP
STCPS
STCRW
STCTL
STIDC
STIDP
lUCV
STNSM
STOSM
STPX
STSYN
TB
TPROT
WRD
Tracing is limited to those instructions that do not produce an operation or
privileged operation exception.
SIM
requests normal simulation of instructions. If neither SIM nor NOSIM are
specified, SIM will be assumed by default. SIM and NOSIM are incompatible
options.
NOSIM
requests deletion of instruction simulation. Through use of the CMD option,
you can use it to define another operation for the instruction to perform.
You can embed instructions in your assembled code as breakpoints and use
TRACE mnemonicl to stop execution; or you can use TRACE mnemonic! to
stop program execution before a questionable instruction is executed. The PSW
will be left pointing to the next sequential instruction.
SIM and NOSIM are incompatible options.
Chapter 2. VM/XA SP CP Commands
689
TRACE mnemonicl
common options
You can specify any of the common options:
PSWA } range] [RUN .]
FRom
NORun
[{ Range
[SKIP n] [PAss n] [STOP n] [STEp n]
[IDentifer ident]
CMd ••• cp command
[ NOCMD
"'J
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
None.
Responses
See "TRACE: Command Responses" on page 663.
690
VM/XA SP2 Cl? Command Reference
TRACE mnemonic2
TRACE mnemonic2
Privilege Class: G
Use TRACE mnemonic2 to trace specific input/output (I/O) instructions within a
device range.
TRace
mnemonic2 [range] [SIM ]
NOSIM
[common options]
I
where:
mnemonic2
must be one of the following standard assembler opcode mnemonics:
CLRCH
CLRIO
C8CH
HDV
HIO
H8CH
M8CH
8T8CH
TCH
TIO
T8CH
Tracing is limited to those instructions that do not produce an operation or
privileged operation exception.
range
is a range of devices. The range may be expressed as a single device number or
pair of device numbers separated by a "-," or a device number followed by a
number which represents the number of consecutive device addresses to be
traced. Wrap around ranges are not allowed.
81M
requests normal simulation of instructions. If neither 81M nor N081M are
specified, 81M will be assumed by default. 81M and N081M are incompatible
options.
N08IM
requests deletion of instruction simulation. Through use of the CMD option,
you can use it to define another operation for the instruction to perform. The
P8W will be left pointing to the next sequential instruction. 81M and N081M
are incompatible options.
common options
You can specify any of the common options:
[
-{~~~~ } range]
[ RUN
NORun
'J
Range
[SKI P n] [PAss n] [STOP n] [STEp n]
[IDentifer ident]
CMd ... cp command •..
[ NOCMD
J
Chapter 2. VM/XA SP CP Commands
691
TRACE mnemonic2
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
None.
Responses
See "TRACE: Command Responses" on page 663.
692
VM/XA SP2 CP Command Reference
TRACE RIO/RSCH/SIO/SIOF/SSCH
TRACE RIO/RSCH/SIO/SIOF/SSCH
Privilege Class: G
Use TRACE RIO/RSCH/SIO/SIOF/SSCH to trace the SIO, SIOF, SSCH, RIO, or
RSCH instructions for all input/output (I/O) devices, or for a range of devices.
Tracing is limited to those instructions that do not produce an operation or
privileged operation exception.
TRace
!
l
RSCH
RIO
SIO..
SIOF
SSCH
[range] [SIM
] [ CCW]
NOSIM, NOCCW'
[common options]
where:
RIO
RSCH
SIO
SIOF
SSCH
is the instruction that you want to trace.
range
is a hexadecimal range of device numbers. A range may be expressed as a single
device number, a device number followed by a period followed by a number
which represents the number of consecutive device addresses to be traced, or a
pair of device numbers separated by a "." or "-." Wrap-around ranges are not
allowed.
SIM
requests normal simulation of instructions. If neither SIM nor NOSIM are
specified, SIM will be assumed by default. SIM and NOSIM are incompatible
options.
NOSIM
requests deletion of instruction simulation. Through use of the CMD option,
you can use it to define another operation for the instruction to perform. SIM
and NOSIM are incompatible options.
CCW
specifies that CCWs will be displayed with the SIO, SIOF, SSCH, RIO, and
RSCH instructions that successfully initiate I/O. CCW and NOCCW are
incompatible options.
NOCCW
specifies that CCW's will not be displayed. If you specify neither CCW or
NOCCW, NOCCW will be assumed. CCW and NOCCW are incompatible
options.
Chapter 2. VMjXA SP CP Commands
693
TRACE RIO/RSCH/SIO/SIOF/SSCH
common options
You can specify any of the common options:
PSWA } range;] [RUN '.J
' FRom
,NORun
[{
: Range :
._--"--
[SKIP nJ [PAss nJ [STOP nJ [STEp nJ
[IDentifer identJ
CMd .•• cp command ...
[ NOCMD
J
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
None.
Responses
See "TRACE: Command Responses" on page 663.
694
VMjXA SP2 CP Command Reference
TRACE STORE
TRACE STORE
Privilege Class: G
Use TRACE STORE to trace alterations to virtual machine storage that were made
by the processor. You can trace all alterations, or only those alterations causing a
specified set of logical locations to assume a specified value.
TRace
STore [INTO {range
}]
hexloc [DATA string [MASK string] ]
[common options]
where:
STORE
traces alterations to virtual machine storage by the processor.
range
permits a trap to be taken if any data is stored into any location within the
specified range.
The range may be a single address or a pair of addresses separated by a "." or
"-." A dash denotes a starting and ending range. A period denotes a starting
range for a byte count. A data specification is considered to be within the range
if the first byte is within the range.
hexloc
permits a trap to be taken when the following DATA or MASK options for the
location are met. See DATA and MASK below. The hexloc may be any valid
address. It may not be a range of addresses.
DATA string
specifies a hexadecimal data string that is to be matched when a store occurs
into the specified hexloc. The length of the data string determines the bounds of
the test. If MASK is specified with DATA, the MASK is logically applied to
both storage and the DATA string before the comparison is made. The DATA
operand requires the INTO hexloc operand.
MASK string
specifies a hexadecimal string that forms a mask for data comparison when a
store occurs into the specified hexloc. When you specify MASK, the MASK is
logically applied to both storage and the DATA string before the comparison is
made. Only those bits and bytes that are binary ones are checked. The MASK
operand requires the INTO hexloc operand and the DATA option. The length
of the MASK string must be the same as the length of the string you specified
for the DATA option.
Chapter 2. YM/XA SP CP Commands
695
TRACE STORE
common options
You can specify any of the common options:
'J.
PSWA } range:]. [RUN
FRom
NORun
[{ Range
.
[SKIP n] [PAss n] [STOP n] [STEp n]
~a 1J [~~~;i~~er} [~~~:~:sorJ ~~~~ATJ
[ ~~~~~~~
Bath
..
.
[IDentifer ident]
CMd
[ NOCMD
0
0
0
cp command
0
0
oJ
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
1. TRACE STORE does not trace "MVCL" instructions.
2. If the DATA option is specified, the length of the virtual storage that is
monitored for alteration is defined by the length of the DATA string.
Responses
See "TRACE: Command Responses" on page 663.
696
VMjXA SP2 CP Command Reference
TRACE SVC/DIAGNOSE/MC
TRACE SVC/DIAGNOSE/MC
Privilege Class: G
Use TRACE SVCjDIAGNOSEjMC to trace supervisor calls (SVC), DIAGNOSE
instructions, or monitor calls (MC), or a range of these events.
TRace
SVC}
[SIM ]
{ ~~AGnOSe [range] NOSIM, [common opti ons]
where:
SVC
DIAGNOSE
MC
traces sunervisor calls. diarmose instructions. or monitor
.&.
~......
-
-
-
-
-
-" - -;,
-
-
--- -
--- -
-
-
CH
-
lls. resnectivelv
r - - . . - . - -.,/
-~---;1
- - -
~
range
is a hexadecimal range of SVC numbers, DIAGNOSE codes, or monitor call
codes. A range may be specified as a single number or pair of numbers
separated by a "." or "-." Wrap-around ranges are not allowed.
SIM
requests normal simulation of instructions. If neither SIM nor NOSIM are
specified, SIM will be assumed by default. SIM and NOSIM are incompatible
options.
NOSIM
requests deletion of instruction simulation. Through the use of the CMD
option, you can use it to define another operation for the instruction to perform.
common options
You can specify any of the common options:
PSWA }"". range]
FRom
.
[{ Range
[RUN ]
NORun
[SKIP n] [PAss n] [STOP n] [STEp n]
[IDentifer ident]
-CMd ... cp command .•.•J[ NOCMD
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Chapter 2. VM/XA SP CP Commands
697
TRACE SVC/DIAGNOSE/MC
Usage Notes
None.
Responses
See "TRACE: Command Responses" on page 663.
698
VM/XA SP2 CP Command Reference
TRACE TABLE
TRACE TABLE
Privilege Class: G
Use TRACE TABLE to display the traceback table.
I
TRace
TAble
where:
TABLE
causes the traceback table to be displayed.
The traceback table is a list of successful branch instructions which is maintained
while branch tracing is active. It contains the most recent branch instructions
executed. If the same instruction is executed with no intervening branch
instructions, then the number of times the instruction was executed will be
maintained.
Up to six instructions are maintained in the traceback table. The most recent
branch will be displayed as the last entry in the table.
Usage Notes
None.
Response 1
aaaaaaaa mnem xxxxxxxx
->
tttttttt nn times
is displayed if there is at least one entry in the traceback table. This may be
repeated for up to six entries. nn times specifies the number of times in a row this
branch instruction was executed. This value is not displayed if n = 1.
Response 2
Traceback table is empty
is the response received if there are no entries in the traceback table.
Chapter 2. VM/XA SP CP Commands
699
TRACE TPI
TRACE TPI
Privilege Class: G
Use TRACE TPI to trace Test-Pending-Interrupt instructions. TRACE TPI is
accepted only if your virtual machine is operating in 370-XA mode, and tracing is
limited to those instructions that do not produce an operation or privileged
operation exception.
TRace
TPI [range]
[common options]
[SIM ]
NOSIM
where:
TPI
traces Test-Pending-Interrupt instructions.
range
is a range of device numbers. If you specify a device range, only those TPI
instructions that store an interruption will be traced. If you do not specify a
range, all TPI instructions will be traced. The device range applies to the device
name, and not the subchannel address.
The range may be a single device number, a device number followed by a period
and followed by a number which represents the number of consecutive device
addresses to be traced, or pair of device numbers separated by a "." or "-."
Wrap-around ranges are not allowed.
NOSIM and a device range are incompatible options.
SIM
requests normal simulation of instructions. If neither SIM nor NOSIM are
specified, SIM will be assumed by default. SIM and NOSIM are incompatible
options.
NOSIM
requests deletion of instruction simulation. This is invalid when TPI specifies a
device range. Through use of the CMD option, you can use it to define another
operation for the instruction to perform. The PSW will be left pointing to the
next sequential instruction. SIM and NOSIM are incompatible options.
common options
You can specify any of the common options:
[{
~~~~ }
range]-
RUN ]
[ NORun
; Range
[SKIP n] [PAss n] [STOP n] [STEp n]
J' -[-NOPRINTe~
Pri nter J-- [SUperVi sor:J
PROBl em
TErmi na 1
NOTERMi na 1,
[ BOth
'
[IDentifer ident]
rCMd ••• cp command ••• ,
LNOCMD
J
700
VM/XA SP2 CP Command Reference
[DAT 'J
NODAT
TRACE TPI
For a full explanation of the common options, see "TRACE: Common
Options" on page 659.
Usage Notes
None.
Responses
See "TRACE: Command Responses" on page 663.
Chapter 2. VM/XA SP CP Commands
701
TRACE TRAP Commands
TRACE TRAP
Privilege Class: G
Use the TRACE TRAP commands to alter or delete a trace trap by name.
TRace
TRAP
ident
{ DELete
[common options] }
where:
TRAP
applies the options you specify to a single event. All primary TRACE operands
establish units of control called "traps." Each trap, except for TRACE ALL, is
assigned a unique identifier and has its own set of options: TERM, PRINT,
RUN, STEP, and so on. TRACE ALL creates a unique set of traps replacing
any active TRACE ALL command. These traps each have an identifier of
"ALL,;; which may be used for changing trace options or deleting the trap. For
those traps for which SIM and NOSIM are valid options, you can specify SIM
or NOSIM with TRAP.
Any valid option you may specify with the TRAP operand you may specify
without any primary TRACE operand. Not specifying a primary TRACE
operand has the same effect as a TRACE TRAP command executed for each
event in the current TRACE set.
DELETE
The DELETE operand deletes an event from the current set.
ident
specifies an identifier for a trace trap describing the event. It must be one to
four characters in length. If a trap already exists with the given identifier, it will
be replaced by the trap for the newly defined event. You cannot use the word
"ALL" as an identifier; on the TRACE TRAP commands, this is an invalid
option.
common options
Except for ID, you can specify any of the common options:
PSWA } range] [RUN ]
FRom
NORun
[{Range
.
[SKI P n] [PAss n] [STOP n] [STEp n]
rCMd .•. cp command .•. ]
lJjQQm
For a full explanation of the common options, see "TRACE: Common Options" on
page 659.
702
VM/XA SP2 CP Command Reference
TRACE TRAP Commands
Usage Notes
1. Note that you cannot specify the ID option with TRACE TRAP to change the
identifier of an existing trap. In order to change the identifier, you must
redefine the trap.
2. With the exception of SIM and NOSIM, you can use TRACE TRAP to modify
only those options listed here. To change unique options not listed here, you
must redefine the trap. However, you can use TRACE TRAP to modify the
SIM and NOSIM on any trap for which they are valid options.
Responses
See "TRACE: Command Responses" on page 663.
Chapter 2. VM/XA SP CP Commands
703
TRANSFER
TRANSFER
Privilege Class: 0, G
Use the TRANSFER command to send files to or retrieve files from another user's
virtual reader, printer, or punch queue.
Class G users can manipulate files that they own or originate.
If you do not specify any of the options (SYSTEM, userid, or asterisk "*"), the
default is to transfer or reclaim your own spool files ("*").
A class 0 user can transfer any spool files in the system, regardless of their
ownership or origin.
TRANsfer
[SYSTEM] fPri nter'l (CLass c
)
PUnch
~FORM form (
LReader.j tALL
)
d'] {Re~der } \( CLass. c
[ USeri
~
Prlnter SPOOlld
PUnch
FORM form
ALL
(options)
[To 1 {us~ri
Parameters For Type DATA:
LOC
DL
address instruction
}
{ modname + disp instruction
..
datal inks
where:
ID traceid
is a user-defined, alphanumeric, 1- to 8-character string that identifies the trace.
You can specify the trace ID as a target on the ENABLE, DISABLE, and
DROP operands to activate, deactivate, or delete a particular trace; you can also
use the trace ID as a target for the TRSAVE command, which can alter the
recording options for a trace.
I
I /
I
I
I
Used with the SET operand, trace IDs can be grouped to form trace sets. A
trace ID cannot be a member of more than one trace set at a time.
The trace ID also serves as the default name of the system trace file for the trace
data.
722
VM/XA SP2 CP Command Reference
TRSOURCE ID (Definition Operands)
Trace IDs cannot duplicate any of the following TRSOURCE keywords or any
accepted abbreviation of these keywords: ID, SET, TYPE, ENABLE,
DISABLE, DROP, DISPLAY, and ALL.
SET {traceset }
NULL
is a user-defined, alphanumeric, 1- to 8-character string which identifies a trace
ID as a member of a specific trace set. Creating trace sets allows you to Group
individual traces that are functionally or logically related. You can then specify
traceset as the target of the ENABLE, DISABLE, and DROP operands to
activate, deactivate, or delete all of the trace IDs in traceset.
A trace set can contain trace IDs of more than one type. A trace set of NULL
indicates that the trace ID is not a member of any specific set. Set operations
cannot be performed on the NULL set.
A trace ID cannot be made a member of a set while the trace ID is enabled.
Tracesets cannot duplicate any of the following TRSOURCE keywords or any
accepted abbreviation of these keywords: ID, SET, TYPE, ENABLE,
DISABLE, DROP, DISPLAY, and ALL.
TYPE
{~T
}
DATA
is a system-defined trace type. Each trace-type (10, GT, and DATA) The trace
type determines which parameters are allowed and which are required for the
specified trace ID. The TYPE operand need only be specified once for a given
trace ID but must be specified prior to or concurrently with any type parameters
for that trace ID.
Different trace IDs of the same trace type can be placed in the same or different
trace sets. Trace types cannot be used as targets of the ENABLE, DISABLE,
and DROP operands. Grouping of trace IDs is done with the SET operand, not
the TYPE operand.
type parameters
The parameters and descriptions for the respective trace types are documented in
the following sections:
• "The I/O Trace"
• "The GT Trace" on page 724
• "The DATA Trace" on page 725.
DISPLAY
displays the status for each trace ID or trace set specified on this command. If
you specify DISPLAY, it must be the last operand on the command line.
The 1/0 Trace
The I/O trace allows you to trace all I/O activity on a user-specified real device, a
list of real devices, or range of real devices. The times, channel programs, SCSWs
and data transferred for each I/O operation to the specified devices are made
available for data analysis.
Note: Any or none of the following I/O parameters may be specified in any order
on a TRSOURCE command.
Chapter 2. VM/XA SP CP Commands
723
TRSOURCE ID (Definition Operands)
DEVice
rdevl[-rdev2] [rdev3[-rdev4]] •••
USER
userid }
ALL
{ SYSTEM
IOData
where:
DEVICE rdevl(-rdev2),rdev3(-rdev4)•••
specifies the device number or ranges of device numbers whose I/O activity is to
be traced. The number of devices or ranges that can be traced with one trace ID
of type 10 is limited to 255. DEVICE is the only mandatory parameter before
enabling of trace IDs of type 10. There are no defined defaults for the DEVICE
parameter and any respecification of DEVICE for a previously defined trace
results in new devices being appended to the definition. A device can be a
member of only one enabled trace ID. Attempts to enable the same device from
two or more different trace IDs result in an error message.
USER{,~~d
}
SYSTEM
specifies which user's I/O should be traced. I/O done by the system on behalf of
the user is traced. Tracing can be done only for one user per trace ID and any
respecification of the user parameter replaces the existing definition. The userid
SYSTEM is a valid userid for I/O traces. Only one user's I/O or all I/O is
traced. The default value, ALL, specifies that all I/O to the specified device is
traced for all userids.
IODATA nnnn
specifies how many bytes, if possible, of the transferred data should be traced.
The valid range for nnnn is 0 to 3800 decimal and the default is 0 bytes.
The OT Trace
Traces of type GT allow a guest virtual machine to record events. Guests can use
the monitor call class 10 interface to pass a trace event record to CPo
The parameters for type GT are as follows:
FOR
[USER]
,
userid
VMGROUP sysname
ON LY u1 u2 ••• ux
[ALL
]
: EXCLUDE u1 u2 ••• ux
INCLUDE ul u2 ..• ux
where:
FOR USER userid
specifies the virtual machine can use the monitor call class 10 interface to record
trace events.
724
VM/XA SP2 CP Command Reference
TRSOURCE ID (Definition Operands)
FOR VMGROUP sysname
specifies the virtual machines in the specified VMGROUP can use the monitor
call class 10 interface to record trace events.
ALL
specifies that every virtual machine in the VMGROUP sysname is included in
the defined GT trace. This is the default.
ONLY
specifies that the virtual machines included in the defined GT trace are limited
to userids (ul u2 ... ux).
EXCLUDE
specifies that every virtual machine in the VMGROUP sysname is included in
the defined GT trace except those virtual machines with userids ul u2 ... ux.
INCLUDE
specifies that userid(s) (ul u2 ... ux) should be added to those virtual machines
which currently comprise the VMGROUP sysname in the defined GT trace.
Parameters may be specified after a VMGROUP trace has been defined to allow
further modification of which virtual machines comprise the GT trace. The
VMGROUP trace is identified using the ID parameter. These modifications can be
entered at any time; the trace specified does not need to be disabled.
The DATA Trace
Trace type DATA allows the user to define trace entries dynamically to record
execution of most code paths in CPo The LOC parameter specifies which
instruction, when executed, triggers recording of information. Data link parameters
define what information is collected when the trace begins.
Note: Any or none of the following DATA parameters may be specified on a
TRSOURCE command.
LOC
DL
address instruction
}
{ modname + disp instruction
datal inks
where:
LOC address
specifies the virtual address in the CP nucleus that identifies the trace point at
which the data is to be collected.
LOC modname + disp
specifies the CP module name and displacement into that module of the trace
point at which the data is to be collected. If the module is written in a
higher-level language, then an 8-character module name must be supplied.
Refer to 7 on page 728 for a list of restricted locations.
instruction
is the hexadecimal representation of the contents of storage at the specified trace
point. Matching the specified instruction with the contents of storage verifies
that the trace point is at the intended location in the CP nucleus. The
instruction supplied must be at least as long as the instruction to be verified.
Only that instruction is verified and any extraneous hexadecimal data is ignored.
If the verification fails then the LOC parameters are not accepted and a message
is sent to the user who entered the command.
Chapter 2. VMjXA SP CP Commands
725
TRSOURCE ID (Definition Operands)
DL datalinks
specify what data should be traced. There are six character groups that can be
used to make up a data link string;
1. Constants: substrings consisting of 0-9, A-F.
2. Registers: substrings beginning with G (for general purpose registers) or X
(for control registers) followed by a constant less than decimal 16.
3. Indirection: a percentage sign (0/0). Indirection means that the contents of
an address or register are used instead of the address or register itself.
4. Arithmetic: a plus sign (+ ) or a minus sign (-).
5. Length delimiter: a period (.).
6. Mnemonic marker: an equals sign (=).
These data link strings define how to combine constants and indirection to reach
the data to be traced. The following is a Backus/Naur definition of the syntax
of data link strings:
I = I NULL
I I .
::=
::=
.
I
I 0•.. FFFFFFFF I %
::= I % I
::= + I - I + I -
::=
::= 0••• F00
::= G:
::= G
::= 0••. 15
I X:
I X
I 0•.. 9,
A, B, C, D, E, F
::= 0•.• 7FFF
.. =
(user generated 1-to 8-character
alphanumeric string)
Data can be identified either by using the current register contents as pointers or
by knowing the reallocation of the data to be traced. Data links define the
procedure to be used to locate the desired data.
General Usage Notes
The following list contains the syntax rules that apply to the TRSOURCE
command:
1. If you use the ID operand to define a trace ID, it must be the first operand on
the command line.
2. While specific type-dependent operands are optional on the TRSOURCE
command, certain type-dependent operands may be required for a trace ID
before it can be enabled. Refer to the description of the specific trace types to
726
VM/XA SP2 CP Command Reference
TRSOURCE ID (Definition Operands)
determine which operands are required before a trace ID of that trace type can
be enabled.
3. The TYPE operand, if used, must directly precede any type dependent operands.
4. All type-dependent operands must be contiguous. The order depends on the
requirements of the trace type.
1/0 Trace Usage Notes
1. An I/O trace may be defined for a nonexistent device (that is, a device that has
no RDEVICE entry in module HCPRIO). If a trace with only such devices is
enabled, message HCPTXI477I is issued:
Traceid (TRACE ID) not enabled;
incomplete definition
Note, however, that a trace with a nonexistent device and a device defined in
HCPRIO (whether the latter be online or offline) can be enabled, and the
response to QUERY TRSOURCE will indicate that a trace for the nonexistent
device is activated.
2. If and when a device is subject to I/O assist, then I/O activity to that device is
not traced.
3. System trace files reside on system spool space. Tracing I/O to system spool
space causes trace recursion and may cause severe performance degradation,
especially for large values of 10DATA.
Type GT Usage Notes
1. Specification of a TYPE GT trace for a VMGROUP makes it easier to control
and define guest traces for the members of a group.
A trace TYPE GT for a VMGROUP is used to sift TRSOURCE definition and
TRSAVE destination information from the VMGROUP to the virtual machines
that are members of the VMGROUP. (The sysname specified on the
VMGROUP parameter is the name of the named saved system which was IPLed
by its members.)
2. Multiple TYPE GT traces may be defined for each virtual machine. Only one
TYPE GT trace may be enabled for each virtual machine.
3. A TYPE GT USER trace for a virtual machine that has been defined before the
virtual machine becomes a member of a VMGROUP for which a TYPE GT
trace is enabled is automatically disabled when the virtual machine becomes a
member of the VMGROUP. The USER TYPE GT trace remains in its disabled
state after the virtual machine either severs from the VMGROUP, is removed
from the VMGROUP due to a subsequent TRSOURCE command that excludes
the virtual machine userid from the VMGROUP trace, or the VMGROUP trace
is disabled. A TRSOURCE ENABLE command is required to re-enable the
USER TYPE GT trace.
4. If you need to redefine the destination of the trace data where trace data is to be
placed for one of the members of a VMGROUP trace, you must exclude the
virtual machine's userid from the VMGROUP trace and then enable a TYPE
GT USER trace containing the desired destination information for the virtual
machine.
5. A message is sent to the user who defined a USER TYPE GT trace whenever a
defined and enabled USER TYPE GT trace is disabled due to VMGROUP
TYPE GT trace activity for a VMGROUP member.
Chapter 2. VMjXA SP CP Commands
727
TRSOURCE ID (Definition Operands)
6. A message is sent to the user who defined a USER TYPE GT trace whenever a
virtual machine that is a member of a VMGROUP trace is excluded from the
VMGROUP by a subsequent TRSOURCE command. This user is also notified
if the virtual machine was a member of a VMGROUP for which tracing was
disabled.
Type DATA Usage Notes
1. If a trace point is defined in a pageable module then the module is automatically
locked into storage while the trace is enabled.
2. Data collection for trace IDs of trace type DATA occurs before execution of the
overlaid instruction. If no data links are specified for the trace ID, a trace entry
is created in the system trace file, but no data is collected.
3. Usually, the total amount of data collected in a trace record cannot exceed 4000
decimal bytes. To calculate the exact amount of data that can be collected in a
trace record, use the following formula:
(3 times the number of data links specified)
+
(the total lengths of the data links)
+ (the total number of bytes to be collected)
SUM
SUM must be less than or equal to 4024 (decimal).
Also, the maximum number of data links allowed for any given trace ID is 255.
The maximum data link length is 250.
4. DATA traces should always be placed at instruction boundaries. The
TRSOURCE command can only verify that the specified location is on a
halfword boundary and that it contains a valid operation code; if these
conditions are not met, the command fails with an error message.
If the verification is successful, the TRSOURCE command overlays the specified
location with a data trace SVC instruction. If the location is not an instruction
boundary, this can cause unpredictable system results, including a probable
system failure.
5. As there is ho way of deleting a data link from a trace definition, if an error is
made while entering a data link the entire trace must be dropped and redefined
to remove the data link from the definition. For this reason, it is recommended
that the definitions of commonly used type DATA traces be saved in EXECs.
Locations can be changed for defined but disabled DATA traces.
6. Specification of extra data links for a defined but disabled trace result in an
addition to the definition.
7. The following is a list of restricted locations for the definition of trace points.
These locations are restricted because enabling DATA traces in them would
cause recursion or interlocks. If an attempt is made to define or enable a trace
that violates one of these restrictions then the command is rejected and a
message indicating invalid location for tracing is issued.
a. Locations within the following modules:
HCPABN, HCPBMS, HCPSTK, HCPSVC, HCPTSR, HCPTSV,
HCPTXD, HCPTXE, HCPTXG, HCPTXI, HCPTXJ, HCPTXL, HCPTXP,
HCPTXR.
Note: HCPSTK, HCPSVC, HCPABN, and HCPRUN are only partially
728
VM/XA SP2 CP Command Reference
TRSOURCE ID (Definition Operands)
b. Locations not on halfword boundaries.
c. Locations not mapped in CP virtual storage.
d. Locations of already enabled DATA traces. Note that multiple DATA
traces may be defined at the same location but only one trace at a time may
be enabled at that location.
8. In addition to the modules that would definitely cause recursive situations, there
exist modules that are invoked after collection of a page worth of data. No
restrictions prevent users from placing traces in these modules. However, if the
records produced by these traces are one page in length, this causes recursion.
Therefore it is recommended that records defined for any code path within
system trace file (including paging and spooling code paths and some code paths
in lOS) be kept under a page in length.
9. Users should avoid placing traces in code paths that hold spin locks as this
situation increases the path length under the spin lock and seriously decreases
system performance.
10. Users should avoid placing data traces on instructions that are targets of
EXECUTE instructions; otherwise, unpredictable results may occur.
11. If interpretation of a data link string during execution results in a negative or
invalid address, a record is added to the system trace file to indicate that the
error occurred. However, there will be no external indication that the error
occurred.
12. To trace data located in the absolute page zero, reverse prefixing must be used.
When the value of the prefix register is added to the datalink string, values are
obtained from absolute page zero. On the other hand, if the address calculated
from a data link is less than hexadecimal 1000, the value recorded is obtained
from the prefix page of the processor in which the data trace event occurs.
Chapter 2. VM/XA SP CP Commands
729
TRSOURCE ID (Definition Operands)
Examples of Data Link Usage: The following examples are based on the status of
the registers and the storage pictured below.
Registers
+--------+
G1 1000010001
+--------+
Main Storage
4000 00005008 00000000 0000A000 00000000
5000 0000A004 00001144 00005555 00000000
6000 00000000 00000000 0000A000 00000000
+--------+
G4 1000040001
+--------+
+--------+
G5 1000050001
+--------+
+--------+--------Datalink
--------
A000 00008000 0000C000 0000D000 0000E000
8000 C4CIE3C3 E3D9CID7 11110000 00000000
C000 C4C1E3C3 E3D9CID7 FFFF0000 00000000
D000 DDDDDDDD 00000000 00000000 00000000
G6 1000060001
Ex.
1)
2)
3)
4)
5)
6)
7)
8)
9)
10)
11)
12)
13)
14)
4000
4000%
5000%.8
G5
G5.4
G5+4
G5+4%
G5+G6+8%
G5%%.C
G4:6
G6+A.2
G4+8%+4%.A
G5%+4
G5%+4%
Data Collected
00005008
00005555
0000C000
00005000
0000A004
00001144
contents
contents
C4CIE3C3
00004000
A000
C4CIE3C3
0000D000
DDDDDDDD
0000D000
of 1144
of 11110000
E3D9CID7 FFFF0000
00005000 00006000
E3D9CID7
FFFF
Note: Registers, when specified alone as in example 4 above, do not default to an
indirection and a length of 4, as other data link values do. In this case, the
data collected is simply the contents of the register.
730
VM/XA SP2 CP Command Reference
UNDEDICATE
UNDEDICATE
Privilege Class: A
Use this command to remove a real processor from a user's exclusive use.
UNDEDicate
CPU CPUaddrJ
[ CPU ALL
I
where:
USER
{~rid}
is the user whose virtual CPU will be undedicated from a real processor. If the
USER operand is specified then either a userid or "*,, must be used. If the
USER operand is not specified, then the V = R user is the default.
CPU cpuaddr
is the defined virtual CPU address in a virtual machine configuration from
which a real processor, if it was dedicated, will become undedicated.
CPU ALL
will undedicate every dedicated real processor from the corresponding virtual
CPU in a virtual machine configuration. If a CPU is not specified, CPU ALL is
the default.
Usage Notes
1. The default for the UNDEDICATE command is CPU ALL for the V = R
userid. An attempt will be made to undedicate every real processor from each
virtual CPU defined in the V = R virtual machine configuration.
2. If UNDEDICATE USER userid CPU ALL is specified, all the currently defined
virtual processors for the userid are affected. Also, if the userid is running a
V = R machine with automatic dedication in effect, then the command disables
automatic dedication for the V = R machine. To avoid this, use UNDEDICATE
USER userid CPU cpuaddr instead.
Responses
COMMAND COMPLETE
is the response issued upon the successful completion of the UNDEDICATE CPU
command having specified a CPU address in the command line.
Chapter 2. VM/XA SP CP Commands
731
UNLOCK
UNLOCK
Privilege Class: A
Use the UNLOCK command to unlock page frames previously locked by a LOCK
command.
I
UNLOCK
userid
*
SYSTEM
~
pagel pagen
pagel pagen
pagel pagen
symbol
VIRT=REAL
V=R
, RI0370
J
where:
userid
is the user identification of the virtual machine previously specified in a CP
LOCK command. If you are unlocking your own virtual pages, you may specify
userid as an asterisk (*).
SYSTEM
unlocks a previously locked pageable CP nucleus page.
pagel
is the hexadecimal value of the first page to be unlocked.
pagen
is the hexadecimal value of the last page to be unlocked.
symbol
causes the page containing the system .symbol to be unlocked, if the symbol is
contained within the CP pageable area. No action is taken if the symbol is
contained within the CP resident nucleus or if the page has not been locked by
the CP LOCK command.
VIRT=REAL
V=R
releases for normal paging use all the page frames normally reserved for
preferred virtual machines if the area is not occupied by a preferred virtual
machine. Once you release the virtual = real area, you can not reactivate it to
run another preferred virtual machine until you re-IPL VMjXA SP.
RIO 370
requests the release, for normal paging use, of the RI0370 frames reserved at
system generation for DIAGNOSE X 198 I . (Only programs running in 24-bit
addressing mode can use RI0370 frames.) If any RI0370 frames are in use, the
area is not released. Once released, the RI0370 area can be reinstated only by
re-IPLing VMjXA SP.
732
VM/XA SP2 CP Command Reference
UNLOCK
Usage Notes
1. Only specify the page numbers for the fields "pagel" and "pagen." For example,
to unlock USERA's virtual storage locations X 112000 1 to X '2CFFF I , issue the
following command:
UNLOCK USERA 12 2C
2. Exercise caution when you issue the UNLOCK symbol command. The page
containing the symbol may also contain other symbols that have been processed
using the CP LOCK command. A single UNLOCK command unlocks all of the
symbols locked in that page, even if you locked them using multiple CP LOCK
commands.
3. Unlocking V = R page frames unlocks the entire V = R region. This area is
unlocked only if no V = R or V = F guests are logged on.
4. Use the QUERY FRAMES command to determine the status of the RI0370
storage area. If (a) the LOCKRIO count is zero, (b) your program is running in
24-bit addressing mode, and (c) further lock requests are not issued, you can
issue UNLOCK RI0370.
5. Pages locked by programs running in 3l-bit addressing mode using DIAGNOSE
code X ' 98 1 do not use RI0370 frames, so that real I/O is available to 3l-bit
addressing mode programs whether or not the RI0370 area exists.
6. The LOCK command issued for a userid's virtual page or pages operates
independently of the DIAGNOSE X 198 1 page locking facility. Pages locked by
command cannot be unlocked by DIAGNOSE X ' 98 1, nor can REAL I/O pages
locked by DIAGNOSE X 198 1 be unlocked by command.
7. If you issue LOCK to lock a page in a shared segment and do not issue an
UNLOCK, the page is unlocked when the last user of the shared segment
releases the storage with the LOGOFF command or another command that
clears storage.
8. If the UNLOCK command is issued for an address range that includes all or
part of the RI0370 area, the command does not execute for those frames. No
message or response is issued to indicate this. The RI0370 frames remain
locked, and possibly in use, as they were before the command was issued. To
unlock this storage, use the RI0370 option of the UNLOCK command when
the entire RI0370 area is not in use.
Responses
COMMAND COMPLETE
indicates the successful completion of the command. This response is displayed even
if you did not have any pages locked in storage.
Migration Notes
VMISP HPO
1. In VM/XA SP, you can specify a CP system symbol to unlock the page
containing that symbol.
2. In VM/XA SP, the RI0370 parameter on the SYSSTORE macro is used to
create the RI0370 area.
Chapter 2. VM/XA SP CP Commands
733
VARY
VARY
Privilege Class: B
Use the VARY command to make a device or processor usable or unusable by the
control program or a user.
VARY
I
ONl i ne } jrdev
{ OFfline
rdev rdev •••
rdev-rdev
PROCessor nn
where:
ONLINE
makes available a device or devices previously offline.
OFFLINE
makes unavailable the device or devices.
rdev
rdev rdev ••.
rdev-rdev
is the real device number of the device to be varied online or offline. You may
specify a list or range of devices. If you specify a range of real device numbers,
all valid devices in the range, including the first and last devices you specified,
will be varied online or offline. The maximum number of devices allowed in a
range is 256.
PROCESSOR nn
is the processor to be made available or unavailable. The value of nn is the
processor address (hexadecimal value from 00 through 3F) established when the
processor is installed.
Usage Notes
1. If the device you specify is a 2305, the address you indicate must be for the first
of eight "exposures;" that is address xxxO or xxx8. If the device you specify is a
3350 Model 11 or Model 21, the address you indicate must be the first address
(or base path address) of its multi-exposure addresses~'
2. If you specify a list or range of devices, an attempt is made to VARY them
online or offline regardless of whether an error is encountered with anyone of
the specified devices. An error message is issued for every device that cannot be
varied online or offline. A summary message is issued to indicate the number of
devices that were successfully varied online or offiine.
3. The VARY PROCESSOR command will not affect the connection of a Vector
Facility associated with the varied real processor. If the associated Vector
Facility is not connected at the time a VARY ONLINE PROCESSOR
command is issued, it will still not be connected after the VARY command has
completed. Conversely, if a Vector Facility is connected at the time that a
VARY OFFLINE PROCESSOR command is issued, it will remain connected to
its associated processor even after that processor is fully varied offline.
734
VMjXA SP2 CP Command Reference
VARY
4. When a VARY PROCESSOR or VARY VECTOR command affects a processor
dedicated to a preferred-guest virtual CPU, rededication is attempted to:
• Keep real processors with Vector Facilities dedicated to preferred-guest
virtual CPUs with Vector Facilities defined
• Keep real processors without Vector Facilities dedicated to preferred-guest
virtual CPUs with no Vector Facilities defined.
Dedication will occur whether or not the above may be accomplished.
5. When a processor is successfully varied online to a system with a V = R virtual
machine, dedication will occur to an available virtual CPU if automatic
dedication is enabled. The above goals are attempted (that is, match real VF to
virtual VF or no real VF to no virtual VF); however, dedication will occur
whether they can be met.
6. If a virtual CPU with a Vector Facility defined is left without a real Vector
Facility available, subsequent vector instructions will result in one of two guest
interruptions:
• A vector operation exception is presented to those guests who had not been
previously informed by CP that a real Vector Facility was available for their
use
• A Vector Facility failure machine check is presented to those guests who had
been informed by CP that a real Vector Facility was available for their use.
These situations can occur as a result of VARY PROCESSOR, VARY
VECTOR, or changes in dedication. The system operator will always receive a
warning message when such a circumstance arises.
Responses
rdev VARIED {ONLINE }
OFFLINE
indicates that the specified device is now online or offline as you requested in the
command.
rdev-rdev VARIED {ONLINE }
OFFLINE
indicates that all exposures of a multiple exposure device are now online or offline as
requested in the command.
type rdev IS ALREADY {ONLINE }
OFFLINE
indicates that the specified device is already online or offline.
rdev-rdev ALREADY {ONLINE }
OFFLINE
indicates that the specified multiple exposure device is already online or offline.
nnn DEVICE{S) SPECIFIED; nnn DEVICE(S) SUCCESSFULLY VARIED {ONLINE ,}
OFFLINE
is a summary response indicating how many devices were successfully varied online
or offline.
Chapter 2. VM/XA SP CP Commands
735
VARY
PROCESSOR
nn
ONLINE
indicates that the specified processor is now online and operational.
PROCESSOR
nn
OFFLINE
indicates that the specified processor is now offline and not operational.
VECTOR FACILITY
nn
ONLINE
indicates that the Vector Facility nn is now available or online.
VECTOR FACILITY
nn
OFFLINE
indicates that the Vector Facility nn is now unavailable for use or omine.
Migration Notes
VMISPHPO
1. VM/XA SP does not support the FORCE, VPHY, and VLOG options.
2. The VM/XA SP response provides an additional line indicating the number of
devices successfully varied on line.
3. VM/XA SP does not support logical printers.
4. VMjXA SP limits the range of devices varied to 256.
5. VMjXA SP allows you to spell out the entire operand PROCESSOR.
736
VM/XA SP2 CP Command Reference
VARY PATH
VARY PATH
Privilege Class: B
Use the VARY PATH command to make a path to one or more devices logically
available or logically unavailable for use by the system.
VARY
{ONline} PATH
yy
[TO ]
\~~:~ rdev rdev •••
rdev-rdev
ALL
{OFfline} PATH
yy
l
l
[FROM] \rdev
rdev rdev rdev •••
rdev-rdev
ALL
where:
yy
is the channel path ID of the path that is to become logically available or
logically unavailable for use by the system to communicate with the specified
device or devices.
Note: If the specified path is the last available path to the specified device, CP
will attempt to vary the device offline. If the device cannot be varied
offline, the VARY PATH OFFLINE request will be denied.
rdev
rdev rdev •.•
rdev-rdev
is the real device number of the devices to whom the specified path will be made
logically available or logically unavailable. You may specify a single device, a
list, or a range of devices. If you specify a range of real device numbers, all the
valid devices in the range, including the first and last devices you specified, will
be processed. The maximum number of devices allowed in a range is 256.
ALL
specifies that the path will be made logically available or logically unavailable to
all real devices that have access to it.
Usage Notes
1. The VARY PATH command does not invoke the service processor or cause any
hardware functions to be performed.
2. If you specify a list or range· of devices, an attempt is made to vary the specified
path online or offline to each device. An error message is issued for every device
for which the specified path cannot be varied online or offline. Check examples
after these usage notes.
Chapter 2. VMjXA SP CP Commands
737
VARY PATH
3. Warning: Use care when varying offline a path leading to a 370/XA guest's
dedicated device. If the 370-XA guest is using RESERVE/RELEASE to that
device, you may vary its reserved path offline, causing that system to become
hung.
To determine if RESERVE/RELEASE is allowable, look at the SHARED
option on the RDEVICE statement of the HCPRIO block or issue the QUERY
DASD command and look at that SHARED setting.
4. When varying a path offline:
• Vary the path offline from the guest operating system if the guest (such as
MVS/XA) supports a VARY PATH command.
• Vary the path offline from the host system (VM/XA SP).
5. When varying a path online:
• Make the path physically available.
• Vary the path online to the host (VMjXA SP).
• Vary the path online to the guest operating system if the guest supports a
VARY PATH command.
Examples
Enter the following command to make path C2 leading to device 140 available to
that device.
VARY ON PATH C2 TO 140
A typical response may appear as follows:
VARY PATH C2 ONLINE COMMAND INITIATED
VARY PATH C2 ONLINE COMMAND COMPLETE
Enter the following command to make path C2 unavailable to devices 0190 through
0197.
VARY OFF PATH C2 FROM 0190-0197
A typical response may appear as follows:
VARY PATH C2 OFFLINE COMMAND INITIATED
PATH C2 NOT VARIED OFFLINE FROM DEVICE 0192; LAST PATH TO DEVICE
VARY PATH C2 OFFLINE COMMAND COMPLETE
Response 1: Vary Initiated
VARY PATH
YY
{ONLINE .,} COMMAND INITIATED
OFFLINE
is the result of issuing the VARY PATH command and shows that the specified
VARY PATH request has been initiated.
where:
yy
is the path requested to be varied online or offline.
738
VMjXA SP2 CP Command Reference
VARY PATH
Response 2: Vary Complete
VARY PATH YY {ONLINE } COMMAND COMPLETE
OFFLINE
indicates that the VARY PATH processing is complete. An attempt was made to
make the specified path available or unavailable (whichever was specified - online or
offline) to each device specified. While command processing is now complete, check
carefully any console messages which might indicate that not all processing was
successful.
where:
yy
is the path requested to be varied online or offline.
Response 3: Path Not Operational
PATH YY NOT VARIED ONLINE TO
DEVICE rdev; PATH NOT OPERATIONAL
indicates that the specified path has not been made available (varied online) for the
specified device because the path is not operational. Make the path operational and
then retry the command.
where:
yy
is the path not made operational.
rdev
is the real device number.
Response 4: Last Path to Device
PATH yy NOT VARIED OFFLINE FROM DEVICE rdev; LAST PATH TO DEVICE
indicates that the specified logical path is the last path to the specified device. CP
tried unsuccessfully to vary the device offline. Use the VARY command to vary the
device offline, and then retry the VARY PATH command.
where:
yy
is the path which CP tried to make unavailable (vary offline) to the specified
device.
rdev
is the real device number.
Chapter 2. VM/XA SP CP Commands
739
VARY PATH
Response 5: Invalid Channel Path ID
PATH YY NOT VARIED {ONLINE TO } DEVICE rdev; PATH DOES NOT EXIST TO THE DEVICE
OFFLINE FROM
indicates that the specified path was not installed for the specified device.
where:
yy
is the path requested to be made logically available (varied online) or
unavailable (varied offline) to the specified device.
rdev
is the real device number.
Response 6: Device Reserve Held
PATH yy NOT VARIED ONLINE FROM DEVICE rdev; RESERVED PATH
indicates that the specified path was not taken offline because there is a reserved
allegiance to that path.
where:
yy
is the number for the path not taken offline.
rdev
is the real device number.
Response 7: First Path:
FIRST PATH yy TO type rdev VARIED ONLINE; type rdev VARIED ONLINE
indicates that the device was previously offline because all of its channel paths have
been varied offline. The path requested to be varied online was the first path to the
device to be varied online, and therefore the device as well as the path was varied
online.
where:
yy
is the path that was requested to be made available (varied online) to the
specified device.
type
is the device type (for example, DASD or TAPE).
rdev
is the real device number.
740
VM/XA SP2 CP Command Reference
VARY PATH
Response 8: Last Path:
LAST PATH yy TO type rdev VARIED OFFLINE; type rdev VARIED OFFLINE
indicates that the path requested to be varied offline was the last path to the device
and therefore the device (and the path) were varied offline.
where:
yy
is the path that was requested to be made unavailable (varied offline) to the
specified device.
type
is the device type (for example, DASD or TAPE).
rdev
is the real device number.
Response 9: No Online Paths to Device:
type rdev CANNOT BE VARIED ONLINE; DEVICE HAS NO ONLINE CHANNEL PATHS
indicates that the device specified to be varied online has no online (logically
available) channel paths.
where:
type
is the device type (for example, DASD or TAPE).
rdev
is the real device number.
Response 10: Pending Reserve
PATH yy NOT VARIED OFFLINE FROM DEVICE rdev;,DEVICE RESERVE PENDING
indicates that the path requested to be varied offline could not be varied offline
because a reserve request was pending to that device. Check the other system
sharing this device; it may be hung, holding the reserve, thus prohibiting CP's
reserve request from being granted.
where:
yy
is the number of the path not varied offline because of a pending reserve request.
rdev
is the real device number.
Chapter 2. VM/XA SP CP Commands
741
VARY PATH
Response 11: Path Not Physically Available
PATH yy NOT VARIED {ONLINE TO } DEVICE rdev; PATH NOT AVAILABLE TO THE DEVICE
OFFLINE FROM
indicates that the path is not physically available to the device. Ensure that the path
is switched in and varied online from the system's service console.
where:
yy
is the number of the path not physically available to the device.
rdev
is the real device number.
Response 12: Path Already Varied Offline
PATH
yy
HAS ALREADY BEEN VARIED OFFLINE FOR DEVICE rdev
indicates that the system operator has already varied the path offline.
yy
is the path that was both requested to be and then was varied offline.
rdev
is the real device number.
Response 13: Path Already Online
PATH yy ALREADY ONLINE FOR DEVICE rdev
indicates that the path is already online.
yy
is the number of the path already online.
rdev
is the real device number.
742
VM/XA SP2 CP Command Reference
VARY VECTOR
VARY VECTOR
Privilege Class: B
Use the VARY VECTOR command to make a device previously online or offline
either available or unavailable.
This command does not change the status of the associated CPU. If the CPU is
offline, the Vector Facility cannot be brought online.
Similarly, the VARY PROCESSORS command does not change the connection
status of the vector facility. If the facility was connected to the CPU, it becomes
available for use after the CPU has been configured; if it was not connected, it
remains in that state after the command has been executed.
I VARY
ONl i ne } VECtor
{ OFfline
nn
where:
ONLINE
makes a device(s) previously offline available.
OFFLINE
makes the device(s) unavailable.
Vector nn
is the Vector Facility associated with processor nn.
Usage Notes
1. A Vector Facility (VF) is permanently associated with single CPU and can be
used only by the associated CPU. The address of the Vector Facility is the same
as that of the associated CPU.
2. A Vector Facility that is connected to a real dedicated processor may be varied
offline. If the virtual CPU dedicated to the processor with the varied offline VF
already has a virtual VF, subsequent use of the virtual VF will result in virtual
VF failure machine checks. If an attempt is made to vary off a dedicated VF,
the system will issue an error message.
3. If the last nondedicated Vector Facility is being taken by a VARY OFFLINE
command, the system will issue a warning message. Any V=V guest which has
a virtual VF defined when the last real VF becomes unavailable will
subsequently receive a VF failure machine check if it issues any vector
instructions. V = V guests which define virtual Vector Facilities after the last
real vector has gone away will receive a warning message.
Chapter 2. VM/XA SP CP Commands
743
VARY VECTOR
Response 1
VECTOR FACILITY nn OFFLINE
if the Vector Facility is now unavailable.
Response 2
VECTOR FACILITY ONLINE
if the Vector Facility is now available.
744
VMjXA SP2 CP Command Reference
VMDUMP
VMDUMP
Privilege Class: G
Use the VMDUMP command to produce a dump of all or selected pages of the
storage that appears real to your virtual machine (second-level storage). The
resulting dump is in a format that can be used by the dump viewing facility. The
dump will include selected information for up to eight CPUs in your configuration.
VMDurnp
heX10C1][{._}
[heX10C2
]]]
.:
END
[[Q.
{.} [~~~ecount] . [
[
FORMAT {vrntype}.] [DeSS]
FILE
DSS
[XA]
TO ~
TO userid
SYSTEM
]
[*durnpid]
Note: You can specify multiple address ranges on a single VMDUMP command.
The ranges can be in any order. However, you can assign only one dump
identifier (*dumpid) per command.
where:
hexlocl
o
is the starting virtual storage location to be dumped. The address hexlocl may
be one to eight hexadecimal digits; leading zeros are optional. If the value you
specify for hexlocl is not a multiple of 4K, VM/XA SP rounds down the value
to a 4K boundary. If you omit the hexlocl operand, the default is zero.
-}heXloc2
{ :: END
is the ending address in the range of virtual storage locations to be dumped.
The address hexloc2 may be one to eight hexadecimal digits; leading zeros are
optional. The value you specify for hexloc2 must be equal to or greater than
hexloc1, and within the virtual storage size defined for your virtual machine. If
the value you specify for hexloc2 is equal to the starting location, VMjXA SP
dumps the single page of storage containing that location. If the value you
specify for hexloc2 is not equal to the starting location and is not a multiple of
4K, VM/XA SP rounds up the value to the next 4K boundary. Specify END to
dump the remaining contents of storage.
If you specify only a range delimiter ('-' or ':') and omit either hexloc2 or END,
END is the default. However, if you omit both the range delimiter and hexloc2
or END, VM/XA SP dumps the single page of storage starting at hexlocl. If
you omit both hexlocl and hexloc2 or END, hexlocl defaults to zero, hexloc2
defaults to END, and VM/XA SP dumps the entire contents of your virtual
machine's storage. (Note that in this case specification of the range delimiter is
irrelevant. )
{.} bytecount
END
is a hexadecimal number indicating the number of bytes of storage to be
dumped, starting with the first byte at hexlocl. The value you specify for
bytecount must be at least one and can be from one to eight hexadecimal digits;
leading zeros are optional. The ending storage address reSUlting from the
Chapter 2. VMjXA SP CP Commands
745
VMDUMP
specified bytecount must be within the virtual storage size defined for your
virtual machine. If the ending storage address is not a multiple of 4K, VM/XA
SP rounds up the value to the next 4K boundary. Specify END to dump the
remaining contents of storage.
If you specify only the range delimiter ('.') and omit either bytecount or END,
END is the default. However, if you omit both the range delimiter and
bytecount or END, VM/XA SP dumps the single page of storage starting at
hexlocl. If you omit both hexlocl and bytecount or END, hexlocl defaults to
zero, bytecount defaults to END, and VM/XA SP dumps the entire contents of
your virtual machine's storage. (Note that in this case specification of the range
delimiter is irrelevant.)
TO *
TO userid
transfers the dump to the virtual card reader of the specified userid. If you enter
an asterisk (*) after TO, or do not specify the TO operand at all, VM/XA SP
sends the dump to the virtual card reader of the virtual machine from which you
issued the Vr-v1D Ur-vIP com.m.and.
SYSTEM
transfers the dump to the virtual card reader of the userid specified on the
SYSDUMP macro in HCPSYS. (This is the userid designated to receive any CP
abend dumps. For further details, refer to the description of the SYSDUMP
macro in VM/XA SP Planning and Administration.)
FORMAT
{vmtype}
FILE
specifies the type of virtual machine being dumped. For vmtype, specify the Ito 8-character name of the system that had been running in the virtual machine
(for example, CMS, RSCSNET, or PVM). If you omit the FORMAT operand,
the default is FILE.
The dump viewing facility uses the FORMAT operand to identify what type of
system or virtual machine was dumped.
DCSS
DSS
specifies that CP take a dump of all the user's discontiguous saved segments.
XA
specifies that the dump produced should be in the VM/XA SP dump format. If
you do not specify XA, VM/XA SP uses the mode, the storage size of your
virtual machine, and the number of virtual CPU s defined to determine the
format of the dump. For a virtual machine running in System/370 uniprocessor
mode with 16 megabytes or less of storage, VM/XA SP produces a dump in the
same format as the VM/SP (370) VMDUMP command. For all other virtual
machines (System/370 mode virtual machines with more than 16 megabytes of
storage, all 370-XA mode machines, and all virtual MP or AP machines), the
dump produced is in the VM/XA SP dump format.
*dumpid
is a 1- to 100-character identifier (including any imbedded blanks and special
characters) that VM/XA SP assigns to the dump. When specifying the dumpid,
you must precede it with an asterisk (*). Note that VM/XA SP eliminates any
blanks between the asterisk and the first nonblank character of the dumpid. If
you specify a dumpid that is more than 100 characters in length after the blanks
following the asterisk are eliminated, VM/XA SP truncates it on the right to a
746
VM/XA SP2 CP Command Reference
VMDUMP
length of 100 characters. If specified, the dumpid must be the last operand on
the command line.
Usage Notes
1. With the exception of *dumpid, you may specify the operands in any order. If
you specify *dumpid, it must be the last operand on the command line.
2. When you issue the VMDUMP command, the dump that results consists of
4K-byte pages of storage written to a reader spool file. You must dump at least
one 4K-byte page. In addition, VMjXA SP dumps the following information
(not necessarily in this order):
• Program status word (PSW)
• General registers
• Control registers
• Floating point registers
• Vector registers
• Storage keys of dumped storage pages
• TOD clock
• TOD clock comparator
• CPU timer
• Prefix register
• Prefix page.
You can view the dump interactively using the dump viewing facility. For more
information on viewing the dump produced by the VMDUMP command, see
VMjXA SP Dump Viewing Facility Operation Guide and Reference.
3. For virtual machines running in Systemj370 uniprocessor mode with 16
megabytes or less of virtual storage, the VMjXA SP VMDUMP command
provides full compatibility with the VMjSP (370) VMDUMP command. For
these virtual machines, the dump produced by the VMD UMP command can be
either in the format of a VMjXA SP CP abend or stand-alone dump, or in the
format produced by the VMjSP (370) VMDUMP command. For virtual
machines running in Systemj370 mode with more than 16 megabytes of virtual
storage, for all 370-XA mode virtual machines, and for all virtual MP or AP
machines, the VMDUMP command produces only a dump in VMjXA SP dump
format. For more information, see the description of the XA operand above.
For a description of the VMjSP (370) VMDUMP format, see VMjXA SP
Diagnosis Reference - CP (Volume 1).
4. After VMjXA SP has written the dump to a reader spool file, you can use the
CMS DUMPLOAD command to load it from the spool file into a CMS file.
You can also use the DUMPLOAD command to print a hexadecimal dump
(with EBCDIC translation) from a virtual machine dump that has already been
loaded into a CMS file. For a complete description of the DUMPLOAD
command, see VMjXA SP CMS Command Reference.
5. In general, use the VMDUMP command to create dump files that can be used
with the VMjXA SP dump viewing facility, and use the DUMP command to
create dumps that you intend to read without the aid of the dump viewing
facility. For more information, see VMjXA SP Virtual Machine Operation.
Chapter 2. VMjXA SP CP Commands
747
VMDUMP
6. For certain programs running in virtual machines, the dump viewing facility
provides a special dump processing format. The dump viewing facility identifies
these programs by checking the file type of the reader spool file created by
VMDUMP. The filetype is an assigned name that you should specify for
vmtype on the FORMAT operand when dumping a virtual machine in which
one of these programs is running. The IBM -defined programs and their assigned
names are:
Program:
Assigned name:
Remote Spooling Communication
Subsystem (RSCS) Networking
Program Product
RSCSNET
VM!Pass-Through Facility
Program Product
PVM
Conversational monitor system
(CMS)
CMS
There may be additional assigned names, unique to your installation, for
programs that are a part of your system. Ask your system programmer for a
complete list of FORMAT names.
7. If you specify TO SYSTEM, VMjXA SP sends the dump file to the userid of
SYSTEM. However, if you specify only SYSTEM, VMjXA SP sends the dump
file to the userid designated at your installation to receive dumps.
8. Vector registers are dumped for XA format dumps only. You can ensure that
the VMDUMP you create will be XA format and will include the vector
registers (if any) by specifying "XA" on the command line.
Responses
COMMAND COMPLETE
is the response issued by VMjXA SP when it has completed VMDUMP command
processing.
Migration Notes
VMISP HPO: VMjXA SP supports the additional operands DCSS and XA.
748
VMjXA SP2 CP Command Reference
WARNING
WARNING
Privilege Classes: A, B, or C
Use the WARNING command to transmit high priority messages to a specified user
or to all users. The WARNING does not wait for input operations at the terminal to
complete, but breaks in on the line currently being displayed and sends the message
immediately (unless the CP SET WNG OFF command was previously issued for the
virtual machine).
Warning
Wng
!
·1
~perator.·
USerid
msgtext
ALL
Note: Only class A and B users may issue the ALL operand.
where:
userid
OPERATOR
ALL
is the identification of the user to whom you are sending the warning message.
If you are sending the warning to yourself, you can specify userid as an asterisk
(*).
Specify OPERATOR if you want to send a warning to the primary system
operator, regardless qf his or her userid. If you specify ALL, you broadcast the
warning message to all users receiving warning messages.
msgtext
is the text of the message to be sent. The length of the message is limited by the
number of characters remaining on the input line after the command and
appropriate operand are entered.
Usage Notes
1. WARNING commands ring the alarm if the ALARM feature is installed, and
put the screen in a HOLD status if the screen is full. When this occurs, press
the P A2 key or the CLEAR key to clear the screen and put the screen in a
RUNNING status.
2. If a warning is issued from a CMS environment, the command and the message
text cannot be longer than 240 characters.
If a warning is issued from a CP environment, the command and message length
is limited by the input area of the terminaL
3. The WARNING command will route the message to the secondary user of a
disconnected virtual machine. If the secondary user is connected or the
secondary user is disconnected but has a valid path to a *MSG or *MSGALL
CP system service, they will receive the message. If the secondary user is
disconnected and there is no valid path to a *MSG or *MSGALL CP system
service the message 0571 userid NOT RECEIVING, DISCONNECTED is sent
to the issuer of the command.
Chapter 2. VMjXA SP CP Commands
749
WARNING
Responses
hh:mm:dd * WNG FROM userid: msgtext
is the warning message received by the specified users. The hh:mm:dd represents the
time when the message was sent to the user.
Migration Notes
VMISP HPO: VMjXA SP provides the time stamp and warning text on the same
line without blank lines in between as in VMjSP HPO.
750
VMjXA SP2 CP Command Reference
XAUTOLOG
XAUTOLOG
Privilege Class: A, B, G
Use the XAUTOLOG command to log on another user's virtual machine. If you
have class G privileges (and not class A or B), users whose virtual machines you
want to log on must have the appropriate XAUTOLOG statement in their VMjXA
SP directory entries. If you have class A or B privileges and you are not specifying
the userids' passwords, you are automatically authorized to log on their virtual
machines.
XAUTOLog
[#console-input-data]
userid [IPl {Vdev }.]
sysname .
[NOi P1]
[ACcount nnnnnnnn]
ptorage { ~~~~nnnK}J
[PASSword password]
[PRompt
[DIRectory
]
[SYNch]
where:
userid
is the user identification of the virtual machine you are logging on.
IPL
{:::ame}
specifies the virtual device number or named saved system that you want IPLed
after logon processing. This option overrides the IPL (if any) specified in the
user's entry in the system directory.
If SYNCH is not specified, the IPL command processor determines whether the
IPL operand is valid after the logon is completed; it is not verified as part of
LOGON or XAUTOLOG processing.
If SYNCH is specified with IPL, the IPL operand is checked for validity before
control returns to the XAUTOLOG command issuer.
NOIPL
specifies that the IPL device specified in the user's entry in the system directory
should not be used for an automatic IPL.
ACCOUNT nnnnnnnn
specifies an alternate account number to be assigned to the user's virtual
machine at logon time. This account number must be valid in order for the
logon to complete successfully. If you do not specify this option, the primary
(or first) account number specified in the user's entry in the system directory is
used.
Chapter 2. VM/XA SP CP Commands
751
XAUTOLOG
STORAGE {nnnnnnnK }
nnnM
specifies an alternate storage size to be assigned to the user's virtual machine.
The value that you specify for this option must be valid in order for the logon to
complete successfully. If you do not specify a value, the minimum storage size
indicated in the user's entry in the system directory is used.
The minimum value that you can specify is 64K; the maximum value allowed is
the maximum value specified on the USER statement for the user's virtual
machine in the system directory and cannot exceed 999M.
If the value that you specify is not a multiple of 64K, and is less than 16M, it is
rounded up to the next higher 64K boundary. If the value is greater than 16M,
it is rounded up to the next 1M boundary.
PASSWORD password
is the userid's logon password. The ability to specify the password is only
available to class A and B users. Class A and B users are authorized to
automatically log on any virtual machine without specifying a password, but this
PASSWORD option is available when password verification is desired. If your
installation is using the password suppression facility and you want to specify a
password, use the PROMPT parameter; the PASSWORD parameter is not
accepted.
PROMPT
specifies that you should be prompted for the password at the terminal. If your
installation has password suppression active, then you must specify PROMPT in
order to use password authorization when entering the command at the terminal.
The ability to specify PROMPT is only available to class A and B users.
DIRECTORY
indicates that the user's entry in the VMjXA SP directory must contain an
XAUTOLOG statement to authorize you to log on the virtual machine if you do
not have class A or B privileges.
SYNCH
indicates that the command is to be executed synchronously. VM returns
control to the issuer of the XAUTOLOG command when the target userid is
logged on and IPL command is validated (if an automatic IPL is performed).
Unless NOIPL is specified, there must be an IPL statement in the target userid's
directory entry or the IPL parameter must be specified on the XAUTOLOG
command. (Note: If NOIPL is specified, then VM returns control when the
target userid is logged on.)
If SYNCH is not specified, the XAUTOLOG command executes asynchronously
and VM returns control after a LOGON is scheduled. The XAUTOLOG
command issuer receives a message when the target user is logged on. For
asynchronous execution, no IPL statement or parameter is required.
#console-input-clata
is data that you want used as virtual console input in response to the first read
issued by the user's virtual machine. You may use the remainder of the
command line to enter console data; the entire line including any logical line-end
characters (#) is passed to the virtual machine.
Note: If you are using CMS and specify console-input-data on the
XAUTOLOG command line, CMS interprets the input line as two
separate commands because of the logical-line-end character (#). You
can avoid this situation by preceding the logical-line-end character with a
752
VM/XA SP2 CP Command Reference
XAUTOLOG
logical-escape-character or by preceding the XAUTOLOG command line
with #CP, where # is your logical-line-end character.
Usage Notes
1. XAUTOLOG was a synonym for the AUTOLOG command. It was provided
to ease future migration for those who wanted to use the extended options of the
VMjXA SP XAUTOLOG command. In VMjXA SP Release 2, the AUTO LOG
command is changed to be compatible with the VMjSP HPO AUTO LOG
command.
2. If neither IPL nor NOIPL is specified, the virtual machine that you log on using
the XAUTOLOG command must have an IPL statement in its system directory
entry.
Unless NOIPL is specified, an automatic IPL is scheduled. If the IPL statement
is invalid, you receive a message and the userid is forced off the system.
3. Authorization to log on a user via the XAUTOLOG command is granted:
• If you have class A or B privileges and you specify or default to the
DIRECTORY option
• If you have class A or B command privileges and you specify a correct
password via a prompt or the PASSWORD option
• If you have class G (and not class A or B) command privileges and your
userid appears in the XAUTOLOG directory statement belonging to the
virtual machine that you want to XAUTOLOG.
4. Users with a password of NO LOG in their directory entries cannot be logged on
by the XAUTOLOG command.
For a complete description of the XAUTOLOG directory statement, see VMjXA
SP Planning and Administration.
5. The virtual machine that you log on using the XAUTOLOG command operates
in disconnect mode. The same restraints that apply to any disconnected
machine also apply to virtual machines that are logged on with the
XAUTOLOG command.
6. If the userid you specify has a secondary userid specified on the CONSOLE
statement in its directory entry, messages from CP (and from the virtual machine
if automatic IPL takes place) are routed to the secondary user if that user is
logged on and not disconnected. If your use rid (XAUTOLOG issuer) is the
designated secondary userid and you are not running in disconnect mode, you
receive messages resulting from the LOGON of the target user.
7. If your installation is using the password suppression facility (controlled by the
SET PASSWORD command) and you want to use password authorization, you
should enter the PROMPT parameter on the XAUTOLOG command line.
Wait for the "ENTER PASSWORD" prompt before you type in the password.
The password is automatically masked, thus improving system security.
8. VMjXA SP disables the XAUTOLOG and AUTOLOG commands for the rest
of a user's logon session if the user enters excessive incorrect passwords to log on
another userid automatically. The initial system limit is four incorrect
passwords. Use the QUERY CMDLIMIT command to see the system limit
value set by your installation.
The PASSWORD parameter may be used on an XAUTOLOG command in an
EXEC or module (even if your installation is using the password suppression
facility) unless you set the DIAGNOSE X 108 1 control bit to reject a password
Chapter 2. VM/XA SP CP Commands
753
XAUTOLOG
on the command line. See VM/XA SP CP Programming Services for details
about DIAGNOSE X I 08 I .
9. If SYNCH is specified and an automatic IPL is scheduled but IPL processing is
unsuccessful, you receive a message and the userid is forced off the system.
Response 1
ENTER PASSWORD:
is the response if the command line contained the PROMPT parameter. Enter the
password of the userid you want to XAUTOLOG.
Response 2
COMMAND ACCEPTED
is the response to indicate that the command syntax is correct.
This response appears if SYNCH is not specified and the command line syntax is
accepted. This response means that the LOGON has been scheduled and VM/XA
SP has returned control to you. More information about the LOGON and IPL will
arrive later.
If the SYNCH parameter is specified, the COMMAND ACCEPTED response does
not appear. All processing concerning the automatic logon is completed before
VM/XA SP returns control to you.
If an error occurs in trying to autolog the specified user, you receive an error
message.
Response 3
USER DISC XAUTOLOGON useri d USERS = nnnnn BY {SYSTEM }
userid2
is the response to the system operator and issuer of the XAUTOLOG command (if
different from the system operator) upon successful completion of the LOGON
process of the user specified on the XAUTOLOG command.
where:
DISC
indicates that the user you autologged is operating in disconnect mode.
userid
is the identification of the virtual machine initiated by the XAUTOLOG
command.
USERS = nnnnn
is the number of logged-on users.
SYSTEM
indicates that the XAUTOLOG process has occurred as part of VM/XA SP
system initialization. Typically, your primary system operator's virtual machine
is logged on as part of the system initialization process.
userid2
identifies the user who issued the XAUTOLOG command.
754
VM/XA SP2 CP Command Reference
XAUTOLOG
Response 4
hh:mm:ss USER DISC LOGOFF AS userid USERS
= nnnnn FORCED
is the response to the system operator upon failure of the IPL process for the user
specified on the XAUTOLOG command. The system operator receives this response
only if SYNCH is specified and an automatic IPL was scheduled for the userid.
where:
DISC
indicates that the user you autologged is operating in disconnect mode.
userid
is the identification of the virtual machine initiated by the XAUTOLOG
command.
USERS = nnnnn
is the number of logged-on users.
Response 5
HCRmmm6056I XAUTOLOG information for userid : The IPL
command is verified by the IPL command processor.
is the response to the issuer of the XAUTOLOG command when the IPL statement
has been verified by the IPL processor for the user specified in the XAUTOLOG
command. This response is issued when XAUTOLOG is asynchronous (the
SYNCH parameter is not specified).
where:
userid
is the identification of the virtual machine initiated by the XAUTOLOG
command.
Response 6
USER DSC LOGOFF AS userid
USERS
=
nnnnn FORCED
is the response to the system operator if an invalid IPL statement is processed for the
user specified on the XAUTOLOG command. The system operator receives this
response only if an automatic IPL was scheduled for the userid.
where:
userid
is the identification of the virtual machine initiated by the XAUTOLOG
command.
USERS = nnnnn
is the number of logged-on users.
Chapter 2. VM/XA SP CP Commands
755
XAUTOLOG
Migration Notes
VM/SP HPO
1. No migration to the XAUTOLOG command is required.
2. To remove the password from AUTOLOG commands issued from EXECs and
programs, convert those commands to XAUTOLOG commands (for class A and
class B users).
3. In addition, class G users may be authorized to use the XAUTOLOG command
for a given virtual machine if they are listed on an XAUTOLOG statement in
the virtual machine's system directory entry.
VMIXA SP Release 1
1. The XAUTOLOG command replaces the VM/XA SP Release 1 AUTOLOG
command. It supplies all the functions of the VM/XA SP Release 1 AUTO LOG
plus additional functions. To convert a Release 1 AUTOLOG command to
XAUTOLOG, change the command name to XAUTOLOG. You do not have
to convert an existing Release 1 AUTOLOG command in the following
situations:
• You have class A c' class B privileges.
• The existing command is of the form:
AUTO LOG userid
• There is an IPL statement in the user's system directory entry.
• You can tolerate synchronous processing.
• Your installation is using the password suppression facility.
• You want to supply a password to complete the automatic log on.
2. Class G users must use the XAUTOLOG command. The AUTOLOG command
is only class A or class B.
3. XAUTOLOG requires an IPL statement in the system directory entry for the
use rid unless either the IPL or the NOIPL parameter is specified.
4. If SYNCH is not specified, you receive asynchronous messages about the
LOGON and IPL for the userid specified in the XAUTOLOG command.
5. If NOIPL is not specified and thus an automatic IPL is scheduled but the IPL
statement is invalid, you receive a message and the userid will be forced off the
system. In VM/XA SP Release 1, the userid was not forced off the system.
756
VM/XA SP2 CP Command Reference
Appendix A. Restricted Userids
Many keywords have a specific meaning to your VM/XA SP when they are
encountered in a command input line.
The command syntax of the VM/XA SP CP commands often allows you to enter
one of these keywords or a userid with equal frequency. If you have assigned one of
these keywords as a userid, an ambiguity results that may cause the system to
improperly analyze the command line.
You can avoid this problem by not using any of the following words as a userid:
*
ABEND
ACCount
ALL
ALLOC
BRKKEY
CACHE
CCWtran
CONsole
COPY
CPFORMAT
CPT Race
CPUs
CPUID
CTCa
CTLR
DAsd
DCSS
DISPlay
DUMP
Files
GRAF
Hold
IMG
IMSG
Links
LINEs
LINEDit
LOGmsg
MACHine
MITime
MOD
MODEL
MSG
Names
NSS
OFF
Printer
Prt
PASSWORD
PFnn
PRIORity
PROCessor
PUnch
Rdr
Reader
REAL
RECording
REPLY
REServed
RUN
Set
SDF
SPECIFIC
SPOOL
STORage
STORE
SVC76
SYStem
Time
TApes
TAG
TDisk
TERMinal
TIMER
TRace
TYpe
Users
UCR
UR
V=F
V=R
Virtual
VECtor
WNG
XSTORAGE
XSTORE
Note: Uppercase letters in this table represent the minimum truncations that the
system will accept for any of these keywords. Where a keyword is specified
in both uppercase and lowercase letters, you should not assign a userid that is
exactly the same as any acceptable truncation of the keyword. For example:
STORage
is a reserved keyword. You should not assign any of the following as userids:
STOR
STORA
STORAG
STORAGE
Appendix A. Restricted Use rids
757
Summary of Changes
Technical changes throughout this manual are indicated by vertical bars to the left
of the changed material.
Second Edition
Form of Publication: SC23-0358-1
Level of Product: VMjXA System Product Release 2
Date of Publication: November 1988
Changes to this publication:
• New device support
VM/XA System Product Release 2 fully supports, unless otherwise noted, the
following devices:
-
3101 Models 10, 11, 12, 13, 20, 21, 23 (supported through VMjVTAM or
VCNA)
-
3174 Mode11L (non-SNA channel attachment or SNA channel attachment
through VMjVTAM or VCNA)
-
3174 1R, 51R, 81R, 2R, 3R, 52R, 53R, 82R (remote SNA attachment
through VMjVT AM or VCNA)
-
3274 Models lA, 21A, 31A, or 41A (SNA attachment through VMjVTAM
or VCNA)
3274 Models 1C, 21C, 31C, 41C, 51C, 61C (remote SNA attachment
through VMjVTAM or VCNA)
3705, 3720, 3725, 3745 (SNA attachment through VMjVTAM or VCNA)
7171 ASCII Device Attachment Control Unit.
• ASCn device support
VMjXA System Product Release 2 allows you to connect ASCII TTY display
terminals to the system through a VMjVTAM service machine or through a
7171 Device Attachment Control Unit (DACU).
• Processor Resource/Systems Manager (PR/SM) feature
The PRjSM feature supersedes the Multiple High Performance Guests Support
feature on 3090 Enhanced Model Processors, and offers additional functions.
• Group control system (GCS)
GCS is a new component that allows you to implement a native SNA
communication network or run RSCS Version 2.
• CP system trace facility enhancements
The CP system trace facility allows you to save CP system trace data in system
trace files on disk or tape.
Summary of Changes
759
• Data trace facility
VM/XA System Pro,duct Release 2 pro,vides a facility that allo,ws yo,U to, set
three different types o,f data tracing fo,r reco,rding in system data files. These
three data tracing types are:
-
CP data trace
I/O data trace
Guest data trace.
• Soft abend dump enhancements
VM/XA System Pro,duct Release 2 enhances existing So,ft abend dump supPo,rt
by:
Allo,wing mo,re CP functio,ns to, request So,ft abends rather than hard abends
Pro,viding snapsho,t info,rmatio,n abo,ut abending mo,dules' save areas and
asso,cia ted data areas
Flagging sto,rage frames in the So,ft abend dump that have changed between
the time CP started the dump and the time CP actually dumped the frames
Changing the fo,rmat o,f the so,li abend dump to, be co,mpatible with the hard
abend dump fo,rmat.
• Dump viewing facility enhancements
VM/XA System Pro,duct Release 2 enhances the dump viewing facility to, allo,w
yo,U to,:
Fo,rmat CPco,ntro,I blo,cks o,r virtual machine co,ntro,I blo,cks
Select which trace table entries yo,u wish to, view in a CP, standalo,ne, o,r So,ft
abend dump
Pro,cess GCS and RSCS Versio,n 2lo,ad maps (with the MAP and
ADD MAP co,mmands) in additio,n to, the Io,ad maps currently sUPPo,rted
Pro,cess data trace info,rmatio,n as well as CP trace table data
Co,llect GCS guest trace reco,rds in a simulated OS QSAM file
Pro,cess CP So,ft abend dumps
Pro,cess dumps with any CMS file name
View dump data via the XED IT interface
Use the XEDIT interface to, extract data fro,m dumps fo,r use in a REXX
EXEC
Use an IBM-supplied EXEC to, search a dump fo,r a hung user.
• CP national language support (NLS)
VMjXA System Pro,duct Release 2 pro,vides CP HELP files and messages in the
fo,llo,wing languages:
Mixed-case American English (base versio,n)
Uppercase American English
Brazilian Po,rtuguese
French
German
Japanese (Kanji).
• Managing 37xx communication controllers
VM/XA System Pro,duct Release 2 pro,vides new co,mmands that allo,w you to,
manage yo,ur 37xx communicatio,n contro,llers.
760
VM/XA SP2 CP Command Reference
• SPTAPE enhancements
VM/XA System Product Release 2 enhances the SPTAPE command to allow
you to dump and load spool files and system data files that span more than one
tape volume.
• DASD dumping and restoring enhancements
VMjXA System Product Release 2 enhances the DDR and DDRXA programs
to allow you to save the DASD data to tape in compacted form.
• Expanded Storage caching
VMjXA System Product Release 2 uses expanded storage for caching during
logon and IPL processing and for CMS file system minidisk caching.
• DIRECTXA enhancements
VM/XA System Product Release 2 enhances the function of the DIRECTXA
command and the directory build process by providing automatic deactivation of
restricted passwords (ADRP).
• AUTOLOG command enhancements
VM/XA System Product Release 2 provides two commands (AUTOLOG and
XAUTOLOG) to !illow you to log on virtual machines automatically in a
disconnected state.
• LOGON command enhancement
VM/XA System Product Release 2 enhances the LOGON command to allow
users to type in their passwords on the LOGON command line.
• PF key enhancements
VMjXA System Product Release 2 enhances PF key functions QY allowing you
to:
Issue a command to clear the RETRIEVE PF key buffer
Specify whether or not you wish a PF key's definition displayed when you
press the PF key
Specify a PF key definition with substitution characters.
• New and changed publications
VM/XA System Product Release 2 adds two new books to the VM/XA SP
library and combines two existing books into one book. The two new books
are:
VM/XA System Product: Group Control System Command and Macro
Reference, SC23-0433
VM/XA System Product: Group Control System Diagnosis Reference,
LY27-S060
The combined book is VM/XA SP Release 2 Planning and Administration. This
book replaces the VM/XA SP Release 1 Administration (SC23-0353) and VM/XA
SP Release 1 Planning (GC23-037S) manuals.
• Application programming enhancements
VM/XA System Product Release 2 provides new and changed DIAGNOSE code
and IUCV functions.
Summary of Changes
761
Glossary
A
CPo Control program.
automatic software re-IPL. The process by which
the control program attempts to restart the system
after abnormal termination. This process does not
involve the hardware IPL process. See also
virtual = real machine recovery.
D
c
CCS. Console communication services.
CCW. Channel command word.
channel command word (CCW). A doubleword
structure that directs an I/O operation on a device
or channel and includes pointers to any storage
areas associated with the operation. One or more
CCWs make up a channel program.
CMS. Conversational monitor system.
console communication services (CCS). A group of
CP routines that interface with the VT AM service
machine, providing full VM/XA™ SP console
capabilities for SNA/CCS terminal users.
control program (CP). The component of VM/XA
SP that manages the resources of a single
System/370-Extended Architecture system so that
multiple computing systems appear to exist. Each
virtual machine is the functional equivalent of
either a System/370 computing system or a
System/370-Extended Architecture computing
system.
conversational monitor system (CMS). The
component of VM/XA SP that, as a virtual
machine operating system, provides interactive
time-sharing. CMS allows users to communicate
with the system and with each other, to create and
edit files, and to develop and run application
programs. It operates in either System/370 mode or
370-XA mode under the control of CPo
DCSS. Discontiguous saved segment.
directory. A CP disk file that includes an entry for
each user in the system. The entry defines the
characteristics of the user's initial virtual machine
configuration. These characteristics include the
userid, the password, normal and maximum
allowable virtual storage, virtual device definitions,
the privilege class, the dispatching priority, logical
line editing characters, and the account number.
discontiguous saved segment (DCSS). A saved
segment that occupies one or more
architecturally-defined segments. It begins and ends
on segment boundaries. It is accessed by its own
name. Contrast with member saved segment. See
also saved segment, segment, segment space.
dump viewing facility. A VM/XA SP component
that allows users to display, format, and print data
interactively from CP hard and soft abend,
stand-alone, and virtual machine dumps, and to
process CP trace table data stored on tape or in a
system trace file.
dynamic paging area. The area of real storage
allocated by CP for V=V machine paging. This
area also contains CP nonresident modules, CP
control blocks, CP trace tables, free storage pages,
and the alternate processor's prefix storage areas.
E
Expanded Storage. Optional integrated high-speed
storage. In VM/XA SP, Expanded Storage may be
shared by CP and one or more virtual machines. It
may also be dedicated to CP or to a particular
virtual machine.
VM/XA is a trademark of the International Business Machines Corporation.
Glossary
763
F
full-pack minidisk. A virtual disk that contains all
of the addressable cylinders of a real DASD
volume.
full-screen mode. In VM/XA SP, the environment
in which an entire 3270 display screen is under the
control of a program running in a virtual machine.
G
GCS. Group control system.
group control system (GCS). The component 'of
VM/XA SP that, as a virtual machine supervisor,
executes in a group of Systemj370 virtual mac:hines
under CP control to provide an interface that helps
support a native Systems Network Architecture
(SNA) network.
guest. An operating system running in a virtual
machine managed by the VM/XA SP control
program. Contrast with host.
guest real storage. The storage that appears real to
the operating system running in a virtual machine.
Contrast with guest virtual storage, host real
storage, and host virtual storage.
guest virtual storage. The storage that appears
virtual to the operating system running in a virtual
machine. Contrast with guest real storage, host real
storage, and host virtual storage.
H
host. The Vl\1/XA SP control program in its
capacity as manager of a virtual machine in which
another operating system is running. Contrast with
guest.
host real storage. The storage that appears real to
the control program. If VM/XA SP is running
native, this is real storage; if VM/XA SP is running
in a virtual machine, this is virtual storage.
Contrast with guest real storage, guest virtual
storage, and host virtual storage.
host virtual storage. The storage that appears
virtual to the control program. Contrast with guest
real storage, guest virtual storage, and host real
storage.
image library. A set of modules, contained in a
system data file, that define the spacing, characters,
and copy modification data that a 3800 printer uses
to print a spool file or that define the spacing and
character set that an impact printer uses to print a
spool file. See also system data file.
inter-user communication vehicle (IUCV). A
generalized CP interface that facilitates the transfer
of data among virtual machines.
mcv.
Inter-user communication vehicle.
M
member saved segment. A saved segment that
begins and ends on a page boundary. It belongs to
up to 64 segment spaces and is accessed either by
the segment space name or by its own name.
Contrast with discontiguous saved segment. See
also saved segment, segment, segment space.
message repository file. A type of system data file
that contains a set of VM/XA SP messages
translated into a national language.
missing interrupt handler. A CP function for
detecting and dealing with real I/O operations that
do not complete within a specified time.
multiple preferred guests. A VM/XA SP facility
that supports up to six preferred virtual machines
when the Processor Resource/Systems ManagerTM
(PR/SM™) feature is installed in the real machine.
See also preferred virtual machine.
Processor Resource/Systems :Manager and PR/S:M: are trademarks of the International Business M:achines
Corporation.
764
VMjXA SP2 CP Command Reference
N
named saved system (NSS). A copy of an operating
system that a user has named and retained in a
system data file. The user can load the operating
system by its name, which is more efficient than
loading it by device number. See also discontiguous
saved segment, member saved segment, saved
segment, segment space, system data file.
NSS. Named saved system.
p
page able virtual machine. Synonymous with
virtual = virtual machine.
name. A segment space occupies one or more
architecturally-defined segments; it begins and ends
on segment boundaries. A user with access to a
segment space has access to all of its members. See
also discontiguous saved segment, member saved
segment, saved segment, segment.
service virtual machine. A virtual machine that
provides system services. These services include
accounting, error recording, monitoring, and those
provided by supported licensed programs.
SMSG function. A CP function that allows a
virtual machine to send a special message to
another virtual machine programmed to accept and
process the message. See also special message.
SNA. Systems Network Architecture.
preferred virtual machine. A virtual machine that
runs in the V = R area. CP gives this virtual
machine preferred treatment in the areas of
performance, processor assignment, and I/O
interrupt handling. See also multiple preferred
guests, virtual = fixed machine, virtual = real area,
virtual = real machine.
Processor Resource/Systems Manager (PR/SM). A
separately orderable feature available with 3090E
processors that provides for logical partitioning of
the real machine and support of multiple preferred
guests. See also multiple preferred guests.
PRISM. Processor Resource/Systems Manager.
R
real system operator. Any user who loads and runs
VM/XA SP in the real machine. Contrast with
virtual machine operator.
s
saved segment. One or more pages of storage that
have been named and retained in a system data file.
See also discontiguous saved segment, member
saved segment, segment, segment space, system data
file.
segment. In System/370 architecture, 64 kilobytes
of storage. In 370-XA architecture, I megabyte of
storage. See also saved segment.
segment space. A saved segment composed of up
to 64 member saved segments accessed by a single
SNA/CCS terminal. Any terminal accessing
VM/XA SP that is managed by a VTAM service
machine.
special message. A data transmission, made up of
instructions or commands, sent from one virtual
machine to another via the SMSG function. A
special message is processed by the receiving virtual
machine and does not appear on the receiver's
console. See also SMSG function.
spool file. A collection of data along with CCWs
for processing on a unit record device. Contrast
with system data file.
SVC 76. In VM/XA SP, a supervisor call
instruction that records the error incidents
encountered by certain operating systems running in
virtual machines. When a virtual machine
operating system issues an SVC 76, VM/XA SP
translates the virtual storage and I/O device
addresses to real addresses, records the information
on the VM /XA SP error recording virtual machine,
and returns control to the issuing virtual machine.
This interface bypasses the virtual machine's own
error recording routine, and avoids duplicate error
recording.
System/370 mode. A virtual machine operating
mode in which System/370 functions are simulated.
Contrast with 370-XA mode.
system data file. A collection of data associated
with a particular function. Types of system data
files include saved segments, NSSs, VCR files,
image libraries, message repository files, and system
Glossary
765
trace files. Because a system data file contains no
CCWs, it cannot be processed on a unit record
device. Contrast with spool file.
system hold status. A spool file status that prevents
a file from being printed, punched, or read until the
real system operator releases it. Contrast with user
hold status.
system trace file. A type of system data file that
contains CP or virtual machine trace data.
Systems Network Architecture (SNA). The
description of the logical structure, formats,
protocols, and operational sequences for
transmitting information units through, and
controlling the configuration and operation of,
networks.
u
VCR file. User class restructure file.
unit record device. A reader, a printer, or a punch.
user class restructure file (VCR file). A type of
system data file that contains information used to
override the IBM -defined privilege class structure of
CP commands, DIAGNOSE instruction codes, and
certain CP system functions.
user directory. See directory.
user hold status. A spool file status that prevents a
file from being printed, punched, or read until the
file owner releases it. Contrast with system hold
status.
v
Vector Facility (VF). A hardware feature that
provides synchronous instruction processing for
high-speed manipulation of fixed-point and
floating-point data.
VF. Vector Facility.
area of host real storage that does not start at page
O. CP provides performance enhancements for this
virtual machine. See also multiple preferred guests,
preferred virtual machine, virtual = real area,
virtual = real machine, virtual = virtual machine.
virtual machine. In VM/XA SP, a functional
equivalent of either a System/370 computing system
or a System/370-Extended Architecture computing
system. Each virtual machine is controlled by an
operating system. VM/XA SP controls the
concurrent execution of multiple virtual machines
on an actual System/370-Extended Architecture
system.
Virtual Machine/Extended Architecture™ System
Product (VM/XA SP). An operating system that
allows multiple IBl'v1 Systelll/370 and 370-XA
operating systems to run simultaneously on a single
370-XA processor. The multiple systems may be
used for production, testing, developing application
programs, maintenance, and migration. VM/XA
SP also provides a high-capacity interactive
environment. There are four components: the
control program (CP), the conversational monitor
system (CMS), the dump viewing facility, and the
group control system (GCS).
virtual machine operator. Any user who loads and
runs an operating system in a virtual machine.
Contrast with real system operator.
virtual = real area (V = R area). A fixed, contiguous
section of real storage, starting at page 0, in which
preferred virtual machines execute. CP does not
page this storage. See also preferred virtual
machine, virtual = fixed machine, virtual = real
machine.
virtual = real machine (V = R machine). A preferred
virtual machine with a fixed, contiguous area of
host real storage that starts at page O. CP provides
performance enhancements and an automatic
recovery facility for this virtual machine. See also
multiple preferred guests, preferred virtual machine,
virtual = real area, virtual = real machine recovery,
virtual = virtual machine.
V = F machine. Virtual = fixed machine.
virtual = fixed machine (V = F machine). A
preferred virtual machine with a fixed, contiguous
Virtual
766
~.1achine!Extended
virtual = real machine recovery (V = R machine
recovery). A CP function that allows the V = R
machine to resume operation after most CP
Architecture is a trademark of the International Business l\-lachhies Curpuratiun.
VM/XA SP2 CP Command Reference
abnormal terminations. When possible, the facility
reestablishes the V = R machine environment,
allowing the operating system running in that
virtual machine to perform its own recovery
processes. See also automatic software re-IPL.
virtual = virtual machine (V = V machine). A virtual
machine that runs in the dynamic paging area. CP
pages this virtual machine's guest real storage in
and out of host real storage. See also dynamic
paging area, virtual = fixed machine, virtual = real
machine.
virtual supervisor state. A condition, controlled by
a virtual machine's current PSW, during which the
control program allows the virtual machine to issue
input/output and other privileged instructions.
When these instructions are not emulated, the
control program intercepts these instructions and
simulates their functions for the virtual machine.
virtual wait time. The period during which the
control program suspends the processing of a
program while a required resource is unavailable.
VM/XA SP. Virtual Machine/Extended
Architecture System Product.
VTAM service machine. A collection of networking
programs running in a virtual machine that,
together with the CP console communication
services (CCS) routines, provide full VM/XA SP
console capabilities for SNA/CCS terminal users.
A VTAM service machine contains either (1)
VM/VTAM with VSCS running as an application
under control of GCS, or (2) VM/VCNA running
as a VTAM application under control of the VSE
or VSl operating system.
V = R area. Virtual = real area.
V = R machine. Virtual = real machine.
V = R machine recovery. Virtual = real machine
recovery.
V = V machine. Virtual = virtual machine.
Numerics
370 mode. Synonym for System/370 mode.
370-XA mode. A virtual machine operating mode
in which System/370-Extended Architecture
functions are simulated. Contrast with System/370
mode.
Glossary
767
Bibliography
This bibliography gives the names and order numbers of microfiche and publications
about VM/XA System Product.
VM/XA System Product Microfiche
You can order microfiche listings that contain code. The order numbers for the
microfiche are:
Order No.
Description
LYC7·0330
VM/XA System Product: CP listings
LYC7-0331
VM/XA System Product: CMS listings
LYC7-0332
VM/XA System Product: GCS listings
LYC7·0334
VM/XA System Product: dump viewing facility listings.
VM/XA System Product Publications
The publications are shown in Figure 2 on page 770. You can order any of them
by their individual order numbers or you can order most of them as a group by
using a single order number, SBOF-0260. SBOF-0260 provides:
• All unlicensed publications (order numbers that do not begin with Ly)
• Enough three-ring binders to hold the publications
• Spine and cover inserts for the binders.
Bibliography
769
Evaluation
VM/XA
System Product
VM
at a Glance:
Large Systems
GC23-0360
Installation
VM/XA
System Product
VM/XA
System Product
Licensed
Program
Specifications
GC23-0366
General
Information
GC23-0362
Planning and Administration
VM/XA
System Product
Installation
and Service
SC23-0364
Operation
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
Planning and
Administration
GC23-0378
Conversion
Notebook
SC23-0357
Features
Summary
LY27-8058
Real System
Operation
SC23-0371
Virtual
Machine
Operation
SC23-0377
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
CP Command
Reference
SC23-0358
CMSCommand
Reference
SC23-0354
CMS
User's Guide
SC23-0356
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
Quick Reference
SX23-0391
System Product
Editor
User's Guide
SC23-0373
System Product
Editor
Command and
Macro Reference
SC23-0372
Library Guide,
Glossary, and
Master Index
GC23-0367
End Use
Figure 2 (Part 1 of 2). VM/XA System Product Publications
770
VM/XA SP2 CP Command Reference
VM/XA
System Product
CMS Primer
SC23-0368
VM/XA
System Product
CMS Primer
Summary of
Commands
SC23-0421
Application Programming
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
CP
Programming
Services
SC23-0370
CMS
Application
Program
Development
Guide
SC23-0355
CMS
Application
Program
Development
Reference
SC23·0402
CMS
Application
Program
Conversion
Guide
SC23·0403
Application
Development
Guide
for FORTRAN
and COBOL
SC23·0369
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
GCSCommand
and Macro
Reference
SC23-0433
System Product
Interpreter
User's Guide
SC23·0375
System Product
Interpreter
Reference
SC23·0374
EXEC2 Reference
SC23·0361
Directory of
Programming
Interfaces
for Customers
GC23·0434
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
System Messages
and Codes
Reference
SC23-0376
Diagnosis
Guide
LY27·8056
CP Diagnosis
Reference
LY27·8054
CMS
Diagnosis
Reference
LY27·8052
GCS
Diagnosis
Reference
LY27·8060
VM/XA
System Product
VM/XA
System Product
VM/XA
System Product
Dump Viewing
Facility
Operation Guide
and Reference
SC23·0359
CP Data Areas
and Control
Blocks
LY27·8053
CMS Data Areas
and Control
Blocks
LY27·8051
Diagnosis
VM/XA
System Product
Binders and Inserts
I
A single 3-ring
binder (holds
one or more
publications)
SX23·0399
I
Spine and cover
inserts for binders
(enough for all
publications)
SX23·0398
I-
Figure 2 (Part 2 of 2). VM/XA System Product Publications
Bibliography
771
Index
A
accessing the VM/XA SP system
using the LOGON command 244
account number, displaying
ACNT
command 20
activating a protected application environment
using SET CONCEAL command 505
activating CPTRACE entry recording of real machine
events
using SET CPTRACE command 509
activating or deactivating caching
using SET CACHE command 501
activating the pseudo page fault facility
using SET PAGEX command 539
activating TRACE sets
using TRACE GOTO/CALL/RETURN
command 680
allocating DASD volumes for CP uses
using the CPFORMAT command 63
altering
the external attributes of a closed spool file or
files 39
the user HOLD status of an active spool file 39
altering a device's missing interrupt interval setting
using SET MITIME command 531
altering processing parameters for CP recording
facilities
using RECORDING command 472
altering storage locations in real or virtual machine
using STORE command 613
altering the contents of one or more vector registers
using STORE VECTOR command 622
altering trace traps
using TRACE TRAP command 702
assigning the RETRIEVE function to a PF key
using the SET PFnn RETRIEVE function 547
associating information with the VM/XA SP spool files
using TAG command 627
ATTACH
command 21
attaching a partition of real Expanded Storage 21
using ATTACH command 21
attaching DASD device to CP 21
using ATTACH command 21
attaching real or logical devices 21
using ATTACH command 21
attention interruption pending for your virtual console
using ATTN command 30
ATTN
command 30
AUTO LOG command
logging on another user's virtual machine 31
automatic logon
31
B
BACKSPACE
command 35
BACKWARD
command 35
BEGIN
command 37
bibliography 769
C
canceling SPTAPE functions
using SPTAPE CANCEL command 594
CHANGE command
changing attributes of spool files 39
changes to this book 759
changing
the configuration of your virtual machine 75
changing a user's priority of access to system resources
using SET SHARE command 555
changing color or highlighting definitions
using SCREEN command 489
changing control options for your virtual machine
using SPOOL
READER/PRINTER/PUNCH/CONSOLE
command 577
changing current language
using the SET CPLANGUAGE command 508
changing the allocation map of a DASD volume 64
using the CPFORMAT command 64
changing the current session account number
using SET ACCOUNT command 499
changing the dispatching timeslice
using the SET SRM DSPSLICE command 559
changing the identification of a virtual processor
using SET CPUID command 518
changing the interactive bias system parameter
using SET SRM IABIAS command 559
changing the number of users allowed in the dispatch
list
using SET SRM DSPBUF command 559
changing the order of closed spool files on a specified
queue
using the ORDER command 271
changing the storage resources to users
using the SET SRM STORBUF command 559
changing the system's paging resources
using the SET SRM LDUBUF command 559
changing the type of virtual processor configuration
using SET MACHINE command 528
Index
773
changing virtual device numbers
using REDEFINE command 474
checking the system for an eventual warm start
using SHUTDOWN command 568
choosing a virtual processor
using the CPU command 71
classes, user privilege
clearing all pending interrupts from a virtual device
using RESET command 479
clearing storage
using the SYSTEM command 625
CLOSE
command 48
COMMANDS
command 58
commenting on your console sheet
using * command 17
commenting on your display screen
using * command 17
connecting two virtual channel-to-channel adapters
using the COUPLE command 60
connecting (logically) a display
using the DIAL command 120
console
defining 77
control of special messages
using SET SMSG command 558
controlling break-ins
using the TERMINAL BREAKIN command 636
controlling certain functions associated with the virtual
console
using the TERMINAL command 630
controlling CP output destination
using SET CPCONIO command 507
controlling error message handling
using SET EMSG command 522
controlling logical line editing functions
using SET LINED IT command 525
controlling response destination
using SET VMCONIO command 566
controlling simulation of NOP CCWs in channel
programs
using SET NOPDATA command 537
controlling the console mode of your display
using the TERMINAL CONMODE command 640
controlling the terminal attention environment
using TERMINAL MODE command 648
controlling the use of text translation tables
using TERMINAL TEXT command 652
controlling the virtual interval timer
using SET TIMER command 565
controlling use of APL character translation tables
using TERMINAL APL command 633
controlling whether certain informational messages are
displayed
using SET IMSG command 523
controlling whether messages are to be received at your
display
774
VM/XA SP2 CP Command Reference
controlling whether messages are to be received at your
display (continued)
using SET MSG command 536
copying your 3270 display screen to a printer
using the SET PFnn COPY command 545
counting successful trace events
using TRACE COUNT command 677
COUPLE
command 60
CP
command 62
CP commands
executing from any command environment 18
issuing 62
CPFORMAT
command 63
CPTRAP command (see also TRSAVE, TRSOURCE,
SET CPTRACE) 70
CPU
command 71
creating a virtual Vector Facility
using DEFINE VECTOR command 93
creating account records for logged-on users
using ACNT command 20
cylinders, displaying allocated, in use, and
available 299
D
deactivating a protected application environment
using SET CONCEAL command 505
deactivating CPTRACE entry recording of real machine
events
using SET CPTRACE command 509
deactivating the pseudo page fault facility
using SET PAGEX command 539
DEDICATE
command 73
dedicating a real processor to the V = R user
using the DEDICATE command 73
DEFINE command
CONSOLE operand 77
CPU operand 78
CTCA operand 80
GRAF operand 81
MDISK operand 82
spooling device operand 83
STORAGE operand 87
temporary disk operand 89
VECTOR operand 93
virtual device operand 91
defining a function for a program function key on a
3270 display
using the SET PFnn command 542
defining a minidisk
using DEFMDISK command 82
defining a skeleton system data file for a DCSS
using the DEFSEG command 95
defining a skeleton system data file for an NSS 101
using the DEFSYS command 101
defining a spooling device 83
defining a temporary disk
using DEFINE (temporary disk) command 89
defining a virtual channel-to-channel adapter
using DEFINE CTCA command 80
defining a virtual display station
using DEFINE GRAF command 81
defining a virtual system console
using DEFINE CONSOLE command 77
defining a virtual Vector Facility
using DEFINE VECTOR command 93
defining a 3800 printer
using the DEFINE (spooling device) command 83
defining logical tab characters on display devices
using TERMINAL TABCHAR command 651
defining storage size for virtual machine
using DEFSTOR command 87
defining the break key
using the TERMINAL BRKKEY command 637
defining the logical character delete symbol
using TERMINAL CHARDEL command 639
defining the logical escape character
using TERMINAL ESCAPE command 643
defining the logical line delete symbol
using TERMINAL LINEDEL command 645
defining the logical line end symbol
using TERM IN AL LINEND command 646
defining virtual processors
using the DEFINE CPU command 78
defining 3101 s or TTY s
using the TERMINAL TYPE command 653
DEFSEG command 95
DEFSYS command 101
deleting a log message
using SET LOGMSG command 526
deleting a specified line in a log message
using SET LOGMSG command 526
deleting all trace traps and all trace sets
using TRACE END command 678
deleting all traps in a named trace set
using TRACE CLEAR command 676
deleting message repository files
using the PURGE NLS command 283
deleting trace traps
using TRACE TRAP command 702
designating a user for system resources
using SET QUICKDSP command 550
designating a virtual processor
using the CPU command 71
designating the unit to receive a VM/XA SP system
ABEND dump
using SET DUMP command 519
DETACH command
CPU operand 107
VECTOR operand 116
VIRTUAL operand 112
DETACH command (continued)
XSTO RE operand 118
(real device) operand 108
determining all devices on a path
using the QUERY CHPID command 305
determining your system status and machine
configuration
using the QUERY command 290
DIAL command 120
DISABLE command 122
DISCONNECT command 124
disconnecting your display station from the VM/XA SP
system
using the DISCONNECT command 124
DISPLAY
displaying contents of prefix register 139
displaying contents of registers 141
displaying first-level storage 135
displaying guest storage 130
displaying information from SCHIBs 144
displaying PSW information 140
displaying vector registers 146
displaying a user's share of the system
using QUERY SHARE command 401
displaying account number
using QUERY ACCOUNT command 298
displaying all paths available to a specified device
using QUERY PATHS command 377
displaying allocation of cylinders
using QUERY ALLOC command 299
displaying caching status for 3880 subsystems
using QUERY CACHE command 301
displaying contents of first-level storage
using DISPLAY HOST STORAGE command 135
displaying contents of prefix register
using DISPLAY PREFIX command 139
displaying contents of registers
using DISPLAY REGISTERS command 141
displaying contents of storage at specified locations
using DISPLAY GUEST STORAGE command 130
displaying courit of spool files
using QUERY FILES command 337
displaying count of system data files
using QUERY SDF command 393
displaying CP language identifiers
using the QUERY CPLANGLIST command 310
displaying current CP language
using the QUERY CPLANGUAGE command 311
displaying current limit of logged on users ,.
using QUERY MAXUSERS command 352
displaying current online or offline status of paths to a
device
using QUERY PATHS command 377
displaying current profile information
using QUERY MONITOR command 356
displaying current session time and date information
using QUERY TIME command 413
Index
775
displaying current settings of dump options
using QUERY DUMP command 335
displaying current terminal options
using QUERY TERMINAL command 4lO
displaying current TRACE settings
using the QUERY TRACE command 414
displaying current user access to a system DASD
volume
using QUERY SYSTEM command 405
displaying currently defined temporary disk space
using QUERY TDSK command 409
displaying daily system log message
using QUERY LOG command 350
displaying dispatch lists
using INDICATE QUEUES command 211
displaying Expanded Storage Facility current assignment
using QUERY XSTORE command 467
displaying Expanded Storage size
using QUERY VIRTUAL XSTORE command 464
displaying page residency data
using INDICATE PAGING command 209
displaying processor identification
using QUERY CPUID command 317
displaying program function key assignments
using QUERY PFnn command 379,
displaying PSW information
using DISPLAY PSW command 140
displaying real and virtual machine components
using the DISPLAY command 126
displaying real storage allocations for V = R and V = F
guests
using QUERY V = R command 465
displaying resources used by a virtual machine
using INDICATE USER command 213
displaying secondary users
using QUERY SECUSER command 394
displaying setting of real system event tracing
using QUERY CPTRACE command 313
displaying extended color and highlighting values
displaying size of virtual storage
using QUERY SCREEN command 392
displaying file names stored on a tape
using SPTAPE SCAN command 601
displaying lAB lAS system parameter
using QUERY SRM command 402
displaying information about CP system
using QUERY CP command 312
displaying information about image library files
using the QUERY IMG command 345
displaying information about links to virtual device
using QUERY LINKS command 348
displaying information about logged-on users
using QUERY USERS command 431
displaying information about message repository files
using the QUERY NLS command 366
displaying information about NSS/DCSS files
using the QUERY NSS command 368
displaying information about spool files
using QUERY READER/PRINTER/PUNCH
command 383
displaying information about terminal event records
using QUERY MONDATA command 355
displaying information about trace files
using the QUERY TRFILES command 417
displaying information about UCR files
using the QUERY UCR command 428
displaying information from SCHIBs
using DISPLAY SCHIB command 144
displaying list of logged-on users
using QUERY NAMES command 364
displaying list of real processors and their system use
using QUERY PROCESSORS command 381
displaying missing interrupt detector time interval
settings
using QUERY MITIME command 353
displaying operating load
using INDICATE LOAD command 205
using QUERY VIRTUAL STORAGE
command 460
displaying status of a virtual device
using QUERY VIRTUAL DEVICE command 447
displaying status of CP data collection (ACCOUNTING
and EREP)
using QUERY RECORDING command 390
displaying status of data from TRSOURCE traces
using the QUERY TRSOURCE command 423
displaying status of interpretive execution assist
using QUERY IOASSIST command 347
displaying status of locally-attached virtual display
devices
using QUERY VIRTUAL GRAF command 449
displaying status of logical devices
using QUERY LOGICAL command 349
displaying status of real devices
using QUERY real device command 320
displaying status of real storage
using the QUERY FRAMES command 340
displaying status of SET command functions
using QUERY SET command 396
displaying status of SOFT ABEND function
using QUERY ABEND command 297
displaying status of TRSAVE function
using QUERY TRSAVE command 420
displaying status of unit record devices
using QUERY VIRTUAL UR command 462
displaying status of Vector Facilities and users
using QUERY VECTOR command 433
displaying status of virtual channel-to-channel adapters
using QUERY VIRTUAL CTCA command 442
displaying status of virtual DASD
using QUERY VIRTUAL DASD command 444
displaying status of virtual printers
using QUERY VIRTUAL PRINTER
command 451
776
VM/XA SP2 CP Command Reference
displaying status of virtual punches
using QUERY VIRTUAL PUNCH command 455
displaying status of virtual readers
using QUERY VIRTUAL READER command 458
displaying status of virtual tape devices
using QUERY VIRTUAL TAPES command 461
displaying status of virtual Vector Facilities
using QUERY VIRTUAL VECTOR command 463
displaying status of your virtual console
using VIRTUAL CONSOLE command 436
displaying status of your virtual machine configuration
using QUERY VIRTUAL ALL command 435
displaying status reserved DASD full pack mini-disks
using QUERY DASD RESERVE command 318
displaying system resources at your console
using the INDICATE command 202
displaying system-wide parameters used by the scheduler
using QUERY SRM command 402
displaying tag information for a spool device or file
using QUERY TAG command 407
displaying the address of a module identified by a
symbolic label
using the LOCATE command 236
displaying the address of CP control blocks
using the LOCATE command 236
displaying the contents of Vector Facility registers
using the DISPLAY command 146
displaying the size of real storage
using QUERY STORAGE command 404
displaying the spool file limit
using QUERY MAXSPOOL command 351
displaying the traceback table
using TRACE TABLE command 699
displaying user's QUICKDSP attribute
using QUERY QUICKDSP command 382
displaying user's authorized commands
using the COMMANDS command 58
using the QUERY COMMANDS command 308
displaying user's authorized diagnose codes
using the COMMANDS command 58
using the QUERY COMMANDS command 308
displaying userid and system identifier of user/display
using QUERY USERID/userid command 430
displaying users in LOGON HOLD status
using QUERY HOLD command 343
displaying users with output in system HOLD status
using QUERY HOLD command 343
displaying Vector Facility register contents
using the DISPLAY command 126
displaying Vector Facility users
using INDICATE VECTOR command 218
displaying virtual machines in I/O wait state
using INDICATE I/O command 204
displaying virtual machines in page wait status
using INDICATE PAGING command 209
displaying virtual processors defined for your machine
using QUERY VIRTUAL CPUS command 440
displaying warning messages issued from the
WARNING command
using SET WNG command 567
displaying whether passwords go on command line
using the QUERY PASSWORD command 375
documentation 769
DRAIN command
DUMP
designating the unit to receive a VM/XA SP system
ABEND dump 519
displaying setting of dump options 335
formatted for the dump viewing facility 745
GUEST STORAGE operand 161
HOST STORAGE operand 166
including contents of virtual Vector Facilities
containing data 745
using VMDUMP command 745
PREFIX operand 170
PSW operand 171
REGISTERS operand 173
SCHIB operand 176
SPTAPE DUMP command 595
VECTOR operand 178
dumping areas of first-level storage
using DUMP HOST STORAGE command 166
dumping contents of prefix register
using the DUMP PREFIX command 170
dumping files for storage or migration
using SPTAPE DUMP command 595
dumping information from subchannel information
blocks
using the DUMP SCHIB command 176
dumping locations in virtual machine storage
using the DUMP GUEST STORAGE
command 161
dumping program status words information
using DUMP PSW command 171
dumping the contents of registers
using the DUMP REGISTERS command 173
dumping Vector Facility information
using the DUMP VECTOR command 178
dumping Vector Facility registers
using the DUMP VECTOR command 178
E
ECHO command
ENABLE command
enabling disabled or nonenabled display devices
using the ENABLE command 183
ending all system functions
using.SHUTDOWN command 568
event data collection 256
establishing profile for each type of data
collection 256
executing CP commands from any command
environment
using #CP command 18
Index
777
EXTERNAL command
simulating an external interrupt
184
F
FLUSH command
FORCE command
forcing single-spacing of an output file
using SPACE command 572
forcing soft abend codes to cause full system
termination
using SET ABEND command 498
forcing users off the system
using the FORCE command 188
formatting DASD volumes for CP uses
using the CPFO RMA T command 63
FORWARD command
FREE command
LOGON operand 193
PRINTER, PUNCH option 194
H
HALT command
halting or purging a spool file
using the FLUSH command 186
hard-stop 612
highlighting the command redisplay line on console
using TERMINAL HI LIGHT command 644
HOLD command
LOGON option 199
PRINTER, PUNCH options 200
holding current output on a specified real unit record
device
using the FLUSH command 186
including data in MONITOR records
using SET MONDATA command. 535
increasing output file number of copies
using the REPEAT command 476
INDICATE
I/O operand 204
LOAD operand 205
PAGING operand 209
QUEUES operand 211
USER operand 213
VECTOR operand 218
indicating how users must enter commands that require
passwords
using the SET PASSWORD command 540
inserting TTY characters
using the TERMINAL CNTL command 642
intercepting machine checks
using TRACE MCH command 688
interpretive execution assist
displaying status of 347
778
VM/XA SP2 CP Command Reference
IPL command 219
issuing CP commands
using CP command
62
L
labeling volumes for CP uses
using the CPFORMAT command 63
limiting autolog commands
using the QUERY CMDLIMIT command 307
limi ting incorrect passwords
using the SET CMDLIMIT command 504
LINK command
usage notes 224
LOADBUF command
loading files from tape
using the SPTAPE LOAD command 598
loading spool files and system data files from tape
using SPTAPE command 586
loading the Forms Control Buffer with an image
using the LOADBUF command 228
loading the Universal Character Set with a print
chain/train image
using the LOADBUF command 228
LOADVFCB command
LOCATE command 236
LOCK command 238
locking in real storage pages of the page able CP nucleus
using the LOCK command 238
locking in selected pages of the a user's virtual storage
using the LOCK command 238
logging on another user's virtual machine 31
using the XA UTOLOG command 751
LOGOFF command 241
LOGON command
logon, automatic 31
M
make a virtual spooling device appear to have the status
"not ready"
using NOT READY command 270
making a device usable or unusable by the control
program or user
using VARY command 734
using VARY PATH command 737
using VARY VECTOR command 743
making a full pack mini-disk shareable or not shareable
using SET SHARED command 557
making an attention interruption pending for your
virtual console
using REQUEST command 478
making an installed Vector Facility available or
unavailable for use
using VARY VECTOR command 743
making an installed Vector Facility logically available or
unavailable for use
using VARY PATH command 737
making other devices available to your virtual machine
using the LINK command 223
merging trace traps il1:to one trace set
using TRACE APPEND command 673
MESSAGE
ALL operand 250
OPERATOR operand 251
userid operand 251
* operand 251
MONITOR
activating event or sample data monitors 267
deactivating event or sample data monitors 267
EVENT operand 256
SAMPLE operand 262
START operand 267
starting the event data monitor 256
starting the sample data monitor 262
STOP operand 267
stopping the event data monitor 256
stopping the sample data monitor 262
monitoring events in a virtual machine
using the PER command (see also TRACE) 275
MSGNOH command
sending no-header messages to specified users 269
N
NOTREADY command
o
ORDER command
p
passwords
indicating how users must enter commands that
require passwords 540
using the QUERY PASSWORD command 375
PER command (see also TRACE)
placing all virtual processors into soft-stop
using STOP command 612
placing selected processors into hard-stop
using STOP command 612
placing user spool files into system HOLD status
using the HOLD command 198
placing your display device in the echo environment
using the ECHO command 182
preventing display stations from accessing the VMjXA
SP system
using the DISABLE command 122
preventing users from logging on to the system
using the HOLD command 198
privilege classes for users
publications 769
PURGE
1M G operand 281
NLS operand 283
PURGE (continued)
NSS operand 285
TRFILES operand 287
UCR operand 289
purging UCR files
using the PURGE UCR command
289
Q
QUERY command
ABEND operand 297
ACCOUNT operand 298
ALLOC operand 299
CACHE operand 301
CHPID operand 305
CMDLIMIT operand 307
COMMANDS operand 308
CPLANGLIST operand 310
CPLANGUAGE operand 311
CPLEVEL operand 312
CPTRACE operand 313
CPUID operand 317
DUMP operand 335
FILES operand 337
FRAMES operand 340
HOLD operand 343
IMG operand 345
IOASSIST operand 347
LINKS operand 348
LOGICAL operand 349
LOGMSG operand 350
MAXSPOOL operand 351
MAXUSERS operand 352
MITIME operand 353
MONDATA operand 355
MONITOR operand 356
NAMES operand 364
NLS operand 366
NSS operand 368
PASSWORD operand 375
PATHS operand 377
PER operand 378
PFnn operand 379
PRINTER operand 383
PROCESSORS operand 381
PUNCH operand 383
QUERY DASD RESERVE operand
QUICKDSP operand 382
READER operand 383
real device operand 320
RECORDING operand 390
SCREEN operand 392
SDF operand 393
SECUSER operand 394
SET operand 396
SHARE operand 401
SRM operand 402
STORAGE operand 404
318
Index
779
QUERY command (continued)
SYSTEM operand 405
TAG operand 407
TDSK operand 409
TERMINAL operand 410
TIME operand 413
TRACE operand 414
TRFILES operand 417
TRSAVE operand 420
TRSOURCE operand 423
UCR operand 428
USERID operand 430
USERS operand 431
VECTOR operand 433
VIRTUAL ALL operand 435
VIRTUAL CONSOLE operand 436
VIRTUAL CPUS operand 440
VIRTUAL CTCA operand 442
VIRTUAL DASD operand 444
VIRTUAL DEVICE operand 447
VIRTU AL GRAF operand 449
VIRTUAL PRINTER operand 451
VIRTUAL PUNCH operand 455
VIRTUAL READER operand 458
VIRTUAL STORAGE operand 460
VIRTUAL TAPES operand 461
VIRTUAL UR operand 462
VIRTUAL VECTOR operand 463
VIRTUAL XSTORE operand 464
V = R operand 465
XSTORE USER operand 467
QUERY CPT RAP command (see QUERY TRSAVE,
QUERY TRSOURCE, QUERY CPT RACE) 316
R
READY command 471
RECORDING command 472
REDEFINE command 474
redefining
the configuration of your virtual machine 75
redefining a virtual device number 91
releasing a user from LOGON HOLD status
using the FREE LOGON command 193
releasing a user's spool files from system HOLD status
using the FREE PRINTER/PUNCH command 194
removing a real processor from a user's exclusive use
using the UNDEDICATE command 731
removing a set of users' spool files from system hold
status
using the FREE command 192
removing a user from LOGON HOLD status
using the FREE command 192
removing a virtual Vector Facility from the virtual
configuration
using the DETACH command 105
T~moving closed spool files from the system
using the PURGE command 278
780
VM/XA SP2 CP Command Reference
removing real devices from the CP system
using the DETACH command 105
removing real devices from virtual machine
configuration
using the DETACH command 105
removing real Expanded Storage from a user's virtual
machine
using the DETACH command 105
removing system trace files
using the PURGE TRFILES command 287
removing the Expanded Storage capability from your
virtual machine configuration 118
removing virtual devices from your virtual machine
using the DETACH command 105
removing virtual processor(s) from your virtual machine
using the DETACH command 105
REPEAT command
repositioning current spool output on a real printer or
punch
using the PORW ARD command 190
repositioning spool output on real printer or punch
using FORWARD command 190
REQUEST command 478
reserving Expanded Storage for CP use
using RETAIN XSTORE command 481
reset accumulated accounting data
using ACNT command 20
RESET command 479
restarting a spooling device after it has been drained
using START command 603
restarting the current output on a real punch or printer
using the BACKSPACE command 35
using the BACKWARD command 35
resuming execution on a specific processor or processors
using BEGIN command 37
resuming execution on a virtual multiprocessor
configuration
using BEGIN command 37
RETAIN XSTORE command 481
retrieving files from other virtual machines
using the TRANSFER command 704
REWIND
command 484
rewinding a tape on a real tape drive
using REWIND command 484
S
sample data collection 262
establishing profile for each type of data
collection 262
SAVESEG command 485
SAVESYS command 487
saving a DCSS into a defined SDP
using SAVESEG command . 485
saving an NSS into a defined SDF
using SAVESYS command 487
saving spool files and system data files on tape
using SPTAPE command 586
saving trace tables on tape
using the TRSAVE command 710
SCREEN
changing color or highlighting definitions 489
selecting a virtual processor
using the CPU command 71
selecting translation table
using the TERMINAL ASCIITBL command 634
using the TERMINAL ATTN command 635
SEND command 491
sending a special message
using SMSG command 571
sending console input to a disconnected virtual machine
using SEND command 491
sending files to other virtual machines
using the TRANSFER command 704
sending high-priority messages to a specified user
using WARNING command 749
sending messages to virtual consoles of other logged on
users
using the MESSAGE command 248
sending no-header messages to specified users
using the MSGNOH command 269
SET command
ABEND operand 498
ACCOUNT operand 499
AUTOPOLL operand 500
CACHE operand 501
CCWTRAN operand 503
CMDLIMIT operand 504
CONCEAL operand 505
CPCONIO operand 507
CPLANGUAGE operand 508
CPTRACE operand 509
CPUID operand 518
DUMP operand 519
EMSG operand 522
IMSG operand 523
10ASSIST operand 524
LINEDIT operand 525
LOGMSG operand 526
MACHINE operand 528
MAXUSERS operand 529
MIH operand 530
MITIME operand 531
MODE (error recording) operand 534
MONDATA operand 535
MSG operand 536
NOPDATA operand 537
NOTRANS command operand 538
PAGEX operand 539
PASSWORD operand 540
PFnn COPY operand 545
PFnn operand 542
PFnn RETRIEVE operand 547
PFnn TAB operand 549
SET command (continued)
QUICKDSP operand 550
RECORD operand 552
RESERVED operand 553
RUN operand 554
SHARE operand 555
SHARED operand 557
SMSG operand 558
SVC76 operand 564
TIMER operand 565
VMCONIO operand 566
WNG operand 567
SET SRM command 559
sets the prompting sequence to be used on a TTY
device.
using the TERMINAL PROMPT command 649
setting a device-end interruption pending for a virtual
device
using READY command 471
setting CCW translation
using the SET CCWTRAN command 503
setting CP on the virtual machine to handle the SVC76
instruction
using SET SVC76 command 564
setting error recording mode for system recovery
. machine checks
using SET MODE command 534
setting maximum number of logon users
using SET MAXUSERS command 529
setting recording mode for a device
using SET RECORD command 552
setting start interpretive execution assist for a V = R
guest
using SET 10ASSIST command 524
setting the reserved page performance option
using SET RESERVED command 553
setting values for the TAB function
using SET PFnn TAB command 549
setting your virtual machine to run after a command is
issued
using SET RUN command 554
SHUTDOWN command 568
simulating an external interruption pending to your
virtual machine
using the EXTERNAL command 184
simulating an initial program load function for your
virtual machine
using the IPL command 219
simulating an I/O interrupt
using SET MlH command 530
simulating the action of RESET and RESTART on a
real console
using the SYSTEM command 625
SLEEP command 569
SMSG command 571
soft-stop 612
SPACE command 572
Index
781
specifying how CP detects autopolling changes
using SET AUTOPOLL command 500
specifying scrolled lines on 3101
using the TERMINAL SCROLL command 650
specifying the forms control buffer image
using the LOADVFCB command 233
specifying the maximum line length for display screen
output
using the TERMINAL LINESIZE command 647
spool files
changing attributes of 39
SPOOL READER/PRINTER/PUNCH/CONSOLE
command 577
SPTAPE command 586
CANCEL operand 594
DUMP operand 595
LOAD operand 598
SCAN operand 601
STOP operand 602
SPTAPE DUMP command 595
SPTAPE LOAD command 598
START command 603
STOP command 612
stopping processing of SPTAPE dump
using SPTAPE STOP command 602
stopping spooling operations on specified real unit
record devices
using the DRAIN command 150
stopping virtual machine for a specific amount of time
using SLEEP command 569
storage
defining for virtual machine 87
STORE command
GUEST STORAGE operand 615
HOST STORAGE operand 617
PSW /CA W /CSW operands 619
REGISTERS operand 620
STATUS operand 621
VECTOR operand 622
storing data in first-level storage
using STORE HOST STORAGE command 617
storing data in second or third-level storage
using STORE GUEST STORAGE command 615
storing data in the current virtual machine PSW, CAW,
orCSW
using STORE PSW/CAW/CSW command 619
storing data into registers
using STORE REGISTERS command 620
storing selected virtual machine data in low storage
locations
using STORE STATUS command 621
summary of changes to this book 759
SYSTEM command 625
T
TAG command
782
627
VM/XA SP2 CP Command Reference
TERMINAL command
APL operand 633
ASCIITBL operand 634
ATTN operand 635
BREAKIN operand 636
BRKKEYoperand 637
CHARDEL operand 639
CNTL operand 642
CONMODE operand 640
ESCAPE operand 643
HILIGHT operand 644
LINEDEL operand 645
LINEND operand 646
LINESIZE operand 647
MODE operand 648
PROMPT operand 649
SCROLL operand 650
TABCHAR operand 651
TEXT operand 652
TYPE operand 653
terminating execution of an active channel program on a
real device
using the HALT command 196
terminating spooling activity on a console device
using the CLOSE command 48
terminating spooling activity on a virtual spooled unit
record
using the CLOSE command 48
terminating virtual machine execution
using the LOGOFF command 241
TRACE CALL
command 680
TRACE command 654
ALL operand 672
APPEND operand 673
BRANCH operand 674
CLEAR operand 676
COUNT operand 677
END operand 678
EXTERNAL/PROGRAM operand 679
GOTO operand 680
GPRs operand 682
INSTRUCTION operand 684
I/O operand 686
MCH operand 688
mnemonic 1 operand 689
mnemonic2 operand 691
options 659
RIO/RSCH/SIO/SIOF/SSCH operands 693
STORE operand 695
SVC/DIAGNOSE/MC operands 697
TPI operand 700
TRAP operand 702
using TRACE command 654
TRACE RETURN
command 680
TRACE TABLE
command 699
tracing alterations to a virtual machine's general
purpose registers
using TRACE GPRs command 682
tracing alterations to virtual machine storage
using TRACE STORE command 695
tracing external or program interruptions
using TRACE EXTERNAL/PROGRAM 679
tracing input/output instructions and/or interruptions
for devices
using TRACE I/O command 686
tracing input/output instructions within a device range
using TRACE mnemonic2 command 691
tracing instructions in a virtual machine
using TRACE INSTRUCTION command 684
tracing interruptions and instructions
using TRACE ALL command 672
tracing real machine events
using SET CPTRACE command 509
tracing RIO/RSCH/SIO/SIOF /SSCH instructions for
I/O devices
using TRACE RIO/RSCH/SIO/SIOF/SSCH
command 693
tracing successful branching instructions
using TRACE BRANCH command 674
tracing supervisor calls, DIAGNOSE instructions or
monitor calls
using TRACE SVC/DIAGNOSE/MC
command 697
tracing Test-Pending-Interrupt instructions
using TRACE TPI command 700
tracing the execution of assembler language instructions
using TRACE mnemonic 1 command 689
TRANSFER command
TRSAVE command
TRSOURCE command 715
W
WARNING
command
749
X
XAUTOLOG command
751
Special Characters
* (ASTERISK COMMAND)
command 17
#CP command
U
UNDEDICATE command 731
UNLOCK command
unlocking page frames
using the UNLOCK command
732
vVARY command
VARY PATH command
VARY VECTOR command
varying a path offline
using VARY OFFLINE PATH command 737
varying a path online
using VARY ONLINE PATH command 737
virtual machine storage
defining for virtual machine 87
VMDUMP
command 745
formatted for the dump viewing facility
using VMDUMP command 745
Index
783
SYSTEM
USABILITY
COMMENTS
Virtual Machine/
Extended Architecture
System Product
Release 2
Please use this form to communicate your comments about the usability of the VM system, with the understanding that IBM may use or distribute whatever information you supply in any way it believes appropriate
without incurring any obligation to you.
Your comments will be sent to the Product Usability Department for appropriate review and action, if any.
Comments may be written in your own language; English is not required.
System Information
If you answer No, please explain.
•
•
•
•
Does the VM system meet your needs?
Is it easy to use and understand?
Are the commands/messages easy to understand and use?
Are the HELP facilities appropriate?
Yes
No
o
o
o
o
o
o
o
o
Customer Information
• What is your occupation?
• How long have you been in this occupation?
• How long have you been using VM?
• Indicate the tasks your job involves:
Eval uation
0
Installation
0
Customization
0
Diagnosis
0
Other
0
Planning
Administration
Operations
End Use
o
o
o
o
Your Comments:
a;
o
z
We appreciate your comments.
If you would like a reply, please supply your name and address on the reverse side of this form; No
postage stamp necessary if mailed in the U.S.A. (Elsewhere, an IBM office or representative will be happy
to forward your comments or you may mail directly to the address in the Edition Notice on the back of the
title page.)
System Usability Comments
Please Do Not Staple
Fold and Tape
Fold and Tape
111111
111111
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES
BUSINESS REPLY MAIL
FIRST CLASS
PERMIT NO. 40
ARMONK, N.Y.
POSTAGE WILL BE PAID BY ADDRESSEE
International Business Machines Corporation
Department 47U MS 914
Neighborhood Road
Kingston, New York 12401
1.1111 •• 1.1.1 •• 111 •••••• 111.1111.1 •• 1•• 1•••• 11.1.1.1
Please Do Not Staple
Fold and Tape
Fold and Tape
If you would like a reply, please print:
Your Name
-----------------------------------------------Department
Company Name
Street Address
City
State
IBM Branch Office serving you
---------,- - -------
--------------------------------Zip Code
----
-
®
PRINTED IN U.S.A.
READER'S
COMMENT
FORM
Virtual Machinel
Extended Architecture
Program Product
Release 2
CP Command Reference
Order No. SC23-0358-1
This manual is part of a library that serves as a reference source for systems analysts, programmers, and
operators of IBM systems. You may use this form to communicate your comments about this publication,
its organization, or subject matter, with the understanding that IBM may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you. Your comments
will be sent to the author's department for whatever review and action, if any, are deemed appropriate.
Note: Copies of IBM publications are not stocked at the location to which this form is addressed. Please
direct any requests for copies of publications, or for assistance in using your IBM system, to your IBM representative or to the IBM branch office serving your locality.
How did you use this publication?
As an introduction
As a text (student)
As a reference manual
As a text (instructor)
For another purpose (explain)
Is there anything you especially like or dislike about the organization, presentation, or writing in this
manual? Helpful comments include general usefulness of the book; possible additions, deletions, and clarifications; specific errors and omissions.
Page Number:
CD
"0
z
Comment:
What is your occupation?
Newsletter number 'of latest Technical Newsletter (if any) concerning this publication:
If you wish a reply, give your name and address:
IBM branch office serving you
Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A. (Elsewhere, an IBM
office or representative will be happy to forward your comments or you may mail directly to the address in
the Edition Notice on the back of the title page.)
SC23-0358-1
Reader's Comment Form
Please Do Not Staple
Fold and Tape
Fold and Tape
111111
111111
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES
BUSINESS REPLY MAIL
FIRST CLASS
PERMIT NO. 40
ARMONK, N.Y.
POSTAGE WILL BE PAID BY ADDRESSEE
International Business Machines Corporation
Department 52Q MS 458
Neighborhood Road
Kingston, New York 12401
1••• 11 •• 1.1.1 •• 111 •••••• 111.1 •• 1.1 •• 1•• 1•••• 11.1.1.1
Fold and Tape
---- ----- -®
---,-
-- --
Please Do Not Staple
Fold and Tape
PRINTED IN U.S.A.
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 Create Date : 2012:06:08 14:44:32-08:00 Modify Date : 2012:06:09 04:55:35-07:00 Metadata Date : 2012:06:09 04:55:35-07:00 Producer : Adobe Acrobat 9.51 Paper Capture Plug-in Format : application/pdf Document ID : uuid:6b5aa07c-a4c1-4366-b56f-592d50026c15 Instance ID : uuid:4255373b-799f-4758-bb76-4ff9daf0e14a Page Layout : SinglePage Page Mode : UseNone Page Count : 802EXIF Metadata provided by EXIF.tools