C++ Programmer's Guide to JSL

[#1]

Problem

You know some C++ and have some idea what a C++ object is and need the 20 minute intro to JMP's scripting language.

Solution

• There is a JMP scripting index on the Help menu. It describes, together or separately, Functions, DisplayBoxes, and Objects. As you dig deeper, use the search it provides.
• JSL does not have typed variables; there is not a way to declare a double, float, int, or bool. JSL variables hold whatever is assigned to them, usually a number, matrix, or list, but maybe a DisplayBox, Expression, Function, or Object.
• C language control structures for testing and looping (for, while, if) are very different from functions you can call in C. The for statement is something the C compiler understands, but the print statement is something the C runtime understands. JSL is different: the JSL for statement is actually a function, just like the JSL if and the JSL while statement. The function that does the JSL for statement is named "for" and it takes 4 arguments, separated by commas (as you'd expect a function to look).

for( icount = 1, icount <= 10, icount += 1, print( icount ); wait(1); );

• it looks similar to the C for loop, but those pesky comma/semicolon issues will get you a least once. Note the 4th argument is the JSL Expression that will be executed 10 times. Also note the loop starts at 1 and goes to <= 10. In C you'd almost certainly start at 0 and stop on < 10...sae number of iterations, but 0-based. JMP prefers 1-based; almost all of the indexing in JSL is 1-based (I've forgotten about FORTRAN.) The JSL if statement is a function named "if" and takes at least two arguments:

if( a < b
, // comma 
   print("a is less than b"); x=9;
, // comma 
   c < d
, // comma 
   print("c is less than d"); x=10;
, // comma 
   print("a is not < b and c is not < d"); x=11;
);
 

•  That if looks complicated only because it shows the full pattern the function accepts. You can stop anywhere after the 2nd argument. The JSL while statement is also a functiuon (named "while"), taking two arguments.
• Expressions are where JSL gets a lot of its power. An expression is a bit of JSL, perhaps the 4th argument to the for function or the 2nd argument to the while statement. If an expression is in a variable, it can be passed to a function, or it can be evaluated, or it can be inspected and maniplated. JSL has a function named "parse" that turns a string value into an expression.
• JSL matrices, lists, and associative arrays are high level container objects; often it will be an interesting design choice which to use, or whether to use a data table. Each has weaknesses and strengths for different jobs.
• The data table (or multiple tables) is an object you can use in JSL; you can process a single table with the forEachRow( expression ) statement (or function...everything is a function in JSL). With multiple tables you'll want to use JSL variables to refer to different data table objects and send them messages. JSL messages are sent to an object with the << send operator.

dt = open("$sample_data/big class.jmp");
dt << sort( by(height) );

•  the "sort" message, or method, is just one of many messages the data table knows how to handle. Remember the scripting index in point 1; it lists all the messages and usually has an example. The data table also processes requests to open platforms like Distribution. Think of JSL platforms like big useful subroutines that you can string together using the scripting language; your goal should be to get platforms to do the heavy lifting (since they are written in C++, they are very fast) and use JSL scripting just to orchestrate your presentation. (Don't write your own distribution graphs in JSL without a really good reason!)
• JSL's presentations, graphs, tables, output is built from nested DisplayBoxes that are usually displayed in a window. A DisplayBox is a special kind of object (and gets special treatment in the scripting index.) You can build custom displays from scratch, and you can use displays created from platforms (like Distribution). Many platforms have output in the displaybox tree that you can access by subscripting. 
• JSL has functions LoadTextFile and SaveTextFile that move entire files into memory/back to disk. There is no read/write a few bytes at a time.
• JSL has an include function that reads a file of JSL and executes it.
• JSL has user written functions, compiled by the "function" function.
• JSL has local variables that help, a lot, when writing large projects. By default variables are global, which is appropriate for tiny projects and one-of-a-kind tests, but the first time you reuse "i" in a nested loop, it might be time to look into local variables.

[bobmorrane]

A note on the Scirpting index: It is a very powerful tool indeed, with its integratd Scripting window and customisable examples.

But, what I found a bit difficult was the lack of a comprehensive syntax index. There is indeed one pdf book called the JSL syntax reference included in JMP but it is not 100% comprehensive. You can't always find the syntax for every argument of a function or message. You often have to go and use messages such as <<get properties and display that in the log.

I have a suggestion in the JMP wishlist for this, hopefully it gets some kudos.

[Craige_Hales]

Thanks! The scripting index is built from the same information that getProperties returns, and enhanced with examples for common cases. I also wish there were more examples. The language also has features that are not properties of objects which get better coverage in the book. JMP has gotten better over the last N releases about producing better messages in the log, sometimes including usage information as well. 

The documentation, technical support, and development teams would love to have your comments about anything that needs more/better/improved doc. Going through tech support will make sure it gets tracked.

@sheila_loring @shannon_conners @Wendy_Murphrey @XanGregg