PRACTICE Script Language Reference Guide

Transcription

1 PRACTICE Script Language Reference Guide TRACE32 Online Help TRACE32 Directory TRACE32 Index TRACE32 Documents... PRACTICE Script Language... PRACTICE Script Language Reference Guide... 1 Related Documents... 4 A...D... 5 APPEND Append to file 5 BEEP Acoustic signal 5 CLOSE Close file 6 CONTinue Continue PRACTICE program 6 DECRYPT Decrypts PRACTICE program 7 DO Start PRACTICE program 8 DODECRYPT Start encrypted PRACTICE program 8 E...F... 9 ELSE Conditional program execution 9 ENCRYPT Encrypt a text or binary file 9 ENCRYPTDO Encrypt a PRACTICE program 10 ENCRYPTPER Encrypt a PER file 11 END Terminate PRACTICE program 11 ENDDO Return from a PRACTICE program 11 ENTER Window-based input 13 ENTRY Parameter passing 14 G...H GLOBAL Create global PRACTICE macro 16 GLOBALON Global event-controlled PRACTICE script execution 17 GOSUB Subroutine call 21 GOTO Local program jump 22 I...L IF Conditional program execution 23 INKEY Character input 24 JUMPTO Global program jump 24 LOCAL Create local PRACTICE macro 25 M...O ON Event-controlled PRACTICE script execution 27 PRACTICE Script Language Reference Guide 1

2 OPEN Open data file 31 P PBREAK Breakpoints in PRACTICE script files (*.cmm) 32 PBREAK.at Deprecated 32 PBREAK.Delete Delete breakpoint 32 PBREAK.DISable Disable breakpoint 33 PBREAK.ENable Enable breakpoint 33 PBREAK.List Display breakpoint list 35 PBREAK.OFF TRACE32 disables breakpoint handling 36 PBREAK.ON TRACE32 re-enables breakpoint handling 37 PBREAK.RESet Clear all breakpoints 37 PBREAK.Set Add breakpoint 38 PEDIT Edit PRACTICE program 40 PLIST List PRACTICE program 41 PMACRO PRACTICE macros 42 PMACRO.EXPLICIT Enforce explicit PRACTICE macro declaration 42 PMACRO.IMPLICIT Implicit PRACTICE macro declaration 45 PMACRO.list Display PRACTICE macros 45 PMACRO.LOCK Lock PRACTICE macros 46 PMACRO.RESet Clear current PRACTICE macros 46 PMACRO.UNLOCK Unlock PRACTICE macros 46 PRINT Print 47 PRIVATE Create private PRACTICE macro 49 PSTEP Execute single line 50 PSTEPOUT tbd. 50 Q...R READ Read from data file 51 RePeaT Conditional program loop 52 RETURN Return from subroutine 52 RUN Start PRACTICE program 53 S...T SCREEN Screen updating 54 SCREEN.ALways Refresh always 54 SCREEN.display Refresh screen 54 SCREEN.OFF No refresh 55 SCREEN.ON Refresh when printing 55 SCREEN.WAIT Update screen and wait for processing windows 56 STOP Interrupt PRACTICE program 56 W...Z WAIT Wait until a condition is true or a period has elapsed 57 WHILE Conditional program loop 58 WRITE Write to data file 59 PRACTICE Script Language Reference Guide 2

3 WRITEB Write binary data to file 60 PRACTICE Script Language Reference Guide 3

4 PRACTICE Script Language Reference Guide Version 19-May Jan Dec Nov-14 Empty lines and comments are now permissible after IF, ELSE, WHILE, and RePeaT. Consequently, any previous warnings were removed. Updated LOCAL with information for new and experienced users. Added descriptions and examples for PMACRO.EXPLICIT and PMACRO.IMPLICIT. Related Documents For information about literals, operators, and operator precedence, refer to: IDE User s Guide (ide_user.pdf). Alternatively, choose Help menu > Index, and then enter the search item. For information about functions, refer to: IDE Functions (ide_func.pdf) General Functions (general_func.pdf) For information about the purpose of functions in TRACE32, how to use functions, and the difference between functions and commands, refer to: General Functions (general_func.pdf) ;To retrieve the same information via the TRACE32 command line: HELP.Index "literals" HELP.Index "operators" HELP.Index "operator precedence" HELP.Index "functions" PRACTICE Script Language Reference Guide 4 Related Documents

5 A...D APPEND Append to file APPEND <file> <parlist> Append data to a data file. The syntax of the command is similar to the PRINT command. OPEN #1 datafile.dat /Write CLOSE #1 APPEND datafile.dat "Test" CLOSE OPEN WRITE Release Information in Release History BEEP Acoustic signal BEEP [<sound code>] This command generates an acoustic signal on the host computer. The type of the sound depends on the host. To get more complex sounds on workstation hosts it is possible to execute operation system commands. BEEP 5. SETUP.SOUND PRACTICE Script Language Reference Guide 5 A... D

6 CLOSE Close file CLOSE #<bufferno> An input or output file will be closed. OPEN #1 ~~~/test.dat /Write ; open file WRITE #1 "Test data" ; write data to file CLOSE #1 ; close file TYPE ~~~/test.dat ; optional: open file as read-only The path prefix ~~~ expands to the temporary directory of TRACE32. APPEND Data.WRITESTRING OPEN READ Var.WRITE WRITE WRITEB CONTinue Continue PRACTICE program CONTinue [[<line>] [<file>]] A PRACTICE program which has been stopped will be restarted at the current PRACTICE program counter (PC). PRACTICE programs will be stopped by the STOP command or by a breakpoint within the program. The CONTinue command can also be used to resume a program that has been halted due to an error condition. The wrong command may be replaced by an interactive command. <line> Line number. Go till <line> in the active PRACTICE script., <file> Line number is omitted. Path and file name of PRACTICE script. Go till first executable line in the PRACTICE script <file>. <line> <file> Go till <line> in the PRACTICE script <file>. DO test.cmm CONTinue ; start program ; program stopped at breakpoint ; continue PRACTICE Script Language Reference Guide 6 A... D

7 STOP CONTinue ; stop program by STOP command ; continue END PBREAK STOP DECRYPT Decrypts PRACTICE program DECRYPT <string> <filename_encrypted> [<filename_decrypted>] Decrypts together with the original key string an encrypted PRACTICE script. The resulting file can get a new name or replace the old file. PRACTICE Script Language Reference Guide 7 A... D

8 DO Start PRACTICE program DO <filename> [<parlist>] The DO command starts a PRACTICE program. The DO command can be used on the command level to start a PRACTICE program or within a program to run another file like a subroutine. PRACTICE files started by a DO command should be terminated by the ENDDO instruction. Additional parameters may be defined which are passed to the subroutine. The subroutine reads the parameter list by the ENTRY command. Using the DO command even those settings saved by the STOre command can be retrieved. When the TRACE32 system is started, the start-up sequence 't32.cmm' is searched in the current path and the system path. If this file exists, the commands of the file will be executed automatically. The default extension of PRACTICE files may be changed with the SETUP.EXT DO command. ; store window setting to the PRACTICE file 'test.cmm' STOre test Win ; set-up window setting by executing the program 'test.cmm' DO test ; Endless loop with subroutine call &count=1 WHILE TRUE() ( DO mem_test PRINT "MEMTEST " &count &count=&count+1 ) ENDDO DODECRYPT END ENDDO ENTRY GLOBALON GOSUB JUMPTO ON PSTEP RePeaT RUN STOre Starting-up the TRACE32-FIRE in Training FIRE Basics Starting-up the Emulator in Training ICE Basics Introduction to Script Language PRACTICE in Training Script Language Generate a Start-Up Script in Establish Your Debug Session PRACTICE Script Language Reference Guide 8 A... D

