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