The PRAXIS Script Writers' Page

updated 6 August, 2004

What are PRAXIS Scripts all about?

How do PRAXIS Scripts work?

How are Scripts developed?

How are Scripts installed and stored?

Script Writing Tips

Some common pitfalls to avoid in Script development

Script Debugging Tools and Tips

A Script Writing Tutorial Example (pdf format, "LC Meter" project)

Problems?


NEW INFO -- Bug warning for PRAXIS SCRIPTS written in DelphiScript!:

  A bug has been discovered in more advanced Scripts which use multiple forms.  Examples of these would include the "Measurement Guides" script and the "AudioPass" QC Script.  It turns out that if any non-main script form (a form that is created graphically by the script, using the script designer) accesses another non-main script form, then the memory for that form is not freed on leaving PRAXIS, and this can cause error messages on closing or other strange memory-related effects.  The "Main" script form is the first one that is created (shown) when your script starts-- the first one you create when you begin writing a script.  If you are starting with an existing script, it will be the one that has its tab on the far left or the far right.  It will be the form that has the "Initscript" method!

TO WORK AROUND THIS BUG:  In your scripts, have all communication or reference between script forms go through the Main script form.  For example, if a secondary script form called "FormTwo" needs to do something with another secondary script form called "FormThree", then you should write a procedure in "FormOne" (the Main Form, in this example, that exists in the Unit "MainUnit") that does the action on FormThree, and call this FormOne procedure from FormTwo.  If you were wanting to close FormThree from FormTwo, you would do it like this:

