1 10/27/83 stu_
2
3
4 The stu_ symbol table utility subroutine provides a number of entry
5 points for retrieving information from the runtime symbol table section
6 of an object segment generated by the PL/I, FORTRAN, or COBOL
7 compilers. A runtime symbol table is produced when a program is
8 compiled with the -table control argument or when a runtime symbol
9 table is required to support a feature of the language such as PL/I
10 data-directed or FORTRAN NAMELIST input/output statements. A partial
11 symbol table, containing only a statement map, is produced when a
12 program is compiled with the -brief_table control argument.
13
14
15 Entry points in stu_:
16 List is generated by the help command
17
18
19 :Entry: decode_runtime_value: 02/09/83 stu_$decode_runtime_value
20
21
22 Function: This entry point is called to decode encoded values e.g.
23 string length or arithmetic precision stored in a runtime_symbol node.
24
25
26 Syntax:
27 declare stu_$decode_runtime_value entry fixed bin35 ptr ptr ptr
28 ptr ptr fixed bin returns fixed bin35;
29 value = stu_$decode_runtime_value v block_ptr stack_ptr link_ptr
30 text_ptr ref_ptr code;
31
32
33 Arguments:
34 v
35 is an encoded value from a runtime_symbol node, e.g.,
36 runtime_symbol.size. Input
37 block_ptr
38 points to the runtime_block node that corresponds to the block that
39 contains the declaration of the identifier whose runtime_symbol node
40 contains the encoded value. Normally, the value of block_ptr is
41 obtained from a call to the stu_$find_runtime_symbol entry point
42 described below. Input
43
44
45 stack_ptr
46 is a pointer to the active stack frame associated with the procedure
47 or begin block that corresponds to the specified runtime_block node.
48 If the specified block node is quick, stack_ptr should point to the
49 stack frame in which the quick block is placing its automatic
50 storage. If the specified block is not active and does not have a
51 current stack frame, stack_ptr can be null. Input
52 link_ptr
53 is a pointer to the linkage section of the specified block. If
54 link_ptr is null, the stu_$decode_runtime_value entry point attempts
55 to obtain the linkage pointer, if it is needed, from the linkage
56 offset table LOT; decoding fails if a pointer to the linkage
57 section is needed and text_ptr, block_ptr, and link_ptr are all null
58 or if the segment has never been executed. Input
59
60
61 text_ptr
62 is a pointer to the base of the object segment that contains the
63 specified block. If text_ptr is null, the stu_$decode_runtime_value
64 entry point attempts to obtain the text pointer, if it is needed,
65 from the active stack frame or the block_ptr; decoding fails if a
66 pointer to the object segment is needed and stack_ptr, block_ptr,
67 and text_ptr are all null. Input
68 ref_ptr
69 is the value of the pointer to be used as locator qualifier if the
70 variable that corresponds to the runtime_symbol node that contains
71 the encoded value is based. The value of ref_ptr can often be
72 determined by means of the stu_$get_implicit_qualifier entry point
73 described below. Input
74 code
75 is a status code. Output It can be:
76 0 if the encoded value was successfully decoded.
77 1 if the value could not be decoded.
78 value
79 is the decoded value if the value of code is 0. Output
80
81
82 :Entry: decode_runtime_value_extended: 10/27/83 stu_$decode_runtime_value_extended
83
84
85 Function: This entry point is called to decode extended encoded values,
86 such as are stored in a Pascal symbol node.
87
88
89 Syntax:
90 declare stu_$decode_runtime_value_extended entry fixed bin35 ptr
91 ptr ptr ptr ptr ptr fixed bin returns fixed bin35;
92 value = stu_$decode_runtime_value_extended v block_ptr
93 stack_ptr link_ptr text_ptr ref_ptr symbol_ptr code;
94
95
96 Arguments:
97 v
98 is an extended encoded value from an appropriate symbol node, e.g.,
99 pascal_size declared in pascal_symbol_node.incl.pl1. Input
100 block_ptr
101 points to the runtime_block node that corresponds to the block that
102 contains the declaration of the identifier whose symbol node
103 contains the encoded value. Normally, the value of block_ptr is
104 obtained from a call to the stu_$find_runtime_symbol entry point
105 described below. Input
106
107
108 stack_ptr
109 is a pointer to the active stack frame associated with the procedure
110 or begin block that corresponds to the specified runtime_block node.
111 If the specified block node is quick, stack_ptr should point to the
112 stack frame in which the quick block is placing its automatic
113 storage. If the specified block is not active and does not have a
114 current stack frame, stack_ptr can be null. Input
115 link_ptr
116 is a pointer to the linkage section of the specified block. If
117 link_ptr is null, this entry point attempts to obtain the linkage
118 pointer, if it is needed, from the linkage offset table LOT;
119 decoding fails if a pointer to the linkage section is needed and
120 text_ptr, block_ptr, and link_ptr are all null or if the segment
121 has never been executed. Input
122
123
124 text_ptr
125 is a pointer to the base of the object segment that contains the
126 specified block. If text_ptr is null, this entry point attempts to
127 obtain the text pointer, if it is needed, from the active stack frame
128 or the block_ptr; decoding fails if a pointer to the object segment
129 is needed and stack_ptr, block_ptr, and text_ptr are all null. Input
130 ref_ptr
131 is the value of the pointer to be used as locator qualifier if the
132 variable that corresponds to the symbol node that contains the
133 encoded value is based. The value of ref_ptr can often be determined
134 by means of the stu_$get_implicit_qualifier entry point described
135 below. Input
136 symbol_ptr
137 is a pointer to the runtime symbol node. Input
138 code
139 is a status code. Output It can be:
140 0 if the encoded value was successfully decoded.
141 1 if the value could not be decoded.
142 value
143 is the decoded value if the value of code is 0. Output
144
145
146 :Entry: find_block: 02/09/83 stu_$find_block
147
148
149 Function: This entry point, given a pointer to the symbol table header
150 of an object segment, searches the runtime symbol table of the object
151 segment for the runtime_block node that corresponds to a given
152 procedure block in the object program.
153
154
155 Syntax:
156 declare stu_$find_block entry ptr char* aligned returns ptr;
157 block_ptr = stu_$find_block header_ptr name;
158
159
160 Arguments:
161 header_ptr
162 points to a symbol table header. Input
163 name
164 is the ASCII name of the runtime_block node to be found. The name
165 of a runtime_block node is the same as the first name written on the
166 procedure statement that corresponds to the runtime_block node.
167 Input
168 block_ptr
169 is set to point to the runtime_block node if it is found or is null
170 if the block is not found. Output
171
172
173 :Entry: find_containing_block: 02/09/83 stu_$find_containing_block
174
175
176 Function: This entry point, given a pointer to the symbol table header
177 of a standard object segment and an offset into the text section,
178 returns a pointer to the runtime_block node corresponding to the
179 smallest procedure or begin block that lexically contains the source
180 line for the instuction pointed to, or null if none could be found.
181
182
183 Syntax:
184 declare stu_$find_containing_block entry ptr fixed bin18 unsigned
185 returns ptr;
186 bp = stu_$find_containing_block hp offset;
187
188
189 Arguments:
190 hp
191 is a pointer to the symbol table header. Input
192 offset
193 is the offset from the base of the segment of an instruction.
194 Input
195 bp
196 is the returned pointer to the runtime_block node, or null.
197
198
199 :Entry: find_header: 02/09/83 stu_$find_header
200
201
202 Function: This entry point, given an ASCII name and/or a pointer to
203 any location in a possibly bound object segment, searches the given
204 segment for the symbol table header corresponding to the designated
205 program.
206
207
208 Syntax:
209 declare stu_$find_header entry ptr char32 aligned fixed bin24
210 returns ptr;
211 header_ptr = stu_$find_header seg_ptr name bc;
212
213
214 Arguments:
215 seg_ptr
216 points to any location in the object segment. Input
217 name
218 is the ASCII name of the program whose symbol header is to be found.
219 If seg_ptr is null, name is treated as a reference name and the
220 segment is determined according to the user's search rules. If the
221 designated segment is bound, name specifies the component. Input
222 bc
223 is the bit count of the object segment; if 0, the stu_$find_header
224 entry point determines the bit count itself. Input
225 header_ptr
226 points to the symbol table header if it is found or is null if the
227 header is not found. Output
228
229
230 Notes:
231 Since determining the bit count of a segment is relatively expensive,
232 the user should provide the bit count if he has it available e.g. as
233 a result of a call to hcs_$initiate_count.
234
235
236 :Entry: find_runtime_symbol: 02/09/83 stu_$find_runtime_symbol
237
238
239 Function: This entry point, given a pointer to the runtime_block node
240 that corresponds to a procedure or begin block, searches for the
241 runtime_symbol node that corresponds to a specified identifier name.
242 If the name is not found in the given block, the parent block is
243 searched. This is repeated until the name is found or the root block
244 of the symbol structure is reached, in which case a null pointer is
245 returned.
246
247
248 Syntax:
249 declare stu_$find_runtime_symbol entry ptr char* aligned ptr
250 fixed bin returns ptr;
251 symbol_ptr = stu_$find_symbol block_ptr name found_ptr steps;
252
253
254 Arguments:
255 block_ptr
256 points to the runtime_block node in which the search is to begin.
257 Input
258 name
259 is the ASCII name of the runtime_symbol node to be found. A name
260 can be a fully or partially qualified structure name e.g.
261 "a.b.c", in which the runtime_symbol node that corresponds to the
262 lowest level item is located. Input
263 found_ptr
264 is set to point to the runtime_block node in which the specified
265 identifier is found. Output
266
267
268 steps
269 is set to the number of steps that must be taken along the
270 pl1_stack_frame.display_ptr chain to locate the stack_frame
271 associated with the block designated by found_ptr starting at the
272 stack frame for the block designated by block_ptr. See "Example"
273 below. If the given identifier is found in the specified block,
274 the value of steps is 0. Output
275
276 If the search fails, the value of steps indicates the reason for the
277 failure as follows:
278 -1 block_ptr is null
279 -2 more than 64 structure levels
280 -3 name too long
281 -4 no declaration found
282 -5 symbol reference is ambiguous
283
284
285 symbol_ptr
286 is set to point to the runtime_symbol node if it is found or is null
287 if an error occurs. Output
288
289
290 :Entry: get_block: 02/09/83 stu_$get_block
291
292
293 Function: Given a pointer to the stack frame, gets a pointer to the
294 runtime_block for the entry that created the frame and to the header
295 for the object segment. This entry point is equivalent to
296 stu_$get_runtime_block except that the location is determined by the
297 information in the stack frame.
298
299
300 Syntax:
301 declare stu_$get_block entry ptr ptr ptr;
302 call stu_$get_block sp hp bp;
303
304
305 Arguments:
306 sp
307 points to the stack frame in question. Input
308 hp
309 points to the header for the runtime symbol table of the object
310 segment that contains the entry that created the frame. If is set
311 to null if the object segment has no symbol table, or if the object
312 segment cannot be interpreted. Output
313 bp
314 points to the runtime_block node for the entry that created the
315 frame. It is set to null if the object segment has no symbol table
316 or could not be interpreted.
317
318
319 :Entry: get_implicit_qualifier: 02/09/83 stu_$get_implicit_qualifier
320
321
322 Function: This entry point, given a pointer to the symbol node that
323 corresponds to a PL/I based variable, attempts to return the value of
324 the pointer variable that appeared in the based declaration e.g. the
325 value of "p" in "dcl a based p;". A null pointer is returned if the
326 declaration does not have the proper form or if the value of the
327 pointer cannot be determined.
328
329
330 Syntax:
331 declare stu_$get_implicit_qualifier entry ptr ptr ptr ptr ptr
332 returns ptr;
333 ref_ptr = stu_$get_implicit_qualifier block_ptr symbol_ptr
334 stack_ptr link_ptr text_ptr;
335
336
337 Arguments:
338 block_ptr
339 points to the runtime_block node that corresponds to the procedure
340 or begin block in which the based variable is declared. Input
341 symbol_ptr
342 points to the runtime_symbol node that corresponds to the based
343 variable. Input
344 stack_ptr
345 is a pointer to the active stack frame associated with the block in
346 which the based variable is declared. If the specified block node
347 is quick, stack_ptr should point to the stack frame in which the
348 quick block is placing its automatic storage. If the specified
349 block is not active and does not have a current stack frame,
350 stack_ptr can be null. Input
351
352
353 link_ptr
354 is a pointer to the linkage section of the specified block. If
355 link_ptr is null, the stu_$get_implicit_qualifier entry point
356 attempts to obtain the linkage pointer, if it is needed, from the
357 active stack frame; the implicit qualifier cannot be determined if a
358 pointer to the linkage section is needed and stack_ptr and link_ptr
359 are both null. Input
360 text_ptr
361 is a pointer to the base of the object segment that contains the
362 specified block. If text_ptr is null, the
363 stu_$get_implicit_qualifier entry point attempts to obtain the text
364 pointer, if it is needed, from the active stack frame; the implicit
365 qualifier cannot be determined if a pointer to the object section is
366 needed and stack_ptr and text_ptr are both null. Input
367 ref_ptr
368 is set to the value of the implicit qualifier or is null if the
369 value cannot be determined. Output
370
371
372 Notes:
373 A null pointer is returned for any one of a number of reasons. Some of
374 these are:
375
376 The based variable was declared without an implicit qualifier, e.g.,
377 dcl a based;
378 Determining the implicit qualifier involves evaluating an expression,
379 for example, the based variable was declared as:
380 dcl a basedpi;
381 The based variable was declared with an implicit qualifier, but it is
382 not possible to obtain the address of the qualifier e.g. it is an
383 authentic pointer and stack_ptr is null.
384
385
386 :Entry: get_line: 02/09/83 stu_$get_line
387
388
389 Function: This entry point, given a pointer to the symbol header of a
390 standard object segment and an offset in the text section of the object
391 segment, returns information that allows the source line that generated
392 the specified location to be accessed. This entry point can be used
393 with programs that have only a partial runtime symbol table.
394
395
396 Syntax:
397 declare stu_$get_line entry ptr fixed bin18 fixed bin
398 fixed bin18 fixed bin18 fixed bin fixed bin;
399 call stu_$get_line head_ptr offset n_stms line_no line_offset
400 line_length file;
401
402
403 Arguments:
404 head_ptr
405 is a pointer to the symbol section header of a standard object
406 segment. Input
407 offset
408 is the offset of an instruction in the text section. Input
409 n_stms
410 indicates the number of source statements about which information is
411 desired; the string specified by file, line_offset, and line_length
412 is the source for n_stms statements, starting with the statement
413 that contains the given instruction. Input
414 line_no
415 is set to the line number, in the file in which it is contained, of
416 the statement that contains the specified instruction or is -1 if
417 the given offset does not correspond to a statement in the object
418 program. Output
419
420
421 line_offset
422 is set to the number of characters that precede the first character
423 of the source for the specified statement. Output
424 line_length
425 is set to the number of characters occupied by the n_stms statements
426 that start with the statement that contains the specified location;
427 the source for these statements is assumed to be entirely contained
428 within a single source file. Let S be the contents of the source
429 file that contains the specified statements considered as a single
430 string; then the source string for the n_stms statements is
431 substrSline_offset+1line_length. Output
432 file
433 is the number of the source file in which the source for the desired
434 statements is contained. Output
435
436
437 :Entry: get_line_no: 02/09/83 stu_$get_line_no
438
439
440 Function: This entry point, given a pointer to a runtime_block node
441 and an offset in the text segment that corresponds to the block,
442 determines the line number, starting location, and number of words in
443 the source statement that contains the specified location.
444
445
446 Syntax:
447 declare stu_$get_line_no entry ptr fixed bin18 fixed bin18
448 fixed bin18 returns fixed bin18;
449 line_no = stu_$get_line_no block_ptr offset start num;
450
451
452 Arguments:
453 block_ptr
454 points to the runtime_block node that corresponds to the block in
455 which the instruction offset exists. Input
456 offset
457 is the offset of an instruction in the text segment. Input
458 start
459 is set to the offset in the text segment of the first instruction
460 generated for the source line that contains the specified
461 instruction or is -1 if the line is not found. Output
462 num
463 is set to the number of words generated for the specified source
464 line. Output
465 line_no
466 is set to the line number, in the main source file, of the statement
467 that contains the specified instruction or is -1 if the specified
468 offset does not correspond to a statement in the program. Output
469
470
471 Notes:
472 All line numbers refer to the main source file and not to files
473 accessed by means of the %include statement.
474
475 No distinction is made between several statements that occur on the
476 same source line. The start argument is the starting location of the
477 code generated for the first statement on the line and num is the total
478 length of all the statements on the line.
479
480
481 :Entry: get_location: 02/09/83 stu_$get_location
482
483
484 Function: This entry point, given a pointer to a runtime_block node
485 and the line number of a source statement in the block, returns the
486 location in the text segment of the first instruction generated by the
487 specified source line.
488
489
490 Syntax:
491 declare stu_$get_location entry ptr fixed bin18 returns
492 fixed bin18;
493 offset = stu_$get_location block_ptr line_no;
494
495
496 Arguments:
497 block_ptr
498 points to the runtime_block node. Input
499 line_no
500 specifies the source line number, which must be in the main source
501 file. Input
502 offset
503 is set to the offset in the text segment of the first instruction
504 generated for the given line or is -1 if no instructions are
505 generated for the given line. Output
506
507
508 :Entry: get_map_index: 02/09/83 stu_$get_map_index
509
510
511 Function: This entry point, given a pointer to the symbol header of a
512 standard object segment and an offset into the text section, returns
513 the index of the statement map entry for the source line that generated
514 the instruction at the offset and a pointer to the map entry. This
515 entry can be used with object segments that have only a partial runtime
516 symbol table.
517
518
519 Syntax:
520 declare stu_$get_map_index entry ptr fixed bin18 unsigned
521 fixed bin ptr;
522 call stu_$get_map_index header offset map_index map_entry_ptr;
523
524
525 Arguments:
526 header
527 is a pointer to the symbol header for the object segment. Input
528 offset
529 is the offset of an instruction, relative to the base of the
530 segment. Input
531 map_index
532 is the index in the statement map array of the statement map entry
533 for the line corresponding to the instruction, or -1 if no such map
534 entry could be found. Output
535 map_entry_ptr
536 is a pointer to the map entry identified by map_index, or null if no
537 such entry could be found. Outpout
538
539
540 Notes:
541 Even though the map entry index and map entry pointer can be computed
542 from each other, both are supplied to the user for convenience.
543
544
545 :Entry: get_runtime_address: 02/09/83 stu_$get_runtime_address
546
547
548 Function: This entry point, given a pointer to a runtime_symbol node
549 and information about the current environment of the block in which the
550 symbol that corresponds to the runtime_symbol node is declared,
551 determines the address of the specified variable.
552
553
554 Syntax:
555 declare stu_$get_runtime_address entry ptr ptr ptr ptr ptr ptr
556 ptr returns ptr;
557 add_ptr = stu_$get_runtime_address block_ptr symbol_ptr stack_ptr
558 link_ptr text_ptr ref_ptr subs_ptr;
559
560
561 Arguments:
562 block_ptr
563 points to the runtime_block node that corresponds to the block in
564 which the symbol, whose address is to be determined, is declared.
565 Input
566 symbol_ptr
567 points to the runtime_symbol node that corresponds to the symbol
568 whose address is to be determined. Input
569 stack_ptr
570 is a pointer to the active stack frame associated with the procedure
571 or begin block that corresponds to the specified runtime_block node.
572 If the specified block is quick, stack_ptr should point to the stack
573 frame in which the quick block is placing its automatic storage. If
574 the specified block is not active and does not have a current stack
575 frame, stack_ptr can be null. Input
576
577
578 link_ptr
579 is a pointer to the linkage section of the specified block. If
580 link_ptr is null, the stu_$get_runtime_address entry point attempts
581 to obtain the linkage pointer, if it is needed, from the LOT; the
582 address of the specified symbol cannot be determined if a pointer to
583 the linkage section is needed and text_ptr, block_ptr, and link_ptr
584 are all null or the segment has never been executed. Input
585 text_ptr
586 is a pointer to the base of the object segment that contains the
587 specified block. If text_ptr is null, the stu_$get_runtime_address
588 entry point attempts to obtain the text pointer, if it is needed,
589 from the active stack frame or the block_ptr; the address of the
590 specified symbol cannot be determined if a pointer to the object
591 segment is needed and stack_ptr, block_ptr, and text_ptr are all
592 null. Input
593
594
595 ref_ptr
596 is the value of the reference pointer to be used if the
597 runtime_symbol node corresponds to a based variable. If ref_ptr is
598 null, the stu_$get_runtime_address entry point calls the
599 stu_$get_implicit_qualifier entry point described above to
600 determine the value of the pointer that was used in the declaration
601 of the based variable. Input
602 subs_ptr
603 points to a vector of single-precision fixed-point binary
604 subscripts. The number of subscripts is assumed to match the number
605 required by the declaration. This argument can be null if the
606 runtime_symbol node does not correspond to an array. Input
607 add_ptr
608 is set to the full bit address with full bit offset of the
609 variable that corresponds to the symbol node or is null if the
610 address cannot be determined. Output
611
612
613 :Entry: get_runtime_block: 02/09/83 stu_$get_runtime_block
614
615
616 Function: This entry point, given a pointer to an active stack frame
617 and a location within the object segment that created the frame,
618 returns pointers to the symbol table header of the object segment and
619 the runtime_block node that corresponds to the procedure or begin block
620 associated with the stack frame. Null pointers are returned if the
621 stack frame does not belong to a PL/I, FORTRAN, or COBOL program or if
622 the object segment does not have a runtime symbol table.
623
624
625 Syntax:
626 declare stu_$get_runtime_block entry ptr ptr ptr fixed bin18;
627 call stu_$get_runtime_block stack_ptr header_ptr block_ptr loc;
628
629
630 Arguments:
631 stack_ptr
632 points to an active stack frame. Input
633 header_ptr
634 is set to point to the symbol table header or is null if the object
635 segment does not have a runtime symbol table. Output
636 block_ptr
637 is set to point to the runtime_block node that corresponds to the
638 procedure or begin block associated with the stack frame or is null
639 if the object segment does not have a runtime symbol table.
640 Output
641 loc
642 is an address within the object segment e.g. where execution was
643 interrupted; a negative value for loc means no location information
644 is specified. The additional information provided by loc enables
645 the stu_$get_runtime_block entry point to return the runtime_block
646 node that corresponds to the quick PL/I procedure or begin block
647 that is sharing the designated stack frame and was active at the
648 time execution was interrupted. Input
649
650
651 :Entry: get_runtime_line_no: 02/09/83 stu_$get_runtime_line_no
652
653
654 Function: This entry point, given a pointer to the symbol header of a
655 standard object segment and an offset in the text section of the object
656 segment, returns information about the line that caused the specified
657 instruction to be generated. Since the symbol header is used to locate
658 the statement map, this entry point can be used with object segments
659 that have only a partial runtime symbol table.
660
661
662 Syntax:
663 declare stu_$get_runtime_line_no entry ptr fixed bin18
664 fixed bin18 fixed bin18 fixed bin18;
665 call stu_$get_runtime_line_no head_ptr offset start num line_no;
666
667
668 Arguments:
669 head_ptr
670 is a pointer to the symbol section header of a standard object
671 segment. Input
672 offset
673 is the offset of an instruction in the text section. Input
674 start
675 is set to the offset in the text segment of the first instruction
676 generated for the source line that contains the specified
677 instruction or is -1 if the line is not found. Output
678 num
679 is set to the number of words in the object code generated for the
680 specified source line. Output
681 line_no
682 is set to the line number, in the main source file, of the statement
683 that contains the specified instruction or is -1 if the specified
684 offset does not correspond to a statement in the program. Output
685
686
687 Notes:
688 All line numbers refer to the main source file and not to files
689 accessed by means of the %include statement.
690
691 No distinction is made between several statements that occur on the
692 same source line. The start argument is the starting location of the
693 code generated for the first statement on the line and num is the total
694 length of all the statements on the line.
695
696
697 :Entry: get_runtime_location: 02/09/83 stu_$get_runtime_location
698
699
700 Function: This entry point, given a pointer to the symbol header of a
701 standard object segment and a line number in the main source file,
702 returns the starting location in the text section of the object code
703 generated for the line. This entry point can be used with object
704 segments that have only a partial runtime symbol table.
705
706
707 Syntax:
708 declare stu_$get_runtime_location entry ptr fixed bin returns
709 fixed bin18;
710 offset = stu_$get_runtime_location head_ptr line_no;
711
712
713 Arguments:
714 head_ptr
715 is a pointer to the symbol section header of a standard object
716 segment. Input
717 line_no
718 is the line number of a statement in the main source file. Input
719 offset
720 is set to the location in the text segment where the object code
721 generated for the specified line begins or is -1 if no code is
722 generated for the given line. Output
723
724
725 :Entry: get_statement_map: 02/09/83 stu_$get_statement_map
726
727
728 Function: This entry point, given a pointer to the symbol header of a
729 standard object segment, returns information about the statement map of
730 the object segment. This entry point can be used with object segments
731 that have only a partial runtime symbol table.
732
733
734 Syntax:
735 declare stu_$get_statement_map entry ptr ptr ptr fixed bin;
736 call stu_$get_statement_map head_ptr first_ptr last_ptr map_size;
737
738
739 Arguments:
740 head_ptr
741 is a pointer to the symbol section header of a standard object
742 segment. Input
743 first_ptr
744 is set to point to the first entry in the statement map of the
745 object segment or is null if the object segment does not have a
746 statement map. Output
747 last_ptr
748 is set to point to the location following the last entry in the
749 statement map of the object segment or is null if the object segment
750 does not have a statement map. Output
751 map_size
752 is set to the number of words in an entry in the statement map.
753 Output
754
755
756 :Entry: offset_to_pointer: 02/09/83 stu_$offset_to_pointer
757
758
759 Function: This entry point attempts to convert an offset variable to a
760 pointer value using the area, if any, on which the offset was declared.
761
762
763 Syntax:
764 declare stu_$offset_to_pointer entry ptr ptr ptr ptr ptr ptr
765 returns ptr;
766 off_ptr = stu_$offset_to_pointer block_ptr symbol_ptr data_ptr
767 stack_ptr link_ptr text_ptr;
768
769
770 Arguments:
771 block_ptr
772 points to the runtime_block node that corresponds to the procedure
773 or begin block in which the offset variable is declared. Input
774 symbol_ptr
775 points to the runtime_symbol node that corresponds to the offset
776 variable. Input
777 data_ptr
778 points to the offset value to be converted to a pointer. Input
779 stack_ptr
780 is a pointer to the active stack frame associated with the block in
781 which the offset variable is declared. If the specified block node
782 is quick, stack_ptr should point to the stack frame in which the
783 quick block is placing its automatic storage. If the specified
784 block is not active and does not have a current stack frame,
785 stack_ptr can be null. Input
786
787
788 link_ptr
789 is a pointer to the linkage section of the specified block. If
790 link_ptr is null, the stu_$offset_to_pointer entry point attempts to
791 obtain the linkage pointer, if it is needed, from the stack frame;
792 conversion fails if a pointer to the linkage section is needed and
793 stack_ptr and link_ptr are both null. Input
794 text_ptr
795 is a pointer to the base of the object segment that contains the
796 specified block. If text_ptr is null, the stu_$offset_to_pointer
797 entry point attempts to obtain the text pointer, if it is needed,
798 from the active stack frame; conversion fails if a pointer to the
799 text section is needed and stack_ptr and link_ptr are both null.
800 Input
801 off_ptr
802 is set to the pointer value that corresponds to the offset value; it
803 is null if the conversion fails or if the offset value is itself
804 null. Output
805
806
807 :Entry: pointer_to_offset: 02/09/83 stu_$pointer_to_offset
808
809
810 Function: This entry point attempts to convert a pointer value to an
811 offset variable using the area, if any, on which the offset was
812 declared.
813
814
815 Syntax:
816 declare stu_$pointer_to_offset entry ptr ptr ptr ptr ptr ptr
817 returns offset;
818 off_val = stu_$pointer_to_offset block_ptr symbol_ptr data_ptr
819 stack_ptr link_ptr text_ptr;
820
821
822 Arguments:
823 block_ptr
824 points to the runtime_block node that corresponds to the procedure
825 or begin block in which the offset variable is declared. Input
826 symbol_ptr
827 points to the runtime_symbol node that corresponds to the offset
828 variable. Input
829 data_ptr
830 points at the pointer value to be converted to an offset. This
831 pointer value must be an unpacked pointer value. Input
832 stack_ptr
833 is a pointer to the active stack frame associated with the block in
834 which the offset variable is declared. If the specified block node
835 is quick, stack_ptr should point to the stack frame in which the
836 quick block is placing its automatic storage. If the specified
837 block is not active and does not have a current stack frame,
838 stack_ptr can be null. Input
839
840
841 link_ptr
842 is a pointer to the linkage section of the specified block. If
843 link_ptr is null, the stu_$offset_to_pointer entry point attempts to
844 obtain the linkage pointer, if it is needed, from the stack frame;
845 conversion fails if a pointer to the linkage section is needed and
846 stack_ptr and link_ptr are both null. Input
847 text_ptr
848 is a pointer to the base of the object segment that contains the
849 specified block. If text_ptr is null, the stu_$offset_to_pointer
850 entry point attempts to obtain the text pointer, if it is needed,
851 from the active stack frame; conversion fails if a pointer to the
852 text section is needed and stack_ptr and link_ptr are both null.
853 Input
854 off_val
855 is set to the offset value that corresponds to the pointer value; it
856 is null if the conversion fails or if the pointer value is itself
857 null. Output
858
859
860 :Entry: remote_format: 02/09/83 stu_$remote_format
861
862
863 Function: This entry point decodes a remote format specification.
864
865
866 Syntax:
867 declare stu_$remote_format entry fixed bin35 ptr ptr label
868 returns fixed bin;
869 code = stu_$remote_format value stack_ptr ref_ptr format;
870
871
872 Arguments:
873 value
874 is the remote format value to be decoded. Input
875 stack_ptr
876 is a pointer to the active stack frame of the block that contains
877 the format being decoded. Input
878 ref_ptr
879 is the pointer value to be used if the format value being decoded
880 requires pointer qualification. Input
881 format
882 is set to the format value if decoding is successful. Output
883 code
884 is a status code. Output It can be:
885 0 if decoding is successful.
886 1 if decoding is not successful.
887
888
889 Examples:
890 The use of some of the entry points documented above is illustrated by
891 the following sample program, which is called with:
892 stack_ptr
893 a pointer to the stack frame of a PL/I block.
894 symbol
895 an ASCII string giving the name of a user symbol in the PL/I
896 program.
897 subs_ptr
898 a pointer to an array of binary integers that give subscript values.
899
900 The procedure determines the address and size of the specified symbol.
901 If any errors occur, the returned address is null.
902
903 example: proc stack_ptr symbol subs_ptr size returns ptr;
904
905
906 declare stack_ptr ptr,
907 symbol char* aligned,
908 subs_ptr ptr,
909 size fixed bin35;
910 declare header_ptr block_ptr symbol_ptr ref_ptr sp blk_ptr
911 stack_ptr add_ptr ptr,
912 i steps fixed bin,
913 code fixed bin35,
914 stu_$get_runtime_block entry ptr ptr ptr
915 fixed bin18,
916 stu_$find_runtime_symbol entry ptr char* aligned
917 ptr fixed bin returnsptr,
918 stu_$get_runtime_address entry ptr ptr ptr ptr ptr
919 ptr ptr returnsptr,
920 stu_$decode_runtime_value entry fixed bin35 ptr ptr
921 ptr ptr ptr fixed bin returnsfixed bin35;
922
923
924 %include pl1_stack_frame;
925 %include runtime_symbol;
926
927 /* determine header and block pointers */
928 call stu_$get_runtime_block stack_ptr header_ptr
929 block_ptr -1;
930 if block_ptr = null then returnnull;
931 /* search for specified symbol */
932 symbol_ptr = stu_$find_runtime_symbol block_ptr symbol
933 blk_ptr steps;
934 if symbol_ptr = null then returnnull;
935 /* determine stack frame of block owning symbol */
936 sp = stack_ptr;
937 do i = 1 to steps;
938 sp = sp -> pl1_stack_frame.display_ptr;
939 end;
940
941
942 /* determine address of symbol */
943 ref_ptr = null;
944 add_ptr = stu_$get_runtime_address blk_ptr symbol_ptr
945 sp null null ref_ptr subs_ptr;
946 if add_ptr = null then returnnull;
947 /* determine size */
948 size = symbol_ptr -> runtime_symbol.size;
949 if size < 0
950 then do;
951 size = stu_$decode_runtime_value size blk_ptr sp
952 null null ref_ptr code;
953 if code ^= 0 then returnnull;
954 end;
955 returnadd_ptr;
956 end example;
957 ^@^@^@