:Info: probe: pb: 07/24/90 probe, pb Syntax as a command: pb {procedure_name} {-control_args} Function: provides symbolic, interactive debugging facilities for programs compiled with PL/I, Fortran, Pascal, COBOL, ALGOL-68 or C. Arguments: procedure_name is the reference name of an initiated program, or a pathname. If procedure_name is not specified, the procedure owning the frame in which the last condition was raised is assumed. Control arguments: -handle_conditions sets up a handler for any conditions signalled while in probe, that prints an appropriate message and prevents faulting. (Default) -no_handle_conditions does not set up a handler for conditions signalled while in probe. Notes: Probe is self-documenting. For further information, invoke probe and type "help". For a list of all requests, type "list_requests". For a list of all topics described by probe, type "list_help". Programs examined by probe should not have been compiled with code optimizers, such as the -optimize control argument to the pl1 and fortran commands. Optimization can causes program variables to appear to have the wrong value when stopped at a break or fault. :Info: probe.gi: summary: 09/30/88 General information about probe Summary: Probe is a symbolic debugger for programs written in PL/1, Fortran, Pascal, COBOL, ALGOL-68 and C. It permits you to interrupt a program at a specified location, to examine or modify program variables, to examine the stack history of block invocations, and to display source lines and object instructions associated with an object location. Probe can evaluate expressions involving program variables and call external functions. Self-documentation: By using the probe "help" request one can see probe information files. To see a list of them, type "list_help". To see a specific file, type "help file_name". This info file is available by typing "help". Probe interaction: When probe has been invoked it accepts requests from you. A probe request consists of a keyword (the name of the request to be performed) and its arguments, if any. More than one request can appear on a line if they are separated by semicolons (";"). For a list of all requests, type "list_requests" to probe. Breakpoints: A breakpoint is a set of probe requests associated with a program statement. This set of requests is executed automatically by probe whenever the location in the object segment corresponding to the statement is executed. The most common request is "halt", which suspends execution of the program and listens for further requests. You can then examine and modify the state of the suspended program, and resume (or abort) further execution. Other uses of breakpoints are to display the state of the program without halting, or to effect source-level patching by executing assignments. For more information, type "help breaks". :Info: toc: 09/30/88 Summary of help files for probe. Notes on probe help files: Info files are divided into three categories; Info about requests. Info about probe features. Info about probe syntax. Notes on probe request information: To see information about a request, type "help REQUEST_NAME" to probe, where REQUEST_NAME is the name of the request. For example, "help value". Any abbreviation of the request name that probe accepts is also accepted by the help request. Notes on information available: breaks builtins c cobol fortran optimization pascal pointers (source_pointer, control_pointer) variables Notes on syntax info available: CONSTANTS EXPRESSIONS LINE NUMBER PATH PREDICATE REQUEST STRING CROSS-SECTION POINTER Names of syntax topics can be typed in lower case. :Info: C: c: 09/28/88 Probe and C Notes on probe and the c language: When the current language type is C, probe's set of data types expands to include void types, enumeration types, unions, variant records (typedef), and type pointers. The set of builtin functions for use with the C language data types is the function "sizeof". Also the modulus operator (%) (similar to the PL1 builtin "mod" function) and the right (>>) and left (<<) shift operators are available. Differences occur in the syntax that represents array indices, and operators. Array indices are enclosed (as in Pascal) in square brackets. The cross-section ranges are written with ":" e.g. a[first:last]. Although C does not have true character strings (C uses arrays of characters), the array syntax will be used to display a character array. (see "string" for more details) String constants are contained in double quotes (") and single characters are contained in single quotes ('). e.g. a character string - "this is a string" , a single character - 'a'. Pointer values(indirection operators) are represented by the star (*) symbol, and the address operator (if "v" is a variable, then "&v" is the address of that variable) is represented by the ampersand (&) symbol. The relational operators available are: != == < > <= >= To maintain consistency with the other languages that probe supports the following will not be supported : bitwise operators (&& ||), type casting, conditional expressions (?:), logical "and" and "or" operators, and compound assignments (+= -= etc.). :Info: PL1: pl1: 06/28/90 Probe and PL1 Notes on probe and the pl1 language: Probe uses a PL/1_like syntax when the current language is PL/1. Probe communicates with you based on information in the symbol table and the statement map which are produced by the PL/1 compiler. The limitations of the symbol table sometimes limit the communication with probe. Examples: (1) Probe cannot determine the correct dimension size of an array if the upperbound of the dimension is an element other than the first element of an "external" structure. For example: "dcl x dim (1:struct.e4) fixed bin based (pt); where "e4" is the fourth element in, "struct", the external structure. Probe (symbol) incorrectly interprets the upperbound of the dimension as the first element instead of the proper element in the external structure. (2) Probe cannot determine the correct value of a variable if the variable has an implicit subscripted base reference. For example: "dcl x fixed bin based (b (3));". Probe (value) interprets "x based (b (3))" as b(1) -> x. (3) Probe cannot determine the correct value of a variable if the address of the variable has an implicit base reference containing the address expression or is a defined reference. For example: "dcl x fixed bin based (addr (p1))"; or "dcl x fixed bin defined (p2)" :Info: COBOL: cobol: 09/28/79 Probe and COBOL Notes on probe and the cobol language: Probe uses a COBOL-like syntax when the current language is COBOL. The current language will be COBOL whenever the current source line is in a COBOL program. When in COBOL mode, probe is insensitive to the case of variable names. The hyphen character can be used to form names, as it is in COBOL. Aggregate names can be qualified in the COBOL manner (c of b of a) as well as in the PL/I manner (a.b.c) An aggregate is displayed by displaying the values of each of its members. To find out what the current language is, use the "language" request, with no arguments. See "where" and "language". :Info: Fortran: fortran: 09/28/79 Probe and Fortran Notes on probe and the fortran language: When the current source line is a Fortran statement, probe is in fortran mode, and acts a little differently. Logical variables are displayed as ".true." or ".false." instead of as "1"b or "0"b. Case is ignored if the program was compiled with "-card" or "-fold". The relational operators .le., .lt., .eq., .ne., .gt., .ge. can be used. :Info: Pascal: pascal: 09/08/83 Probe and Pascal Notes on probe and the pascal language: Invoked on a Pascal program, probe understands all the Pascal data types, including enumerated types, typed pointers, sets, records, files, and user-defined types. Probe understands the Pascal builtin functions chr, eof, eoln, false, nil, ord, and true. Array indices are enclosed in brackets, for example "a[i,j]". Cross_section ranges are written with "..", as in "a[first..last]". References to record fields must specify all levels; implicit level names are not allowed. For example, "a.b.c.d" cannot be abbreviated as "a.d" as can sometimes be done with PL/1 structure elements. Pointer values are written with circumflex (^) as the up-arrow, for example "p^" to indicate the value that p points to. String constants are enclosed in apostrophes: 'This is a string'. The two boolean values are "true" and "false". :Info: LINE: line: 09/28/79 Syntax of a LINE Notes on the syntax of 'line': A LINE is used to identify a location in an object segment, and possibly the source line associated with that location. A LINE can be a label known in the current procedure, the name of an external entry, a line number in the source file for the current procedure, $b (which denotes the current break), or $c (which denotes the current line). Source line numbers consist of a source file number and a line number. The file number is optional. If it is not specified, the main file (file 0) is used. File numbers can be found by examining the compilation listing. The first include file is file number 1, and so on. The second part of a source line number is the actual line in the file. This number is found printed on the left edge of a compiler listing. It is also the number one would use with an editor. Examples: $c the current line. $b the line where the latest break happened. 259 line 259 in the main file. 2-43 line number 43 in include file 2. grotz(3) the line labelled by label array constant grotz(3). $101 the line labelled by 101 (Fortran - see below). To reference the Nth statement after a given statement, follow the line location by a comma and N. For example, consider the COBOL fragment: para. add 3 to b giving c. display "Cobol is ", c. move spaces to neptune. the request "ps para,1" positions to the "display" statement, because that is the first statement after the one labelled by "para". If the "display" statement is on the next line, instead of the same line, "ps para,1" still works. Fortran: Since Fortran labels are numbers, which probe also uses to specify line numbers, Fortran labels must be preceded by a dollar sign. For example, "100" is a reference to line number 100, but "$100" is a reference to the line whose label is 100. COBOL: COBOL allows the use of labels that look like numbers. When a number is used for a LINE, it refers to a source statement line number, not a label. But if the number is preceded by a dollar sign, it is treated as the name of a paragraph label. :Info: STRING: string: strings: 09/30/88 Syntax of character string constants. Notes on the syntax of character string constants: Probe recognizes character strings and bit strings. A string is delimited by the quote character ("), and for Fortran and Pascal, the apostrophe (') can also be used. In the C language a single character constant can be represented with an apostrophe and a string (which can be any number of characters from 0 to 256) is delimited by the quote. The maximum length of a string is 256 characters. Strings can contain any character. To enclose the quote character in a string, double it. For example, "a""b" represents the string a"b containing a single embedded quote character. See constants for more info. Examples: "preceded by itself, yields falsehood" char string of length 36. "1010"b bit string of length 4. "033"b3 octal bit string, 9 bits. "A79A"b4 four hex digits, 16 bits. """" a string of length 1, containing a quote. 'a Fortran string" apostrophe and quote are equivalent. "newline is \012" a string of length 12. '1' a single character string for C "" an empty string in C In the C language mode you can specify parts of the character array in the following format: *p specifies the single character pointed to by the pointer "p". p[0:4] specifies the 5 characters starting with the character pointed to by "p". p[] specifies all the characters in the array, starting the character pointed to by "p", ending with either the null character, the 256 character, or the maxium size of the array which ever comes first. p[0:N-1] (where N is the index to the null character) this format will over come the 256 character default and all the characters from "p" to "N-1" to be specified. :Info: TOPIC: 09/30/79 Misuse of help command Notes on the misuse of the help command: To see a list of all topics, type "list_help" (lh for short). You misunderstand the documentation. A word in uppercase like TOPIC represents any possible topic that might be supplied as an argument to the help request. By typing "TOPIC" you got information on the subject of "TOPIC". If you had typed "help value", for example, you would see information about values that probe can accept. The word TOPIC in the command description is to be replaced with the name of the topic you are interested in, when you type the help request. Try again. :Info: after: af: a: 05/04/82 after, a Syntax: a {LINE} {:REQUEST} a /REGEXP/ {:REQUEST} Function: This request sets a breakpoint after the location in the object segment given by LINE. The default for LINE is the current line ($c) and the default for REQUEST is "halt". If /REGEXP/ is used instead of LINE, a break is set after every line matching the qedx regular expression REGEXP. See "breaks". A break set after a line happens after all effects of the statement are completed. If the statement sets a variable, the variable will have its new value by the time the break is executed. Depending on the nature of the code generated by the translator for the statement, a break set after a line sometimes cannot be executed. This is often the case for do loops and if-then-else constructions, and always the case for return statements and for gotos. The "after" request cannot be used on COBOL statements. :Info: arguments: args: 05/04/82 arguments, args Syntax: args args N args OBJECT Function: The args request displays the names and values of the arguments to the current procedure or a specified procedure invocation. If N is specified, stack level N is used. If OBJECT is specified, the last :Info: before: be: b: 05/04/82 before, b Syntax: before {LINE} {:REQUEST} before /REGEXP/ {:REQUEST} Function: This request sets a breakpoint before the location in the object segment given by LINE. The default for LINE is the current line ($c) and the default for REQUEST is "halt". If /REGEXP/ is used instead of LINE, a break is set before every line matching the qedx regular expression REGEXP. See "breaks". :Info: breaks: 09/29/79 Probe breakpoints Notes on breakpoints: A breakpoint is a list of one or more probe requests that is associated with some statement in a program. The probe requests of a breakpoint are known as the break request list for the break. A breakpoint can be set "before" or "after" a given line. A break before a line is executed immediately before the line itself is executed, and a break after a line is executed after the line has been executed. Therefore if a transfer is made at line X of a program, a break before line X is executed, but a break after line X is not. If a transfer is made TO the state- ment on line X, a break set before line X is executed, but one set after line X-1 is not. If statement X assigns a new value to a variable, a break set before X is executed before the variable changes, but one after X takes effect after the variable has been changed. List of requests: To set breaks, use the "before" and "after" requests. To list breaks (where they are set, what is in their request lists), use the "status" request. To remove breaks, use the "reset" request. To resume execution after a break, use the "continue" request. Notes on implementation: A breakpoint is set at a particular instruction by replacing it with an instruction that transfers control to a special sequence of code that probe places at the end of the object segment. This sequence of code is called the "map sequence". It extends the current stack frame, stores information about the break in the extension created and uses a special pl1 operator to call probe. :Info: builtins: 09/30/88 Probe builtins Notes on builtins: For a summary of builtins, use the "list_builtins" request. All probe builtins, except "ptr", are exactly equivalent to the Multics PL/I builtins by the same name. The "ptr" builtin is an extension to the Multics "ptr" builtin. The third argument, if given, is the bit offset of the resultant pointer value "sizeof" is the only probe builtin function available for C. Builtins can be prefaced with a "$" to distinguish them from program variables of the same name. :Info: call: cl: 02/13/80 call, cl Syntax: cl PROC_NAME {(arg1, arg2, argN)} Function: Requires an external entry name and an argument list, which can be empty. If an argument is of the type expected by the entry to be called, then it is passed by reference. If the called routine changes an argument passed by reference, the variables value is changed after the call. If probe can't determine what type of argument the entry to be called requires, or if the argument isn't of the expected type, the argument is passed by value. Expressions are always passed by value. See also "value", which is used to call external functions. :Info: CONSTANTS: constants: 09/29/79 Syntax of constants Notes on the syntax of constants: Probe recognizes arithmetic constants, string constants, and pointer constants. Arithmetic constants can be fixed or floating point, binary or decimal. String constants can be character or bit. Bit constants can be entered in any radix from binary to hex. Numbers can be entered in octal. See "NUMBER", "STRING, and "POINTER". :Info: continue: c: 09/29/79 continue, c Syntax: continue Function: If used after a breakpoint, this request resumes execution of the program. :Info: continue_to: ct: 09/29/79 continue_to, ct Syntax: ct LINE Function: This request sets a temporary break before LINE, then continues execution of your program. It is exactly equivalent to the two requests "before LINE:pause;continue". When you resume after a temporary break, it is automatically reset. :Info: CROSS_SECTION: cross_section: 09/30/88 Syntax of a cross_section Notes on the syntax of a cross-section: Probe provides cross_sections to allow reference to more than one element of an array at a time. To reference the i'th through j'th elements of an array, the cross_section reference is i:j (for Pascal, i..j). Asterisk (*) is used to reference all elements of an array. Examples: Suppose any of the following declarations appear: (PL/I) declare gosh (6) fixed bin; (Fortran) integer gosh (6) (Pascal) var gosh: array [1..6] of integer (COBOL) 77 gosh usage is comp-6 occurs 6 times. (C) int gosh [6]; In the case of Pascal, the request "value gosh [*]" prints out all elements of gosh, and "value gosh [2..4]" prints out the values of gosh(2), gosh(3), and gosh(4). For the other languages, the request "value gosh (*)" prints out all elements of gosh, and "value gosh (2:4)" prints out the values of gosh(2), gosh(3), and gosh(4). (note: for C you would use square brackets instead of round brackets) Notes on cross-section restrictions: Only the value and let requests use cross_sections. Cross_sections cannot be used as pointers to values. Cross_sections cannot be assigned to cross_sections (or scalars). :Info: declare: dcl: 09/30/88 declare, dcl Syntax: dcl NAME TYPE {-force} {external} {defined EXPR} Function: This request creates new probe variables, and declares external variables. NAME is the name of a new variable to be created, or the name of an external variable if external (ext) is specified. TYPE is a keyword specifying the type of the variable. If external is not specified (ie., creating a probe variable) and a variable named NAME already exists, you are queried whether to delete the old one. The -force (-fc) control argument causes the old one to be deleted in this case without a query. There are four possible values for TYPE: The first type is equivalent to PL/I fixed bin (35), Fortran, Pascal or C integer, and COBOL comp-6, and can be referred to as fixed, integer, int, or comp-6. The second type is equivalent to PL/I float bin (27), Fortran real, or C float and can be referred to as float or real. The third type is equivalent to PL/I aligned pointer (Multics ITS ptr), and is referred to as pointer or ptr. The fourth type is PL/I unaligned (packed) pointer or referred to as "pointer unaligned" or "ptr unal". Specifying "defined EXPR", where EXPR is a variable expression designating a region of storage having one of the above TYPE's, causes NAME to be a synonym for that region of storage. This feature is a typing convenience, allowing a short name to be used in place of a complicated expression. Notes: You are warned about a name conflict if a program variable of the given NAME is known in the current block when the variable is declared. If this warning is given, you must refer to the variable with a percent sign before its name to distinguish it from the program variable. Examples: dcl gravel comp-6 dcl clover ptr -force dcl sys_info$max_seg_size fixedexternal dcl axi fixed defined info_ptr -> aregs (i).x.index :Info: display: ds: 05/04/82 display, ds Syntax: ds {*} ADDRESS {FORMAT} {COUNT} Function: The display request displays an arbitrary location in a selected format. The location displayed depends on the type of ADDRESS supplied. If ADDRESS is a reference to a VARIABLE, the address of the VARIABLE is the location displayed. Otherwise, ADDRESS must be an expression that evaluates to a pointer; the value of the expression gives the location to be displayed. If an asterisk appears before a pointer VARIABLE, data pointed to by the pointer's value is displayed. Notes on display request formats: octal, o ascii, character, ch bit, b binary, bin, binary35, bin35 binary71, bin71 float, f, float27, f27 float63, f63 pointer, ptr, its instruction, i code (prints the error message associated with a status code) Notes: Count is the number of elements displayed. The size of an element depends on the format displayed. The default count is one. Note that one pointer is 72 bits (two words), and one instruction can be as many as four words (for an EIS instruction). Examples: ds 253|100 octal 20 dumps 20 words in octal. ds foo ascii 64 dumps first 64 chars of foo. ds ip|0 i dumps current instruction. :Info: execute: e: 09/27/79 execute, e Syntax: execute STRING Function: The command line STRING is passed to the Multics command processor. This request is chiefly useful in break request lists, because the more convenient ".." escape to the Multics command processor is not available there. You can pass an arbitrary line to the Multics command processor by preceding it with ".." on a new line. No other requests can follow it on the same line. Examples: ..ls >udd>Gtr>Weir>*.pl1 e "ls >udd>Gtr>Weir>*.pl1" ..cwd >udd>Robot>Gort; dl Klaatu; ls -tt e "cwd >udd>Robot>Gort; dl Klaatu; ls -tt" :Info: EXPRESSIONS: expressions: 09/29/79 Syntax of expressions Notes on expression syntax: Probe expressions are made up using the arithmetic operators "+", "-", "*", "/". Precedence of */ over +- is used in evaluating, and parentheses can be used to alter the order of evaluation. See also PREDICATE :Info: goto: g: 09/29/79 goto, g Syntax: goto LINE Function: This request leaves probe and resumes execution of your program at LINE. It is an error to use this request if the LINE is in a program that is not active. Because of unpredictable compiler optimizations, this request can be dangerous to use if the program was compiled with -optimize. See "optimization". :Info: halt: h: 09/29/79 halt, h Syntax: halt Function: This is the default break request. It invokes a new probe command level. It has no effect when typed at probe command level, only when in break requests. If a break is set with no break request list supplied by you, halt is assumed. :Info: handlers: 05/04/82 handlers Syntax: handlers handlers N handlers OBJECT Function: The handlers request displays the condition names and actions of the condition handlers established by the current procedure or a specified procedure invocation. If N is specified, stack level N is used. If OBJECT is specified, the last stack frame for the procedure OBJECT is used. Notes on handlers: Information about a handler is printed in the following format: on CONDITION_NAME {(FILENAME)} {snap} ACTION where ACTION is one of the following: call PROCEDURE_NAME begin block at line N system :Info: help: 09/29/79 help Syntax: help help * help TOPIC Function: The help request prints information about probe. If it is invoked with no argument, it prints general information about probe. If the argument is an asterisk, it prints a list of all topics for which info exists. Otherwise, it prints information about TOPIC. Examples: help help prints this info. help status prints information about the "status" request. help probe_status prints information about bugs in probe. :Info: if: 09/29/79 if Syntax: if PREDICATE : REQUEST Function: The "if" request evaluates its PREDICATE argument. If the result is true, REQUEST is executed, otherwise it is skipped. This request is especially useful in break request lists, where it can be used to cause conditional breakpoints. For example, to stop whenever the variable "odin" equals 1, the break request list can include "if odin = 1:halt". :Info: input_description: ids: 05/04/82 ids Syntax: ids ATTACH_DESCRIPTION Function: This request takes an ATTACH_DESCRIPTION and creates an IOCB, then causes probe to read all its input from this IOCB until further notice. The IOCB is destroyed the next time input_description or input_switch is invoked. Notes on input description: The effects of input_switch, output_switch, input_description and output_description, unlike other requests, are static to the process and remain from one probe invocation to the next until reverted. Examples: ids tty_ stereo_console causes further input to be read from the device stereo_console. :Info: input_switch: isw: 05/04/82 input_switch, isw Syntax: isw Function: Restores input to the default, user_input; otherwise causes probe to read from a specified switch. The argument must be the name of an already attached IOCB. Notes on restoring the input switch: The effects of input_switch, output_switch, input_description and output_description, unlike other requests, are static to the process and remain from one probe invocation to the next until reverted. :Info: language: lng: 09/29/79 language, lng Syntax: lng Function: Given the name of one of the languages supported by probe, this request sets the current language mode. Otherwise, it displays the name of the current language mode. Notes on setting and displaying the language: See "Languages Supported" in "probe" info. :Info: let: l: 09/29/79 let, l Syntax: let VARIABLE = EXPRESSION let CROSS-SECTION = EXPRESSION Function: This request sets the VARIABLE or CROSS-SECTION to the value of EXPRESSION. If type conversion is needed, it is performed according to the conversion rules of PL/I. Certain data types cannot be assigned to any type other than their own (e.g. area, file). Notes on assigning values: Because of unpredictable compiler optimization, the change sometimes may not take effect, even though the "value" request seems to show that it has. See "optimization". :Info: list_builtins: lb: 01/11/80 list_builtins, lb Syntax: lb Function: This request prints a summary of all builtins and their meanings. :Info: list_help: lh: 09/29/79 lh Syntax: lh Function: The list_help request prints a summary of all TOPICS for which there is info. The topics are divided into three categories. Most files are infos in the segment probe.info, so to see a copy of all probe information, print the entire segment. To print information on a topic, type "help TOPIC". :Info: list_variables: lsv: 01/11/80 list_variables, lsv Syntax: lsv {NAME} Function: This request lists all variables that have been declared by the "declare" request in the current invocation of probe, along with their types and values. If one or more NAMEs are supplied then only those variables are listed, otherwise all defined variables are listed. :Info: modes: mode: 11/07/84 modes, mode Syntax: mode (for display only) mode MODE VALUE (to set mode values) Function: A mode is a probe variable that specifies how a particular function behaves. MODE is the name of the mode to set, and VALUE is the new value. For information about a particular mode, type "section MODE". Notes on modes: Most modes can be set to a value that is either a LENGTH or a BOOLEAN. A LENGTH is either "long" ("lg"), "short" ("sh") or "brief" ("bf"), and is used to specify the kind or amount of printing to be done by the part of probe. The amount of output is greatest for "long", least for "brief", and "short" is intermediate. In some cases "short" is synonymous with "brief". BOOLEAN is used to turn a feature on or off. It can be "yes", "on", or "true"; or "no", "off", or "false". error_messages, em (LENGTH) controls the length of the text used for an error message. The default is "long". qualification, qf (LENGTH) controls the format of variables names as printed by "value": For "brief", prints only the last name of a structure. (Default) For "long", prints names with full qualification. COBOL and Fortran are always printed briefly, regardless of the value of this mode. value_print, vp (LENGTH) controls whether or not the value request prints the name of a variable. Possible values for this mode are: For "brief", names are never printed. For "short", names of array and structure elements are printed (Default). For "long", names are always printed. value_separator, vs (STRING) controls the string printed by the value request between the name of a variable and its value. Only the first 32 characters of STRING are used. The default value_separator is " = ". truncate_strings (BOOLEAN) truncates character and bit string values to 200 characters or bits, printing "" at the end if the string is longer than 200. This mode is on by default. meter (BOOLEAN) controls the printing of meter values when breaks are hit. The meter values are the number of minutes and seconds of real time ("TIME"), the number of seconds of virtual cpu time ("VCPU"), and the number of page faults ("PAGE FAULTS") since the last break was restarted or since "mode meter on". These values do not include any overhead from probe itself. prompt (BOOLEAN) controls whether or not probe prints a prompting string on the terminal when it is listening for a request. It is off by default. See the "prompt_string" mode. prompt_string (STRING) specifies the string to be used for prompting. The initial value is "probe^[(^d)^] ". STRING is used in a call to ioa_$nnl, where the first argument is a bit (1) that is on if the current invocation of probe is recursive, and the second argument is the current probe depth. :Info: NUMBER: number: 09/30/79 number Notes on the syntax of numeric constants: Probe recognizes numeric constants using the rules of PL/I. A numeric constant can be binary or decimal, fixed or float. A binary numeric constant uses only "1" and "0" as digits, and always has a trailing "b". A decimal constant uses the digits "01234565789", or lacks the trailing "b". The type of a constant is determined by its literal appearance. Examples: 259 fixed decimal (3) -1101b fixed binary (4) 12.3 fixed dec (3,1) 4.21f10 fixed dec (3,-8) 4.301e10 float dec (4) Integers can be entered in octal by following them with a lower case "o". (This is not found in PL/I.) Example -- 123o fixed bin (35), value is 83 decimal Fortran double precision constants are not implemented. :Info: object: obj: 05/04/82 object,obj Syntax: object {N} Function: Displays the assembly instructions for the current source line, or for the next N source lines. :Info: optimization: 09/30/79 optimization Notes on the ill effects of optimization: Optimization is an action performed by Multics translators to generate efficient code. This can cause problems for probe, and therefore one should not try to use probe on a segment compiled with "-optimize". Notes on optimization and the 'value' and 'let' requests: One class of problems arises when a compiler stores the value of a variable in a register, instead of in memory. Probe looks in memory for the variable, and obtains an obsolete copy of its value. You can try to set the variable. Probe has no way of knowing which register holds the current copy of the value, and so it changes the value in storage. When the register is later stored, this wipes out the value stored by probe. This problem is particularly insidious, because until the value is wiped out, a look at it with the "value" request will seem to show the proper value. Notes on optimization and 'gotos': Most compilers perform some optimizations on an inter-statement basis. This means that the compiler takes advantage of the fact that if there are no labels on statement N, and if statement N is executed, then statement N-1 must also have been executed, and that any values calculated then are still valid. This assumption is made false by using the probe goto, which can transfer to any line. To use the probe goto safely, one should only goto lines with labels. This request will become safer when compilers are able to suppress this optimization, which will happen in some future release of Multics. :Info: output_description: ods: 05/04/82 output_description, ods Syntax: ods ATTACH_DESCRIPTION Function: This request takes an ATTACH_DESCRIPTION and creates an IOCB, then causes probe to write all its output on this IOCB until further notice. The IOCB is destroyed the next time output_description or output_switch is invoked. Notes on output description: The effects of input_switch, output_switch, input_description and output_description, unlike other requests, are static to the process and remain from one probe invocation to the next until reverted. Examples: ods vfile_ probe_trace.output causes further output to be written to the segment 'probe_trace.output'. :Info: output_switch: osw: 09/17/81 output_switch, osw Syntax: osw {SWITCH} Function: With no argument, causes probe output (except for error output) to be written on the default switch, user_output; otherwise causes non-error output to be written on a specified switch. The argument must be the name of an already attached IOCB. Notes on restoring the output switch: The effects of input_switch, output_switch, input_description and output description, unlike other requests, are static to the process and remain from one probe invocation to the next until reverted. :Info: PATH: path: 09/30/79 path Notes on the syntax of a path: Some probe requests accept a Multics pathname as an argument. If a PATH contains characters other than the letters of the alphabet, the digits 0-9, or the characters ">", "<", ".", ",", "-", "_", "$", or "/", it must be enclosed in quotes. Examples: >udd>SoftWork>Brie>dog_lb absolute pathname hunter>aoxo$moxoa relative pathname "PSC+OCCUPATION.10|06|79" strange characters :Info: pause: pa: 09/30/79 pause, pa Syntax: pa Function: The pause request is useful in breakpoint request lists. It is like halt, in that it causes execution of the breakpoint request list to be suspended and probe to read from the terminal. Unlike "halt", when the breakpoint is continued (by the "continue" request), the break is immediately reset. The effect is a one-time-only temporary break. The "pause" request is used to implement the "step" and "continue_to" requests. :Info: POINTER: pointer: 09/30/79 pointer Notes on the syntax of probe pointer constants: Probe pointer constants are of the form SSS|WWW or SSS|WWW(bbb) where SSS is the segment number in octal, WWW is the word offset in octal, and bbb is the bit offset (optional) in decimal. SSS can be replaced with a two letter code to specify a pointer relative to the current stack frame (sp), linkage section (lp), text segment (tp), or instruction (ip). Examples: 254|100(13) bit 13 of word 100 in segment 254 sp|2500 word at offset 2500 in current stack frame ip|0 instruction last executed lp|10 word 10 in linkage section :Info: pointers: source_pointer: control_pointer: 03/14/83 pointers, source_pointer Notes on probes two program state pointers: Two pointers keep track of the program's state: source indicates current source-program statement. control indicates current control point. The values of the pointers can be obtained using the "where" request. The source pointer is set using the "position" or "use" request. The control pointer is set when probe is entered. Notes on the probe 'source' pointer: The source pointer always indicates some location in a program. If the program is active, then it indicates a stack frame associated with the program. If the object segment was compiled with the "table" options then a source line number will be available, otherwise the location will be indicated by an octal offset from the base of the segment to an instruction. If the program was compiled with a "table" option, probe obtains the text of source lines from the program's source segment (NAME.pl1, NAME.fortran, etc.). This is either the segment that the program was originally compiled from, if it exists, or the first segment with the appropriate name found using the "probe" search paths. If no source segment can be found, the position and source requests are unable to print source lines. Notes on the probe 'control' pointer: If probe was invoked by a breakpoint, indicates the statement where the break occurred. If probe was invoked from the command line, indicates the last location executed in the procedure first examined, whether it took a fault, or called out, unless it was inactive, in which case it is the location of the entry statement for the procedure. :Info: position: ps: 03/14/83 position, ps Syntax: ps STRING ps CONSTANT_ADDRESS_VALUE Function: Sets the source pointer to the statement specified and prints the statement. Notes on positioning: The source segment used is either the one that the program was originally compiled from, if it exists, or the first segment with the appropriate name (NAME.pl1, NAME.fortran, etc.) found using the "probe" search paths. If no source segment can be found, probe is unable to print source lines. It is only possible to set the source pointer to an executable statement. Every language has certain statements that are not executable. Blank lines, comments, and declarations are not executable in any language. See "where" and "LINE" for more information. :Info: PREDICATE: predicate: 09/30/88 predicate Notes on the syntax of a predicate: EXPRESSION COMPARISON EXPRESSION where COMPARISON is one of the following operators: "<", ">", "<=", ">=", "=", "^=". A PREDICATE is a comparison of two values, and yields a Boolean value. (A Boolean variable is one that can have only two possible values, corresponding to "true" or "false". PL/I uses bit (1) for Boolean variables, Fortran use logical. The concept is absent from COBOL.) The "if" and "while" requests accept a predicate, then perform some action if the predicate is true. In Fortran mode, the Fortran equivalents (".lt.", ".gt.", etc.) are allowed and in C mode, "=" and "^=" have the equivalents "==" and "!=" respectively. Notes on the predicate restrictions: PREDICATES cannot be nested or combined. In a future release, the operators "&", "|", and "^" will be available, but not now. :Info: quit: q: 09/30/79 quit, q Syntax: q Function: It exits the current invocation of probe. If the current invocation was a recursive invocation, you may still be in probe, although at a lower level. :Info: REQUEST: request: 09/30/79 request Notes on the syntax of a probe request: Probe requests begin with the name of the probe function to be used (such as "value", or "help") followed by the arguments to the request. A request ends with a newline or with a semicolon. Certain requests accept a request or list of requests as one of their arguments (e.g. "before", "after", "if" and "while"). When a request accepts a request (or list of requests) as an argument, the argument (which is called a "request list") is preceded by a colon (":"). A request list can be either a single request, or a list of requests, enclosed in parenthesis and separated from each other by a semicolon. Examples: before 259 : (value a; value b) sets a break before line 259. When this break is hit, the values of variables a and b are printed. before 680: if a = 3: halt nests 3 levels of requests. When the break at line 680 is hit, the "if" request is executed. If a=3, then, the "halt" request is executed. :Info: reset: r: 05/04/82 reset, r Syntax: reset resets the break at the current statement, if any. reset LINE resets the break at LINE in the current procedure. reset STRING resets all lines containing STRING in the current proc. reset /REGEXP/ resets breaks at all lines matching the regular exp. reset OBJECT resets all breaks in the object segment OBJECT. reset -all resets all breaks set by you in all segments. reset * same as "reset -all". Function: Resets probe breaks at selected lines in selected procedures. Notes on resetting probe breakpoints: The LINE, "STRING", and /REGEXP/ arguments can be preceded by "before" ("b") to set only breaks before statements, or "after" ("a") to set only breaks after statements. As breaks are reset, their line numbers are printed, unless the control arg "-brief" is specified. :Info: source: sc: 03/14/83 source, sc Syntax: sc {N} sc path PATH Function: The first form prints the next N source statements, beginning with the current one. If N is omitted, then one statement is printed. Any lines in the source segment between the first and last statement lines are printed. The second form is used to specify the location of the source segment. It is useful when the source has been moved since the object segment was compiled. In this second form, the literal keyword "path" is followed by the pathname, for example: sc path >udd>Wire>u>Doon>this Notes on the source request: If no PATH is specified, the source segment used is either the one that the program was originally compiled from, if it exists, or the first segment with the appropriate name (NAME.pl1, NAME.fortran, etc.) found using the "probe" search paths. If no source segment can be found, probe is unable to print source lines. :Info: stack: sk: 05/04/82 stack, sk Syntax: sk displays the whole stack. sk N displays the first N frames. sk M, N displays N frames starting with frame M. Function: Displays your stack, showing block names and line numbers (if known) last executed in each frame, and conditions raised. Each frame is displayed with a number, which is the "level number", and used in various requests to indicate a stack frame. If "long" is specified, the pathname of each segment is also printed, along with the octal offset. If "all" is specified, "support" frames are included in the trace; they are skipped by default. (See "Notes on support frames" below.) Examples: sk 4, 3 all displays frames 4, 5, and 6. sk 3 displays three frames, starting with current one. Notes on support frames: Support frames are frames that belong to a support procedure. A support procedure is a system utility that performs action directly related to the compiled user code (for example, allocation) and in which there is a high probability that any errors that arise are due to improper use by you (allocating in a full area). When conditions arise in support frames, the standard Multics error handler attributes the error to the user code that called the support procedure, rather than the support procedure. The probe "stack" request does not display support frames unless invoked as "stack all". Support frames are given incremental numbers between those of the surrounding frames (6.1, 6.2, ..., 6.11, ...). :Info: status: st: 09/30/79 status, st Syntax: status displays all breaks in the current proc. status LINE displays break at LINE in current proc. status OBJECT displays all breaks in proc OBJECT. status -all displays all breaks set by you in all procs. status * displays the pathnames of all procs with breaks set by you. Function: Displays line numbers of breaks, and optionally the break request list. Notes on the status request: The break request list of the break is displayed by default for "status LINE", and omitted for all other forms. The control arg "-long" causes the break list to be printed; "-brief" suppresses it. Just as for the "reset" request, a break before a line can be distinguished from a break after a line by prefacing the LINE with "before" or "after" (abbreviations: "be", "b"; "af", "a"). Examples: status >udd>Dog20>foo>zloty lists all breaks in zloty. status 35 -lg lists breaks and text at line 35. st b 7 lists only the break before line 7. st -all lists all breaks set by you. :Info: step: s: 09/30/79 step, s Syntax: step Function: The step request places a temporary break (see "pause") at the statement that it feels is "next", and then resumes executing your program. It is somewhat unreliable (see below) but, when it works, it allows you to step through the program a statement at Notes on the pitfalls of the step request: The reason that "step" is so unreliable is that often the statement that comes next in the object segment is not the next one executed by the program. This happens when the current statement is a call, a goto, the "end" statement of a loop (or continue statement for Fortran), or the "then" statement of an "if-then-else". (There are other statements that fail, but these are the most common). In some cases (do loop, call), the "next" statement is eventually executed, and the break occurs. :Info: symbol: sb: 09/30/88 symbol, sb Syntax: sb VARIABLE {long} Function: This request displays the attributes of a symbol. The attributes of all members of a PL/1 or C structure, or a COBOL or Pascal record can be displayed by following the name with "long". :Info: use: 03/14/83 use Syntax: use with no arg, source pointer is reset to initial value (same as control pointer). use LINE LINE in current procedure. use +N the statement N statements after the current one. use -N the statement N statements before the current one. use line +N the statement N lines after the current one. use line -N the statement N lines before the current one. use level N the last line executed in the block at stack level N. use level +N the last line executed for stack level (this + N). use level -N the last line executed for stack level (this - N). use OBJECT the last line executed in the most recent invocation of OBJECT - if OBJECT inactive, then its entry point. use STRING the next statement containing the literal string. use /REGEXP/ the next statement that matches the qedx regular expression REGEXP. Function: Sets the source pointer to the statement specified and but does not print the statement. Notes: See 'Notes on positioning' for more details. :Info: value: v: 09/30/88 value, v Syntax: value [EXPRESSION | CROSS-SECTION] {data} Function: The value request displays the value of a given EXPRESSION or CROSS-SECTION. For the syntax of an EXPRESSION or CROSS-SECTION, see the help files "expressions" and/or "cross_sections". Character string values are surrounded by quotes (") and quotes inside them are doubled. The data pointed to by C pointers may be displayed by following the EXPRESSION or CROSS-SECTION with "data". The simplest example of an EXPRESSION is the name of a variable, for example: v subr_args.ptr_len which prints the value of the variable or substructure ptr_len in the structure subr_args. You can control the circumstances under which the name of the variable being displayed is printed, the way a name is printed if it is printed, and the string that separates the name from the value - all by using the "modes" request. See "modes". If the EXPRESSION is an external function, it is called. See the "call" request. :Info: variables: 01/15/80 variables Notes on probe variables: Probe variables are variables created by the probe declare request. They are used like variables from programs. Unlike program variables, probe variables are not associated with a given block. Once defined, they can be referenced no matter what value the source pointer has. All probe variables are discarded when the process ends. Examples: Suppose there is a PL/1 structure 'struc' that is threaded onto a linked list by the pointer 'next', and you want to count the number of structures. This can be done by creating two probe variables, a pointer 'p', and a counter 'i', and using them in a while loop as follows: declare p ptr declare i integer let p = first let i = 0 while p ^= null : (let i = i + 1; let p = p -> struc.next) If the current program declares a variable with the same name as a probe variable, the program variable is used. To reference the probe variable, preface it with a percent sign, e.g. %p or %i in the above example. It is recommended for clarity that probe variables always be prefixed by %. :Info: where: wh: 09/24/84 where,wh Syntax: wh source prints the value of the source pointer. wh source path prints the pathname of the segment referenced by the source pointer. (ie., the source segment currently in use). wh control prints the value of the control pointer. wh object prints the value of the control pointer. wh control path prints the value of the control pointer. prints the pathname of the segment referenced by the control pointer (ie., the current object segment). wh object path prints the value of the control pointer. prints the pathname of the segment referenced by the control pointer (ie., the current object segment). Function: This request displays the values of the probe pointers. If invoked with no arguments, it displays the values of the source and control pointers. The following are also allowed: Notes: See also "pointers". :Info: while: wl: 09/30/79 while, wl Syntax: wl PREDICATE: REQUEST Function: This request executes REQUEST repeatedly, testing PREDICATE before each execution, as long as PREDICATE is true. See "PREDICATE", "if" and "REQUEST". An example of usage is in the info file describing probe variables. Type "help variables". ----------------------------------------------------------- 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