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