9 DODECRYPT Start encrypted PRACTICE program DODECRYPT <keystring> <filename_encrypted> [<parlist>] DODECRYPT starts a PRACTICE program that was encrypted with same key string by command ENCRYPTDO. The key string is necessary for execution. The PRACTICE script file stays encrypted. DO PRACTICE Script Language Reference Guide 9 A... D

10 E... F ELSE Conditional program execution ELSE [IF <cond>] The command or program block following an ELSE statement will be executed, if the condition in the previous IF statement is false. IF Register(PC)==ADDRESS.OFFSET(main) PRINT "PC on start position" ELSE PRINT "PC not on start position" IF Register(PC)==ADDRESS.OFFSET(main) ( PRINT "PC on start position" STOP ) ELSE IF Register(PC)==ADDRESS.OFFSET(end) ( PRINT "PC on end position" STOP ) ELSE ( PRINT "PC neither on start nor on end position" Register.Set PC main STOP ) IF Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 10 E... F

11 ENCRYPT Encrypt a text or binary file ENCRYPT <keystring> <src_file> [<encrypted_file>] Encrypts the contents of a text or binary file using the specified key string. If no file name for the encrypted file is specified, the original file will be replaced by the encrypted file. The resulting file can be decrypted with the command DECRYPT, together with the original key string. ENCRYPTDO ENCRYPTPER ENCRYPTDO Encrypt a PRACTICE program ENCRYPTDO <keystring> <src_file> [<encrypted_file>] Encrypt a PRACTICE program using the specified key string. If no file name for the encrypted file is specified, the original file will be replaced by the encrypted file. The encrypted PRACTICE program can be executed with the command DODECRYPT using the original key string. Decrypting the PRACTICE program or viewing its contents is not possible. Use ENCRYPTDO to generate PRACTICE programs which can be executed by the end user, without the possibility to read or modify the program. NOTE: Do not use ENCRYPTDO on already encrypted scripts! ENCRYPT ENCRYPTPER Release Information in Release History PRACTICE Script Language Reference Guide 11 E... F

12 ENCRYPTPER Encrypt a PER file ENCRYPTPER <keystring> <src_file> [<encrypted_file>] Encrypts a PER definition file using the specified key string. If no file name for the encrypted file is specified, the original PER file will be replaced by the encrypted PER file. The encrypted PER file can be executed and viewed with the command PER.viewDECRYPT using the original key string. Decrypting the PER file or viewing its original file contents in plain text is not possible. Use ENCRYPTPER to generate PER files which can be executed by the end user, without the possibility to read or modify the original PER file contents. NOTE: Do not use ENCRYPTPER on already encrypted PER files! ;encrypt a PER file residing in the system directory of TRACE32 ENCRYPTPER " " ~~\pera940t.per ~~\pera940t_encrypted.per ;execute the encrypted PER file, expand the section "ID Registers" PER.viewDECRYPT " " ~~\pera940t_encrypted.per "ID Registers" ENCRYPT ENCRYPTDO PER.viewDECRYPT END Terminate PRACTICE program END The PRACTICE program is stopped and its stack is cleared. All loaded PRACTICE programs are removed from memory. All setups and PRACTICE macros stored in the PRACTICE stack are deleted, e.g. command extensions, error exits. Usually the END command is used in a PRACTICE file. Interactive usage is needed to clear the PRACTICE stack after a stack overrun has occurred. END CONTinue DO GLOBALON STOP PRACTICE Script Language Reference Guide 12 E... F

13 ENDDO Return from a PRACTICE program ENDDO [<return value list>] Ends a PRACTICE program. Execution is continued in the calling program. If no calling routine file exists, the PRACTICE program execution will be stopped. It is recommended to end all PRACTICE script files (*.cmm) with ENDDO to remove them from the PRACTICE stack. ; Sub-module memory test Data.Test 0x0--0x0fff Data.Test 0x x0ffff ENDDO PRACTICE programs can pass return values to the caller: ; script test_status.cmm ENDDO TRUE() ; ENDDO FALSE() ; return TRUE as result ; return FALSE as result ; script enddo_param.cmm DO test_status ENTRY &result IF &result DIALOG.OK "Test passed" ELSE DIALOG.OK "Test failed" ;execute test_status.cmm ;read result ;react on result ENDDO NOTE: TRUE() and FALSE() are PRACTICE functions returning the corresponding boolean values. DO RUN STOP PRACTICE Script Language Reference Guide 13 E... F

14 ENTER Window-based input ENTER <parlist> This is the window-based input function. Input is always done via a special PRACTICE I/O window (See the AREA command set). Area.Create IO Area.Select IO ; create an AREA window ; select the AREA window as PRACTICE ; input/output window Area.view IO ; display the AREA window PRINT "Coordinate (x y)? " PRINT "x=" ENTER &x PRINT "y=" ENTER &y PRINT "x=" &x " y=" &y WAIT 1.s WinCLEAR TOP AREA.RESet ENDDO ; print input request ; enter x ; enter y ; print x value and y value ; wait 1 second ; then the window is closed ; automatically ; reset AREA window system to default ; settings INKEY Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 14 E... F

15 ENTRY Parameter passing ENTRY <parlist> <parlist> [%LINE] <macroname> Passing of parameters to or from PRACTICE scripts/subroutines. Arguments are separated by blanks. With the LINE option a complete line is read into one PRACTICE macro. Without a LOCAL command for defining local PRACTICE macros, existing PRACTICE macros from preceding routines are used. Only not existing PRACTICE macros are defined automatically. B::DO test.cmm P:0x1000 ; TRACE32 POWERVIEW command line SYStem.Up ;... ENTRY &address GOSUB func1 &address 1. ENTRY &result PRINT "Result=" &result ENDDO func1: LOCAL &addr &size ENTRY &addr &size &size=&size-1. Data.Set &addr++&size 0x2 &retval=data.byte(&addr) RETURN &retval ; content of PRACTICE script test.cmm ; Take argument, here P:0x1000, from ; the PRACTICE script call ; Call subroutine func1 with two args ; Get return value of subroutine ; Define local PRACTICE macros ; Get arguments from subroutine call ; Perform command ; Calculate return value ; Return value to caller DO GLOBALON GOSUB GOTO JUMPTO LOCAL RETURN Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 15 E... F

16 G...H GLOBAL Create global PRACTICE macro GLOBAL <macro> Creates a global macro. Global macros are visible everywhere. They are not erased when the declaring file or block ends. That is, global macros remain in the global PRACTICE stack after execution of the procedure or subroutine. Private macros Local macros Global macros Global PRACTICE stack frame The example below shows how to declare and initialize global PRACTICE macros. Stepping through the code allows you to see how global macros behave in relation to local and private macros (See How to... ). PMACRO.list GLOBAL &SessionStart &State &Level LOCAL &val1 &val2 &SessionStart=CLOCK.TIME() &val1=0x1f &val2=0x2f ;View the PRACTICE stack ;Declare three global macros ;Declare two local macros ;Initialize a global macro ;Initialize the local macros ( ;Open a sub-block PRIVATE &val1 &val2 ;Declare private macros &val1=0x3f ;Initialize private macros &val2=0x4f ) ;Close sub-block LOCAL PMACRO.EXPLICIT PMACRO.IMPLICIT PMACRO.list PMACRO.RESet PRIVATE PRACTICE Script Language Reference Guide 16 G... H

