10/27/83 stu_ The stu_ (symbol table utility) subroutine provides a number of entry points for retrieving information from the runtime symbol table section of an object segment generated by the PL/I, FORTRAN, or COBOL compilers. A runtime symbol table is produced when a program is compiled with the -table control argument or when a runtime symbol table is required to support a feature of the language such as PL/I data-directed or FORTRAN NAMELIST input/output statements. A partial symbol table, containing only a statement map, is produced when a program is compiled with the -brief_table control argument. Entry points in stu_: (List is generated by the help command) :Entry: decode_runtime_value: 02/09/83 stu_$decode_runtime_value Function: This entry point is called to decode encoded values (e.g., string length or arithmetic precision) stored in a runtime_symbol node. Syntax: declare stu_$decode_runtime_value entry (fixed bin(35), ptr, ptr, ptr, ptr, ptr, fixed bin) returns (fixed bin(35)); value = stu_$decode_runtime_value (v, block_ptr, stack_ptr, link_ptr, text_ptr, ref_ptr, code); Arguments: v is an encoded value from a runtime_symbol node, e.g., runtime_symbol.size. (Input) block_ptr points to the runtime_block node that corresponds to the block that contains the declaration of the identifier whose runtime_symbol node contains the encoded value. Normally, the value of block_ptr is obtained from a call to the stu_$find_runtime_symbol entry point described below. (Input) stack_ptr is a pointer to the active stack frame associated with the procedure or begin block that corresponds to the specified runtime_block node. If the specified block node is quick, stack_ptr should point to the stack frame in which the quick block is placing its automatic storage. If the specified block is not active and does not have a current stack frame, stack_ptr can be null. (Input) link_ptr is a pointer to the linkage section of the specified block. If link_ptr is null, the stu_$decode_runtime_value entry point attempts to obtain the linkage pointer, if it is needed, from the linkage offset table (LOT); decoding fails if a pointer to the linkage section is needed and text_ptr, block_ptr, and link_ptr are all null or if the segment has never been executed. (Input) text_ptr is a pointer to the base of the object segment that contains the specified block. If text_ptr is null, the stu_$decode_runtime_value entry point attempts to obtain the text pointer, if it is needed, from the active stack frame or the block_ptr; decoding fails if a pointer to the object segment is needed and stack_ptr, block_ptr, and text_ptr are all null. (Input) ref_ptr is the value of the pointer to be used as locator qualifier if the variable that corresponds to the runtime_symbol node that contains the encoded value is based. The value of ref_ptr can often be determined by means of the stu_$get_implicit_qualifier entry point described below. (Input) code is a status code. (Output) It can be: 0 if the encoded value was successfully decoded. 1 if the value could not be decoded. value is the decoded value if the value of code is 0. (Output) :Entry: decode_runtime_value_extended: 10/27/83 stu_$decode_runtime_value_extended Function: This entry point is called to decode extended encoded values, such as are stored in a Pascal symbol node. Syntax: declare stu_$decode_runtime_value_extended entry (fixed bin(35), ptr, ptr, ptr, ptr, ptr, ptr, fixed bin) returns (fixed bin(35)); value = stu_$decode_runtime_value_extended (v, block_ptr, stack_ptr, link_ptr, text_ptr, ref_ptr, symbol_ptr, code); Arguments: v is an extended encoded value from an appropriate symbol node, e.g., pascal_size declared in pascal_symbol_node.incl.pl1. (Input) block_ptr points to the runtime_block node that corresponds to the block that contains the declaration of the identifier whose symbol node contains the encoded value. Normally, the value of block_ptr is obtained from a call to the stu_$find_runtime_symbol entry point described below. (Input) stack_ptr is a pointer to the active stack frame associated with the procedure or begin block that corresponds to the specified runtime_block node. If the specified block node is quick, stack_ptr should point to the stack frame in which the quick block is placing its automatic storage. If the specified block is not active and does not have a current stack frame, stack_ptr can be null. (Input) link_ptr is a pointer to the linkage section of the specified block. If link_ptr is null, this entry point attempts to obtain the linkage pointer, if it is needed, from the linkage offset table (LOT); decoding fails if a pointer to the linkage section is needed and text_ptr, block_ptr, and link_ptr are all null or if the segment has never been executed. (Input) text_ptr is a pointer to the base of the object segment that contains the specified block. If text_ptr is null, this entry point attempts to obtain the text pointer, if it is needed, from the active stack frame or the block_ptr; decoding fails if a pointer to the object segment is needed and stack_ptr, block_ptr, and text_ptr are all null. (Input) ref_ptr is the value of the pointer to be used as locator qualifier if the variable that corresponds to the symbol node that contains the encoded value is based. The value of ref_ptr can often be determined by means of the stu_$get_implicit_qualifier entry point described below. (Input) symbol_ptr is a pointer to the runtime symbol node. (Input) code is a status code. (Output) It can be: 0 if the encoded value was successfully decoded. 1 if the value could not be decoded. value is the decoded value if the value of code is 0. (Output) :Entry: find_block: 02/09/83 stu_$find_block Function: This entry point, given a pointer to the symbol table header of an object segment, searches the runtime symbol table of the object segment for the runtime_block node that corresponds to a given procedure block in the object program. Syntax: declare stu_$find_block entry (ptr, char(*) aligned) returns (ptr); block_ptr = stu_$find_block (header_ptr, name); Arguments: header_ptr points to a symbol table header. (Input) name is the ASCII name of the runtime_block node to be found. The name of a runtime_block node is the same as the first name written on the procedure statement that corresponds to the runtime_block node. (Input) block_ptr is set to point to the runtime_block node if it is found or is null if the block is not found. (Output) :Entry: find_containing_block: 02/09/83 stu_$find_containing_block Function: This entry point, given a pointer to the symbol table header of a standard object segment and an offset into the text section, returns a pointer to the runtime_block node corresponding to the smallest procedure or begin block that lexically contains the source line for the instuction pointed to, or null if none could be found. Syntax: declare stu_$find_containing_block entry (ptr, fixed bin(18) unsigned) returns (ptr); bp = stu_$find_containing_block (hp, offset); Arguments: hp is a pointer to the symbol table header. (Input) offset is the offset from the base of the segment of an instruction. (Input) bp is the returned pointer to the runtime_block node, or null. :Entry: find_header: 02/09/83 stu_$find_header Function: This entry point, given an ASCII name and/or a pointer to any location in a (possibly bound) object segment, searches the given segment for the symbol table header corresponding to the designated program. Syntax: declare stu_$find_header entry (ptr, char(32) aligned, fixed bin(24)) returns (ptr); header_ptr = stu_$find_header (seg_ptr, name, bc); Arguments: seg_ptr points to any location in the object segment. (Input) name is the ASCII name of the program whose symbol header is to be found. If seg_ptr is null, name is treated as a reference name and the segment is determined according to the user's search rules. If the designated segment is bound, name specifies the component. (Input) bc is the bit count of the object segment; if 0, the stu_$find_header entry point determines the bit count itself. (Input) header_ptr points to the symbol table header if it is found or is null if the header is not found. (Output) Notes: Since determining the bit count of a segment is relatively expensive, the user should provide the bit count if he has it available (e.g., as a result of a call to hcs_$initiate_count). :Entry: find_runtime_symbol: 02/09/83 stu_$find_runtime_symbol Function: This entry point, given a pointer to the runtime_block node that corresponds to a procedure or begin block, searches for the runtime_symbol node that corresponds to a specified identifier name. If the name is not found in the given block, the parent block is searched. This is repeated until the name is found or the root block of the symbol structure is reached, in which case a null pointer is returned. Syntax: declare stu_$find_runtime_symbol entry (ptr, char(*) aligned, ptr, fixed bin) returns (ptr); symbol_ptr = stu_$find_symbol (block_ptr, name, found_ptr, steps); Arguments: block_ptr points to the runtime_block node in which the search is to begin. (Input) name is the ASCII name of the runtime_symbol node to be found. A name can be a fully or partially qualified structure name (e.g., "a.b.c"), in which the runtime_symbol node that corresponds to the lowest level item is located. (Input) found_ptr is set to point to the runtime_block node in which the specified identifier is found. (Output) steps is set to the number of steps that must be taken along the pl1_stack_frame.display_ptr chain to locate the stack_frame associated with the block designated by found_ptr starting at the stack frame for the block designated by block_ptr. (See "Example" below.) If the given identifier is found in the specified block, the value of steps is 0. (Output) If the search fails, the value of steps indicates the reason for the failure as follows: -1 block_ptr is null -2 more than 64 structure levels -3 name too long -4 no declaration found -5 symbol reference is ambiguous symbol_ptr is set to point to the runtime_symbol node if it is found or is null if an error occurs. (Output) :Entry: get_block: 02/09/83 stu_$get_block Function: Given a pointer to the stack frame, gets a pointer to the runtime_block for the entry that created the frame and to the header for the object segment. This entry point is equivalent to stu_$get_runtime_block except that the location is determined by the information in the stack frame. Syntax: declare stu_$get_block entry (ptr, ptr, ptr); call stu_$get_block (sp, hp, bp); Arguments: sp points to the stack frame in question. (Input) hp points to the header for the runtime symbol table of the object segment that contains the entry that created the frame. If is set to null if the object segment has no symbol table, or if the object segment cannot be interpreted. (Output) bp points to the runtime_block node for the entry that created the frame. It is set to null if the object segment has no symbol table or could not be interpreted. :Entry: get_implicit_qualifier: 02/09/83 stu_$get_implicit_qualifier Function: This entry point, given a pointer to the symbol node that corresponds to a PL/I based variable, attempts to return the value of the pointer variable that appeared in the based declaration (e.g., the value of "p" in "dcl a based (p);"). A null pointer is returned if the declaration does not have the proper form or if the value of the pointer cannot be determined. Syntax: declare stu_$get_implicit_qualifier entry (ptr, ptr, ptr, ptr, ptr) returns (ptr); ref_ptr = stu_$get_implicit_qualifier (block_ptr, symbol_ptr, stack_ptr, link_ptr, text_ptr); Arguments: block_ptr points to the runtime_block node that corresponds to the procedure or begin block in which the based variable is declared. (Input) symbol_ptr points to the runtime_symbol node that corresponds to the based variable. (Input) stack_ptr is a pointer to the active stack frame associated with the block in which the based variable is declared. If the specified block node is quick, stack_ptr should point to the stack frame in which the quick block is placing its automatic storage. If the specified block is not active and does not have a current stack frame, stack_ptr can be null. (Input) link_ptr is a pointer to the linkage section of the specified block. If link_ptr is null, the stu_$get_implicit_qualifier entry point attempts to obtain the linkage pointer, if it is needed, from the active stack frame; the implicit qualifier cannot be determined if a pointer to the linkage section is needed and stack_ptr and link_ptr are both null. (Input) text_ptr is a pointer to the base of the object segment that contains the specified block. If text_ptr is null, the stu_$get_implicit_qualifier entry point attempts to obtain the text pointer, if it is needed, from the active stack frame; the implicit qualifier cannot be determined if a pointer to the object section is needed and stack_ptr and text_ptr are both null. (Input) ref_ptr is set to the value of the implicit qualifier or is null if the value cannot be determined. (Output) Notes: A null pointer is returned for any one of a number of reasons. Some of these are: The based variable was declared without an implicit qualifier, e.g., dcl a based; Determining the implicit qualifier involves evaluating an expression, for example, the based variable was declared as: dcl a based(p(i)); The based variable was declared with an implicit qualifier, but it is not possible to obtain the address of the qualifier (e.g., it is an authentic pointer, and stack_ptr is null). :Entry: get_line: 02/09/83 stu_$get_line Function: This entry point, given a pointer to the symbol header of a standard object segment and an offset in the text section of the object segment, returns information that allows the source line that generated the specified location to be accessed. This entry point can be used with programs that have only a partial runtime symbol table. Syntax: declare stu_$get_line entry (ptr, fixed bin(18), fixed bin, fixed bin(18), fixed bin(18), fixed bin, fixed bin); call stu_$get_line (head_ptr, offset, n_stms, line_no, line_offset, line_length, file); Arguments: head_ptr is a pointer to the symbol section header of a standard object segment. (Input) offset is the offset of an instruction in the text section. (Input) n_stms indicates the number of source statements about which information is desired; the string specified by file, line_offset, and line_length is the source for n_stms statements, starting with the statement that contains the given instruction. (Input) line_no is set to the line number, in the file in which it is contained, of the statement that contains the specified instruction or is -1 if the given offset does not correspond to a statement in the object program. (Output) line_offset is set to the number of characters that precede the first character of the source for the specified statement. (Output) line_length is set to the number of characters occupied by the n_stms statements that start with the statement that contains the specified location; the source for these statements is assumed to be entirely contained within a single source file. Let S be the contents of the source file that contains the specified statements considered as a single string; then the source string for the n_stms statements is substr(S,line_offset+1,line_length). (Output) file is the number of the source file in which the source for the desired statements is contained. (Output) :Entry: get_line_no: 02/09/83 stu_$get_line_no Function: This entry point, given a pointer to a runtime_block node and an offset in the text segment that corresponds to the block, determines the line number, starting location, and number of words in the source statement that contains the specified location. Syntax: declare stu_$get_line_no entry (ptr, fixed bin(18), fixed bin(18), fixed bin(18)) returns (fixed bin(18)); line_no = stu_$get_line_no (block_ptr, offset, start, num); Arguments: block_ptr points to the runtime_block node that corresponds to the block in which the instruction offset exists. (Input) offset is the offset of an instruction in the text segment. (Input) start is set to the offset in the text segment of the first instruction generated for the source line that contains the specified instruction or is -1 if the line is not found. (Output) num is set to the number of words generated for the specified source line. (Output) line_no is set to the line number, in the main source file, of the statement that contains the specified instruction or is -1 if the specified offset does not correspond to a statement in the program. (Output) Notes: All line numbers refer to the main source file and not to files accessed by means of the %include statement. No distinction is made between several statements that occur on the same source line. The start argument is the starting location of the code generated for the first statement on the line and num is the total length of all the statements on the line. :Entry: get_location: 02/09/83 stu_$get_location Function: This entry point, given a pointer to a runtime_block node and the line number of a source statement in the block, returns the location in the text segment of the first instruction generated by the specified source line. Syntax: declare stu_$get_location entry (ptr, fixed bin(18)) returns (fixed bin(18)); offset = stu_$get_location (block_ptr, line_no); Arguments: block_ptr points to the runtime_block node. (Input) line_no specifies the source line number, which must be in the main source file. (Input) offset is set to the offset in the text segment of the first instruction generated for the given line or is -1 if no instructions are generated for the given line. (Output) :Entry: get_map_index: 02/09/83 stu_$get_map_index Function: This entry point, given a pointer to the symbol header of a standard object segment and an offset into the text section, returns the index of the statement map entry for the source line that generated the instruction at the offset and a pointer to the map entry. This entry can be used with object segments that have only a partial runtime symbol table. Syntax: declare stu_$get_map_index entry (ptr, fixed bin(18) unsigned, fixed bin, ptr); call stu_$get_map_index (header, offset, map_index, map_entry_ptr); Arguments: header is a pointer to the symbol header for the object segment. (Input) offset is the offset of an instruction, relative to the base of the segment. (Input) map_index is the index in the statement map array of the statement map entry for the line corresponding to the instruction, or -1 if no such map entry could be found. (Output) map_entry_ptr is a pointer to the map entry identified by map_index, or null if no such entry could be found. (Outpout) Notes: Even though the map entry index and map entry pointer can be computed from each other, both are supplied to the user for convenience. :Entry: get_runtime_address: 02/09/83 stu_$get_runtime_address Function: This entry point, given a pointer to a runtime_symbol node and information about the current environment of the block in which the symbol that corresponds to the runtime_symbol node is declared, determines the address of the specified variable. Syntax: declare stu_$get_runtime_address entry (ptr, ptr, ptr, ptr, ptr, ptr, ptr) returns (ptr); add_ptr = stu_$get_runtime_address (block_ptr, symbol_ptr, stack_ptr, link_ptr, text_ptr, ref_ptr, subs_ptr); Arguments: block_ptr points to the runtime_block node that corresponds to the block in which the symbol, whose address is to be determined, is declared. (Input) symbol_ptr points to the runtime_symbol node that corresponds to the symbol whose address is to be determined. (Input) stack_ptr is a pointer to the active stack frame associated with the procedure or begin block that corresponds to the specified runtime_block node. If the specified block is quick, stack_ptr should point to the stack frame in which the quick block is placing its automatic storage. If the specified block is not active and does not have a current stack frame, stack_ptr can be null. (Input) link_ptr is a pointer to the linkage section of the specified block. If link_ptr is null, the stu_$get_runtime_address entry point attempts to obtain the linkage pointer, if it is needed, from the LOT; the address of the specified symbol cannot be determined if a pointer to the linkage section is needed and text_ptr, block_ptr, and link_ptr are all null or the segment has never been executed. (Input) text_ptr is a pointer to the base of the object segment that contains the specified block. If text_ptr is null, the stu_$get_runtime_address entry point attempts to obtain the text pointer, if it is needed, from the active stack frame or the block_ptr; the address of the specified symbol cannot be determined if a pointer to the object segment is needed and stack_ptr, block_ptr, and text_ptr are all null. (Input) ref_ptr is the value of the reference pointer to be used if the runtime_symbol node corresponds to a based variable. If ref_ptr is null, the stu_$get_runtime_address entry point calls the stu_$get_implicit_qualifier entry point (described above) to determine the value of the pointer that was used in the declaration of the based variable. (Input) subs_ptr points to a vector of single-precision fixed-point binary subscripts. The number of subscripts is assumed to match the number required by the declaration. This argument can be null if the runtime_symbol node does not correspond to an array. (Input) add_ptr is set to the full bit address (with full bit offset) of the variable that corresponds to the symbol node or is null if the address cannot be determined. (Output) :Entry: get_runtime_block: 02/09/83 stu_$get_runtime_block Function: This entry point, given a pointer to an active stack frame and a location within the object segment that created the frame, returns pointers to the symbol table header of the object segment and the runtime_block node that corresponds to the procedure or begin block associated with the stack frame. Null pointers are returned if the stack frame does not belong to a PL/I, FORTRAN, or COBOL program or if the object segment does not have a runtime symbol table. Syntax: declare stu_$get_runtime_block entry (ptr, ptr, ptr, fixed bin(18)); call stu_$get_runtime_block (stack_ptr, header_ptr, block_ptr, loc); Arguments: stack_ptr points to an active stack frame. (Input) header_ptr is set to point to the symbol table header or is null if the object segment does not have a runtime symbol table. (Output) block_ptr is set to point to the runtime_block node that corresponds to the procedure or begin block associated with the stack frame or is null if the object segment does not have a runtime symbol table. (Output) loc is an address within the object segment (e.g., where execution was interrupted); a negative value for loc means no location information is specified. The additional information provided by loc enables the stu_$get_runtime_block entry point to return the runtime_block node that corresponds to the quick PL/I procedure or begin block that is sharing the designated stack frame and was active at the time execution was interrupted. (Input) :Entry: get_runtime_line_no: 02/09/83 stu_$get_runtime_line_no Function: This entry point, given a pointer to the symbol header of a standard object segment and an offset in the text section of the object segment, returns information about the line that caused the specified instruction to be generated. Since the symbol header is used to locate the statement map, this entry point can be used with object segments that have only a partial runtime symbol table. Syntax: declare stu_$get_runtime_line_no entry (ptr, fixed bin(18), fixed bin(18), fixed bin(18), fixed bin(18)); call stu_$get_runtime_line_no (head_ptr, offset, start, num, line_no); Arguments: head_ptr is a pointer to the symbol section header of a standard object segment. (Input) offset is the offset of an instruction in the text section. (Input) start is set to the offset in the text segment of the first instruction generated for the source line that contains the specified instruction or is -1 if the line is not found. (Output) num is set to the number of words in the object code generated for the specified source line. (Output) line_no is set to the line number, in the main source file, of the statement that contains the specified instruction or is -1 if the specified offset does not correspond to a statement in the program. (Output) Notes: All line numbers refer to the main source file and not to files accessed by means of the %include statement. No distinction is made between several statements that occur on the same source line. The start argument is the starting location of the code generated for the first statement on the line and num is the total length of all the statements on the line. :Entry: get_runtime_location: 02/09/83 stu_$get_runtime_location Function: This entry point, given a pointer to the symbol header of a standard object segment and a line number in the main source file, returns the starting location in the text section of the object code generated for the line. This entry point can be used with object segments that have only a partial runtime symbol table. Syntax: declare stu_$get_runtime_location entry (ptr, fixed bin) returns (fixed bin(18)); offset = stu_$get_runtime_location (head_ptr, line_no); Arguments: head_ptr is a pointer to the symbol section header of a standard object segment. (Input) line_no is the line number of a statement in the main source file. (Input) offset is set to the location in the text segment where the object code generated for the specified line begins or is -1 if no code is generated for the given line. (Output) :Entry: get_statement_map: 02/09/83 stu_$get_statement_map Function: This entry point, given a pointer to the symbol header of a standard object segment, returns information about the statement map of the object segment. This entry point can be used with object segments that have only a partial runtime symbol table. Syntax: declare stu_$get_statement_map entry (ptr, ptr, ptr, fixed bin); call stu_$get_statement_map (head_ptr, first_ptr, last_ptr, map_size); Arguments: head_ptr is a pointer to the symbol section header of a standard object segment. (Input) first_ptr is set to point to the first entry in the statement map of the object segment or is null if the object segment does not have a statement map. (Output) last_ptr is set to point to the location following the last entry in the statement map of the object segment or is null if the object segment does not have a statement map. (Output) map_size is set to the number of words in an entry in the statement map. (Output) :Entry: offset_to_pointer: 02/09/83 stu_$offset_to_pointer Function: This entry point attempts to convert an offset variable to a pointer value using the area, if any, on which the offset was declared. Syntax: declare stu_$offset_to_pointer entry (ptr, ptr, ptr, ptr, ptr, ptr) returns (ptr); off_ptr = stu_$offset_to_pointer (block_ptr, symbol_ptr, data_ptr, stack_ptr, link_ptr, text_ptr); Arguments: block_ptr points to the runtime_block node that corresponds to the procedure or begin block in which the offset variable is declared. (Input) symbol_ptr points to the runtime_symbol node that corresponds to the offset variable. (Input) data_ptr points to the offset value to be converted to a pointer. (Input) stack_ptr is a pointer to the active stack frame associated with the block in which the offset variable is declared. If the specified block node is quick, stack_ptr should point to the stack frame in which the quick block is placing its automatic storage. If the specified block is not active and does not have a current stack frame, stack_ptr can be null. (Input) link_ptr is a pointer to the linkage section of the specified block. If link_ptr is null, the stu_$offset_to_pointer entry point attempts to obtain the linkage pointer, if it is needed, from the stack frame; conversion fails if a pointer to the linkage section is needed and stack_ptr and link_ptr are both null. (Input) text_ptr is a pointer to the base of the object segment that contains the specified block. If text_ptr is null, the stu_$offset_to_pointer entry point attempts to obtain the text pointer, if it is needed, from the active stack frame; conversion fails if a pointer to the text section is needed and stack_ptr and link_ptr are both null. (Input) off_ptr is set to the pointer value that corresponds to the offset value; it is null if the conversion fails or if the offset value is itself null. (Output) :Entry: pointer_to_offset: 02/09/83 stu_$pointer_to_offset Function: This entry point attempts to convert a pointer value to an offset variable using the area, if any, on which the offset was declared. Syntax: declare stu_$pointer_to_offset entry (ptr, ptr, ptr, ptr, ptr, ptr) returns (offset); off_val = stu_$pointer_to_offset (block_ptr, symbol_ptr, data_ptr, stack_ptr, link_ptr, text_ptr); Arguments: block_ptr points to the runtime_block node that corresponds to the procedure or begin block in which the offset variable is declared. (Input) symbol_ptr points to the runtime_symbol node that corresponds to the offset variable. (Input) data_ptr points at the pointer value to be converted to an offset. This pointer value must be an unpacked pointer value. (Input) stack_ptr is a pointer to the active stack frame associated with the block in which the offset variable is declared. If the specified block node is quick, stack_ptr should point to the stack frame in which the quick block is placing its automatic storage. If the specified block is not active and does not have a current stack frame, stack_ptr can be null. (Input) link_ptr is a pointer to the linkage section of the specified block. If link_ptr is null, the stu_$offset_to_pointer entry point attempts to obtain the linkage pointer, if it is needed, from the stack frame; conversion fails if a pointer to the linkage section is needed and stack_ptr and link_ptr are both null. (Input) text_ptr is a pointer to the base of the object segment that contains the specified block. If text_ptr is null, the stu_$offset_to_pointer entry point attempts to obtain the text pointer, if it is needed, from the active stack frame; conversion fails if a pointer to the text section is needed and stack_ptr and link_ptr are both null. (Input) off_val is set to the offset value that corresponds to the pointer value; it is null if the conversion fails or if the pointer value is itself null. (Output) :Entry: remote_format: 02/09/83 stu_$remote_format Function: This entry point decodes a remote format specification. Syntax: declare stu_$remote_format entry (fixed bin(35), ptr, ptr, label) returns (fixed bin); code = stu_$remote_format (value, stack_ptr, ref_ptr, format); Arguments: value is the remote format value to be decoded. (Input) stack_ptr is a pointer to the active stack frame of the block that contains the format being decoded. (Input) ref_ptr is the pointer value to be used if the format value being decoded requires pointer qualification. (Input) format is set to the format value if decoding is successful. (Output) code is a status code. (Output) It can be: 0 if decoding is successful. 1 if decoding is not successful. Examples: The use of some of the entry points documented above is illustrated by the following sample program, which is called with: stack_ptr a pointer to the stack frame of a PL/I block. symbol an ASCII string giving the name of a user symbol in the PL/I program. subs_ptr a pointer to an array of binary integers that give subscript values. The procedure determines the address and size of the specified symbol. If any errors occur, the returned address is null. example: proc (stack_ptr, symbol, subs_ptr, size) returns (ptr); declare stack_ptr ptr, symbol char(*) aligned, subs_ptr ptr, size fixed bin(35); declare (header_ptr, block_ptr, symbol_ptr, ref_ptr, sp, blk_ptr, stack_ptr, add_ptr) ptr, (i, steps) fixed bin, code fixed bin(35), stu_$get_runtime_block entry (ptr, ptr, ptr, fixed bin(18)), stu_$find_runtime_symbol entry (ptr, char(*) aligned, ptr, fixed bin) returns(ptr), stu_$get_runtime_address entry (ptr, ptr, ptr, ptr, ptr, ptr, ptr) returns(ptr), stu_$decode_runtime_value entry (fixed bin(35), ptr, ptr, ptr, ptr, ptr, fixed bin) returns(fixed bin(35)); %include pl1_stack_frame; %include runtime_symbol; /* determine header and block pointers */ call stu_$get_runtime_block (stack_ptr, header_ptr, block_ptr, -1); if block_ptr = null then return(null); /* search for specified symbol */ symbol_ptr = stu_$find_runtime_symbol (block_ptr, symbol, blk_ptr, steps); if symbol_ptr = null then return(null); /* determine stack frame of block owning symbol */ sp = stack_ptr; do i = 1 to steps; sp = sp -> pl1_stack_frame.display_ptr; end; /* determine address of symbol */ ref_ptr = null; add_ptr = stu_$get_runtime_address (blk_ptr, symbol_ptr, sp, null, null, ref_ptr, subs_ptr); if add_ptr = null then return(null); /* determine size */ size = symbol_ptr -> runtime_symbol.size; if size < 0 then do; size = stu_$decode_runtime_value (size, blk_ptr, sp, null, null, ref_ptr, code); if code ^= 0 then return(null); end; return(add_ptr); end example; ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved