Debug Procedures

Debug procedures are the equivalent to functions in the C language.  When a debug procedure is defined, it is saved in memory for later execution.  Debug procedures can accept arguments and return values.

The define command is used to define a debug procedure.  The show command lists debug procedures, and the remove command can be used to remove debug procedures. The proc  command can be used to display a debug procedure definition.

Typically, a command file is loaded that contains one or more debug procedure definitions.  The user can type a procedure name at the command line to execute it, or assign the procedure to a user-defined toolbar button, and press the button to execute it.

Syntax

define proc [data-type] proc-name ([argument-name][,...])

[define argument-type argument-name][...]

{

     commands [...]

 

     [return expr]

}

Where:

define	signals creation of a user-defined procedure or procedure argument.
proc	specifies a user-defined procedure.
data-type	specifies the data type to be returned.
proc-name	specifies the name of a debug procedure.
argument-name	specifies the name of an argument that is used in the procedure. Separates the names of arguments with commas.
argument-type	specifies the data type of the argument.
commands	any emulator commands (except for include).
return	specifies an argument name whose value is returned upon completion of proc execution.

Discussion:

Use debug procedures (procs) to define custom functions. Create a proc with the  proc command. You can use any text editor to initially create and edit a proc. You can also enter a proc at the command line. A proc is executed when it is called by name, just as a built-in function is executed.

You can define debug procedures that accept arguments. If an argument name is specified but not an the argument type, the caller data type is used as the default. When executing a proc, an error message is displayed if the proc requires arguments that have not been passed to it.

To define debug procedures that accept a variable number of arguments, use two predefined local variables, argvector and argcount. The argcount variable tracks the number of arguments supplied when the function is called. The argvector variable (array) stores the actual arguments passed when a function is called.

Recursive or reentrant debug procedures are supported to the extent of available host memory. Debug procedures can also call other debug procedures that have been previously defined. Use the forward option to reference debug objects (including other debug procedures) that have not yet been defined. To define recursive debug procedures, the forward option must be used.

Debug variables defined inside the proc are local to the proc unless declared as global (see define). Debug variables inside the proc not declared as global are automatically removed after the execution of the proc.

Use the return command to return values from a proc. If the return command is not used or executed, the proc returns a null value. If the return data type does not match the calling data type, then an explicit data type conversion occurs. If a return datatype is not specified, then the type comes from the value returned.

If a proc executes an emulation command (such as go or step), the statements after the emulation command are executed immediately unless followed by the wait command. The wait command prevents the emulator from executing any more commands until a breakpoint is reached.

Note: You can use debug procedures and macro files to create a library of frequently used commands. The emulator displays a syntax error when a proc processes an undefined proc symbol or variable. Define all program symbols before referencing.

Example 1

To define and then execute a procedure named avg that accepts three parameters and returns their average:

Note: Types are not specified for a, b and c, so the caller's data type is assumed.

 

Command input:

define proc avg(a,b,c)
{
  return ((a + b + c) / 3)
}
avg(4, 6, 3)

Result:

4T

Example 2

To use the forward option to refer to undefined debug procedures:

Command input:

define proc int8 calc(a,b,c)
define int8 a
define int8 b
define int8 c
{
  forward proc int8 min                  // forward references procs
  forward proc int8 max                  // min and max.
  if ((a > 0) && (b > 0))
       return (max (a,b) * c) \
  else if ((a < 0) && ( b < 0))
       return (min(a,b) * c) \
  else return (0)
}                                        
 

define proc int8 min(x,y)                // define min proc
{
  return ((x < y) ? (x): (y))
}

 

define proc int8 max(x,y)                // define max proc.
{
  return ((x > y) ? (x): (y))
}
 

base = 10t
calc(2,4,6)                              // execute calc proc.

Result:

24T

Example 3

To use the forward option to create a recursive procedure:

Command input:

define proc ord4 factorial (n)
define ord4 n
{
  forward proc ord4 factorial            // recursive proc
                                        // forward reference
  if (n == 0)
       return 1

  else
       return (n * factorial(n-1))
}
 

base = 10t
factorial (4)

Result:

24T

Example 4

A return data type is not specified, so the type comes from the value returned.

Command input:

define proc truefalse(b)

{

     if(b) {

          return "true"

     } else {

          return "false"

     }

}

Related Topics

define