11/26/87 dump_segment, ds Syntax as a command: ds segname {offset} {length} {-control_args} ds segno {offset} {length} {-control_args} ds virtual_pointer {offset} {length} {-control_args} Syntax as an active function: [ds segname {offset} {length} {-control_args}] [ds segno {offset} {length} {-control_args}] [ds virtual_pointer {offset} {length} {-control_args}] Function: prints, in octal or hexadecimal format, selected portions of a segment. It prints out either four or eight words per line, and optionally print out an edited version of the ASCII, BCD, EBCDIC (in 8 or 9 bits), or 4-bit byte representation. Alternately, data can be displayed as a PL/I structure, in a format similar to that of the probe value request. Arguments: segname is either a pathname or an octal segment number to the segment to be dumped. To specify a segment name that consists entirely of octal digits, the name must be preceded by the -name control argument. offset is the (octal) offset of the first word to be dumped. If both offset and length are omitted, the entire segment is dumped. length is the (octal) number of words to be dumped. If you supply offset and omit length, one word is dumped. segno is the octal segment number of a segment to be dumped. It cannot be a hardcore segment number. virtual_pointer is an ASCII representation of a pointer. See virtual_pointers.gi.info for further descriptions of virtual pointers. Control arguments: -block N, -bk N dumps words in blocks of N words separated by a blank line. The offset, if being printed, is reset to the initial value at the beginning of each block. -entry_point NAME, -ep NAME specifies that the offset of the first word to be dumped is relative to the location defined by the externally available symbol NAME. Use -entry_point only for object segments (created by a compiler or by the create_data_segment command). -name PATH, -nm PATH indicates that PATH is a pathname even though it may look like an octal segment number. Control arguments for display: -address, -addr prints the address (relative to the base of the segment) with the data. (Default) -header, -he prints a header line containing the pathname (or segment number) of the segment being dumped as well as the date-time printed. (Default: to print a header only if the entire segment is being dumped, i.e., if you give neither the offset nor the length argument) -interpreted, -it prints the data decoded into the indicated format. -long, -lg prints eight words on a line. Four is the default. This control arguement cannot be used with -4bit, -bcd, -character, -ebcdic8, -ebcdic9, or -short. (Its use with these control arguments, other than -short, results in a line longer than 132 characters.) -no_address, -nad does not print the address. -no_header, -nhe does not print the header line even though the entire segment is being dumped. -no_interpret, -nit suppresses printing of the decoded data. (Default) -no_offset, -nofs does not print the offset. (Default) -no_raw, -nraw suppresses printing of the raw data. -no_suppress_duplicates, -nsd indicates that sequential lines are to be printed even if they would be identical to previous lines. -offset {N}, -ofs {N} prints the offset (relative to N words before the start of the data block being dumped) along with the data. If you supply no N, 0 is assumed. -raw indicates that the raw data is to be printed. (Default) -rest prints from any given offset (specified by -offset or the offset argument) to the end of the segment. -short, -sh compacts lines to fit on a terminal with a short line length. Single spaces are placed between fields, and only the two low-order digits of the address are printed except when the high-order digits change. This shortens output lines to less than 80 characters. -suppress_duplicates, -sd indicates that if lines to be printed are identical to the previous line with a single block, they are to be replaced by a short line of equal signs. (Default) Control arguments for structure display: -as STRUCTURE_NAME displays the data as a PL/I structure defined by STRUCTURE_NAME. The STRUCTURE_NAME can be a structure defined in one of the system include files supported by the analyze_multics display request. See >doc>ss>azm>structure_names.info for a list of supported include files and structures. Or the STRUCTURE_NAME can be a PL/I structure declared in an object program specified in the -in control argument. See "Notes for structure display" below. -in VIRTUAL_ENTRY identifies an object program compiled with the -table control argument which declares the STRUCTURE_NAME given with the -as control argument. If -in is not given, then STRUCTURE_NAME must be found in one of the segments listed in the structure search list. -long, -lg displays each element of the structure on a separate line. -short, -sh displays as many structure elements as will fit on a line, and groups elements with common data types together. (Default) Control arguments for interpreted data: -4bit prints out, or returns, a translation of the octal or hexadecimal dump based on the Multics unstructured 4-bit byte. The translation ignores the first bit of each 9-bit byte and uses each of the two groups of four bits remaining to generate a digit or a sign. -bcd prints the BCD representation of the words in addition to the octal or hexadecimal dump. There are no nonprintable BCD characters, so periods can be taken literally. It causes the active function to return BCD. -character, -ch, -ascii prints the ASCII representation of the words in addition to the octal or hexadecimal dump. Characters that cannot be printed are represented by periods. It causes the active function to return ASCII. (Default) -ebcdic8 prints the EBCDIC representation of each eight bits in addition to the octal or hexadecimal dump. It causes the active function to return 8-bit EBCDIC. Characters that cannot be printed are represented by periods. If an odd number of words is requested to dump, the last four bits of the last word do not appear in the translation. -ebcdic9 prints the EBCDIC representation of each 9-bit byte in addition to the octal or hexadecimal dump. Characters that cannot be printed are represented by periods. It causes the active function to return 9-bit EBCDIC. Control arguments for raw data: -hex8 prints the dumped words in hexadecimal with nine hexadecimal digits per word rather than octal with 12 octal digits per word. -hex9 prints the dumped words in hexadecimal with eight hexadecimal digits per word rather than 12 octal digits per word. Each pair of hexadecimal digits corresponds to the low-order eight bits of each 9-bit byte. -octal, -oc display the raw data in octal format, with 12 octal digits per word. (Default, for raw data) Notes: The defaults for use as a command are -address, -no_interpret, -no_offset, -raw, and -supress_duplicates with -header if the entire segment is printed, and -no_header if only parts of the segment are to be printed. The defaults for use as an active function are -no_address, -no_header, -no_interpret, -no_offset, -no_suppress_duplicates, and -raw. Supply only one of -4bit, -bcd, -character, -ebcdic8, or -ebcdic9. If you invoke -4bit, -bcd, -character, -ebcdic8, -ebcdic9, -hex8, or -hex9, the information is returned in the specified format only. All other arguments are ignored in active function invocation. In the active function the following control arguments are invalid-- -address, -as, -block, -header, -offset, and -suppress_duplicates. When you give conflicting control arguments, the last one on the command line is used. The active function returns either raw data in octal or hexadecimal representation or the interpreted data representation. Notes for structure display: When -as is given, the segname/offset, segno/offset or virtual_ptr is taken as the address of the beginning of the structure. If the whole structure is being displayed, that is the address where display begins. If only certain elements are being displayed, that is the address used to compute offsets of the elements. The structure reference following -as must be a single string, containing no spaces, used to specify structure elements, array indexes, and substring matching. The structure reference is made up of two parts: a structure element reference and an optional set of match strings. If no match strings are supplied, no string matching is done. The structure element reference syntax consists of one or more element names, separated by periods, and may contain subscripts following some of these element names. The first name in a structure element reference must be a level-one structure reference; partially qualified top-level references are not permitted. Intermediate levels of qualification may be omitted as long as there is no ambiguity. All subscripts must be supplied as decimal integers. The subscripts can be cross-section references such as "(1:4)" to reference elements one through four. Asterisk bounds cannot be used: if a cross section is desired, its upper and lower bounds must be given as decimal constants. If an element has more subscripts than are supplied, the complete cross section is printed for the remaining subscripts. To eliminate the need for quoting, subscripts may be surrounded by braces instead of parentheses. In order to specify that only certain elements be displayed (such as all those with names containing the string "time"), a set of match strings can be given after the structure element reference. Each match string begins with a slash and is followed by the string itself. The final match string can be followed by a slash, but this is not required. If match strings are specified, any element that matches at least one string is displayed. Examples of structure display: ds 234 -as stack_header the whole structure "stack_header". ds 234 -as stack_header/ptr/, ds 234 -as stack_header/ptr any elements in the structure "stack_header" containing the string "ptr". Note that the final slash is optional. ds 234 -as stack_header/isot/lot/ any elements in the structure "stack_header" containing either the string "isot" or the string "lot". ds 234 -as stack_header.stack_begin_ptr the single element "stack_begin_ptr" in the structure "stack_header". The following examples assume it has a value of 234|2000. ds 234|2000 -as stack_frame.pointer_registers all elements of array "stack_frame.pointer_registers". ds 234|2000 -as stack_frame.pointer_registers{3} element three of "stack_frame.pointer_registers". ds 234|2000 -as stack_frame.pointer_registers{2:4} elements two, three, and four of "stack_frame.pointer_registers". ds prog_data -as data_array -in my_prog all elements in the data_array declared in the my_prog object program, compiled with -table. The array is stored at [wd]>prog_data|0. Structure output format: The default output format is a compressed form, which places as many values on a line as will fit within the line length. The -long control argument places one value on a line. The short form, additionally, collects all bit(1) flags and displays them, at the end of the display for each substructure or array element, in two groups: one listing all the flags that were on ("1"b) and one for all the ones that were off ("0"b). All PL/I data types are displayed in the same representations used by probe. Additionally, the following special formats are used: 1. Bit strings are displayed in octal if the length is divisible by three, in hex if divisible by four, and as bit strings otherwise. 2. Character strings are displayed as a string concatenated with a repeated constant if the string is padded on the right with more than 16 nulls, spaces, or octal 777 characters. 3. Large-precision (> 51) fixed binary values are also displayed as clock readings if their values represent clock readings within 10 years of the present. ----------------------------------------------------------- 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