17 GLOBALON Global event-controlled PRACTICE script execution GLOBALON <event> [<action>] <event>: <PRACTICE_specific> <device_specific> <CPU_specific> <PRACTICE_ specific>: ALWAYS ERROR STOP KEY <code> CMD <commandname> <action> TIME <delay> <action>: DO <filename> The GLOBALON command enables the automatic start or branching of the PRACTICE programs controlled by several events. In order for events and their actions to be available, they need to be registered in TRACE32. To register events and their actions, you can: Run the GLOBALON commands via the TRACE32 command line. Include the GLOBALON commands in the t32.cmm start-up script (location: C:\T32\t32.cmm). As a result, they are automatically registered when you start TRACE32. Include the GLOBALON commands in any other script. As a result, they are only registered when you run that script. Registered actions remain stored on the global PRACTICE stack frame. Therefore, the actions are valid for the entire duration of the TRACE32 session, or until removed manually. The currently active actions can be viewed with the PMACRO command. The outermost frame is the global PRACTICE stack frame, as shown below. Global PRACTICE stack frame with GLOBALON actions Next: Description of <events> (PRACTICE specific) Description of <actions> Creating and Registering User-defined Commands - This section provides one simple and two advanced examples for GLOBALON CMD <commandname> <action>. Unregistering GLOBALON Actions PRACTICE Script Language Reference Guide 17 G... H

18 <events> (PRACTICE specific) for the GLOBALON Command The following table focuses on the PRACTICE-specific GLOBALON events and tells you where to find the descriptions of the device-specific and CPU-specific events. Events ALWAYS ERROR STOP CMD TIME KEY <device_specific_ events> <CPU_specific_ events> Descriptions The defined PRACTICE sequence is executed permanently, as long as no keyboard input occurs or no normal PRACTICE program is activated. Will be executed if a syntax or runtime error occurs in PRACTICE. The default action of this event is to halt script execution. Will be executed, when the STOP button from the toolbar is pushed. Warning: A PRACTICE program using this feature may hang and cannot by stopped then by the STOP button! Definition of a user-defined command. The command set of the system can be extended. The length of the command name is limited to 9 characters. Arguments can be passed in the usual way. See Creating GLOBALON Actions for PRACTICE Events. Execute the program after a delay time. Defines shortcuts on function keys. For a description of device-specific events, see GLOBALON in General Commands Reference Guide G (general_ref_g.pdf). Debuggers providing CPU specific events are listed in the block at the end of the GLOBALON command description in the General Commands Reference Guide G (general_ref_g.pdf). <actions> for the GLOBALON Command One of the following actions can be defined for any of the above events: Actions no action specified DO Descriptions An already defined action for a particular global event will be removed from the global PRACTICE stack frame. See Unregistering GLOBALON Actions. If the event occurs, the specified PRACTICE script file will be executed automatically. PRACTICE Script Language Reference Guide 18 G... H

19 Creating and Registering User-Defined Commands (GLOBALON) To illustrate GLOBALON CMD <commandname> <action>, the following examples are provided: Example 1: This is a very simple example for demo purposes. It creates the user-defined command TICONS, which opens the TRACE32 icon library. Example 2: The user-defined command SOURCE displays the HLL source code without changing your emulation mode setting ASM, HLL, or MIX; see DEBUGMODE() and Mode. Example 3: The user-defined command SOURCE2 accepts an argument if you enter one at the TRACE32 command line and passes it to the <action>. Example 1: TICONS Register your user-defined command TICONS, e.g. by copying and pasting the following GLOBALON CMD into the TRACE32 command line: ; Register the user-defined command TICONS ; <command> <action> GLOBALON CMD TICONS DO "~~/demo/menu/internal_icons.cmm" Result: Typing TICONS at the TRACE32 command line now opens the TRACE32 icon library. NOTE: Built-in commands cannot be overwritten, i.e. a user-defined command named SYS is not possible. SYS will continue to open the SYStem.state window. Example 2: GLOBALON CMD without an Argument 1. Develop the action (PRACTICE script *.cmm), such as the following one: ;Check if the window named mywin01 already exists to prevent ;duplicate windows IF!WIN.EXIST(myWin01) ( ;Additionally, assign a user-defined window position and name WinPOS 0% 0% 100% 50%,, mywin01 ;Display the program in source format (HLL, high level ;language) Data.ListHLL /Track ) ENDDO PRACTICE Script Language Reference Guide 19 G... H

20 2. Register your user-defined command and its action in TRACE32. GLOBALON CMD SOURCE DO "~~/globalon_cmd_source.cmm" Example 3: GLOBALON CMD with an Argument 1. Develop the action (PRACTICE script *.cmm), such as the following one: ; Displays the program in source format (HLL, high-level language) ; Starts the listing at the symbol passed as an argument, ; e.g. at main LOCAL &myarg ENTRY &myarg ; Get the argument the user has entered at the TRACE32 ; command line ; Check if an argument is passed or not IF "&myarg"=="" Data.ListHLL /Track ELSE Data.ListHLL &myarg /Track ENDDO 2. Register your user-defined command and its action in TRACE32. GLOBALON CMD SOURCE2 DO "~~/globalon_cmd_source2.cmm" PRACTICE Script Language Reference Guide 20 G... H

21 Unregistering GLOBALON Actions You can unregister all GLOBALON actions or just a selected GLOBALON action. NOTE: Unregistering all GLOBALON actions from the global PRACTICE stack frame also deletes all global PRACTICE macros (variables). To unregister all GLOBALON actions, type at the TRACE32 command line: END ; Ends all active PRACTICE scripts PMACRO.RESet ; Unregisters all GLOBALON actions and ; deletes all global PRACTICE macros (variables) To unregister just a selected GLOBALON action, type at the TRACE32 command line: END ; Ends all active PRACTICE scripts ; Unregisters the action for the user-defined command TICONS GLOBALON CMD TICONS ; Do not include the DO <action> here! Result: The respective line or lines are no longer displayed in global PRACTICE stack frame of the PMACRO window. Thus the global action can no longer be executed. DO ENTRY LOCAL ON PRACTICE Script Language Reference Guide 21 G... H

22 GOSUB Subroutine call GOSUB <label> [<parlist>] The PRACTICE program continues at the defined label. Optionally, parameters may be passed, which can be taken over by the subroutine using the ENTRY command. GOSUB subr1 0x "abc" ENDDO subr1: ENTRY &address &len &string Data.Set &address++(&len-1) &string RETURN NOTE: Labels must start in the first column of a line and end with a colon. No preceding white space allowed. DO ENTRY GOTO JUMPTO ON RETURN Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 22 G... H

23 GOTO Local program jump GOTO label The PRACTICE program continues to execute at the defined label. You can also jump out of program blocks. In interactive mode, the program counter can be altered using the GOTO command. GOTO endloop GOTO 102. &abc="lab10" GOTO &abc ; label as target ; line number as target ; PRACTICE macro for variable target NOTE: Labels must start in the first column of a line and end with a colon. No preceding white space allowed. ENTRY GOSUB JUMPTO Release Information in Release History Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 23 G... H

24 I...L IF Conditional program execution IF <condition> The command or program block following an IF statement will be executed, if the condition is true. Emulators and debuggers have an counterpart of this command that works in the HLL syntax of the target program (command Var.IF). NOTE: IF must be followed by a white space. IF Register(d0)>0x0 PRINT "Register not zero" ELSE PRINT "Register zero" Var.IF flags[5]>35 STOP ELSE Step ; Hll expression in condition Please avoid the following mistake: IF Register(d0)==0x0 ( step ) ; not allowed ELSE STATE.RUN() Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 24 I... L