In FormOne, write a procedure (make sure it is declared in the FormOne's type definition)::

Procedure TFormOne.MakeFormThreeClose;
Begin
    FormThree.Close; //note: do reference this procedure by the form's name, 
                                  //because the procedure method is an
                                  //automatically created event handler!
End;

Then, in FormTwo call:

MainUnit.MakeFormThreeClose; //note: reference this by the UNIT name, because 
                                          //the procedure was not automatically created by the script
                                          //designer application! ("MainUnit", not "FormOne")

Do that instead of trying to call "FormThree.Close" directly from within FormTwo!  Note that in other units, you must call procedures that were not automatically created, by using the UNIT name (not the form name).  Automatically created event handlers are called using the form name; other procedure use the Unit name, even if those procedures are methods of the form.  (This is another oddity of DelphiScript that is different than actual Delphi).

Also, make sure that the secondary forms reference ONLY the main form in their "uses" clause (or by using the Useunit procedure).

In short, the secondary units should not directly reference or use objects or code in each other's units, but instead do all inter-form accesses by calling procedures in the Main Form.

Sorry for any difficulties this may have caused Script Writers!  It is an obscure bug, in the Dream Scripter component, which we are unable to fix.


 

What are PRAXIS Scripts all about?

There are many audio measurement tools that can provide basic measurement functions: send an impulse! record a voltage waveform! perform a Fourier Transform! plot a spectrum!... etc. . With these basic functions, evaluation and analysis of audio and vibrational systems is possible...at least in principle.

But real-world audio measurements are more than just the resulting numbers or graphs.  They are, in reality,  processes. They involve numerous settings, adjustments, decision points, and often require mathematical  manipulations and graphic presentation of the acquired data results.  Each measurement is actually an experiment and an interpretation, and the value of the result is directly dependent on your ability to intelligently define and control the vast number of parameters and conditions for each test. 

And while handling all these details may appeal to an engineer's intellectual curiosity, often the more practical requirement is to have a repeatable test that can be executed efficiently and can provide clearly interpreted results.  An engineer on a schedule needs to repeat or even automate measurements to work efficiently.  

Some end users want to be shielded entirely from the technical process and would really prefer something like this: 


(note for gullible readers: that is a joke..)

PRAXIS Scripts are a powerful way to define and reuse measurement processes, to automate complicated processes,  to extend the capabilities of the Praxis system, and to simplify procedures for use by others.

PRAXIS comes with a number of scripts already included in its installation.  Some of these automate common measurements (such as extraction of Thiele/Small parameters or Room Acoustic measurements).  Some provide on-screen guidance or tutorials to help you manually configure and perform measurements.  Some illustrate features of the PRAXIS system, and others can be used for diagnostics.  The code for these scripts can be easily inspected or modified using the Liberty Script Designer.

You can also develop your own custom scripts from scratch with the Liberty Script Designer application (included with PRAXIS, and accessible even in "Free Demo" mode), to easily create your user interface and to write code to control the operation of PRAXIS.

How do PRAXIS Scripts work?

PRAXIS Scripts typically consist of form files (*.dfm) which detail properties of your user interface forms, and Code files (*.pas or *.vbs) which contain the instruction code that tells the computer what to do.  

Your code and forms control the computer (and the PRAXIS measurement system) from within the PRAXIS program itself.  The operations occur as if they were built-in features of PRAXIS, and the script executes between procedure calls within PRAXIS.  "Event handlers" can be defined within your script so that they are called when PRAXIS encounters certain events during its operation.

Nearly all operations of PRAXIS and most commands of the Delphi language (including operating system "API" calls) can be commanded by a script.  You could even, if you wanted, write Windows programs that have little to do with PRAXIS other than being executed from within it -- file editors, movie viewers, etc.  

Script execution utilizes a component, called "Dream Scripter", that is built into PRAXIS.  Dream Scripter is a Delphi component developed by Dream Company (www.dream-com.com/index.html) that can interpret Script code (and pre-compiles it, in the case of DelphiScript) from within host programs.  The Liberty Script Designer application (included with PRAXIS installation), which you can use to author or modify scripts, was adapted from another Dream Company product called "Instant Report".

When you execute a script (starting it from PRAXIS' "Script Launcher" form), Dream Scripter displays the forms and controls of the form files, executes any initialization instructions defined in the script code, and passes control back to PRAXIS main code.  When the user operates those controls on the script's form , Dream Scripter executes the script code that is associated with those controls on the scripts' forms and again passes control back to PRAXIS main code.   Dream Scripter also links certain events (such as completion of an Acquisition, or drawing of a plot) within PRAXIS to named code blocks, if they exist within the script, so that those procedures can occur in response to operating events within PRAXIS.  This is the means by which script code can synchronize with PRAXIS's progress during complicated measurement procedures.

How are Scripts developed?

The Script code can be written in DelphiScript (a modified subset of the Borland Delphi language, based on Pascal) or in VBScript (a scripting language based on Microsoft Visual Basic).  Scripts could also be written in other Active Scripting languages (JavaScript, Perl, Python).  Because both PRAXIS and DREAM SCRIPTER are written in Borland Delphi, DelphiScript is the preferred language for script development.  DelphiScript code can also be expected to execute somewhat more quickly and smoothly than that of other scripting languages.

The Form files are designed graphically in the Liberty Script Designer environment (see the illustration at the top of this page), mostly using point, click and drag operations with the mouse.  The Liberty Script Designer also provides the editors for developing the script code and to integrate the form files with the script code.  For example, if you put a button on a form that your are designing, and click on it during the design process, the Liberty Script Designer will paste into the Script code a skeletal block for you to add instructions that are to be followed when the mouse is clicked during execution of your script.

The most efficient way to create a script is usually to start with a script that is similar to the one you wish to create, copy that script's files to another subdirectory, and then modify it to suit your requirements.  If you use the menu option for a New Script in the Liberty Script Designer, you will be given the option to start you script from a copy of another.  Or you can start yours script from an automatically constructed template pre-loaded with PRAXIS event handlers or controls for a 'Wizard' format.

How are Scripts installed and stored?

Each PRAXIS script is installed into its own separate subdirectory.  If you want your new script to be listed in the Script Launcher (and to be easily selectable from there), create the new subdirectory directly under one of these directories:
      ...\Program Files\Praxis\VCLscripts (for use with the AudPod)
              or
      ...\Program Files\Praxis\DemoScripts (for use in Free/Demo mode)

If you want the PRAXIS Script Launcher to display a description of your script, create a "Rich Text File" (rtf)  using the Windows Accessory application "Word Pad" and describe your script in the text of this file.  Save the file under the name "Description.rtf",  in your new script's directory.  You can open this for editing from within the Script Designer (see its "Tools" menu).

If you want the PRAXIS Script Launcher to display a small picture for your script, create a bitmap picture with the Windows Accessory application "PaintBrush".  The picture should have a width of less than 150 pixels and height of less than 100 pixels, and should be stored under the name "Picture.bmp", in your new script's directory.  You can open this for editing from within the Script Designer (see its "Tools" menu).

The easiest way to begin creation of a new script  is to use the "New PRAXIS Script" option in the Script Designer (which allows you to copy from an existing script, or to generate a script template complete with PRAXIS event handlers, or with a handy Wizard Format).  Use the "Edit Script Description" and "Edit Script Picture" menus (under "Tools") to set up how your script appears in the Launcher.

To distribute your script to other users or computers (or install one that was shared by another user, or on a different computer of yours), use the "Zipped Script" menu options that are given under the Scripts menu of PRAXIS' main form.

Script Writing Tips

Some common pitfalls to avoid in Script development

1) Never have your code Wait!  Because the script runs from within PRAXIS,  you should avoid using script operations during PRAXIS data acquisition that may prevent PRAXIS from servicing the soundcard A/D and D/A converters in a timely manner.  In particular,  you cannot wait within script code for something to happen before proceeding further -- because if your script waits, so does the entire PRAXIS system, preventing PRAXIS from doing anything else!  Instead, use "Event Handlers" to respond to (rather than to wait for) events.

This "not waiting" requirement also affects the debugging process.  If you debug using "ShowMessage" popup windows or breakpoints of  the Dream Script Debugger, you must avoid having such "breakpoints" occur at any time during which you need to maintain data acquisition.  Breakpoints and ShowMessage operations cause the script, and PRAXIS, to wait for the operator.   PRAXIS won't crash, but acquisition will stop with a "speed error" when PRAXIS again gets control.  A better debugging strategy is to use the Script Debug Form logging commands.

2) Backup Your Settings and be careful!  While the power of PRAXIS Scripting is a good thing, there is also a "dark side": a script is entirely capable of crashing the PRAXIS program or even the operating system!  For example, executing a DelphiScript line like:

