OS/2 Procedures Language 2/REXX


Inf-HTML [About][Toc][Index] 0.9b (c) 1995 Peter Childs


TRACE





>>- TRACE -+------------------+----------+--------+-;-><
           | +-----------+    +- number -+        |
           | v           |                        |
           +-+-+-------+-+-+--------------------+-+
               +---?---+   +-- All -------------+
                           +-- Commands --------+
                           +-- Error -----------+
                           +-- Failure ---------+
                           +-- Intermediates ---+
                           +-- Labels ----------+
                           +-- Normal ----------+
                           +-- Off -------------+
                           +-- Results ---------+


Or, alternatively: 



>>--TRACE---+--------------------------+---;-------><
            +------string--------------+
            +------symbol--------------+
            +--+-------+--expression---+
               +-VALUE-+


TRACE is used for debugging.  It controls the tracing action taken (that 
is, how much is displayed to the user) during execution of a REXX program. 
 The syntax of TRACE is more concise than other REXX instructions.  The 
economy of key strokes for this instruction is especially convenient since 
TRACE is usually entered manually during interactive debugging. 
The number is a whole number. 
The string or expression evaluates to: 
   o  A number option 
   o  One of the valid prefix, alphabetic character (word) options, or 
      both, shown in this panel 
   o  Null. 
 
 The symbol is taken as a constant and is: 
   o  A number option 
   o  One of the valid prefix, alphabetic character (word) options, or 
      both, shown in this panel. 
 
 The tracing action is determined from the option specified following 
 TRACE or from the result of evaluating expression. If expression is used, 
 you can omit the subkeyword VALUE as long as expression starts with a 
 special character or operator (so it is not mistaken for a symbol or 
 string). 
 Alphabetic Character (Word) Options 
 Although it is acceptable to enter the word in full, only the uppercase 
 letter is significant; all other letters are ignored. That is why these 
 are referred to as alphabetic character options. 
 TRACE actions correspond to the alphabetic character options as follows: 
 All                   All clauses are traced (that is, displayed) before 
                       execution. 
 Commands              All host commands are traced before execution, and 
                       any error return code is displayed. 
 Error                 Any host command resulting in an error return code 
                       is traced after execution. 
 Failure               Any host command resulting in a failure is traced 
                       after execution. This is the same as the Normal 
                       option. 
 Intermediates         All clauses are traced before execution. 
                       Intermediate results during evaluation of 
                       expressions and substituted names are also traced. 
 Labels                Labels passed during execution are traced. This is 
                       especially useful with debug mode, when the 
                       language processor pauses after each label.  It is 
                       also convenient for the user to make note of all 
                       subroutine calls and signals. 
 Normal                Any failing host command is traced after execution. 
                       This is the default setting. 
                       For the default CMD processor in the OS/2 operating 
                       system, an attempt to issue an unknown command 
                       raises a FAILURE condition. An attempt to issue a 
                       command to an unknown subcommand environment also 
                       raises a FAILURE condition; in such a case, the 
                       variable RC is set to 2, the OS/2 return code for 
                       "file not found". 
 Off                   Nothing is traced, and the special prefix actions 
                       (see below) are reset to OFF. 
 Results               All clauses are traced before execution.  Final 
                       results (contrast with Intermediates, above) of 
                       evaluating an expression are traced.  Values 
                       assigned during PULL, ARG, and PARSE instructions 
                       are also displayed.  This setting is recommended 
                       for general debugging. 
 
 Prefix Option 
 The prefix ? is valid either alone or with one of the alphabetic 
 character options. You can specify the prefix more than once, if desired. 
  Each occurrence of a prefix on an instruction reverses the action of the 
 previous prefix. The prefix must immediately precede the option (no 
 intervening blanks). 
 The prefix ? modifies tracing and execution.  ? is used to control 
 interactive debug. During normal execution, a TRACE instruction prefixed 
 with ? causes interactive debug to be switched on. 
 When interactive debug is in effect, you can switch it off by issuing a 
 TRACE instruction with a prefix ?.  Repeated use of the ? prefix, 
 therefore, switchs you alternately in and out of interactive debug. Or, 
 interactive debug can be turned off at any time by issuing TRACE O or 
 TRACE with no options. 
 Numeric Options 
 If interactive debug is active and if the option specified is a positive 
 whole number (or an expression that evaluates to a positive whole 
 number), that number indicates the number of debug pauses to be skipped 
 over. However, if the option is a negative whole number (or an expression 
 that evaluates to a negative whole number), all tracing, including debug 
 pauses, is temporarily inhibited for the specified number of clauses. 
 If interactive debug is not active, numeric options are ignored. 
 Format of TRACE Output 
 
 Every clause traced will be displayed with automatic formatting 
 (indentation) according to its logical depth of nesting and so on, and 
 the results (if requested) are indented an extra two spaces and are 
 enclosed in double quotation marks so that leading and trailing blanks 
 are apparent. 
 All lines displayed during tracing have a three-character prefix to 
 identify the type of data being traced.  The prefixes and their 
 definitions are the following: 
 *-*       Identifies the source of a single clause, that is, the data 
           actually in the program. 
 +++       Identifies a trace message.  This can be the nonzero return 
           code from a command, the prompt message when interactive debug 
           is entered, an indication of a syntax error when in interactive 
           debug, or the traceback clauses after a syntax error in the 
           program. 
 >>>       Identifies the result of an expression (for TRACE R) or the 
           value assigned to a variable during parsing, or the value 
           returned from a subroutine call. 
 >.>       Identifies the value assigned to a placeholder during parsing. 
 
 The following prefixes are only used if Intermediates (TRACE I) are being 
 traced: 
 >C>       The data traced is the name of a compound variable, traced 
           after substitution and before use, provided that the name had 
           the value of a variable substituted into it. 
 >F>       The data traced is the result of a function call. 
 >L>       The data traced is a literal (string, uninitialized variable, 
           or constant symbol). 
 >O>       The data traced is the result of an operation on two terms. 
 >P>       The data traced is the result of a prefix operation. 
 >V>       The data traced is the contents of a variable. 
 

Inf-HTML End Run - Successful