DEBUG

The DEBUG instruction provides a method to activate the PLBDEBUG symbolic debugger. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

mode

Optional. A parameter that can disable or enable any specific debug instruction dynamically.

cmd

Optional. A Character String Variable or Literal that contains Character Debugger commands. (10.B)

Flags Affected: NONE

Note the following:

1. The debugger must have previously been loaded before it may be activated.

2. The instruction is ignored if the debugger has not been previously loaded.

3. The MODE parameter can be one of the following values:
    

Mode	Function
0	Disable the DEBUG instruction.
!0	Enable the DEBUG instruction when debugging.

 

4. DEBUG is not supported when using the PLBCE runtime.

5. The CMD keyword parameter allows the DEBUG instruction to provide debugger commands that are executed by the character debugger. The DEBUG CMD capability is implemented to provide an easy way to invoke debug commands from a PL/B program without having to use repetitive manual commands while in a debug session. Also, any DEBUG instructions in a PL/B program are ignored when a PL/B program executes normally without debugging. The syntax of the command(s) in the {cmd} data is the same as described in the PLBDBUG section of the Utilities Reference Manual. In addition, the 'X' debugger commands are implemented to store and execute one or more commands.

6. When using the DEBUG instruction CMD command keyword, the command string found in {cmd} is used by the character debugger when a user PL/B program is executing in a debug mode invoked with the '-d' or '-dr' runtime options. The DEBUG instruction is ignored if the user program is not being executed in a debug mode.

7. The {cmd} string can contain one or more character debugger commands up to a maximum limit of 71 characters. Any command data beyond the 71st byte is ignored by the character debugger.

8. There normal character debugger commands as described in the PL/B Utilities Reference under the 'PLBDBUG Commands' section are all implemented to be executed by the character debugger manually. Therefore, if the normal commands are included in the {cmd} command string, the execution of these commands have behaviors as if they were executed by use.

9. The command 'Xn' has been implemented to allow one or more debugger commands to be stored and executed by the character debugger. The 'Xn' commands can be used in the {cmd} command string using three syntax formats as follows:

 

Command	Meaning
Xn	The 'n' can be a numeric digit from '0 to '9'. When the Xn' command is executed, the debug retrieves a previously stored command string and executes it.
Xn {cmddata}	When this 'Xn' command is executed, the {cmddata} string is stored into the debugger 'X' command table. The {cmddata} string can include one or more of the debugger commands. After the {cmddata} is stored into the debugger 'X' command table. Execution using the simple 'Xn' command causes the {cmddata} string to be parsed and executed. The {cmddata} string has a size limitation of 71 characters including the leading 'Xn'.   {cmddata} Syntax   <cmd>[; <cmd>[...]]   Where:   <cmd> - Single character debugger command.   Example of 'Xn' entered a the debugger console:   "X0 DV S$CMDLIN"   This 'X0' command stores the 'DV S$CMDLIN' string into the 'X' command table position 0.   "X1 DV S$ERROR$; BP ProgLabel"   This 'X1' command stores the 'DV S$ERROR$; BP Proglabel' string into the 'X' command table position 1.   "X9 X0; X1"   This command stores the 'X0; X1' string into the 'X' command table position 9. When the simple 'X9' command is executed, the simple 'X0' is executed followed by the execution of the simple 'X1' command.
Xn! {cmddata}	When this 'Xn!' command is executed, the {cmddata} string is stored into the debugger 'X' command table the same as described for the 'Xn {cmddata}' command. The '!' appended to form the 'Xn!' causes the {cmddata} string to be parsed and executed immediately by the character debugger. The debugger command behavior depends on the commands used in the {cmddata} string.   Example of 'Xn!' entered a the debugger console:   "X0! DV S$CMDLIN"   This 'X0!' command stores the 'DV S$CMDLIN' string into the 'X' command table position 0. Then the {cmddata} table position 0 is executed by the character debugger. In this case, the 'DV S$CMDLIN' is shown in the character debugger window and the debugger breaks waiting for the next end-user command.   "X1! BP ProgLabel; G"   This 'X1!' command stores the 'DV S$CMDLIN' string into the 'X' command table position 1. Then the {cmddata} table position 1 is executed by the character debugger. In this case, the 'BP ProgLabel' command is executed by the character debugger which is followed by the execution of the 'G' command.
Xn? {cmddata}	When this 'Xn?' command is executed, the {cmddata} string is stored into the debugger 'X' command table the same as described for the 'Xn {cmddata}' command The '?' appended to form the 'Xn?' command causes the character debugger to continue the PL/B program execution immediately after the {cmddata} is stored. In this case, the {cmddata} is not executed as the program execution continues.   Example of 'Xn?' entered a the debugger console:   "X0? BP ProgLabel"   This 'X0?' command stores the 'BP ProgLabel' string into the 'X' command table position 0. Then the PL/B program continues to execute without executing the 'BP ProgLabel' command. After this 'X0' command string is store, the execution of the simple 'X0' command will execute the 'BP ProgLabel' command.

 

10. The new command 'Xn' can be executed directly at the character debugger input window. However, when the 'X' commands are executed in the PL/B 'DEBUG CMD={cmd}' instruction while a PL/B program is executing in the debug mode, the character debugger retrieves the {cmd} information and processes the commands. This allows PL/B programs to be programed to selectively execute and/or build DEBUG commands dynamically.

Example of static CMD commands:

This instruction uses the 'X0!' command as follows:

1. The command string 'BC *; BP ABC; G' is stored into the 'X' command table position 0.

2. The '!' causes the character debugger to execute the newly stored 'X0' command.

3. The character debugger executes the debug commands as follows:

execute> BC * //Clears all break points

execute> BP ABC //Set Break Point for ABC

execute> G //Continue Program Execution

     DEBUG CMD="X0! BC *; BP ABC; G"

Example of dynamic CMD commands:

This instruction uses the 'X0?' and 'X1?' commands to store break points for program use.

     DEBUG CMD="X0? BP ABC; BL"

     DEBUG CMD="X1? BP XYZ; BL"

doCmd DIM 71

 ....

.

     IF (CONDITION1)

       MOVE "X9! BC *; X0; G", doCmd //Use ABC break point!

     ELSE IF (CONDITION2)

       MOVE "X9! BC *; X1; G", doCmd //Use XYZ break point!

     ELSE

       MOVE "X9! X0; X1; G", doCmd //Use both break points!

     ENDIF

     DEBUG CMD=doCmd

See Also: Example Code, TRACE, Program Control Instructions