1 :Info: probe: pb:
2 1990-07-24 probe, pb
3
4
5 Syntax as a command: pb procedure_name -control_args
6
7
8 Function:
9 provides symbolic, interactive debugging facilities for
10 programs compiled with PL/I, Fortran, Pascal, COBOL, ALGOL-68 or C.
11
12
13 Arguments:
14 procedure_name
15 is the reference name of an initiated program, or a pathname.
16 If procedure_name is not specified, the procedure owning the frame
17 in which the last condition was raised is assumed.
18
19
20 Control arguments:
21
22 -handle_conditions
23 sets up a handler for any conditions signalled while in probe,
24 that prints an appropriate message and prevents faulting.
25 Default
26 -no_handle_conditions
27 does not set up a handler for conditions signalled while in probe.
28
29
30 Notes:
31 Probe is self-documenting. For further information, invoke probe and
32 type: help
33
34 For a list of all requests, type: list_requests
35
36 For a list of all topics described by probe, type: list_help
37
38
39 Programs examined by probe should not have been compiled with code
40 optimizers, such as the -optimize control argument to the pl1 and
41 fortran commands. Optimization can causes program variables to
42 appear to have the wrong value when stopped at a break or fault.
43
44
45 :Info: summary.topic: summary:
46 1988-09-30 General information about probe
47
48 Summary:
49
50 Probe is a symbolic debugger for programs written in PL/1, Fortran,
51 Pascal, COBOL, ALGOL-68 and C. It permits you to interrupt a program
52 at a specified location, to examine or modify program variables, to
53 examine the stack history of block invocations, and to display source
54 lines and object instructions associated with an object location.
55 Probe can evaluate expressions involving program variables and call
56 external functions.
57
58
59 Self-documentation:
60
61 Use the probe "help" request to display information about probe
62 requests and other probe-related topics.
63
64 To see a list of probe requests, type:
65 list_requests
66 or
67 lr
68
69 To see details about a particular request, type:
70 help REQUEST_NAME
71 where REQUEST_NAME is the name of one of the probe requests.
72
73 To see a list of topics, type:
74 list_help
75 or
76 lh
77
78 To display information about a particular topic, type:
79 help TOPIC
80 where TOPIC gives one of the topic names shown by the list_help
81 request.
82
83
84 Probe interaction:
85
86 When probe has been invoked, it accepts requests from you. A probe
87 request consists of a keyword the name of the request to be
88 performed and its arguments, if any. More than one request can
89 appear on a line if they are separated by semicolons ";". For a
90 list of all requests, type: list_requests
91
92
93 Breakpoints:
94
95 A breakpoint is a set of probe requests associated with a program
96 statement. This set of requests is executed automatically by probe
97 whenever the location in the object segment corresponding to the
98 statement is executed. The most common request is "halt", which
99 suspends execution of the program and listens for further requests.
100 You can then examine and modify the state of the suspended program,
101 and resume or abort further execution. Other uses of breakpoints
102 are to display the state of the program without halting, or to effect
103 source-level patching by executing assignments.
104
105 For more information, type: help breaks
106
107
108 :Info: toc.topic: toc:
109 1988-09-30 Summary of help files for probe.
110
111
112 Info files are divided into three categories;
113 Info about requests.
114 Info about probe features.
115 Info about probe syntax.
116
117
118 Notes on probe request information:
119
120 To see information about a request, type:
121 help REQUEST_NAME
122 where REQUEST_NAME is the name of the request.
123
124 For example: help value
125
126 The help request accepts either long or short name for a request.
127
128
129 Notes on available probe features:
130
131 breaks
132 builtins
133 c
134 cobol
135 fortran
136 optimization
137 pascal
138 pointers source_pointer control_pointer
139 variables variables created by the probe declare request
140
141
142 Notes on syntax info available:
143
144 CONSTANTS
145 EXPRESSIONS
146 LINE
147 NUMBER
148 PATH
149 PREDICATE
150 REQUEST
151 STRING
152 CROSS-SECTION
153 POINTER
154
155 Names of syntax topics can be typed in lower case.
156
157
158 :Info: C: c:
159 1988-09-28 Probe and C
160
161 Notes on probe and the c language:
162
163 When the current language type is C, probe's set of data types
164 expands to include void types, enumeration types, unions, variant
165 records typedef, and type pointers. The set of builtin functions
166 for use with the C language data types is the function "sizeof".
167 Also the modulus operator % similar to the PL1 builtin "mod"
168 function and the right >> and left << shift operators are
169 available.
170
171
172 Differences occur in the syntax that represents array indices, and
173 operators. Array indices are enclosed as in Pascal in square
174 brackets. The cross-section ranges are written with ":" e.g.
175 afirst:last. Although C does not have true character strings C
176 uses arrays of characters, the array syntax will be used to display
177 a character array. see "string" for more details String constants
178 are contained in double quotes " and single characters are
179 contained in single quotes '. e.g. a character string - "this is
180 a string" , a single character - 'a'.
181
182
183 Pointer valuesindirection operators are represented by the star *
184 symbol, and the address operator if "v" is a variable then "&v" is
185 the address of that variable is represented by the ampersand &
186 symbol.
187
188 The relational operators available are: != == < > <= >=
189
190 To maintain consistency with the other languages that probe supports
191 the following will not be supported : bitwise operators && ||, type
192 casting, conditional expressions ?:, logical "and" and "or"
193 operators, and compound assignments += -= etc..
194
195
196 :Info: PL1: pl1:
197 1990-06-28 Probe and PL1
198
199 Notes on probe and the pl1 language:
200
201 Probe uses a PL/1_like syntax when the current language is PL/1. Probe
202 communicates with you based on information in the symbol table and the
203 statement map which are produced by the PL/1 compiler. The limitations
204 of the symbol table sometimes limit the communication with probe.
205
206
207 Examples:
208
209 1 Probe cannot determine the correct dimension size of an array if
210 the upperbound of the dimension is an element other than the first
211 element of an "external" structure.
212 For example: "dcl x dim 1:struct.e4 fixed bin based pt;
213 where "e4" is the fourth element in, "struct", the external
214 structure. Probe symbol incorrectly interprets the upperbound
215 of the dimension as the first element instead of the proper
216 element in the external structure.
217
218 2 Probe cannot determine the correct value of a variable if the
219 variable has an implicit subscripted base reference.
220 For example: "dcl x fixed bin based b 3;".
221 Probe value interprets "x based b 3" as b1 -> x.
222
223
224 3 Probe cannot determine the correct value of a variable if the
225 address of the variable has an implicit base reference containing
226 the address expression or is a defined reference.
227 For example: "dcl x fixed bin based addr p1"; or
228 "dcl x fixed bin defined p2"
229
230
231 :Info: COBOL: cobol:
232 1979-09-28 Probe and COBOL
233
234 Notes on probe and the cobol language:
235
236 Probe uses a COBOL-like syntax when the current language is COBOL.
237 The current language will be COBOL whenever the current source line
238 is in a COBOL program. When in COBOL mode, probe is insensitive to
239 the case of variable names. The hyphen character can be used to form
240 names, as it is in COBOL. Aggregate names can be qualified in the
241 COBOL manner c of b of a as well as in the PL/I manner a.b.c An
242 aggregate is displayed by displaying the values of each of its
243 members.
244
245 To find out what the current language is, use the "language" request,
246 with no arguments. See "where" and "language".
247
248
249 :Info: Fortran: fortran:
250 1979-09-28 Probe and Fortran
251
252 Notes on probe and the fortran language:
253
254 When the current source line is a Fortran statement, probe is in
255 fortran mode, and acts a little differently.
256
257 Logical variables are displayed as ".true." or ".false." instead of as
258 "1"b or "0"b.
259
260 Case is ignored if the program was compiled with "-card" or "-fold".
261
262 The relational operators .le., .lt., .eq., .ne., .gt., .ge. can be
263 used.
264
265
266 :Info: Pascal: pascal:
267 1983-09-08 Probe and Pascal
268
269 Notes on probe and the pascal language:
270
271 Invoked on a Pascal program, probe understands all the Pascal data
272 types, including enumerated types, typed pointers, sets, records,
273 files, and user-defined types. Probe understands the Pascal builtin
274 functions chr, eof, eoln, false, nil, ord, and true.
275
276 Array indices are enclosed in brackets, for example "aij".
277 Cross_section ranges are written with "..", as in "afirst..last".
278 References to record fields must specify all levels; implicit level
279 names are not allowed. For example, "a.b.c.d" cannot be abbreviated
280 as "a.d" as can sometimes be done with PL/1 structure elements.
281
282
283 Pointer values are written with circumflex ^ as the up-arrow, for
284 example "p^" to indicate the value that p points to. String
285 constants are enclosed in apostrophes: 'This is a string'. The two
286 boolean values are "true" and "false".
287
288
289 :Info: LINE: line:
290 1979-09-28 Syntax of a LINE
291
292 Notes on the syntax of 'line':
293
294 A LINE is used to identify a location in an object segment, and
295 possibly the source line associated with that location. A LINE can
296 be a label known in the current procedure, the name of an external
297 entry, a line number in the source file for the current procedure, $b
298 which denotes the current break, or $c which denotes the current
299 line.
300
301
302 Source line numbers consist of a source file number and a line number.
303 The file number is optional. If it is not specified, the main file
304 file 0 is used. File numbers can be found by examining the
305 compilation listing. The first include file is file number 1, and so
306 on. The second part of a source line number is the actual line in
307 the file. This number is found printed on the left edge of a
308 compiler listing. It is also the number one would use with an
309 editor.
310
311
312 Examples:
313
314 $c the current line.
315 $b the line where the latest break happened.
316 259 line 259 in the main file.
317 2-43 line number 43 in include file 2.
318 grotz3 the line labeled by label array constant grotz3.
319 $101 the line labeled by 101 Fortran or COBOL - see below.
320
321
322 To reference the Nth statement after a given statement, follow the
323 line location by a comma and N. For example, consider the COBOL
324 fragment:
325
326 para.
327 add 3 to b giving c. display "Cobol is ", c. move spaces to neptune.
328
329 the request "ps para,1" positions to the "display" statement, because
330 that is the first statement after the one labeled by "para". If the
331 "display" statement is on the next line, instead of the same line,
332 "ps para,1" still works.
333
334
335 Fortran: Since Fortran labels are numbers, which probe also uses to
336 specify line numbers, Fortran labels must be preceded by a dollar
337 sign. For example, "100" is a reference to line number 100, but
338 "$100" is a reference to the line whose label is 100.
339
340
341 COBOL: COBOL allows the use of labels that look like numbers. When a
342 number is used for a LINE, it refers to a source statement line
343 number, not a label. But if the number is preceded by a dollar sign,
344 it is treated as the name of a paragraph label.
345
346
347 :Info: STRING.topic: STRING: string: STRINGS: strings:
348 1988-09-30 Syntax of character string constants.
349
350 Probe recognizes character strings and bit strings. A string is
351 delimited by the quote character ", and for Fortran and Pascal, the
352 apostrophe ' can also be used. In the C language a single
353 character constant can be represented with an apostrophe and a string
354 which can be any number of characters from 0 to 256 is delimited by
355 the quote. The maximum length of a string is 256 characters.
356 Strings can contain any character. To enclose the quote character in
357 a string, double it. For example, "a""b" represents the string a"b
358 containing a single embedded quote character. See constants for more
359 info.
360
361
362 Examples:
363 "preceded by itself, yields falsehood"
364 char string of length 36.
365
366 "1010"b bit string of length 4.
367 "033"b3 octal bit string, 9 bits.
368 "A79A"b4 four hex digits, 16 bits.
369
370 """" a string of length 1, containing a quote.
371 'a Fortran string" apostrophe and quote are equivalent.
372 "newline is \012" a string of length 12.
373
374 '1' a single character string for C
375 "" an empty string in C
376
377
378 In the C language mode you can specify parts of the character array
379 in the following format:
380
381 *p specifies the single character pointed to by the
382 pointer "p".
383 p0:4 specifies the 5 characters starting with the character
384 pointed to by "p".
385 p specifies all the characters in the array, starting
386 the character pointed to by "p", ending with either
387 the null character, the 256th character, or the maximum
388 size of the array which ever comes first.
389 p0:N-1 where N is the index to the null character this
390 format will over come the 256 character default and
391 all the characters from "p" to "N-1" to be specified.
392
393
394 :Info: TOPIC:
395 1979-09-30 Misunderstanding of the help command
396
397 Notes on the help command:
398 You may have misunderstood the documentation. A word in uppercase
399 like TOPIC represents any possible topic that might be supplied as an
400 argument to the help request. By typing "TOPIC" you got information
401 on the subject of "TOPIC". If you had typed a lowercase string like
402 "help value", you would see information about the probe value request.
403 The word TOPIC in the command description is to be replaced with the
404 name of the topic you are interested in, when you type the help
405 request. Please try again.
406
407 To see a list of all topics, type:
408 list_help
409 or just:
410 lh
411
412
413 :Info: after: af: a:
414 2020-12-19 after, af, a
415
416 Syntax: a LINE :REQUEST
417 a /REGEXP/ :REQUEST
418
419
420 Function:
421 This request sets a breakpoint after a location in the object
422 segment. The "after" request cannot be used on COBOL statements.
423 For more information on breakpoints, type: help breaks
424
425
426 Arguments:
427 LINE
428 gives a source line number on which a statement begins. The
429 breakpoint is set after the end of that statement. The default for
430 LINE is the current line $c.
431 :REQUEST
432 gives the probe request or list of requests to be executed if the
433 breakpoint is reached. A colon : separates the after request
434 name and optional location from the REQUEST. The default for
435 :REQUEST is ":halt".
436 /REGEXP/
437 If /REGEXP/ is used instead of LINE, a break is set after every
438 line matching the qedx regular expression REGEXP.
439
440
441 Notes:
442 A break set after a line happens after all effects of the statement
443 are completed. If the statement sets a variable, the variable will
444 have its new value by the time the break is executed. Depending on
445 the nature of the code generated by the translator for the statement,
446 a break set after a line sometimes cannot be executed. This is often
447 the case for do loops and if-then-else constructions, and always the
448 case for return statements and for gotos.
449
450
451 For information about setting a breakpoint in a line containing
452 several statements, type: help LINE
453
454 For information about associating several probe requests with a given
455 breakpoint, type: help REQUEST
456
457
458 :Info: arguments: args:
459 1985-05-04 arguments, args
460
461 Syntax: args
462 args N
463 args OBJECT
464
465
466 Function:
467 The args request displays the names and values of the arguments to
468 the current procedure or a specified procedure invocation.
469
470
471 Arguments:
472 N
473 stack level N is used. The default is to use the stack level
474 associated with the current procedure.
475 OBJECT
476 is the reference name of an entry point into some object segment.
477 The most recent stack frame for the procedure OBJECT is used.
478
479
480 :Info: before: be: b:
481 2020-12-19 before, be, b
482
483 Syntax: b LINE :REQUEST
484 b /REGEXP/ :REQUEST
485
486
487 Function:
488 This request sets a breakpoint before the location in the object
489 segment given by LINE. For more information on breakpoints,
490 type: help breaks
491
492
493 Arguments:
494 LINE
495 gives a source line number on which a statement begins. The
496 breakpoint is set before the start of that statement. The default
497 for LINE is the current line $c.
498 :REQUEST
499 gives the probe request or list of requests to be executed if the
500 breakpoint is reached. A colon : separates the before request
501 name and optional location from the REQUEST. The default for
502 :REQUEST is ":halt".
503 /REGEXP/
504 If /REGEXP/ is used instead of LINE, a break is set before every
505 line matching the qedx regular expression REGEXP.
506
507
508 Notes:
509 For information about setting a breakpoint in a line containing
510 several statements, type: help LINE
511
512 For information about associating several probe requests with a given
513 breakpoint, type: help REQUEST
514
515
516 :Info: breaks.topic: breaks:
517 1979-09-29 Probe breakpoints
518
519 A breakpoint is a list of one or more probe requests that is
520 associated with some statement in a program. The probe requests of a
521 breakpoint are known as the break request list for the break. A
522 breakpoint can be set "before" or "after" a given line. A break
523 before a line is executed immediately before the line itself is
524 executed, and a break after a line is executed after the line has
525 been executed. Therefore if a transfer is made at line X of a
526 program, a break before line X is executed, but a break after line X
527 is not. If a transfer is made TO the state- ment on line X, a break
528 set before line X is executed, but one set after line X-1 is not. If
529 statement X assigns a new value to a variable, a break set before X
530 is executed before the variable changes, but one after X takes effect
531 after the variable has been changed.
532
533
534 Breakpoint requests:
535 To set breaks, use the "before" and "after" requests.
536 To list breaks where they are set what is in their request lists,
537 use the "status" request.
538 To remove breaks, use the "reset" request.
539 To resume execution after a break, use the "continue" request.
540
541
542 Implementation of breakpoints:
543 A breakpoint is set at a particular instruction by replacing it with
544 an instruction that transfers control to a special sequence of code
545 that probe places at the end of the object segment. This sequence of
546 code is called the "map sequence". It extends the current stack
547 frame, stores information about the break in the extension created
548 and uses a special pl1 operator to call probe.
549
550
551 :Info: builtins:
552 1988-09-30 Probe builtins
553
554 Notes on builtins:
555
556 For a summary of builtins, use the "list_builtins" request.
557
558 All probe builtins, except "ptr", are exactly equivalent to the
559 Multics PL/I builtins by the same name. The "ptr" builtin is an
560 extension to the Multics "ptr" builtin. The third argument, if
561 given, is the bit offset of the resultant pointer value
562
563 "sizeof" is the only probe builtin function available for C.
564
565 Builtins can be prefaced with a "$" to distinguish them from program
566 variables of the same name.
567
568
569 :Info: call: cl:
570 2020-12-19 call, cl
571
572 Syntax: cl PROC_NAME
573 cl PROC_NAME ARG1 ARG2 ... ARGn
574
575
576 Function:
577 Invokes an external entry point, optionally passing as arguments one
578 or more variables from the current program, or other EXPRESSIONs.
579
580
581 Arguments:
582 PROC_NAME
583 names the external entry point to be called.
584 ARG1, ARG2, ARGn
585 each is an EXPRESSION whose value is passed as an argument to the
586 external entry point. The simplest EXPRESSION is the name of a
587 variable declared by the current program. EXPRESSIONs are
588 documented with the value request. For information about
589 EXPRESSIONs, type: help value
590
591
592 Notes:
593 Only external program entry points may be called. The call is
594 performed by searching for the PROC_NAME external entry point and
595 examining the entry point descriptors for its expected arguments. If
596 the given ARGi is of the data type requested in the descriptor, then
597 ARGi is passed by reference. If the called routine changes an
598 argument passed by reference, that variable's value is changed after
599 the call.
600
601 If probe can't determine what type of argument the external entry
602 point expects, or if the argument isn't of the expected type, the
603 argument is passed by value. EXPRESSIONs more complicated than a
604 single variable name are always passed by value. For information
605 about EXPRESSIONs, type: help value
606
607
608 For information about creating temporary variables for use in call
609 requests, type: help declare
610
611
612 Examples:
613 To invoke an external entry point that requires no arguments:
614
615 call date_time
616 12/19/20 1752.9 pst Sat
617
618 To invoke an entry point with an EXPRESSION:
619
620 call clock "iso_date_time"
621 2020-12-19 17:52:19 pst
622
623
624 To invoke a subroutine, passing variables declared by the current
625 program or declared by probe's "declare" request:
626
627 call date_time_ my_clock my_time_string
628
629 If my_clock is declared as fixed bin71 aligned, then it is passed
630 by reference; otherwise its value is converted to that data type
631 following PL1 conversion rules. If my_time_string is declared as a
632 non-varying character string, then it is passed by reference;
633 otherwise its value is converted to a temporary character string, and
634 that temporary string is passed as the argument. If passed by
635 reference, then the value of my_time_string is the my_clock number
636 converted by the date_time_ subroutine to an equivalent character
637 representation of that clock reading.
638
639
640 :Info: CONSTANTS: constants:
641 1979-09-29 Syntax of constants
642
643
644 Notes on the syntax of constants:
645
646 Probe recognizes arithmetic constants, string constants, and pointer
647 constants. Arithmetic constants can be fixed or floating point,
648 binary or decimal. String constants can be character or bit. Bit
649 constants can be entered in any radix from binary to hex. Numbers
650 can be entered in octal.
651
652 See "NUMBER", "STRING, and "POINTER".
653
654
655 :Info: continue: c:
656 1989-09-29 continue, c
657
658 Syntax: c
659
660
661 Function:
662 If used after a breakpoint, this request resumes execution of the
663 program.
664
665
666 :Info: continue_to: ct:
667 1989-09-29 continue_to, ct
668
669 Syntax: ct LINE
670
671
672 Function:
673 This request sets a temporary break before LINE, then continues
674 execution of your program. It is exactly equivalent to the two
675 requests "before LINE:pause;continue". When you resume after a
676 temporary break, it is automatically reset.
677
678
679 Arguments:
680 LINE
681 is the line number at which the new temporary break point is set.
682
683
684 :Info: CROSS-SECTION: cross-section: CROSS_SECTION: cross_section: cross_section.topic:
685 1988-09-30 Syntax of a cross-section
686
687
688 Probe provides cross-sections to allow reference to more than one
689 element of an array at a time. To reference the i'th through j'th
690 elements of an array, the cross-section reference is i:j for Pascal
691 i..j. Asterisk * is used to reference all elements of an array.
692
693
694 Examples:
695
696 Suppose any of the following declarations appear:
697 PL/I declare gosh 6 fixed bin;
698 Fortran integer gosh 6
699 Pascal var gosh: array 1..6 of integer
700 COBOL 77 gosh usage is comp-6 occurs 6 times.
701 C int gosh 6;
702
703 In the case of Pascal, the request "value gosh *" prints out all
704 elements of gosh, and "value gosh 2..4" prints out the values of
705 gosh2, gosh3, and gosh4. For the other languages, the request
706 "value gosh *" prints out all elements of gosh, and "value gosh
707 2:4" prints out the values of gosh2, gosh3, and gosh4.
708 note: for C you would use square brackets instead of parentheses.
709
710
711 Limits on cross-section usage:
712
713 Only the value and let requests use cross-sections. cross-sections
714 cannot be used as pointers to values. cross-sections cannot be
715 assigned to cross-sectionS or scalars.
716
717
718 :Info: declare: dcl:
719 1988-09-30 declare, dcl
720
721 Syntax: dcl NAME TYPE -force external defined EXPRESSION
722
723
724 Function:
725 This request creates new probe variables, and declares external
726 variables.
727
728
729 Arguments:
730 NAME
731 gives the name of a new variable. By default, storage for a new
732 variable is created in the process directory.
733 TYPE
734 gives a keyword specifying the data type of the variable. If
735 external is not specified i.e. creating a probe variable and a
736 another instance of variable NAME is already declared, the user is
737 queried about whether to delete the old instance.
738 external, ext
739 specifies that NAME is an existing external variable that probe may
740 reference in expressions.
741
742
743 defined EXPRESSION
744 EXPRESSION is a variable expression that designates an existing
745 region of storage having one of the data types associated with a
746 TYPE keyword. See "List of type keywords" below. NAME becomes a
747 synonym for that storage region. This feature is a typing
748 convenience, allowing a short name to be used in place of a
749 complicated expression.
750
751
752 Control arguments:
753 -force, -fc
754 causes any prior instance of the variable to be deleted without a
755 query.
756
757
758 List of type keywords:
759 The following possible values may be given for TYPE.
760 fixed, integer, int, comp-6
761 This type is equivalent to PL/I fixed bin 35; or Fortran, Pascal
762 or C integer; or COBOL comp-6.
763 float, real
764 This type is equivalent to PL/I float bin 27; Fortran real;
765 or C float.
766 pointer, ptr
767 This type is equivalent to PL/I aligned pointer Multics ITS ptr.
768 pointer unal, ptr unal
769 This type is equivalent to PL/I unaligned pointer a packed
770 pointer.
771
772
773 Notes:
774 A warning about a name conflict is displayed if a program variable of
775 the given NAME is known in the current block when the variable is
776 declared. If this warning is given, refer to the probe declared
777 variable with a percent sign before its name to distinguish it from
778 the program variable.
779
780
781 Examples:
782
783 dcl gravel comp-6
784 dcl clover ptr -force
785 dcl sys_info$max_seg_size fixed external
786 dcl axi fixed defined info_ptr -> aregs i.x.index
787
788
789 :Info: display: ds:
790 1985-05-04 display, ds
791
792 Syntax: ds * ADDRESS FORMAT COUNT
793
794
795 Function:
796 displays an arbitrary storage location in a selected format.
797
798
799 Arguments:
800 ADDRESS
801 The location displayed depends on the kind of ADDRESS supplied. If
802 ADDRESS is a reference to a program or probe variable, the storage
803 location associated with that variable is displayed. Otherwise,
804 ADDRESS must be an EXPRESSION that evaluates to a pointer which
805 points to the storage location that is displayed.
806 * ADDRESS
807 If an asterisk appears before a reference to pointer variable, data
808 at the storage location pointed to by that variable is displayed.
809
810
811 FORMAT
812 is one of the supported display formats. See "List of display
813 formats" below.
814 COUNT
815 gives the number of storage format items to display from storage at
816 the given location. The count defaults to 1.
817
818
819 List of display formats:
820 octal, o
821 displays the storage location as octal words.
822 ascii, character, ch
823 displays the storage location as characters.
824 bit, b
825 displays the storage location as a bit string value.
826 binary, bin, binary35, bin35
827 displays the storage location as 1-word integers.
828 binary71, bin71
829 displays the storage location as 2-word integer.
830
831
832 float, f, float27, f27
833 displays the storage location as 1-word floating point values.
834 float63, f63
835 displays the storage location as 2-word floating point values.
836 pointer, ptr, its
837 displays the storage location as 2-word pointer values.
838 instruction, i
839 displays the storage location as interpreted instruction words.
840 code
841 displays the storage location as a Multics status code, with the
842 error message associated with that status code.
843
844
845 Notes:
846
847 COUNT is the number of elements displayed. The size of an element
848 depends on the format displayed. Note that one pointer is 72 bits
849 two words, and one instruction may be as many as four words for
850 an EIS instruction.
851
852
853 Examples:
854
855 ds 253|100 octal 20 dumps 20 words in octal.
856 ds foo ascii 64 dumps first 64 chars of foo.
857 ds ip|0 i dumps current instruction.
858
859
860 :Info: execute: e:
861 1989-09-27 execute, e
862
863 Syntax: e "STRING"
864 .. STRING
865
866
867 Function:
868 Pass a STRING to the Multics command processor. This request is
869 chiefly useful in break request lists, because the more convenient
870 ".." escape to the Multics command processor is not available there.
871
872 You can pass an arbitrary line to the Multics command processor by
873 preceding it with ".." on a new line. No other requests can follow
874 it on the same line.
875
876
877 Arguments:
878 STRING
879 is the command line to be passed to the Multics command processor.
880 As an argument to the execute e request, this command line must be
881 enclosed in double quote " characters. All double quote
882 characters inside the string must be doubled. As an argument to the
883 .. escape, the STRING should not be enclosed in double quotes.
884
885
886 Examples:
887
888 ..ls >udd>Gtr>Weir>*.pl1
889 e "ls >udd>Gtr>Weir>*.pl1"
890 ..cwd >udd>Robot>Gort; dl Klaatu; ls -tt
891 e "cwd >udd>Robot>Gort; dl Klaatu; ls -tt"
892
893
894 :Info: EXPRESSIONS: expressions: EXPRESSION: expression:
895 1979-09-29 Syntax of expressions
896
897 Notes on expression syntax:
898
899 Probe expressions are made up using the arithmetic operators "+", "-",
900 "*", "/". Multiply and divide operators have higher precedence than
901 add and subtract operators. Parentheses can be used to override the
902 default order of evaluation.
903
904 Many requests include an EXPRESSION in their syntax. The probe "if"
905 and "while" requests include a PREDICATE, which is a comparison of two
906 EXPRESSION values. For more information about expression comparision,
907 type: help PREDICATE
908
909
910 :Info: goto: g:
911 1989-09-29 goto, g
912
913 Syntax: g LINE
914
915
916 Function:
917 This request leaves probe and resumes execution of your program at
918 LINE. It is an error to use this request if the LINE is in a program
919 that is not active.
920
921 Because of unpredictable compiler optimizations, this request can be
922 dangerous to use if the program was compiled with -optimize. For
923 more information, type: help optimization
924
925
926 Arguments:
927 LINE
928 gives a source line number on which a statement begins.
929
930
931 Notes:
932 For information about selecting a statement in a line containing
933 several statements, type: help LINE
934
935
936 :Info: halt: h:
937 1989-09-29 halt, h
938
939 Syntax: h
940
941
942 Function:
943 This is the default break request. It invokes a new probe command
944 level. It has no effect when typed at probe command level, only when
945 in break requests. If a break is set with no break request list
946 supplied by you, halt is assumed.
947
948
949 :Info: handlers:
950 1985-05-04 handlers
951
952 Syntax: handlers
953 handlers N
954 handlers OBJECT
955
956
957 Function:
958
959 The handlers request displays the condition names and actions of the
960 condition handlers established by the current procedure or a
961 specified procedure invocation.
962
963
964 Arguments:
965 N
966 gives the stack level N for the program block whose handlers are
967 displayed.
968 OBJECT
969 selects the most recent stack frame for the procedure OBJECT.
970
971
972 Notes on handlers:
973
974 Information about a handler is printed in the following format:
975
976 on CONDITION_NAME FILENAME snap ACTION
977
978 where ACTION is one of the following:
979
980 call PROCEDURE_NAME
981 begin block at line N
982 system
983
984
985 :Info: help:
986 1989-09-29 help
987
988 Syntax: help
989 help *
990 help TOPIC -control_args
991
992
993 Function:
994 The help request prints information about probe.
995
996
997 Arguments:
998 TOPIC
999 prints information about TOPIC. Topic may be the name of a probe
1000 request, or the name of some other probe topic. If TOPIC is
1001 omitted, help prints general information about probe.
1002 *
1003 If the argument is an asterisk, help prints a list of all
1004 probe-related topics for which info exists.
1005
1006
1007 Control arguments:
1008 One of the following control arguments may be given in each
1009 request.
1010 -brief, -bf
1011 displays a summary of request syntax, arguments, and control
1012 arguments.
1013 -control_arg ARG_NAME, -ca ARG_NAME
1014 displays full information about the given argument or control
1015 argument or item in a "List of ..." section.
1016
1017
1018 Examples:
1019
1020 help help prints this info.
1021 help status prints information about the "status" request.
1022 help errors prints information about known errors in probe.
1023
1024
1025 :Info: if:
1026 1989-09-29 if
1027
1028 Syntax: if PREDICATE :REQUEST
1029
1030
1031 Function:
1032 The "if" request evaluates its PREDICATE argument. If the result is
1033 true, REQUEST is executed, otherwise it is skipped. The if request is
1034 especially useful in breakpoint request lists, where it can be used to
1035 cause a conditional breakpoint.
1036
1037
1038 Arguments:
1039 PREDICATE
1040 is a comparison of two EXPRESSIONS that evaluates to true "1"b or
1041 false "0"b. For more information, type: help PREDICATE
1042 :REQUEST
1043 gives the probe request or list of requests to be executed if
1044 PREDICATE evaluates to true. A colon : separates the PREDICATE
1045 from the request list. For more information, type: help REQUEST
1046
1047
1048 Examples:
1049
1050 To stop whenever the variable "odin" equals 1, the breakpoint request
1051 list can include the request: if odin = 1 : halt
1052
1053
1054 :Info: input_description: ids:
1055 1985-05-04 input_description, ids
1056
1057 Syntax: ids ATTACH_DESCRIPTION
1058
1059
1060 Function:
1061 This request takes creates a new I/O switch, attaches that switch
1062 through a given I/O module to a device or file, and opens that switch
1063 for stream_input. probe then reads all its input from this switch
1064 until a subsequent input_description or input_switch request is given.
1065
1066
1067 Arguments:
1068 ATTACH_DESCRIPTION
1069 gives a full I/O attach description. It includes the name of an
1070 I/O module followed by arguments specifying a device, media, or
1071 file to which that I/O module should be attached. The I/O module
1072 must support the stream_input opening mode.
1073
1074
1075 Notes:
1076 The effects of input_switch, output_switch, input_description and
1077 output_description, unlike other requests, are static to the process
1078 and remain from one probe invocation to the next until reverted.
1079
1080 For information about reverting, type: help input_switch
1081
1082
1083 Examples:
1084
1085 ids tty_ stereo_console
1086
1087 causes further probe input to be read from the device stereo_console.
1088
1089
1090 :Info: input_switch: isw:
1091 1985-05-04 input_switch, isw
1092
1093 Syntax: isw SWITCH_NAME
1094
1095
1096 Function:
1097 Reverts probe input source to the default I/O switch: user_input; or
1098 switches probe input to another I/O switch.
1099
1100
1101 Arguments:
1102 SWITCH_NAME
1103 is the name of an I/O switch which is already attached and open for
1104 stream_input or stream_input_output. If SWITCH_NAME is omitted,
1105 probe reads from the user_input switch.
1106
1107
1108 Notes:
1109
1110 The effects of input_switch, output_switch, input_description and
1111 output_description, unlike other requests, are static to the process
1112 and remain from one probe invocation to the next until reverted.
1113
1114
1115 :Info: language: lng:
1116 1989-09-29 language, lng
1117
1118 Syntax: lng LANGUAGE_NAME
1119
1120
1121 Function:
1122 Given the name of one of the languages supported by probe, this
1123 request sets the current language mode. Otherwise, it displays the
1124 name of the current language mode.
1125
1126
1127 Arguments:
1128 LANGUAGE_NAME
1129 may be one of the names in "List of language types" below.
1130
1131
1132 List of language types:
1133 The LANGUAGE_NAME argument may be one of the following:
1134 PL/I, pl1, PL1
1135 FORTRAN, fortran, fortran2, FT, ft
1136 COBOL, cobol
1137 ALM, alm
1138 ALGOL68, Algol68, algol68, a68
1139 PASCAL, pascal
1140 C, c
1141
1142
1143 :Info: let: l:
1144 1989-09-29 let, l
1145
1146 Syntax: let VARIABLE = EXPRESSION
1147 l CROSS-SECTION = EXPRESSION
1148
1149
1150 Function:
1151 This request sets the VARIABLE or CROSS-SECTION to the value of
1152 EXPRESSION.
1153
1154
1155 Arguments:
1156 VARIABLE
1157 gives the name of a program variable or probe variable storage
1158 created by the probe declare request whose value is set.
1159 CROSS-SECTION
1160 is a VARIABLE followed by a range of array index values. For
1161 syntax details of a cross-section, type: help cross-section
1162 EXPRESSION
1163 gives a value to be assigned to the VARIABLE or CROSS-SECTION
1164 array elements. If type conversion is needed, it is performed
1165 according to the conversion rules of PL/I. Certain data types
1166 cannot be assigned to any type other than their own e.g. area
1167 file.
1168
1169
1170 Notes on assigning values:
1171
1172 Because of unpredictable compiler optimization, the change sometimes
1173 may not take effect, even though the "value" request seems to show
1174 that it has. For more information, type: help optimization
1175
1176
1177 :Info: list_builtins: lb:
1178 1985-01-11 list_builtins, lb
1179
1180 Syntax: lb
1181
1182
1183 Function:
1184 This request prints a summary of all builtins and their meanings.
1185
1186
1187 :Info: list_help: lh:
1188 1989-09-29 list_help, lh
1189
1190 Syntax: lh
1191
1192
1193 Function:
1194 The list_help request prints a summary of all TOPICS for which there
1195 is info. The topics are divided into three categories. Most files
1196 are infos in the segment probe.info, so to see a copy of all probe
1197 information, print the entire segment.
1198
1199 To print information on a topic, type: help TOPIC
1200
1201
1202 :Info: list_variables: lsv:
1203 1985-01-11 list_variables, lsv
1204
1205 Syntax: lsv NAMEs
1206
1207
1208 Function:
1209 This request lists all variables that have been declared by the
1210 "declare" request in the current invocation of probe, along with
1211 their types and values.
1212
1213
1214 Arguments:
1215 NAME
1216 If one or more NAMEs are supplied, then only those variables are
1217 listed. By default, all defined variables are listed.
1218
1219
1220 :Info: modes: mode:
1221 1985-11-07 modes, mode
1222
1223 Syntax: mode for display only
1224 mode MODE VALUE to set mode values
1225
1226
1227 Function:
1228 A mode is a probe variable that specifies how a particular function
1229 behaves. This request displays current mode settings, and changes
1230 the value of a given mode.
1231
1232 For a description of available modes, see "List of modes" below.
1233
1234
1235 Arguments:
1236 MODE
1237 gives the name of a mode to set.
1238 VALUE
1239 gives the new value for MODE. Most modes can be set to a value
1240 that is either a LENGTH or a BOOLEAN.
1241
1242 A LENGTH is either "long" "lg", "short" "sh" or "brief" "bf",
1243 and is used to specify the kind or amount of printing to be done by
1244 the part of probe. The amount of output is greatest for "long",
1245 least for "brief", and "short" is intermediate. In some cases
1246 "short" is synonymous with "brief".
1247
1248 BOOLEAN is used to turn a feature on or off. It can be "yes",
1249 "on", or "true"; or "no", "off", or "false".
1250
1251
1252 List of modes:
1253 error_messages, em
1254 LENGTH controls the length of the text used for an error message.
1255 Possible values for this mode are:
1256 long: full message text is printed default.
1257 brief: short error message keywords are printed.
1258
1259 qualification, qf
1260 LENGTH controls the format of variables names as printed by the
1261 value request. Possible values for this mode are:
1262 long: prints names with full qualification.
1263 brief: prints only the last name of a structure default.
1264 Note that COBOL and Fortran names are always printed briefly,
1265 regardless of the value of this mode.
1266
1267
1268 value_print, vp
1269 LENGTH controls whether or not the value request prints the name
1270 of a variable. Possible values for this mode are:
1271 long: names are always printed.
1272 short: names of array and structure elements are shown default.
1273 brief: values are printed without names.
1274
1275 value_separator, vs
1276 STRING controls the string printed by the value request between
1277 the name of a variable and its value. Only the first 32 characters
1278 of STRING are used. The default value_separator is " = ".
1279
1280
1281 truncate_strings
1282 BOOLEAN truncates character and bit string values to 200
1283 characters or bits, printing "<MORE>" at the end if the string is
1284 longer than 200. This mode is on by default.
1285
1286 meter
1287 BOOLEAN controls the printing of meter values when breaks are
1288 hit. The meter values are the number of minutes and seconds of
1289 real time "TIME", the number of seconds of virtual cpu time
1290 "VCPU", and the number of page faults "PAGE FAULTS" since
1291 the last break was restarted or since "mode meter on". These
1292 values do not include any overhead from probe itself.
1293
1294
1295 prompt
1296 BOOLEAN controls whether or not probe prints a prompting
1297 string on the terminal when it is listening for a request. It
1298 is off by default. See the "prompt_string" mode.
1299
1300 prompt_string
1301 STRING specifies the string to be used for prompting. The
1302 initial value is "probe^^d^ ". STRING is used in a call to
1303 ioa_$nnl, where the first argument is a bit 1 that is on if
1304 the current invocation of probe is recursive, and the second
1305 argument is the current probe depth.
1306
1307
1308 :Info: NUMBER: number:
1309 1979-09-30 number
1310
1311 Notes on the syntax of numeric constants:
1312
1313 Probe recognizes numeric constants using the rules of PL/I. A
1314 numeric constant can be binary or decimal, fixed or float. A binary
1315 numeric constant uses only "1" and "0" as digits, and always has a
1316 trailing "b". A decimal constant uses the digits "01234565789", or
1317 lacks the trailing "b". The type of a constant is determined by its
1318 literal appearance.
1319
1320
1321 Examples:
1322
1323 259 fixed decimal 3
1324 -1101b fixed binary 4
1325 12.3 fixed dec 31
1326 4.21f10 fixed dec 3-8
1327 4.301e10 float dec 4
1328
1329 Integers can be entered in octal by following them with a lower case
1330 "o". This is not found in PL/I. Example --
1331
1332 123o fixed bin 35, value is 83 decimal
1333
1334 Fortran double precision constants are not implemented.
1335
1336
1337 :Info: object: obj:
1338 1985-05-04 object, obj
1339
1340 Syntax: obj N
1341
1342
1343 Function:
1344 Displays the assembly instructions for source lines.
1345
1346
1347 Arguments:
1348 N
1349 specifies the number of source lines for which instructions are
1350 displayed. By default, N is 1.
1351
1352
1353 :Info: optimization:
1354 1989-09-30 optimization
1355
1356 Notes on the ill effects of optimization:
1357
1358 Optimization is an action performed by Multics translators to
1359 generate efficient code. This can cause problems for probe, and
1360 therefore one should not try to use probe on a segment compiled with
1361 "-optimize".
1362
1363
1364 Notes on optimization and the 'value' and 'let' requests:
1365
1366 One class of problems arises when a compiler stores the value of a
1367 variable in a register, instead of in memory. Probe looks in memory
1368 for the variable, and obtains an obsolete copy of its value. You can
1369 try to set the variable. Probe has no way of knowing which register
1370 holds the current copy of the value, and so it changes the value in
1371 storage. When the register is later stored, this wipes out the value
1372 stored by probe. This problem is particularly insidious, because
1373 until the value is wiped out, a look at it with the "value" request
1374 will seem to show the proper value.
1375
1376
1377 Notes on optimization and 'gotos':
1378
1379 Most compilers perform some optimizations on an inter-statement
1380 basis. This means that the compiler takes advantage of the fact that
1381 if there are no labels on statement N, and if statement N is
1382 executed, then statement N-1 must also have been executed, and that
1383 any values calculated then are still valid. This assumption is made
1384 false by using the probe goto, which can transfer to any line. To
1385 use the probe goto safely, one should only goto lines with labels.
1386 This request will become safer when compilers are able to suppress
1387 this optimization, which will happen in some future release of
1388 Multics.
1389
1390
1391 :Info: output_description: ods:
1392 1985-05-04 output_description, ods
1393
1394 Syntax: ods ATTACH_DESCRIPTION
1395
1396
1397 Function:
1398 This request takes creates a new I/O switch, attaches that switch
1399 through a given I/O module to a device or file, and opens that switch
1400 for stream_output. probe then writes all its output to this switch
1401 until a subsequent output_description or output_switch request is
1402 given.
1403
1404
1405 Arguments:
1406 ATTACH_DESCRIPTION
1407 gives a full I/O attach description. It includes the name of an
1408 I/O module followed by arguments specifying a device, media, or
1409 file to which that I/O module should be attached. The I/O module
1410 must support the stream_output opening mode.
1411
1412
1413 Notes on output description:
1414
1415 The effects of input_switch, output_switch, input_description and
1416 output_description, unlike other requests, are static to the process
1417 and remain from one probe invocation to the next until reverted.
1418
1419 For information about reverting, type: help output_switch
1420
1421
1422 Examples:
1423
1424 ods vfile_ probe_trace.output
1425
1426 causes further output to be written to the segment
1427 'probe_trace.output'.
1428
1429
1430 :Info: output_switch: osw:
1431 1985-09-17 output_switch, osw
1432
1433 Syntax: osw SWITCH_NAME
1434
1435
1436 Function:
1437 Reverts probe output except for error messages to the default I/O
1438 switch: user_output; or switches probe output except for error
1439 messages to another I/O switch.
1440
1441
1442 Arguments:
1443 SWITCH_NAME
1444 is the name of an I/O switch which is already attached and open for
1445 stream_output or stream_input_output. If SWITCH_NAME is omitted,
1446 probe writes non-error output to the user_output switch.
1447
1448
1449 Notes on restoring the output switch:
1450
1451 The effects of input_switch, output_switch, input_description and
1452 output description, unlike other requests, are static to the process
1453 and remain from one probe invocation to the next until reverted.
1454
1455
1456 :Info: PATH: path:
1457 1979-09-30 path
1458
1459 Notes on the syntax of a path:
1460
1461 Some probe requests accept a Multics pathname as an argument. If a
1462 PATH contains characters other than the letters of the alphabet, the
1463 digits 0-9, or the characters ">", "<", ".", ",", "-", "_", "$", or
1464 "/", it must be enclosed in quotes.
1465
1466
1467 Examples:
1468
1469 >udd>SoftWork>Brie>dog_lb absolute pathname
1470 hunter>aoxo$moxoa relative pathname
1471 "PSC+OCCUPATION.10|06|79" strange characters
1472
1473
1474 :Info: pause: pa:
1475 1989-09-30 pause, pa
1476
1477 Syntax: pa
1478
1479
1480 Function:
1481 The pause request is useful in breakpoint request lists. It is like
1482 halt, in that it causes execution of the breakpoint request list to
1483 be suspended and probe to read from the terminal. Unlike "halt",
1484 when the breakpoint is continued by the "continue" request, the
1485 break is immediately reset. The effect is a one-time-only temporary
1486 break. The "pause" request is used to implement the "step" and
1487 "continue_to" requests.
1488
1489
1490 :Info: POINTER: pointer:
1491 1979-09-30 pointer
1492
1493 Notes on the syntax of probe pointer constants:
1494
1495 Probe pointer constants are of the form SSS|WWW or SSS|WWWbbb where
1496 SSS is the segment number in octal, WWW is the word offset in octal,
1497 and bbb is the bit offset optional in decimal. SSS can be replaced
1498 with a two letter code to specify a pointer relative to the current
1499 stack frame sp, linkage section lp, text segment tp, or
1500 instruction ip.
1501
1502
1503 Examples:
1504
1505 254|10013 bit 13 of word 100 in segment 254
1506 sp|2500 word at offset 2500 in current stack frame
1507 ip|0 instruction last executed
1508 lp|10 word 10 in linkage section
1509
1510
1511 :Info: pointers.topic: pointers: source_pointer: control_pointer:
1512 1985-03-14 pointers for source and control location
1513
1514 Two pointers keep track of the program's state.
1515
1516 source indicates current source-program statement.
1517 control indicates current control point.
1518
1519 The values of the pointers can be obtained using the "where" request.
1520 The source pointer is set using the "position" or "use" request. The
1521 control pointer is set when probe is entered.
1522
1523
1524 Notes on the probe 'source' pointer:
1525
1526 The source pointer always indicates some location in a program. If
1527 the program is active, then it indicates a stack frame associated
1528 with the program. If the object segment was compiled with the
1529 "table" options then a source line number will be available,
1530 otherwise the location will be indicated by an octal offset from the
1531 base of the segment to an instruction.
1532
1533
1534 If the program was compiled with a "table" option, probe obtains the
1535 text of source lines from the program's source segment NAME.pl1
1536 NAME.fortran etc.. This is either the segment that the program was
1537 originally compiled from, if it exists, or the first segment with the
1538 appropriate name found using the "probe" search paths. If no source
1539 segment can be found, the position and source requests are unable to
1540 print source lines.
1541
1542
1543 Notes on the probe 'control' pointer:
1544
1545 If probe was invoked by a breakpoint, the control pointer indicates
1546 the statement where the break occurred. If probe was invoked from
1547 the command line, it indicates either: the last location executed in
1548 the procedure first examined, whether it took a fault, or called out;
1549 of if the procedure was inactive, the control pointer is the location
1550 of the entry statement for the procedure.
1551
1552
1553 :Info: position: ps:
1554 2020-12-21 position, ps
1555
1556 Syntax:
1557 ps OPERANDs
1558
1559
1560 Function:
1561 Sets the source pointer to the statement specified and prints the
1562 statement. For information on repositioning without printing the
1563 source statement, type: help use
1564
1565
1566 Arguments:
1567 OPERAND
1568 The position request accepts many different operand types. See a
1569 complete list in the following section.
1570
1571
1572 List of position operands:
1573 Items below show the position request being used with each form
1574 of operand.
1575 ps
1576 with no operands, position resets the source pointer to its initial
1577 value same as the control pointer.
1578 ps LINE
1579 positions to a LINE in the current procedure. This could be a line
1580 number, or one of the line reference symbols. For details, type:
1581 help LINE
1582 ps +N
1583 position to the statement N statements after the current one.
1584 ps -N
1585 position to the statement N statements before the current one.
1586
1587
1588 ps line +N
1589 position to the statement N lines after the current one.
1590 ps line -N
1591 position to the statement N lines before the current one.
1592 ps level N
1593 position to the last line executed in the block at stack level N.
1594 ps level +N
1595 position to the last line executed for the block N levels more
1596 recent than the current stack level.
1597 ps level -N
1598 position to the last line executed for the block N levels less
1599 recent than the current stack level.
1600
1601
1602 ps OBJECT
1603 position to the last line executed in the most recent invocation of
1604 OBJECT, where OBJECT is a program reference. For more information,
1605 type: help OBJECT
1606 ps "STRING"
1607 search in the source for the next statement containing the literal
1608 string. STRING may be any program label, or statement element.
1609 ps /REGEXP/
1610 search in the source for the next statement that matches the qedx
1611 regular expression REGEXP.
1612
1613
1614 Notes on positioning:
1615
1616 In PL/I, names including labels are not available to probe when the
1617 source pointer is outside the block in which they are declared. This
1618 means that probe cannot find a label in an internal procedure or
1619 begin block unless that block is now the "current block". The label
1620 can still be found by a search for a character string that appears in
1621 the labeled line e.g. "program_label:".
1622
1623 The source segment used is either the one that the program was
1624 originally compiled from, if it exists, or the first segment with the
1625 appropriate name NAME.pl1 NAME.fortran etc. found using the
1626 "probe" search paths. If no source segment can be found, probe is
1627 unable to search in source, or print source lines.
1628
1629
1630 It is only possible to set the source pointer to an executable
1631 statement. Every language has certain statements that are not
1632 executable. Blank lines, comments, and declarations are not
1633 executable in any language. For more information, type:
1634 help where
1635 help LINE
1636
1637
1638 :Info: PREDICATE: predicate:
1639 1988-09-30 predicate
1640
1641 Notes on the syntax of a predicate:
1642
1643 EXPRESSION COMPARISON EXPRESSION
1644
1645 where COMPARISON is one of the following operators:
1646 "<", ">", "<=", ">=", "=", "^=".
1647
1648 A PREDICATE is a comparison of two values, and yields a Boolean
1649 value. A Boolean variable is one that can have only two possible
1650 values corresponding to "true" or "false". PL/I uses bit 1 for
1651 Boolean variables Fortran use logical. The concept is absent from
1652 COBOL. The "if" and "while" requests accept a predicate, then
1653 perform some action if the predicate is true.
1654
1655
1656 In Fortran mode, the Fortran equivalents ".lt." ".gt." etc. are
1657 allowed and in C mode, "=" and "^=" have the equivalents "==" and
1658 "!=" respectively.
1659
1660
1661 Notes on the predicate restrictions:
1662
1663 PREDICATES cannot be nested or combined. In a future release, the
1664 operators "&", "|", and "^" will be available, but not now.
1665
1666
1667 :Info: quit: q:
1668 1989-09-30 quit, q
1669
1670 Syntax: q
1671
1672
1673 Function:
1674 It exits the current invocation of probe. If the current invocation
1675 was a recursive invocation, you may still be in probe, although at a
1676 lower level.
1677
1678
1679 :Info: REQUEST: request:
1680 1979-09-30 request
1681
1682 Notes on the syntax of a probe request:
1683
1684 Probe requests begin with the name of the probe function to be used
1685 such as "value" or "help" followed by the arguments to the
1686 request. A request ends with a newline or with a semicolon.
1687
1688 Certain requests accept a request or list of requests as one of their
1689 arguments e.g. "before" "after" "if" and "while". When a
1690 request accepts a request or list of requests as an argument, the
1691 argument which is called a REQUEST is preceded by a colon
1692 ":". A :REQUEST can be either a single request, or a list of
1693 requests enclosed in parenthesis and separated from each other by a
1694 semicolon ";".
1695
1696
1697 Examples:
1698
1699 before 259 : value a; value b
1700 sets a break before line 259. When this break is hit, the values
1701 of variables a and b are printed.
1702 before 680: if a = 3: halt
1703 nests 3 levels of requests. When the break at line 680 is hit,
1704 the "if" request is executed. If a=3, then, the "halt" request
1705 is executed.
1706
1707
1708 :Info: reset: r:
1709 1985-05-04 reset, r
1710
1711 Syntax:
1712 r OPERAND -control_arg
1713
1714
1715 Function:
1716 Resets probe breaks at selected lines in selected procedures. Line
1717 number of each reset breakpoint is printed as the break is removed.
1718
1719
1720 Arguments:
1721 OPERAND
1722 may be any of the items shown below in "List of reset operands".
1723
1724
1725 Control arguments:
1726 -brief, -bf
1727 suppresses printing of line numbers as breakpoints are removed.
1728
1729
1730 List of reset operands:
1731 Items below show the reset request being used with each form
1732 of operand.
1733 reset
1734 reset the break at the current statement, if any.
1735 reset before|after LINE,
1736 r be|af LINE,
1737 r b|a LINE
1738 reset the break at LINE in the current procedure. This could be a
1739 line number, or one of the line reference symbols. If STRING is
1740 preceded by the keyword "before" or "be" or "b", only breaks
1741 before statements are removed. If preceded by "after" or "af" or
1742 "a", only breakpoints after statements are removed. For details,
1743 type: help LINE
1744
1745
1746 reset OBJECT
1747 reset all breaks in the object segment OBJECT.
1748 reset -all,
1749 r *
1750 reset all breaks set by you in all segments.
1751 reset before|after "STRING",
1752 r be|af "STRING",
1753 r b|a "STRING"
1754 reset all lines containing STRING in the current procedure.
1755 STRING may be any program label, or statement element. If STRING is
1756 preceded by the keyword "before" or "be" or "b", only breaks
1757 before statements are removed. If preceded by "after" or "af" or
1758 "a", only breakpoints after statements are removed.
1759
1760
1761 reset before|after /REGEXP/,
1762 r be|af /REGEXP/,
1763 r b|a /REGEXP/
1764 reset breaks at all lines matching the regular expression REGEXP.
1765 If REGEXP is preceded by the keyword "before" or "be" or "b", only
1766 breaks before statements are removed. If preceded by "after" or
1767 "af" or "a", only breakpoints after statements are removed.
1768
1769
1770 :Info: source: sc:
1771 1985-03-14 source, sc
1772
1773 Syntax: sc COUNT
1774 sc path PATHNAME
1775
1776
1777 Function:
1778
1779 The first form prints the next N source statements, beginning with
1780 the current one. If COUNT is omitted, then one statement is printed.
1781 Any lines in the source segment between the first and last statement
1782 lines are printed.
1783
1784 The second form is used to specify the location of the source
1785 segment. It is useful when the source has been moved since the
1786 object segment was compiled. In this second form, the literal
1787 keyword "path" is followed by the pathname, for example:
1788 sc path >udd>Wire>u>Doon>new_program.pl1
1789
1790
1791 Arguments:
1792 COUNT
1793 is in integer giving the number of source statements to display.
1794 path PATHNAME
1795 gives the PATHNAME for the source segment compiled to create the
1796 object being probed.
1797
1798
1799 Notes on the source request:
1800
1801 If the "sc path PATHNAME" form has not be used, the source segment is
1802 either: the source program originally compiled to create the object,
1803 if it exists; or the first segment with the appropriate name
1804 NAME.pl1 NAME.fortran etc. found using the "probe" search paths.
1805 If no source segment can be found, probe is unable to print source
1806 lines.
1807
1808
1809 :Info: stack: sk:
1810 1985-05-04 stack, sk
1811
1812 Syntax:
1813 sk N COUNT all long
1814
1815
1816 Function:
1817 Displays your stack, showing block names and line numbers if known
1818 last executed in each frame, and conditions raised. Each frame is
1819 displayed with a number, which is the "level number", and used in
1820 various requests to indicate a stack frame. Most recent stack frames
1821 have higher levels and appear earliest in the display.
1822
1823
1824 Arguments:
1825 COUNT
1826 gives the number of stack frames to display. The default is to
1827 display all frames.
1828 N
1829 gives a starting "level number". COUNT frames are displayed
1830 beginning with that level and including earlier frames.
1831 all
1832 includes "support" frames in the trace. By default, these frames
1833 are skipped. See "Notes on support frames" below.
1834 long
1835 prints the pathname for the object segment that owns each stack
1836 frame.
1837
1838
1839 Notes on support frames:
1840
1841 Support frames are frames that belong to a support procedure. A
1842 support procedure is a system utility that performs action directly
1843 related to the compiled user code for example allocation and in
1844 which there is a high probability that any errors that arise are due
1845 to improper use by the calling program such as allocating in a full
1846 area. When conditions arise in support frames, the standard Multics
1847 error handler attributes the error to the code that called the
1848 support procedure, rather than the support procedure.
1849
1850 The probe "stack" request does not display support frames unless
1851 invoked as "stack all". Support frames are given incremental numbers
1852 between those of the surrounding frames 6.1 6.2 ....
1853
1854
1855 Examples:
1856
1857 sk 4, 3 all displays frames 4, 3, and 2.
1858 sk 3 displays three frames, starting with the most recent
1859
1860
1861 :Info: status: st:
1862 1989-09-30 status, st
1863
1864 Syntax:
1865 st OPERANDs -control_arg
1866
1867
1868 Function:
1869 Displays line numbers of breaks, and optionally the break request
1870 list.
1871
1872
1873 Arguments:
1874 OPERAND
1875 may be any of the items shown below in "List of status operands".
1876
1877
1878 Control arguments:
1879 One of the following control argument may be given with a status
1880 request. If neither is given, the break request list is
1881 displayed for the "status LINE" request, and omitted for other
1882 status requests.
1883 -long, -lg
1884 displays the break request list for each displayed breakpoint.
1885 -brief, -bf
1886 suppresses display of the break request list.
1887
1888
1889 List of status operands:
1890 Items below show the status request being used with each form
1891 of operand.
1892 status
1893 displays all breaks in the current procedure.
1894 status before|after LINE,
1895 st be|af LINE,
1896 st b|a LINE
1897 displays the break at LINE in current procedure. This could be a
1898 line number, or one of the line reference symbols. For details,
1899 type: help LINE
1900
1901 If LINE is preceded by the keyword "before" or "be" or "b", only
1902 breaks before the statement is displayed. If preceded by "after"
1903 or "af" or "a", only breaks after the statement is removed.
1904
1905
1906 status OBJECT
1907 displays all breaks in object segment named OBJECT.
1908 status *
1909 displays the pathnames of all object segments in which breaks were
1910 set by the user.
1911 status -all, st -a
1912 displays breaks set by the user in all object segments. If status
1913 is used without any OPERAND, the default displays breaks only in the
1914 current procedure.
1915
1916
1917 Examples:
1918
1919 status >udd>Dog20>foo>zloty lists all breaks in zloty.
1920 status 35 -lg lists breaks and text at line 35.
1921 st b 7 lists only the break before line 7.
1922 st -all lists all breaks set by you.
1923
1924
1925 :Info: step: s:
1926 1989-09-30 step, s
1927
1928 Syntax: s
1929
1930
1931 Function:
1932 The step request places a temporary break see "pause" at the
1933 statement that it feels is "next", and then resumes executing your
1934 program. It is somewhat unreliable see below but, when it works,
1935 it allows you to step through the program a statement at
1936
1937
1938 Notes on the pitfalls of the step request:
1939
1940 The reason that "step" is so unreliable is that often the statement
1941 that comes next in the object segment is not the next one executed by
1942 the program. This happens when the current statement is a call, a
1943 goto, the "end" statement of a loop or continue statement for
1944 Fortran, or the "then" statement of an "if-then-else". There are
1945 other statements that fail but these are the most common. In some
1946 cases do loop call, the "next" statement is eventually executed,
1947 and the break occurs.
1948
1949
1950 :Info: symbol: sb:
1951 1988-09-30 symbol, sb
1952
1953 Syntax: sb VARIABLE long
1954
1955
1956 Function:
1957 This request displays the attributes of a program variable symbol
1958 or probe-declared variable.
1959
1960
1961 Arguments:
1962 VARIABLE
1963 gives the name of a program variable or probe variable storage
1964 created by the probe declare request whose attributes should be
1965 displayed.
1966 long
1967 display attributes of all members of a PL/1 or C structure, or a
1968 COBOL or Pascal record referenced by the VARIABLE name.
1969
1970
1971 :Info: use:
1972 2020-12-21 use
1973
1974 Syntax:
1975 use OPERANDs
1976
1977
1978 Function:
1979 Sets the source pointer to the statement specified and but does
1980 not print the statement. For information on printing the
1981 source statement when repositioning, type: help position
1982
1983
1984 Arguments:
1985 OPERAND
1986 The use request accepts many different operand types. See a
1987 complete list in the following section.
1988
1989
1990 List of use operands:
1991 Items below show the use request being used with each form
1992 of operand.
1993 use
1994 with no operands, use resets the source pointer to its initial
1995 value same as the control pointer.
1996 use LINE
1997 positions to a LINE in the current procedure. This could be a line
1998 number, or one of the line reference symbols. For details, type:
1999 help LINE
2000 use +N
2001 position to the statement N statements after the current one.
2002 use -N
2003 position to the statement N statements before the current one.
2004
2005
2006 use line +N
2007 position to the statement N lines after the current one. This
2008 differs from the "use +N" operand when the current line contains
2009 more than one statement.
2010 use line -N
2011 position to the statement N lines before the current one.
2012 use level N
2013 position to the last line executed in the block at stack level N.
2014 use level +N
2015 position to the last line executed for the block N levels more
2016 recent than the current stack level.
2017 use level -N
2018 position to the last line executed for the block N levels less
2019 recent than the current stack level.
2020
2021
2022 use OBJECT
2023 position to the last line executed in the most recent invocation of
2024 OBJECT, where OBJECT is a program reference. For more information,
2025 type: help OBJECT
2026 use "STRING"
2027 search in the source for the next statement containing the literal
2028 string. STRING may be any program label, or statement element.
2029 use /REGEXP/
2030 search in the source for the next statement that matches the qedx
2031 regular expression REGEXP.
2032
2033
2034 Notes on positioning:
2035
2036 In PL/I, names including labels are not available to probe when the
2037 source pointer is outside the block in which they are declared. This
2038 means that probe cannot find a label in an internal procedure or
2039 begin block unless that block is now the "current block". The label
2040 can still be found by a search for a character string that appears in
2041 the labeled line e.g. "program_label:".
2042
2043 The source segment used is either the one that the program was
2044 originally compiled from, if it exists, or the first segment with the
2045 appropriate name NAME.pl1 NAME.fortran etc. found using the
2046 "probe" search paths. If no source segment can be found, probe is
2047 unable to search in source, or print source lines.
2048
2049
2050 It is only possible to set the source pointer to an executable
2051 statement. Every language has certain statements that are not
2052 executable. Blank lines, comments, and declarations are not
2053 executable in any language. For more information, type:
2054 help where
2055 help LINE
2056
2057
2058 :Info: value: v:
2059 1988-09-30 value, v
2060
2061 Syntax: v EXPRESSION data
2062 v CROSS-SECTION data
2063
2064
2065 Function:
2066
2067 The value request displays the value of a given EXPRESSION or
2068 CROSS-SECTION.
2069
2070
2071 Arguments:
2072 EXPRESSION
2073 gives a variable name or expression. Character string values are
2074 surrounded by double-quote " and double-quotes inside them are
2075 doubled. For the syntax of an EXPRESSION, type: help expressions
2076 CROSS-SECTION
2077 gives a cross-section reference. For the syntax of a cross-section,
2078 type: help cross-section
2079 data
2080 The data pointed to by C pointers may be displayed by following the
2081 EXPRESSION or CROSS-SECTION with the keyword "data".
2082
2083
2084 Notes:
2085 You can control the circumstances under which the name of the
2086 variable being displayed is printed, the way a name is printed if it
2087 is printed, and the string that separates the name from the value.
2088 For details, type: help modes
2089
2090 If the EXPRESSION is an external function, it is called and its
2091 return value is displayed. For details, type: help call
2092
2093
2094 Examples:
2095 The simplest example of an EXPRESSION is the name of a variable, for
2096 example:
2097 v subr_args.ptr_len
2098 which prints the value of the variable or substructure ptr_len in the
2099 structure subr_args.
2100
2101
2102 :Info: variables:
2103 1985-01-15 variables
2104
2105 Notes on probe variables:
2106
2107 Probe variables are variables created by the probe declare request.
2108 They are used like variables from programs. Unlike program
2109 variables, probe variables are not associated with a given block.
2110 Once defined, they can be referenced no matter what value the source
2111 pointer has. All probe variables are discarded when the process
2112 ends.
2113
2114
2115 Examples:
2116
2117 Suppose there is a PL/1 structure 'struc' that is threaded onto a
2118 linked list by the pointer 'next', and you want to count the number
2119 of structures. This can be done by creating two probe variables, a
2120 pointer 'p', and a counter 'i', and using them in a while loop as
2121 follows:
2122
2123 declare p ptr
2124 declare i integer
2125 let p = first
2126 let i = 0
2127 while p ^= null : let i = i + 1; let p = p -> struc.next
2128
2129
2130 If the current program declares a variable with the same name as a
2131 probe variable, the program variable is used. To reference the probe
2132 variable, preface it with a percent sign, e.g. %p or %i in the above
2133 example. It is recommended for clarity that probe variables always
2134 be prefixed by %.
2135
2136
2137 :Info: where: wh:
2138 1985-09-24 where, wh
2139
2140 Syntax:
2141 wh OPERANDs
2142
2143
2144 Function:
2145 This request displays the values of the probe pointers. For
2146 definitions of these pointers, type: help pointers
2147
2148
2149 Arguments:
2150 OPERAND
2151 The where request accepts several different operands. See a
2152 complete list in the following section.
2153
2154
2155 List of where operands:
2156 Items below show the where request being used with each form
2157 of operand. If where is invoked with no arguments, it displays the
2158 values of the source and control pointers.
2159 wh source
2160 prints the value of the source pointer.
2161 wh source path
2162 prints the pathname of the segment referenced by the source pointer.
2163 ie. the source segment currently in use.
2164 wh control|object
2165 prints the value of the control pointer.
2166 wh control|object path
2167 prints the value of the control pointer and the pathname of the
2168 segment referenced by the control pointer ie. the current object
2169 segment.
2170
2171
2172 :Info: while: wl:
2173 1989-09-30 while, wl
2174
2175 Syntax: wl PREDICATE :REQUEST
2176
2177
2178 Function:
2179 This request executes REQUEST repeatedly verifying that PREDICATE is
2180 true before each execution. Execution stops when PREDICATE is false.
2181 For information about testing a PREDICATE, type:
2182 help PREDICATE
2183 help if
2184 help REQUEST
2185
2186 For an example of the while request, type: help variables
2187
2188
2189 Arguments:
2190 PREDICATE
2191 compares two expressions using a Boolean operator, returning a
2192 true-or-false value. For details, type: help PREDICATE
2193 :REQUEST
2194 gives the probe request or list of requests to be executed if the
2195 PREDICATE evaluates to true. A colon : separates the PREDICATE
2196 from the REQUEST. For details, type: help REQUEST
2197
2198
2199 :hcom:
2200
2201 /****^ HISTORY COMMENTS:
2202 1) change2020-12-19GDixon, approve2021-02-22MCR10084,
2203 audit2021-05-27Swenson, install2021-05-27MR12.6g-0055:
2204 A) Convert all heading line dates to iso_date format.
2205 B) All info blocks but the first document probe requests or
2206 other subsystem topics. Therefore, none of the names on
2207 these info blocks should be added as external names on the
2208 probe.info segment. Change the :Info: divider to :Info: to
2209 inform verify_info of this intended naming scheme. probe's
2210 help request will display such "internal" info blocks using
2211 help_'s info_name selection value.
2212 C) Under verify_info rules, an info block whose first section
2213 title is "Syntax" with heading line date before 1985 is
2214 treated as documenting a command. Since probe wants all
2215 such blocks treated as a Request, all of the 1979 years were
2216 changed to 1989; 1980, 1981, 1982, 1983, and 1984 were
2217 changed to 1985.
2218 D) Many requests had Syntax lines that referenced arguments
2219 without providing an Arguments section to describe them.
2220 Instead, they were mentioned in summary fashion in the
2221 Function section. For these requests, an Arguments section
2222 was added in that request's info block.
2223 E) Enhance documentation for the "call" request.
2224 F) Enhance documentation for "position" and "use" requests by
2225 including text from MPM Commands writeup of probe.
2226 G) Change probe "help" request to support -brief and -control_arg
2227 arguments, and TOPIC values containing two hyphenated words
2228 e.g. CROSS-SECTION.
2229 END HISTORY COMMENTS */
2230