25 INKEY Character input INKEY [<par>] The command waits for a keystroke. The code of the key is placed in the PRACTICE macro. If no parameter is used, the command will stop program execution until a key will be pressed on the keyboard. INKEY ; wait until any key is pressed INKEY &key IF &key==0x0d ; wait for one key from keyboard ; check for carriage return ENTER WAIT Structure of PRACTICE Programs in Training Script Language JUMPTO Global program jump JUMPTO <label> The PRACTICE program continues to execute at the defined label. Subroutine calls and block nestings are removed from the PRACTICE stack. The target label can also reside in a stacked program module. The label must reside on the top level of a module! NOTE: Labels must start in the first column of a line and end with a colon. No preceding white space allowed. DO ENTRY GOSUB GOTO Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 25 I... L

26 LOCAL Create local PRACTICE macro LOCAL <macro> The LOCAL command is used to create an empty PRACTICE macro in the current block. The macro hides any macro with the same name potentially created earlier (e.g. at a higher level of the PRACTICE stack). The word local implies the life-time of the macro: it is created with the LOCAL command and erased when the declaring block is left. PRACTICE macros created via LOCAL are visible in all subsequently executed code within their life-time (unless hidden by later macro declarations). In particular they are visible in: Subroutines (GOSUB...RETURN) Sub-scripts (DO...ENDDO) Sub-blocks (IF..., RePeaT, WHILE, etc.) NOTE: For creating macros only visible within their declaring block (as in the C programming language) use the command PRIVATE. Example 1: LOCAL &a &b &c ENTRY &a &b &c=&a*&b ENDDO &c Example 2: LOCAL &result GOSUB myfunc ENTRY &result PRINT "Result is &result" ENDDO myfunc: LOCAL &a &b &c ENTRY &a &b &c=&a*&b RETURN &c PRACTICE Script Language Reference Guide 26 I... L

27 Example 3 prints two sequences of the numbers 1, 2, 3, 4: LOCAL &I &I=1. ;declare macro &I ;assign value WHILE &I<=2. ( PRINT "--Sequence #" &I "--" GOSUB sequence &I=&I+1. ) ENDDO sequence: LOCAL &I ;hides the previously declared &I and declares new macro &I=1. WHILE &I<=4. ( GOSUB output &I=&I+1. ) RETURN output: PRINT &I RETURN ;uses the macro &I declared in subroutine 'sequence' ENTRY GLOBAL GLOBALON PMACRO.EXPLICIT PMACRO.IMPLICIT PMACRO.list PRIVATE PRACTICE Script Language Reference Guide 27 I... L

28 M... O ON Event-controlled PRACTICE script execution ON <event> [<action>] <event>: <PRACTICE_specific> <device_specific> <CPU_specific> <PRACTICE_ specific>: ALWAYS ERROR STOP KEY <code> CMD <commandname> TIME <delay> <action>: inherit CONTinue DO <filename> GOSUB <label> <block> GOTO <label> <block> JUMPTO <label> <block> DEFault The ON command enables the automatic start or branching of the PRACTICE programs controlled by several events. The registered actions are stored on the PRACTICE stack, therefore the command is only valid in the block in which it was set, and in the subroutines called in this block. The currently active ON actions can be viewed with the PMACRO command. The PRACTICE program will be started and stopped automatically, if the GOSUB action is used. If no target label is given, the line or block after the ON command will be executed instead. NOTE: If the action should remain permanently active, use the GLOBALON command. Next: Description of <events> (PRACTICE specific) for the ON Command Description of <actions> for the ON Command Examples PRACTICE Script Language Reference Guide 28 M... O

29 <events> (PRACTICE specific) for the ON Command The following table focuses on the PRACTICE-specific ON events and tells you where to find the descriptions of the device-specific and CPU-specific events: Events ALWAYS ERROR STOP CMD TIME <delay> KEY <device_specific_ events> <CPU_specific_ events> Descriptions The defined PRACTICE sequence is executed permanently, as long as no keyboard input occurs or no normal PRACTICE program is activated. Will be executed if a syntax or runtime error occurs in PRACTICE. The default action of this event is to halt script execution. Will be executed, when the STOP button from the toolbar is pushed. Warning: A PRACTICE program using this feature may hang and cannot by stopped then by the STOP button! Definition of a new command. The command set of the system can be extended. The length of the command name is limited to nine characters. Arguments can be passed in the usual way. Execute the program after a delay time. Defines shortcuts on function keys. For a description of the device specific events, refer to ON in the General Commands Reference Guide O. Debuggers providing CPU specific events are listed in the block at the end of the ON command description in the General Commands Reference Guide O. <actions> for the ON Command One of the following actions can be defined for any of the above events: Actions inherit CONTinue DO Descriptions An already defined action for this event in the current stack level will be removed. If an action is registered in a higher stack level, the action of the higher stack level will be inherited. If no action is registered in any higher stack level, the debugger s default action will be performed (e.g. stop on error event). If the event occurs, script execution will be continued. Use this option e.g. to ignore errors which would cause the script execution to halt. If the event occurs, the PRACTICE script in the specified file will be executed. PRACTICE Script Language Reference Guide 29 M... O

30 Actions GOSUB GOTO JUMPTO DEFault Descriptions If the event occurs, a subroutine call will occur. The subroutine can be specified as label, or inline as PRACTICE block. With RETURN, the subroutine will return normal program execution. For the ERROR event, the subroutine will return to the line after the command which caused the error. If the event occurs, the script execution will continue at the specified label, or in the specified inline PRACTICE block. If the event occurs, the script execution will continue at the specified label, or in the specified inline PRACTICE block. Subroutine calls and block nestings are removed from the PRACTICE stack. Use this action e.g. as global error/ expection handler. The debugger s default action will be performed if the specified event occurs. Actions defined in a higher stack level for this event will be ignored. Use this action e.g. inside an event handler subroutine to avoid re-entry while the handler s subroutine is active. Example 1: Error Handler ON ERROR JUMPTO errorhandler_filenotfound Data.LOAD.ELF project.x ON ERROR inherit ENDDO ;set up error handler ;disable error handler errorhandler_filenotfound: PRINT %ERROR "File not found!" ENDDO PRACTICE Script Language Reference Guide 30 M... O

31 Example 2: Define a New Command ; define new command LoadEx <filename> ON CMD LoadEx GOSUB ( LOCAL &filename ) STOP ENTRY &filename Break.Delete Data.LOAD.ELF "&filename" RETURN ;declare local macros ;get parameter(s) Example 3: Timeout on User Input To try out this script, simply copy it to a test.cmm file, and then run it in TRACE32 (See How to... ). AREA.Create USRINP ;create and show message area AREA.Select USRINP AREA.view USRINP PRINT "Press return (within 5 seconds) to abort configuration > " ON TIME 5.0s GOTO timeout ENTER &invalue ON TIME 5.0s inherit PRINT "Configuration aborted." ENDDO ;set up timeout ;script waits here for user input ;disable timeout timeout: PRINT "Configuration starting..." ENDDO A more complex demo script is included in your TRACE32 installation. To access the script, run this command: B::CD.PSTEP ~~\demo\practice\event_controlled_program\dialog_ontime.cmm PRACTICE Script Language Reference Guide 31 M... O

32 Example 4: Background Task in PRACTICE: ON ALWAYS GOSUB ( PRINT Register(PC) RETURN ) DO GLOBALON GOSUB Release Information in Release History PRACTICE Script Language Reference Guide 32 M... O

