1 :Info: display: d:
  2 1984-11-19  display, d
  3 
  4 Syntax:  d VIRTUAL-ADDR {EXP} {RANGE} {-ctl_args}
  5 
  6 
  7 Syntax as an active request:
  8         [d VIRTUAL-ADDR {EXP} {RANGE} {-ctl_args}]
  9 
 10 
 11 Function: displays a selected portion of a segment in the FDUMP.
 12 As an active request, the value(s) that would have been displayed are
 13 returned as the active request result.
 14 
 15 
 16 Arguments:
 17 VIRTUAL-ADDR
 18    specifies the initial offset of the virtual address space to be
 19    dumped.  May be a segment number, name, or symbolic address (e.g.,
 20    64, prds, prds$am_data).    Do a 'help virtual_address' for more
 21    detailed information on acceptable virtual-address constructs.
 22 EXP
 23    is an expression, which is either an octal value or a VIRTUAL-ADDR
 24    construct yielding an octal value.  This value can be positive or
 25    negative, specified by the plus or minus sign.
 26 RANGE
 27    specifies the octal number of words to be dumped.  (default: dump
 28    one word; or if an ITS pointer format is specified, dump two words)
 29 
 30 
 31 Control arguments (mode specification):
 32 -character, -ch, -ascii
 33    displays the selected number of stored words as ascii characters.
 34    Characters that cannot be printed are represented as periods.  As
 35    an active request, returns the character representation of data
 36    stored at the requested address.
 37 -instruction, -inst
 38    displays the selected number of stored words as instructions.
 39    Usage as an active request is not allowed.
 40 -octal, -oc
 41    displays the selected number of stored words in octal.  (default)
 42    When used as an active request, returns data stored at the
 43    requested address in octal format.
 44 
 45 
 46 -ptr, -p
 47    displays the selected number of word pairs as ITS pointers.  When
 48    used as an active request, returns the stored data in the form
 49    SEGNO|OFFSET where the components are octal numbers.
 50 -ptrx, -px
 51    displays the selected number of word pairs as pointers and expands
 52    the segno|offset to a segment name.  Usage as an active request is
 53    not allowed.
 54 
 55 
 56 -pptr, -pp
 57    displays each of the selected number of words as a packed-pointer.
 58    When used as an active request, returns the stored data in the form
 59    SEGNO|OFFSET where the component are octal numbers.
 60 -pptrx, -ppx
 61    displays the selected number of words as packed-pointers and expands
 62    the segno|offset to a segment name.  Usage as an active request is
 63    not allowed
 64 
 65 
 66 Control arguments (structure display):
 67 -as STRUCTURE_NAME
 68    displays stored data as a PL/I structure defined by STRUCTURE_NAME.
 69    This is usually a structure name from a system-defined hardcore
 70    include file.  For a list of supported STRUCTURE_NAMEs, type:
 71       help structure_names
 72 
 73    The address given in the display request is taken as the address of
 74    the beginning of the structure.  If the whole structure is being
 75    displayed, that is the address where display begins.  If only
 76    certain elements are being displayed, that is the starting address
 77    to which the computed offset of the named element is applied.
 78 
 79 
 80    The structure reference following -as must be a single string,
 81    containing no spaces, and follows the syntax described below.  The
 82    single string is used to specify structure elements, array indexes,
 83    and substring matching.  Usage as an active request is not allowed.
 84 
 85 -long, -lg
 86    displays each element of the structure on a separate line.  This
 87    control argument is only implemented with -as.
 88 
 89 
 90 Notes on structure names:
 91 The structure reference is made up of two parts: a structure element
 92 reference, and an optional set of match strings.  If no match strings
 93 are supplied, all structure elements are displayed.
 94 
 95 The structure element reference syntax consists of one or more element
 96 names, separated by periods, and may contain subscripts following some
 97 of these element names.  The first name in a structure element
 98 reference must be a level one structure reference; partially qualified
 99 top level references are not permitted.  Intermediate levels of