k:=0; While k<10 do;

Will lock-up both your script and Praxis (remember, they both run as if they were the same program)!  Always save your PRAXIS settings if they are important to your script's operation, before trying out a new script or before testing changes within a script.  Also, use of the Windows2000 or WindowsXP operating systems will make crash recovery less painful than in Windows98 or WindowsME.

3) Explicitly identify Properties and Methods of Objects. Objects are programming entities that combine code or programming items that relate together.  For example, from the viewpoint of a script, "Praxis" is an object that has many Properties (settings or other objects) and Methods (commands) associated with it.  One of Praxis' Properties is "PrimaryPlot", which also has many Properties and Methods of its own.  If you need to refer to, for instance, the "HorizontalStart" property of the PrimaryPlot, write it out as, for example:

Praxis.PrimaryPlot.HorziontalStart := 100;

Although the Delphi "with..do" construction is supported in Praxis Scripts, its use is NOT RECOMMENDED because the scripter can become confused and will merely bail temporarily out of your code (without even informing you!) if it thinks it sees an object identifier that it can't resolve.  Avoid code like this:

with Praxis do                      
begin                                     
   UnitsMetric:=true;           
   InputSampleRate:=48000;
end;                                       

Instead, use this type construction:

Praxis.UnitsMetric:=true;  
Praxis.InputSampleRate:=48000;

Remember -- if you refer to an Object method, variable or property that doesn't exist, you probably won't get an error message.  Instead, the scripter will likely just jump out of your procedure.  (Also, be aware that many of the scripts shipped with PRAXIS do use the "with..do" construction -- because they were written before this glitch was identified).

4) Beware of Mismatched Begin/End pairs.  "Begin" and "End" are the ubiquitous block identifiers in Pascal (and Delphi) code.  But the scripter does not check to make sure that their numbers are matched.  If you should have more Begins than Ends (or more Ends than Begins), your script will fail to execute, and the scripter will give you rather confusing error messages.  Should you ever find that the script won't run and the messages make no sense, check to make sure your Begin and End usage is equal!

5) Avoid global variables, procedures and Functions.  Make all Procedures and Functions into Form Object Methods. And all Variables into Object Variables --this will be less confusing to the script interpreter and will be able to be "seen" from other procedures and functions.  But be sure to use different names for the  methods (procedure or method) or variables for each form type -- assume each variable behaves as if it were global.

Also, notice that in scripts, you can NOT define properties for your objects or forms (however,  you CAN read or write the properties that are already defined within PRAXIS or in Delphi's VCL).

6) All references to PRAXIS and its objects are unknown to the script when the script is first created.  Because of this, do not try to use the Praxis object or its methods or properties in the "FormCreate" method of your script.  If you need to set properties of (or to control) PRAXIS when the script is first started, do this in the "InitScript" event handler which is called when your script is ready to deal with PRAXIS objects.

7) Event handlers should be procedures of your main script form, not global procedures.  For example, the event handler that is called after PRAXIS begins script execution is called "InitScript".  This should be implemented as a method of your main script form, so if your main script form is "Form1", then implement the event handler as:
       Procedure TForm1.InitScript(Sender:TObject);
       begin
         //handler code goes here
       end;

8) If you use multiple forms in your script, call "UseUnit" in the FormCreate procedure of each of them to notify each form of the others' existence.  Otherwise your code in your forms cannot use entities in other forms.  Example:

procedure TForm1.FormCreate(Sender: TObject);
begin
  UseUnit('Diagram.pas'); //needed so that the form code
                     //in "Diagram.pas" is known from Form1
  UseUnit('LevAdj.pas');  //needed so that the form code
                    //in "LevAdj.pas" is known from Form1
end;

9) Remember to save your Script (using "Save All"), after changes, before launching it within PRAXIS! PRAXIS can only use the version that is in the last saved disk file, and it can't see the text or forms that are only in the Liberty Script Designer.  This may seem obvious, but it is a common "gotcha" (because it is different from using Delphi, in which you don't normally need to explicitly save your files before testing them).

Script Debugging Tools and Tips

Problems?

If the Liberty Script Designer will not run on your system:

We have had a report that the Liberty Script Designer application will not run within a Hebrew Language version of Windows XP.   But the following workaround was found to be successful:

Liberty Script Designer was adapted from a program called "Instant Report", developed by Dream Company.  In fact, Liberty Script Designer is essentially a stripped-down version of Instant Report.  A number of controls were removed from the palette, and ability to run scripts from within the environment was disabled.  These were removed to avoid confusion from controls that would be unlikely to be useful in measurements and which might cause speed problems.  Also, PRAXIS commands could not be executed from within that environment, so the "run" option would not be helpful.

But you can use Instant Report to develop your PRAXIS Scripts, just as if it were the Script Designer.  And, Instant Report does run in that Hebrew version of XP which (for unknown reasons), will not run our Script Designer!  You can download Instant Report from this link.