1 10/27/83  runtime_symbol_info_
  2 
  3 This subroutine's various entry points return runtime information about
  4 program variables (address, type, etc.)  for programs compiled with
  5 symbol tables (-table).  Declarations for the entry points and the
  6 structures they return can be found in the include file
  7 runtime_symbol_info_.incl.pl1.  Most entry points take a pointer
  8 (symbol_ptr) to a symbol node, which can be obtained by calling
  9 stu_$find_runtime_symbol.  Rather than return error codes, these entry
 10 points return null pointers or zero fields in their structures if the
 11 symbol node does not contain the requested information.  Also see the
 12 various stu_ entry points for additional information about program
 13 variables and text.
 14 
 15 
 16 WARNING:
 17 Use of these subroutines requires a good understanding of the symbol
 18 table structures generated by translators.  For example, given a Pascal
 19 symbol "foo" declared variable of type packed array [1..10] of char,
 20 runtime_symbol_info_ does not return any useful information because
 21 this information resides in the symbol node for the TYPE of "foo".
 22 
 23 
 24 Entry points in runtime_symbol_info_:
 25    (List is generated by the help command)
 26 
 27 
 28 :Entry:  address:  10/27/83 runtime_symbol_info_$address
 29 
 30 
 31 Function:  This entry point returns information about the location of a
 32 symbol at runtime.
 33 
 34 
 35 Syntax:
 36 declare runtime_symbol_info_$address entry (ptr, ptr, fixed bin (35));
 37 call runtime_symbol_info_$address (symbol_ptr, info_ptr, code);
 38 
 39 
 40 Arguments:
 41 symbol_ptr
 42    is a pointer to a symbol node.  (Input)
 43 info_ptr
 44    is a pointer to a user-allocated structure to be filled in by the
 45    call.  This structure, called runtime_address_info, is declared
 46    in the include file runtime_symbol_info_.incl.pl1.
 47 code
 48    is error_table_$unimplemented_version if
 49    runtime_address_info.version has not been set to a valid version for
 50    the structure.
 51 
 52 
 53 :Entry:  array:  10/27/83 runtime_symbol_info_$array
 54 
 55 
 56 Function:  This entry point returns information about array storage
 57 allocation.
 58 
 59 
 60 Syntax:
 61 declare runtime_symbol_info_$array entry (ptr, ptr, fixed bin (35));
 62 call runtime_symbol_info_$array (symbol_ptr, info_ptr, code);
 63 
 64 
 65 Arguments:
 66 symbol_ptr
 67    is a pointer to a symbol node.  (Input)
 68 info_ptr
 69    is a pointer to a user-allocated structure to be filled in by the
 70    call.  This structure, called runtime_array_info, is declared in
 71    the include file runtime_symbol_info_.incl.pl1.
 72 code
 73    is error_table_$unimplemented_version if runtime_array_info.version
 74    has not been set to a valid version for the structure.
 75 
 76 
 77 :Entry:  array_dims:  10/27/83 runtime_symbol_info_$array_dims
 78 
 79 
 80 Function:  This entry point returns the number of dimensions of an
 81 array.  It returns null if the symbol has no dimensions.
 82 
 83 
 84 Syntax:
 85 declare runtime_symbol_info_$array_dims entry (pointer) returns
 86       (fixed bin);
 87 n_dims = runtime_symbol_info_$array_dims (symbol_ptr);
 88 
 89 
 90 Arguments:
 91 symbol_ptr
 92    is a pointer to a symbol node.  (Input)
 93 
 94 
 95 :Entry:  brother:  10/27/83 runtime_symbol_info_$brother
 96 
 97 
 98 Function:  This entry point, given a pointer to a symbol node for an
 99 aggregate component, returns a pointer to the next component at the