100 qualification may be omitted as long as there is no ambiguity.
101 
102 
103 The following examples show various kinds of structure references
104 which may be given when displaying a location as a structure.
105 
106 pvt
107    The whole structure "pvt".
108 pvt.n_entries
109    The single element "n_entries" in the structure "pvt".
110 
111 
112 All subscripts must be supplied as decimal integers.  The subscripts
113 may be cross-section references such as "(1:4)" to reference elements
114 one through four.  Asterisk bounds may not be used: if a cross-section
115 is desired, its upper and lower bounds must be given as decimal
116 constants.  If an element has more subscripts than are supplied, the
117 complete cross-section is printed for the remaining subscripts.
118 
119 
120 The parenthesis normally surrounding an array index specification
121 would trigger an iteration when given in the request line.  To avoid
122 quoting, subscripts may be surrounded by braces instead of parentheses.
123 
124 sst.space
125    all elements of "sst.space".
126 sst.space{3}
127    element three of the "sst.space" array.
128 sst.space{2:4}
129    cross-section of elements two, three, and four of the "sst.space".
130 
131 
132 sst.level{1}
133    both elements of the "level" array-of-structures.
134 sst.level{1}.ausedp, sst.level.ausedp{1}
135    the single element "ausedp" of the "level" array of structures.
136    As in PL/I, the index may follow the array element, or any
137    sub-element of that array.
138 
139 
140 In order to specify that only certain elements be displayed (such as
141 all those with names containing the string "time"), a set of match
142 strings may be given after the structure element reference.  Each match
143 string begins with a slash and is followed by the string itself.  The
144 final match string may be followed by a slash, but this is not
145 required.  If match strings are specified, any element which matches at
146 least one string will be displayed.
147 
148 sst/time/,  sst/time
149    Any elements in the structure "sst" containing the string "time".
150    Note that the final slash is optional.
151 sst/time/meter/
152    Any elements in the structure "sst" containing either the string
153    "time" or the string "meter".
154 
155 
156 Notes on structure output format:
157 The default output format is a compressed form, which places as many
158 values on a line as will fit within the line length.  The -long control
159 argument places one value on a line.  The short form, additionally,
160 collects all bit(1) flags and displays them at the end of the display
161 for each substructure or array element, in two groups: one listing all
162 the flags which were on ("1"b), and one for all the ones which were off
163 ("0"b).
164 
165 
166 All PL/I datatypes are displayed in the same representations used by
167 probe.  Additionally, the following special formats are used:
168 
169  1) Bit strings are displayed as octal, if the length is divisible by
170     three, in hex if divisible by four and not three, and as bit
171     strings otherwise.
172  2) Character strings are displayed as a string concatenated with a
173     repeated constant, if the string is padded on the right with more
174     than sixteen nulls, spaces, or octal 777 characters.
175  3) Large precision (> 51) fixed binary values are also displayed as
176     clock readings if the stored value represents a clock reading
177     within ten years of the present.
178 
179 
180 Examples:
181 d 75|560 2
182    displays the two words in seg number 75 starting at octal offset
183    560.
184 
185 d pds|560 2
186    displays the two words in the segment named pds starting at octal
187    offset 560.
188 
189 d pds$trace
190    displays one word in the pds segment beginning at the offset
191    specified by $trace.
192 
193 
194 display 244|260 +20 4
195    displays four words of segment number 244 starting at octal offset
196    300.
197 
198 d sp 20
199    displays 20 octal words starting with the segment offset defined in
200    the azm internal temporary pointer.  For information about temporary
201    pointers, type:  help set
202 
203 
204 d sst$cmp,* +sst$cmesize sst$strsize
205    causes the word at sst$cmp to be used as an indirect word (or an
206    indirect pointer if the resultant address pair has ITS
207    modification) to develop the starting virtual address.  The value
208    stored at sst$cmesize will then be added to the starting offset to
209    obtain a 'final' starting address.  The range, or number of words
210    to be displayed, is specified by the value stored at sst$strsize.
211 
212 
213 d sst|2 -as apte
214    displays the APTE entry at the given offset in the SST as it is
215    defined by apte.incl.pl1
216 
217 
218 :hcom:
219 /****^  HISTORY COMMENTS:
220   1) change(2022-11-14,GDixon), approve(2023-01-16,MCR10129),
221      audit(2023-02-28,Swenson), install(2023-02-28,MR12.8-1054):
222       A) Correct typos and vi-reported formatting errors.
223                                                    END HISTORY COMMENTS */
224