33 OPEN Open data file OPEN #<bufferno> <filename> [/<option>] <option>: Read Write Create Append Binary Open a file for reading or writing. When a file is opened in Write mode, the data is per default appended at the end of the file (same behavior as with option /Append). The option /Create creates a new file and overwrites an old one if the file already exists. The default file format is text. The options /Create /Binary create a binary file. OPEN #1 datafile.dat /Read READ #1 &data CLOSE #1 APPEND Data.WRITESTRING Var.WRITE WRITEB FILE.EOFLASTREAD() FILE.OPEN() OS.FILE() OS.FILE.DATE() OS.FILE.EXTENSION() OS.FILE.NAME() OS.FILE.SIZE() Release Information in Release History CLOSE READ WRITE FILE.EOF() FILE.EXIST() FILE.TYPE() OS.FILE.ACCESS() OS.FILE.DATE2() OS.FILE.LINK() OS.FILE.PATH() OS.FILE.TIME() PRACTICE Script Language Reference Guide 33 M... O

34 P... PBREAK Breakpoints in PRACTICE script files (*.cmm) Using the PBREAK command group, you can set, enable, disable, save, and clear an unlimited number of breakpoints in PRACTICE script files (*.cmm). These program breakpoints are set with the PBREAK.Set command. The PBREAK.List window shows an overview of the breakpoints you have set in your PRACTICE script files (*.cmm). For compatibility reasons, TRACE32 continues to support the breakpoint that can be set with the deprecated PBREAK.at command. CONTinue PBREAK.at PBREAK.Delete PBREAK.DISable PBREAK.ENable PBREAK.List PBREAK.OFF PBREAK.ON PBREAK.RESet PBREAK.Set PEDIT PLIST PSTEP PBREAK.at Deprecated PBREAK [<line>] [<filename>] (deprecated) PBREAK.at [<line>] [<filename>] (deprecated) Use PBREAK.Set instead. PRACTICE supports setting (a single) breakpoint into one of the scripts currently active (located on the socalled PRACTICE stack of scripts, see PMACRO). This feature is primarily used while testing PRACTICE scripts. PBREAK.at sets the breakpoint at the given line number in the PRACTICE program. If no file name is indicated, a breakpoint will be set in the program currently loaded on top of the PRACTICE stack. Without a line number, the breakpoint is set on line 1. Without arguments the (single) breakpoint is removed. PBREAK 10. PBREAK PBREAK 10. test PBREAK, test ; Breakpoint at line 10 of currently loaded ; PRACTICE program ; Remove breakpoint ; Breakpoint at line 10 in file 'test.cmm' ; Breakpoint at line 1 in file 'test.cmm' PBREAK PRACTICE Script Language Reference Guide 34 P...

35 PBREAK.Delete Delete breakpoint PBREAK.Delete [<line> [<file>]] If no argument is passed, this command deletes all program breakpoints from the list displayed in the PBREAK.List window. That is, PBREAK.Delete has the same effect as PBREAK.RESet. You can delete specific breakpoints by passing the following arguments: <line> Line number. Deletes all breakpoints at <line> for all PRACTICE scripts., <file> Line number is omitted; path and file name of the PRACTICE script are specified. Deletes all breakpoints for the PRACTICE script <file>. <line> <file> Deletes the breakpoint at <line> for the PRACTICE script <file>. PBREAK PBREAK.RESet Release Information in Release History PBREAK.DISable Disable breakpoint PBREAK.DISable [<line>] [<file>] If no argument is passed, this command disables all program breakpoints. Disabled breakpoints are flagged with a small gray bar in the PLIST and PSTEP windows. PRACTICE Script Language Reference Guide 35 P...

36 You can disable specific breakpoints by passing the following arguments: <line> Line number. Disables all breakpoints at <line> for all PRACTICE scripts., <file> Line number is omitted; path and file name of PRACTICE script are specified. Result: All breakpoints for the PRACTICE script <file> are disabled. <line> <file> Disables the breakpoint at <line> for the PRACTICE script <file>. PBREAK PBREAK.ENable Release Information in Release History PBREAK.ENable Enable breakpoint PBREAK.ENable [<line>] [<file>] If no argument is passed, this command enables all program breakpoints. Enabled breakpoints are flagged with a small red bar in the PLIST and PSTEP windows. You can enable specific breakpoints by passing the following arguments: <line> Line number. Enables all breakpoints at <line> for all PRACTICE scripts., <file> Line number is omitted; path and file name of PRACTICE script are specified. Result: All breakpoints for the PRACTICE script <file> are enabled. <line> <file> Enables the breakpoint at <line> for the PRACTICE script <file>. PBREAK PBREAK.DISable Release Information in Release History PRACTICE Script Language Reference Guide 36 P...

37 PBREAK.List Display breakpoint list PBREAK.List Lists all program breakpoints you have created for PRACTICE script files (*.cmm). The PBREAK.List window shown below provides the following commands via the toolbar and the popup menu: You can delete, disable, and enable all breakpoints or a selected breakpoint. In addition, you can save the breakpoints to file with the STOre command, and load them for the next session with the DO command. Set a new breakpoint. All breakpoints created with PBREAK.Set. Edit the selected breakpoint. Open the file in the PLIST window at line number 42. Descriptions of columns in the PBREAK.List window type: PRACTICE supports program breakpoints. Yellow indicates that script execution has stopped at this breakpoint. You can continue script execution with the CONTinue command. line: Line number of breakpoint - An asterisk (*) in the line column indicates that a breakpoint is set at the first executable line in this PRACTICE script. - A dot before a line number indicates that the breakpoint was originally set to an empty line or comment line. Such a breakpoint automatically moves to the next executable line. file: Lists all PRACTICE script files where breakpoints have been set. - An asterisk (*) in the file column indicates that a breakpoint is dynamically set in any active PRACTICE script at the specified line number (see PBREAK.Set... /AnyFile). This is useful for testing nested PRACTICE script files. action: Action of the breakpoint, i.e. stop or Count. See PBREAK.Set... /Count. count: - Counts how often the PRACTICE program counter (PC) has hit the counter breakpoint. Counter breakpoints are typically set at counters in WHILE loops. - A dot after a counter indicates that the counter limit is unspecified. See PBREAK.Set... /Count. PRACTICE Script Language Reference Guide 37 P...

38 mode: - Old mode: This breakpoint was created with the deprecated PBREAK.at command. - Disabled is displayed for disabled breakpoints. All other breakpoints are enabled. - Temporary is displayed until the PRACTICE program counter (PC) has reached the line with the temporary breakpoint. A temporary breakpoint is created when you right-click a program line in a PLIST window and select Go Till. PBREAK Release Information in Release History PBREAK.OFF TRACE32 disables breakpoint handling PBREAK.OFF Disables all breakpoints for the program currently loaded on top of the PRACTICE stack. If no PRACTICE program is running this command is locked. TRACE32 generates a breakpoint script when you click the Store button in a PBREAK.List window. In this script, your breakpoint settings are enclosed between the PBREAK.OFF and PBREAK.ON command. The two commands ensure that a breakpoint script can be re-loaded without being stopped by the breakpoints it contains. PBREAK.RESet PBREAK.OFF PBREAK.Set 5.,, /AnyFile PBREAK.Set 8. C:\T32\TEST.CMM PBREAK.ON ;reset all PRACTICE breakpoints ;switch off further breakpoint checking ;set a breakpoint to line 5 in any file ;set a breakpoint to line 8 in file ;switch on breakpoint checking again PBREAK PBREAK.ON PRACTICE Script Language Reference Guide 38 P...

39 PBREAK.ON TRACE32 re-enables breakpoint handling PBREAK.OFF Re-enables all breakpoints for the program currently loaded on top of the PRACTICE stack. If no PRACTICE program is running this command is locked. TRACE32 generates a breakpoint script when you click the Store button in a PBREAK.List window. In this script, your breakpoint settings are enclosed between the PBREAK.OFF and PBREAK.ON command. The two commands ensure that a breakpoint script can be re-loaded without being stopped by the breakpoints it contains. PBREAK PBREAK.OFF PBREAK.RESet Clear all breakpoints PBREAK.RESet Deletes all breakpoints from the list displayed in the PBREAK.List window. PBREAK PBREAK.Delete PRACTICE Script Language Reference Guide 39 P...