100 same level or null if this is the last component at this level of the
101 aggregate.  Given a pointer to a formal parameter, it returns a pointer
102 to the node for the next parameter, or null if there is no next
103 parameter.  Given a pointer to any other symbol node whose level is <=
104 1 (non_aggregate or top-level structure) and which has a name, returns
105 a pointer to the next element on the list of symbol nodes ordered
106 alphabetically by size.  It returns null if there is no next symbol.
107 
108 
109 Syntax:
110 declare runtime_symbol_info_$brother entry (pointer) returns (pointer);
111 brother_ptr = runtime_symbol_info_$brother (symbol_ptr);
112 
113 
114 Arguments:
115 symbol_ptr
116    is a pointer to a symbol node.  (Input)
117 
118 
119 :Entry:  father:  10/27/83 runtime_symbol_info_$father
120 
121 
122 Function:  This entry point, given a pointer to a symbol node for an
123 aggregate component, returns a pointer to the symbol node for its
124 parent aggregate.  Given a pointer to a symbol node whose level is <= 1
125 and which has a name, returns a pointer to the runtime block node that
126 represents the block in which the identifier is declared.  It returns
127 null if father = 0 or if there is no father field.
128 
129 
130 Syntax:
131 declare runtime_symbol_info_$father entry (pointer) returns (pointer);
132 father_ptr = runtime_symbol_info_$father (symbol_ptr);
133 
134 
135 Arguments:
136 symbol_ptr
137    is a pointer to to a symbol node.  (Input)
138 
139 
140 :Entry:  father_type:  10/27/83 runtime_symbol_info_$father_type
141 
142 
143 Function:  This entry point, given a pointer to a symbol node for a
144 Pascal enumerated type element, returns a pointer to the symbol node
145 for the parent type.  Otherwise, it returns null.
146 
147 
148 Syntax:
149 declare runtime_symbol_info_$father_type entry (pointer) returns
150      (pointer);
151 father_type_ptr = runtime_symbol_info_$father_type (symbol_ptr);
152 
153 
154 Arguments:
155 symbol_ptr
156    is a pointer to a symbol node.  (Input)
157 
158 
159 :Entry:  level:  10/27/83 runtime_symbol_info_$level
160 
161 
162 Function:  This entry point, given a pointer to a symbol node for an
163 aggregate component, returns the level number of the component in the
164 aggregate or zero if the symbol is not an aggregate component.  Fields
165 in a Pascal "with" block are at level 0.
166 
167 
168 Syntax:
169 declare runtime_symbol_info_$level entry (pointer) returns (fixed bin);
170 level_number = runtime_symbol_info_$level (symbol_ptr);
171 
172 
173 Arguments:
174 symbol_ptr
175    is a pointer to a symbol node.  (Input)
176 
177 
178 :Entry:  n_variants:  10/27/83 runtime_symbol_info_$n_variants
179 
180 
181 Function:  This entry point, given a pointer to a symbol node for a tag
182 field in a Pascal record, returns the number of case variants for the
183 field.  It returns 0 if the symbol is not a tag field.
184 
185 
186 Syntax:
187 declare runtime_symbol_info_$n_variants entry (pointer) returns
188      (fixed bin);
189 n_variants = runtime_symbol_info_$n_variants (symbol_ptr);
190 
191 
192 Arguments:
193 symbol_ptr
194    is a pointer to a symbol node.  (Input)
195 
196 
197 :Entry:  name:  10/27/83 runtime_symbol_info_$name
198 
199 
200 Function:  This entry point, given a pointer to a symbol node, returns
201 a pointer to the symbol's name in packed form (see "Notes" below).  It
202 returns null if there is no name.
203 
204 
205 Syntax:
206 declare runtime_symbol_info_$name entry (pointer) returns (pointer);
207 name_string = runtime_symbol_info_$name (symbol_ptr) -> acc.string;
208 
209 
210 Arguments:
211 symbol_ptr
212    is a pointer to a symbol node.  (Input)
213 
214 
215 Notes: The variable acc.string is declared in the include file
216 acc.incl.pl1:
217 
218    dcl 1 acc based aligned,
219          2 num_chars fixed bin (9) unsigned unaligned,
220          2 string char (0 refer (acc.num_chars)) unaligned;
221 
222 
223 
224 :Entry:  next:  10/27/83 runtime_symbol_info_$next
225 
226 
227 Function:  This entry point, given a pointer to a symbol node, returns
228 a pointer to the symbol node for the next identifier having the same
229 name as the current identifier.  It returns null if there is no name or
230 if there are no more identifiers with the same name.
231 
232 
233 Syntax:
234 declare runtime_symbol_info_$next entry (pointer) returns (pointer);
235 next_symbol_ptr = runtime_symbol_info_$next (symbol_ptr);
236 
237 
238 Arguments:
239 symbol_ptr
240    is a pointer to a symbol node.  (Input)
241 
242 
243 :Entry:  son:  10/27/83 runtime_symbol_info_$son
244 
245 
246 Function:  This entry point, given a pointer to a symbol node for an
247 aggregate, returns a pointer to the symbol node for the aggregate's
248 first component.  Given a pointer to a symbol node for a procedure, it
249 returns a pointer to the symbol node for the first formal parameter.
250 Given a pointer to a symbol node for an enumerated type, it returns a
251 pointer to the symbol node for the first element of the type.
252 Otherwise, it returns null.
253 
254 
255 Syntax:
256 declare runtime_symbol_info_$son entry (pointer) returns (pointer);
257 son_ptr = runtime_symbol_info_$son (symbol_ptr);
258 
259 
260 Arguments:
261 symbol_ptr
262    is a pointer to a symbol node.  (Input)
263 
264 
265 :Entry:  successor:  10/27/83 runtime_symbol_info_$successor
266 
267 
268 Function:  This entry point, given a pointer to a symbol node for a
269 Pascal enumerated type element, returns a pointer to the symbol node
270 for the next element in the set of enumerated values for the type, or
271 null if there is no next element or no successor field.
272 
273 
274 Syntax:
275 declare runtime_symbol_info_$successor entry (pointer) returns
276      (pointer);
277 successor_ptr = runtime_symbol_info_$successor (symbol_ptr);
278 
279 
280 Arguments:
281 symbol_ptr
282    is a pointer to a symbol node.  (Input)
283 
284 
285 :Entry:  type:  10/27/83 runtime_symbol_info_$type
286 
287 
288 Function:  This entry point returns information about the data type of
289 a symbol.
290 
291 
292 Syntax:
293 declare runtime_symbol_info_$type entry (pointer, pointer);
294 call runtime_symbol_info_$type (symbol_ptr, info_ptr);
295 
296 
297 Arguments:
298 symbol_ptr
299    is a pointer to a symbol node.  (Input)
300 info_ptr
301    is a pointer to a user-allocated structure to be filled in by the
302    call.  This structure, called runtime_type_info, is declared in
303    the include file runtime_symbol_info_.incl.pl1.
304 
305 
306 :Entry:  variant:  10/27/83 runtime_symbol_info_$variant
307 
308 
309 Function:  This entry point, given a pointer to a symbol node for a
310 Pascal record field with case variants, returns information describing
311 the variants.  If the symbol is not a Pascal symbol, number_of_variants
312 is returned as 0 and the rest of the information is invalid.
313 
314 
315 Syntax:
316 declare runtime_symbol_info_$variant entry (ptr, ptr, fixed bin (35));
317 call runtime_symbol_info_$variant (symbol_ptr, info_ptr, code);
318 
319 
320 Arguments:
321 symbol_ptr
322    is a pointer to a symbol node.  (Input)
323 info_ptr
324    is a pointer to a user-allocated structure to be fille din by the
325    call.  This structure, called runtime_variant_info, is declared in
326    the include file runtime_symbol_info_.incl.pl1.
327 code
328    is error_table_$unimplemented_version if
329    runtime_variant_info.version has not been set to a valid version for
330    the structure.
331