: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 "<MORE>" 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".