40 PBREAK.Set Add breakpoint PBREAK.Set <line> <file> [/DISabled /Count /AnyFile /DIALOG] Sets a program breakpoint at <line> for the PRACTICE script <file>. Optionally, the PBREAK.Set dialog can be displayed. If the specified line number refers to an empty line or a PRACTICE comment, then the breakpoint is set at the next executable line. By default, a program breakpoint in a PRACTICE script stops script execution. However, if a program breakpoint is modified with the Count option, script execution continues, and breakpoint hits are counted. The PBREAK.List window lists the breakpoints you have created with PBREAK.Set. <line> Line number. Sets a breakpoint at <line> in the current PRACTICE script or in any script if none is loaded., <file> Line number is omitted; path and file name of PRACTICE script are specified. Result: A breakpoint is set at the first executable line in the PRACTICE script <file>. <line> <file> DISabled Count AnyFile Sets a breakpoint at <line> in the PRACTICE script <file>. The breakpoint is created as a disabled breakpoint. The breakpoint is created as a counter which does not stop the execution of a PRACTICE script, but counts breakpoint hits. Useful for counters in WHILE loops. See Example. Sets a breakpoint at <line> in any PRACTICE script file. You need to replace <file> with two,, (commas) when using AnyFile. TRACE32 then applies the breakpoint to the currently active PRACTICE script. AnyFile is intended for testing nested PRACTICE script files. It automatically stops script execution at the first executable line of any PRACTICE script file that is called next. See Example. PRACTICE Script Language Reference Guide 40 P...

41 DIALOG Displays the PBREAK.Set dialog. Clicking the Add button closes the dialog and makes the PRACTICE breakpoint available in TRACE32. Available breakpoints are listed in the PBREAK.List window. See Example. Example for the Count option: The following example is for demo purposes only. To try out this script, copy it to a test.cmm file, and then run it in TRACE32 (See How to... ). PBREAK.Set 7.,, /Count PBREAK.List &tmp=0. WHILE &tmp<1000. ( &tmp=&tmp+1. PRINT "looprun: &tmp" ) PRINT "loop finished" PBREAK.Delete 7. ;set a breakpoint in line 7. as loop counter ;display the list of breakpoints set in ;PRACTICE script files ;the spot breakpoint is set here ;note that the 'count' column in the ;PBREAK.List updates automatically ;prints the counter to the message bar ;right-click in the PLIST window, and then ;select 'Go Till' ;Delete all breakpoints at line 7. for ;all PRACTICE scripts! Example for the AnyFile option: PBREAK.List ;display breakpoint list for PRACTICE scripts PBREAK.Set 1.,, /AnyFile ;set breakpoint to first executable line ;in any file CD.DO file1.cmm ;script execution automatically stops at the ; file2.cmm ;first executable line of each file ; file3.cmm PBREAK.RESet ;always clear all breakpoints at the end of your session PRACTICE Script Language Reference Guide 41 P...

42 Example for the DIALOG option: ;Opens the list of PRACTICE breakpoints PBREAK.List ;Sets a breakpoint in line 12. of the demo.cmm file and ;opens the PBREAK.Set dialog. PBREAK.Set 12. C:\t32\demo.cmm /DIALOG ;Click the Add button. ;- The dialog closes. ;- The PRACTICE breakpoint appears in the list of PRACTICE breakpoints. ;Sets a breakpoint in line 49. for the currently active script file and ;opens the PBREAK.Set dialog. PBREAK.Set 49.,, /DIALOG ;Click the Add button. ;- The dialog closes. ;- The PRACTICE breakpoint appears in the list of PRACTICE breakpoints. ;The * lets you select a script file from the file browser. ;Then the PBREAK.Set dialog opens. PBREAK.Set, * /DIALOG ;Click the Add button. ;- The dialog closes. ;- The PRACTICE breakpoint appears in the list of PRACTICE breakpoints. PBREAK Release Information in Release History PRACTICE Script Language Reference Guide 42 P...

43 PEDIT Edit PRACTICE program PEDIT <filename> [<line>] The PEDIT command is used to create and edit PRACTICE script files (*.cmm). It works in the same manner as the EDIT command. The default extension is '.cmm'. Auto-saving is active, the file is always saved after leaving the window. PEDIT test ; Edit file 'test.cmm' ClipSTOre EDIT.file PBREAK PLIST PSTEP Create PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 43 P...

44 PLIST List PRACTICE program PLIST [<line>] The currently loaded PRACTICE module is listed. Program nesting, branching and single jumping are marked in the scale on the left. Enabled breakpoints are flagged with a small red bar, disabled breakpoints are flagged with a small gray bar in the PLIST window. PRACTICE breakpoints are listed in the PBREAK.List window. Disabled Enabled Line numbers Program nesting Double-clicking a line toggles a breakpoint (set/delete). PLIST 10. ; List as of line 10 PLIST ; an example for plist PSTEP DO test.cmm PLIST ; List as of the current program counter ; Set PRACTICE program execution to ; single step mode ; Load PRACTICE module ; List PRACTICE module for debugging PBREAK PEDIT PMACRO PSTEP Release Information in Release History PRACTICE Script Language Reference Guide 44 P...

45 PMACRO PRACTICE macros If a PRACTICE program is executed, the PRACTICE stack frame and the PRACTICE macros (variables) can be visualized and the macro search priority can be manipulated by the commands of the PMACRO command group. PLIST PMACRO.EXPLICIT PMACRO.IMPLICIT PMACRO.list PMACRO.LOCK PMACRO.RESet PMACRO.UNLOCK Release Information in Release History PMACRO.EXPLICIT Enforce explicit PRACTICE macro declaration PMACRO.EXPLICIT Enforces explicit declarations of PRACTICE macros. That is, macros in PRACTICE scripts (*.cmm) must be declared with the commands GLOBAL or LOCAL or PRIVATE. Starting a PRACTICE script with PMACRO.EXPLICIT enforces an explicit declaration of all PRACTICE macros for the entire PRACTICE script. The explicit declaration in the parent PRACTICE script extends to all blocks, sub-blocks (e.g. IF..., RePeaT..., WHILE..., etc.), subroutines (GOSUB...RETURN), and sub-scripts (DO...ENDDO). Starting a sub-block or subroutine with PMACRO.EXPLICIT enforces explicit declarations only for the subblock (e.g. IF..., RePeaT..., WHILE..., etc.) or subroutine (GOSUB...RETURN). A B A. Thick gray bar = explicit macro declaration range; here in a subroutine block (GOSUB...RETURN) B. Thin gray bar = implicit macro declaration range PRACTICE Script Language Reference Guide 45 P...

