1 11/26/87 ring_zero_dump, rzd
2
3 Syntax as a command:
4 rzd segname offset length -control_args
5 rzd segno offset length -control_args
6 rzd virtual_pointer offset length -control_args
7
8
9 Syntax as an active function:
10 rzd segname offset length -control_args
11 rzd segno offset length -control_args
12 rzd virtual_pointer offset length -control_args
13
14
15 Function: prints, in octal or hexadecimal format, selected portions of
16 the specified ring 0 segment. This command does not require access to
17 phcs_ gate for those segments accessible through the ring_zero_peek_
18 subroutine. Alternately, data can be displayed as a PL/I structure, in
19 a format similar to that of the probe value request.
20
21
22 Arguments:
23 segname
24 is either a pathname, the name of a ring 0 segment, or an octal
25 segment number to the segment to be dumped. To specify a segment
26 name that consists entirely of octal digits, the name must be
27 preceded by the -name control argument.
28 offset
29 is the octal offset of the first word to be dumped. If both
30 offset and length are omitted, the entire segment is dumped.
31 length
32 is the octal number of words to be dumped. If you supply offset
33 and omit length, one word is dumped.
34
35
36 segno
37 is the octal segment number of a segment to be dumped.
38 virtual_pointer
39 is an ASCII representation of a pointer. See
40 virtual_pointers.gi.info for further descriptions of virtual
41 pointers.
42
43
44 Control arguments:
45 -block N, -bk N
46 dumps words in blocks of N words separated by a blank line. The
47 offset, if being printed, is reset to the initial value at the
48 beginning of each block.
49 -entry_point NAME, -ep NAME
50 specifies that the offset of the first word to be dumped is relative
51 to the location defined by the externally available symbol NAME.
52 Use -entry_point only for object segments created by a compiler or
53 by the create_data_segment command.
54 -name PATH, -nm PATH
55 indicates that PATH is a pathname even though it may look like an
56 octal segment number.
57
58
59 Control arguments for display:
60 -address, -addr
61 prints the address relative to the base of the segment with the
62 data. Default
63 -header, -he
64 prints a header line containing the pathname or segment number of
65 the segment being dumped as well as the date-time printed.
66 Default: to print a header only if the entire segment is being
67 dumped i.e. if you give neither the offset nor the length
68 argument
69 -interpreted, -it
70 prints the data decoded into the indicated format.
71
72
73 -long, -lg
74 prints eight words on a line. Four is the default. This control
75 arguement cannot be used with -4bit, -bcd, -character, -ebcdic8,
76 -ebcdic9, or -short. Its use with these control arguments other
77 than -short results in a line longer than 132 characters.
78 -no_address, -nad
79 does not print the address.
80 -no_header, -nhe
81 does not print the header line even though the entire segment is
82 being dumped.
83 -no_interpret, -nit
84 suppresses printing of the decoded data. Default
85 -no_offset, -nofs
86 does not print the offset. Default
87
88
89 -no_raw, -nraw
90 suppresses printing of the raw data.
91 -no_suppress_duplicates, -nsd
92 indicates that sequential lines are to be printed even if they would
93 be identical to previous lines.
94 -offset N, -ofs N
95 prints the offset relative to N words before the start of the data
96 block being dumped along with the data. If you supply no N, 0 is
97 assumed.
98 -raw
99 indicates that the raw data is to be printed. Default
100 -rest
101 prints from any given offset specified by -offset or the offset
102 argument to the end of the segment.
103
104
105 -short, -sh
106 compacts lines to fit on a terminal with a short line length.
107 Single spaces are placed between fields, and only the two low-order
108 digits of the address are printed except when the high-order digits
109 change. This shortens output lines to less than 80 characters.
110 -suppress_duplicates, -sd
111 indicates that if lines to be printed are identical to the previous
112 line with a single block, they are to be replaced by a short line of
113 equal signs. Default
114
115
116 Control arguments for structure display:
117 -as STRUCTURE_NAME
118 displays the data as a PL/I structure defined by STRUCTURE_NAME.
119 The STRUCTURE_NAME can be a structure defined in one of the system
120 include files supported by the analyze_multics display request.
121 See >doc>ss>azm>structure_names.info for a list of supported
122 include files and structures. Or the STRUCTURE_NAME can be a PL/I
123 structure declared in an object program specified in the -in control
124 argument. See "Notes for structure display" below.
125 -in VIRTUAL_ENTRY
126 identifies an object program compiled with the -table control
127 argument which declares the STRUCTURE_NAME given with the -as
128 control argument. If -in is not given, then STRUCTURE_NAME must be
129 found in one of the segments listed in the structure search list.
130
131
132 -long, -lg
133 displays each element of the structure on a separate line.
134 -short, -sh
135 displays as many structure elements as will fit on a line, and
136 groups elements with common data types together. Default
137
138
139 Control arguments for interpreted data:
140 -4bit
141 prints out, or returns, a translation of the octal or hexadecimal
142 dump based on the Multics unstructured 4-bit byte. The translation
143 ignores the first bit of each 9-bit byte and uses each of the two
144 groups of four bits remaining to generate a digit or a sign.
145 -bcd
146 prints the BCD representation of the words in addition to the octal
147 or hexadecimal dump. There are no nonprintable BCD characters, so
148 periods can be taken literally. It causes the active function to
149 return BCD.
150
151
152 -character, -ch, -ascii
153 prints the ASCII representation of the words in addition to the
154 octal or hexadecimal dump. Characters that cannot be printed are
155 represented by periods. It causes the active function to return
156 ASCII. Default
157 -ebcdic8
158 prints the EBCDIC representation of each eight bits in addition to
159 the octal or hexadecimal dump. It causes the active function to
160 return 8-bit EBCDIC. Characters that cannot be printed are
161 represented by periods. If an odd number of words is requested to
162 dump, the last four bits of the last word do not appear in the
163 translation.
164
165
166 -ebcdic9
167 prints the EBCDIC representation of each 9-bit byte in addition to
168 the octal or hexadecimal dump. Characters that cannot be printed
169 are represented by periods. It causes the active function to return
170 9-bit EBCDIC.
171
172
173 Control arguments for raw data:
174 -hex8
175 prints the dumped words in hexadecimal with nine hexadecimal digits
176 per word rather than octal with 12 octal digits per word.
177 -hex9
178 prints the dumped words in hexadecimal with eight hexadecimal digits
179 per word rather than 12 octal digits per word. Each pair of
180 hexadecimal digits corresponds to the low-order eight bits of each
181 9-bit byte.
182 -octal, -oc
183 display the raw data in octal format, with 12 octal digits per word.
184 Default for raw data
185
186
187 Notes: The defaults for use as a command are -address, -no_interpret,
188 -no_offset, -raw, and -supress_duplicates with -header if the entire
189 segment is printed, and -no_header if only parts of the segment are to
190 be printed. The defaults for use as an active function are
191 -no_address, -no_header, -no_interpret, -no_offset,
192 -no_suppress_duplicates, and -raw.
193
194 Supply only one of -4bit, -bcd, -character, -ebcdic8, or -ebcdic9.
195
196 If you invoke -4bit, -bcd, -character, -ebcdic8, -ebcdic9, -hex8, or
197 -hex9, the information is returned in the specified format only. All
198 other arguments are ignored in active function invocation.
199
200 In the active function the following control arguments are invalid--
201 -address, -as, -block, -header, -offset, and -suppress_duplicates.
202
203
204 When you give conflicting control arguments, the last one on the
205 command line is used.
206
207 The active function returns either raw data in octal or hexadecimal
208 representation or the interpreted data representation.
209
210
211 Notes for structure display:
212 When -as is given, the segname/offset, segno/offset or virtual_ptr is
213 taken as the address of the beginning of the structure. If the whole
214 structure is being displayed, that is the address where display begins.
215 If only certain elements are being displayed, that is the address used
216 to compute offsets of the elements.
217
218
219 The structure reference following -as must be a single string,
220 containing no spaces, used to specify structure elements, array
221 indexes, and substring matching. The structure reference is made up of
222 two parts: a structure element reference and an optional set of match
223 strings. If no match strings are supplied, no string matching is done.
224 The structure element reference syntax consists of one or more element
225 names, separated by periods, and may contain subscripts following some
226 of these element names. The first name in a structure element
227 reference must be a level-one structure reference; partially qualified
228 top-level references are not permitted. Intermediate levels of
229 qualification may be omitted as long as there is no ambiguity.
230
231
232 All subscripts must be supplied as decimal integers. The subscripts
233 can be cross-section references such as "1:4" to reference elements
234 one through four. Asterisk bounds cannot be used: if a cross section
235 is desired, its upper and lower bounds must be given as decimal
236 constants. If an element has more subscripts than are supplied, the
237 complete cross section is printed for the remaining subscripts. To
238 eliminate the need for quoting, subscripts may be surrounded by braces
239 instead of parentheses.
240
241
242 In order to specify that only certain elements be displayed such as
243 all those with names containing the string "time", a set of match
244 strings can be given after the structure element reference. Each match
245 string begins with a slash and is followed by the string itself. The
246 final match string can be followed by a slash, but this is not
247 required. If match strings are specified, any element that matches at
248 least one string is displayed.
249
250
251 Examples of structure display:
252 rzd pvt -as pvt
253 the whole structure "pvt".
254 rzd pvt -as pvt.n_entries
255 the single element "n_entries" in the structure "pvt".
256 rzd sst_seg -as sst/time/,
257 rzd sst_seg -as sst/time
258 any elements in the structure "sst" containing the string
259 "time". Note that the final slash is optional.
260 rzd sst_seg -as sst/time/meter/
261 any elements in the structure "sst" containing either the
262 string "time" or the string "meter".
263
264
265 rzd sst_seg -as sst.space3
266 element three of "sst.space".
267 rzd sst_seg -as sst.space2:4
268 elements two, three, and four of "sst.space".
269 rzd sst_seg -as sst.space
270 all elements of "sst.space".
271 rzd sst_seg -as sst.level1
272 both elements of the "level" array for "sst.level1"
273 rzd sst_seg -as sst.level1.ausedp,
274 rzd sst_seg -as sst.level.ausedp1
275 the single element "ausedp" of the "level" array for
276 "sst.level1"
277
278
279 Structure output format:
280 The default output format is a compressed form, which places as many
281 values on a line as will fit within the line length. The -long control
282 argument places one value on a line. The short form, additionally,
283 collects all bit1 flags and displays them, at the end of the display
284 for each substructure or array element, in two groups: one listing all
285 the flags that were on "1"b and one for all the ones that were off
286 "0"b.
287
288
289 All PL/I data types are displayed in the same representations used by
290 probe. Additionally, the following special formats are used:
291
292 1. Bit strings are displayed in octal if the length is divisible by
293 three, in hex if divisible by four, and as bit strings otherwise.
294
295 2. Character strings are displayed as a string concatenated with a
296 repeated constant if the string is padded on the right with more
297 than 16 nulls, spaces, or octal 777 characters.
298
299 3. Large-precision > 51 fixed binary values are also displayed as
300 clock readings if their values represent clock readings within 10
301 years of the present.