46 If the explicit-declaration setting is violated during PRACTICE script execution, the TRACE32 message line informs you with an error message and script execution stops. If an undeclared macro is initialized, the following error message is displayed: explicit PRACTICE macro declaration expected. If an explicitly declared macro is declared again, the following error message is displayed: explicitly declared PRACTICE macro already exists. NOTE: Explicit macro declaration is recommended for fail-safe operation of PRACTICE scripts. PMACRO.EXPLICIT together with the error messages assists you in declaring all macros explicitly. Examples - GLOBAL Macro Example 1: When GLOBAL macros are declared before PMACRO.EXPLICIT, then the same GLOBAL macros can be re-declared at any time during a TRACE32 session (but not while the parent script is still running). The parameter of a GLOBAL macro can re-initialized by any PRACTICE script. GLOBAL &ProjName1 GLOBAL &Start1 PMACRO.EXPLICIT ;declare PRACTICE macros with GLOBAL ;enforce explicit PRACTICE macro declaration &ProjName1="Project 10" ;initialize the GLOBAL macros &Start1=CLOCK.TIME() Example 2: When GLOBAL macro declarations are placed after PMACRO.EXPLICIT, the GLOBAL macros can be declared only once during a TRACE32 session. If they are declared again, a script error occurs, script execution stops, and an error message is displayed. The parameter of a GLOBAL macro can re-initialized by any PRACTICE script. PMACRO.EXPLICIT GLOBAL &ProjName2 GLOBAL &Start2 ;enforce explicit PRACTICE macro declaration ;declare PRACTICE macro explicitly with GLOBAL &ProjName2="Poject X" ;initialize the GLOBAL macro &Start2=CLOCK.TIME() PRACTICE Script Language Reference Guide 46 P...

47 Examples - LOCAL Macro Example 3: Correct explicit declaration of the PRACTICE macro LOCAL &file1 PMACRO.EXPLICIT LOCAL &file1 &file1=os.pef() PRINT "&file1" ;enforce explicit PRACTICE macro declaration ;declare PRACTICE macro explicitly with LOCAL ;initialize PRACTICE macro ;print name of the currently used TRACE32 executable Example 4: The explicit declaration of the PRACTICE macro LOCAL &file2 is missing, which will result in an error message. PMACRO.EXPLICIT //enforce explicit PRACTICE macro declaration //the explicit declaration with the LOCAL command is missing here &file2=os.pef() //now, a script error occurs, script execution stops, //and the following error message is displayed: //"explicit PRACTICE macro declaration expected" GLOBAL LOCAL PMACRO PMACRO.IMPLICIT PRIVATE Release Information in Release History PRACTICE Script Language Reference Guide 47 P...

48 PMACRO.IMPLICIT Implicit PRACTICE macro declaration PMACRO.IMPLICIT Ends the explicit macro declaration range started with the PMACRO.EXPLICIT command. NOTE: By default, TRACE32 declares macros implicitly if you neglected to declare them with the commands LOCAL or PRIVATE. GLOBAL LOCAL PMACRO PMACRO.EXPLICIT PRIVATE Release Information in Release History PMACRO.list Display PRACTICE macros PMACRO.list Displays the global, local, and private PRACTICE macros. In addition, the PMACRO.list window displays: The global PRACTICE stack frame Local PRACTICE stack frames Program nesting PRACTICE Script Language Reference Guide 48 P...

49 Loop commands (WHILE, RePeaT) User-defined ON and GLOBALON commands Local PRACTICE stack frames Global PRACTICE stack frame Example of a user-defined command named TICONS GLOBAL LOCAL PMACRO PRIVATE PMACRO.LOCK Lock PRACTICE macros PMACRO.LOCK All macros of higher nesting levels are disabled. The lock will be released automatically if the current level is left. PMACRO PMACRO.UNLOCK PMACRO.RESet Clear current PRACTICE macros PMACRO.RESet All macros in the current level are removed. If no PRACTICE program is running, all macros on the top level will be erased. GLOBAL GLOBALON PMACRO Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 49 P...

50 PMACRO.UNLOCK Unlock PRACTICE macros PMACRO.UNLOCK Re-enables the macros that were previously disabled with PMACRO.Lock. PMACRO PMACRO.LOCK PRACTICE Script Language Reference Guide 50 P...

51 PRINT Print PRINT [%<format1>] [%<format2>] <data> <format1>: Ascii BINary Decimal Hex String <format2> ATTR <value> CONTinue ERROR HOME Prints the given arguments to the selected AREA window. NOTE: Only when printing to the default AREA A000, the printed data is also shown in the TRACE32 message line. <format1> ATTR <value> CONTinue ERROR HOME Converts all following <data> to the specified format. Prints data with special attribute (internal feature only). Prints data to current line instead of new line. Data will be printed in red. Only when printing to the default AREA A000, the text is also shown as an error in the TRACE32 message line. Prints to top line in AREA window. PRINT "Data &data found at " ADDRESS.OFFSET(TRACK.ADDRESS()) PRINT %ERROR "FLASH programming failed" PRACTICE Script Language Reference Guide 51 P...

52 ;define position, size and name of the AREA window OUT WINPOS OUTWIN AREA.Create OUT AREA.Select OUT AREA.view OUT ; create AREA window OUT ; assign AREA window OUT as standard I/O ; for PRINT command ; display AREA window OUT on the screen PRINT "Text 1 " PRINT %CONTinue "Text 2 " PRINT %ERROR "Error text" ; print text without line break ; print error text in red ; prints all data in a certain data format PRINT %Decimal 0x1f ":" 0x2f ":" 0x3f "-" %BINary 0x1f ":" 0x2f ":" 0x3f ; prints all data in certain format using PRACTICE formatting functions PRINT FORMAT.Decimal(5.,0x1f) " - " FORMAT.BINary(10.,0x1f) ; formatted printing (includes character repetition with <<) PRINT "="<<24. PRINT " " "NAME" "."<<(20.-STRing.LENgth("NAME")) " " WinClear OUTWIN ; remove AREA window OUT AREA.CLEAR AREA.CLOSE AREA.Create AREA.OPEN AREA.RESet AREA.Select AREA.view PRinTer WinPrint Release Information in Release History Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 52 P...

53 PRIVATE Create private PRACTICE macro PRIVATE <macro> Creates a private macro. Private macros exist inside the declaring block and are erased when the block ends. They are only visible in the declaring block and in all sub-blocks (e.g. IF..., RePeaT..., WHILE..., etc.), but neither in subroutines (GOSUB...RETURN) nor in sub-scripts (DO...ENDDO). The following example is just intended to illustrate the usage of private macros. Simply copy the script to a test.cmm file, and then step through the script (See How to... ). LOCAL &msg //Declare LOCAL macro &msg="hello World!" PRINT "&msg" //Show LOCAL macro GOSUB child1 //Call a subroutine PRINT "&msg" //Show LOCAL macro ENDDO ; child1: PRIVATE &msg //Declare PRIVATE macro &msg="this comes from a private macro" //Show PRIVATE macro defined in child1 PRINT "child1 says: &msg" ( //PRIVATE macros are visible inside a sub-block: &msg="this comes again from the private macro" PRINT "&msg" ) GOSUB grandchild1 //Show PRIVATE macro defined in child1 PRINT "child1 says: &msg" RETURN ; grandchild1: //LOCAL macros visible in any subroutine: //Show again LOCAL macro defined in the beginning of the script PRINT "grandchild1 says: &msg" &msg="hello Universe!" RETURN GLOBAL LOCAL PMACRO.EXPLICIT PMACRO.IMPLICIT PMACRO.list Release Information in Release History PRACTICE Script Language Reference Guide 53 P...

54 PSTEP Execute single line PSTEP [<filename> [<parlist>]] If no PRACTICE program is loaded, the command will toggle the run mode. If the run mode is switched to single step, the next started PRACTICE program will stop at the first line and can be executed in single step mode. With a given PRACTICE program filename the DO command will be superfluous. PSTEP DO test PSTEP PSTEP test.cmm 0x1fff ; sets PRACTICE program execution to ; single step mode ; starts PRACTICE program ; single step in PRACTICE program ; sets PRACTICE program execution to ; single step mode and starts PRACTICE ; program DO PBREAK PEDIT PLIST RUN Release Information in Release History PSTEPOUT tbd. tbd. PRACTICE Script Language Reference Guide 54 P...

55 Q... R READ Read from data file READ #<bufferno> [%LINE] <parlist> Read data from an open file. Arguments in the file are separated by blanks. With the LINE option a complete line is read into one PRACTICE macro. LOCAL &offset &data &headerline OPEN #1 datafile.dat /Read READ #1 %line &headerline PRINT "&headerline" // script for newer software versions RePeaT 10. ( READ #1 &offset &data IF EOF() GOTO endloop Data.Set &offset &data ) endloop: CLOSE #1 // for older software versions than RePeaT 10. ( READ #1 &offset &data IF "&offset"=="" GOTO endloop Data.Set &offset &data ) endloop: CLOSE #1 CLOSE OPEN WRITE PRACTICE Script Language Reference Guide 55 Q... R

56 RePeaT Conditional program loop RePeaT [<count>] <block> [WHILE [<condition>]] or RePeaT <count> <command> The command or program block following a RePeaT command will be executed as long as the condition is true. However, at least one program loop and max. <count> loops will be executed. The second form can be used to repeat the execution of a single command. If the <count> value is zero, it will execute an endless loop. The command may be started interactively from the command line. RePeaT Data.Find 0x0--0x0fff 0x0 WHILE!FOUND() RePeaT 100. PRINT "X" RePeaT 0x0 Data.Test 0x0--0x0ffff DO WHILE Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 56 Q... R

57 RETURN Return from subroutine RETURN [<parlist>] The subroutine is finished. Optionally, parameters may be passed, which can be taken over using the ENTRY command. GOSUB subr2 ENTRY &portval subr2: &result=data.byte(sd:0x100) RETURN &result ENTRY GOSUB Structure of PRACTICE Programs in Training Script Language RUN Start PRACTICE program RUN <filename> [<parlist>] The RUN command starts a PRACTICE program after clearing the old PRACTICE stack. Additional parameters may be defined which are passed to the subroutine. The command is identical to the DO command, except that it clears the old stack before starting the PRACTICE module. DO ENDDO PSTEP Introduction to Script Language PRACTICE in Training Script Language PRACTICE Script Language Reference Guide 57 Q... R

58 S... T SCREEN Screen updating If PRACTICE programs are executed, the screen is normally not updated. The screen commands allow updating of the screen manually or automatically. The command has no effect on the screen update, while PRACTICE is not running, e.g. the update at spot points. SCREEN.ALways SCREEN.display SCREEN.OFF SCREEN.ON SCREEN.WAIT SCREEN.ALways Refresh always SCREEN.ALways The screen is refreshed after every PRACTICE line. This slows down the execution speed, but allows tracing the program flow. PLIST SCREEN.ALways DO test.cmm ; display program state ; run SCREEN SCREEN.display SCREEN.OFF SCREEN.ON PRACTICE Script Language Reference Guide 58 S... T

59 SCREEN.display Refresh screen SCREEN.display The screen is updated. SCREEN.OFF PRINT " Screen Mask: A" PRINT " B" PRINT SCREEN ; turn refresh off for fast printing ; update the screen SCREEN SCREEN.ALways SCREEN.OFF SCREEN.ON SCREEN.WAIT SCREEN.OFF No refresh SCREEN.OFF No refreshing of the screen is done, while PRACTICE programs are running (except SCREEN.display commands). This allows PRACTICE programs to execute very fast, but the results will not be seen on the screen during program execution. SCREEN SCREEN.ALways SCREEN.display SCREEN.ON SCREEN.ON Refresh when printing SCREEN.ON The screen is refreshed after every PRINT command. SCREEN SCREEN.ALways SCREEN.display SCREEN.OFF PRACTICE Script Language Reference Guide 59 S... T

60 SCREEN.WAIT Update screen and wait for processing windows SCREEN.WAIT Updates the screen and furthermore wait until all processing windows are completed before the next PRACTICE instruction is interpreted. Examples for processing windows are: Trace.STATistic.Func, Trace.Chart.sYmbol or CTS.List. Go WAIT!STATE.RUN() Trace.Chart.sYmbol SCREEN.WAIT ; start program execution ; wait until program execution ; stopped ; perform a flat function run-time ; analysis ; update screen and wait until ; flat function run-time analysis ; is completed ; continue PRACTICE program ; execution SCREEN SCREEN.display STOP Interrupt PRACTICE program STOP [<parlist> ] The program is stopped, but it remains in the working storage and can be reactivated by the CONTinue command. The arguments are displayed in the message line and AREA window (same as command PRINT). Data.Test 0x0--0x0ffff IF FOUND() STOP "Memory error" CONTinue END ENDDO WAIT PRACTICE Script Language Reference Guide 60 S... T

61 W...Z WAIT Wait until a condition is true or a period has elapsed WAIT [<condition>] [<period>] Wait for the specified condition to become true or for the specified period to elapse. If both a condition and a period are specified, the first to enter the desired state terminates the command. The period can be between 10.ms and s. WAIT 1.s WAIT Register(PC)==0x1000 WAIT!STATE.RUN() WAIT Register(PC)==0x s IF!Register(PC) ( PRINT %ERROR "Timeout" ENDDO ) ; wait for 1. second ; wait for the PC to become 1000H ; wait for the target to stop ; wait until PC is 1000H for max. ; one second ; if one second is over, display an ; error message and abort the script INKEY STOP WHILE Win PRACTICE Script Language Reference Guide 61 W... Z

62 WHILE Conditional program loop WHILE [<condition>] The command or program block following a WHILE statement will be executed as long as the condition is true. Emulators and debuggers have an counterpart of this command that works in the HLL syntax of the target program (command Var.WHILE). WHILE Register(d0)==0x0 ( Register.Set pc testprog Break testend Go ) ENDDO Var.WHILE flags[9]!=0 Step ENDDO ; HLL expression in condition NOTE: WHILE must be followed by a white space. RePeaT Var.WHILE WAIT Win FILE.EOF() FILE.EOFLASTREAD() STATE.RUN() Structure of PRACTICE Programs in Training Script Language PRACTICE Script Language Reference Guide 62 W... Z

63 WRITE Write to data file WRITE #<bufferno> <parlist> Save data in a data file. The syntax of the command is similar to the PRINT command. To try out this script, simply copy it to a test.cmm file, and then run it in TRACE32 (See How to... ). ;create a file in the temporary directory of TRACE32 and OPEN #1 ~~~/datafile.dat /Create ;open the file for writing &offset=0x2228 WHILE &offset<0x22c4 ( ;write data to file WRITE #1 "At Address " &offset " is Data " Data.Long(SR:&offset) &offset=&offset+1 ) CLOSE #1 TYPE ~~~/datafile.dat /LineNumbers ;close the file for writing ;optional: open file as read-only The path prefix ~~~ expands to the temporary directory of TRACE32. APPEND CLOSE OPEN READ Win WRITEB Release Information in Release History PRACTICE Script Language Reference Guide 63 W... Z

64 WRITEB Write binary data to file WRITEB #<bufferno> [%<format>] <data> <string> <format>: Byte Word Long BE LE Writes binary data to a file. The option /Binary for the OPEN command allows to open or create binary files. ;create a binary file in the temporary directory of TRACE32 and ;open the binary file for writing OPEN #1 ~~~/test.bin /CREATE /BINARY WRITEB #1 Var.VALUE(flags[0]) WRITEB #1 Var.VALUE(flags[1]) WRITEB #1 Var.VALUE(flags[3]) WRITEB #1 Var.VALUE(flags[4]) CLOSE #1 DUMP ~~~/test.bin ;write the values of a HLL variable ;to the binary file ;close the binary file for writing ;display a binary file in hex ;and ASCII format. CLOSE OPEN Win WRITE Release Information in Release History PRACTICE Script Language Reference Guide 64 W... Z