JMP® Scripting Guide

Release 7

Scripting Guide “The real voyage of discovery consists not in seeking new landscapes, but in having new eyes.” Marcel Proust

JMP, A Business Unit of SAS SAS Campus Drive Cary, NC 27513

JMP Scripting Guide, Release 7 Copyright © 2007, SAS Institute Inc., Cary, NC, USA ISBN 978-1-59994-412-8 All rights reserved. Produced in the United States of America. For a hard-copy book: No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, or otherwise, without the prior written permission of the publisher, SAS Institute Inc. For a Web download or e-book: Your use of this publication shall be governed by the terms established by the vendor at the time you acquire this publication. U.S. Government Restricted Rights Notice: Use, duplication, or disclosure of this software and related documentation by the U.S. government is subject to the Agreement with SAS Institute and the restrictions set forth in FAR 52.227-19, Commercial Computer Software-Restricted Rights (June 1987). SAS Institute Inc., SAS Campus Drive, Cary, North Carolina 27513. 1st printing, May 2007 JMP®, SAS® and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. ® indicates USA registration. Other brand and product names are registered trademarks or trademarks of their respective companies.

Contents JMP Scripting Guide 1

Tutorial and Examples See for yourself what JSL can do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Hello, World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Modify the script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Save your script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Save your log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Saving and sharing your work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Capturing scripts for data tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Capturing scripts for analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 A general method for creating scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Use JMP interactively to learn scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Samples of JSL Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Data table programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Customized analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Custom displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Matrix algebra with JSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Scripting graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Scripting instructional simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2

Elements of JSL Learn the basic components of JSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . First JSL script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The JSL language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lexical rules of the language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Context: meaning is local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programming vs. scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data table context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scoping operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Graph context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locking Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27 29 29 30 35 35 38 38 38 39 40 40 40

ii

Name-binding rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Frequently-asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function resolution rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the JSL Editor and Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The JSL Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The JSL Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3

41 43 44 44 44 49

Programming Basics Learn how to use the basic elements of JSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Numeric operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Numeric operators not found in the formula editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Character functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Comparison and logical operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Date/time operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Inquiry functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Programming functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Programming example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Gluing expressions together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Iterating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Conditional functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Throwing and catching exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Stopping manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Recursion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Local variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Loading and Saving Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 XML Parsing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Pattern Matching and Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Dynamic Link Libraries (DLLs) (Windows Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Main Menu Commands (Windows Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Lists and expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Stored expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Manipulating lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Manipulating expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Associative arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Associative Array Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

iii

4

Utilities Communicating with users and JMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Communication between JMP and users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Communicating with users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting information about objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructing modal dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General-purpose modal dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data column dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details common to Dialog and Column Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Personalizing JMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

127 129 129 132 135 136 137 140 142 144 144 145

Data Tables Create, open, and manipulate data tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data table basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting a data table object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Objects and messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Messages for data tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Naming, saving, and printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Journal and Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and deleting columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summarize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commands from the Rows menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commands from the Tables menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manipulating columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting and getting attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Row State operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What are row states? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . An overview of row state operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Each of the row state operators in detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Optional: the numbers behind row states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pre-evaluated statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calculator formulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

147 149 149 152 156 156 156 157 159 162 165 169 173 177 180 186 186 190 194 201 202 202 203

Contents

Graph Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

iv

6

Scripting Platforms Create, repeat, and modify analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scripting analysis platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Launching platforms interactively and obtaining the equivalent script . . . . . . . . . . . . . . . . . . Sending script commands to a live analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Launching platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . By-group columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Objects within analysis objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General messages for platform windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scripting specific platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7

Displays Create and navigate results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manipulating displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction to display boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DisplayBox object references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Platform example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructing display trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Updating an existing display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Text Wrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interactive Display Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Send messages to constructed displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Build your own displays from scratch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Construct display boxes containing platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Construct a custom platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Journals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8

205 207 207 212 215 217 219 219 220 246

249 251 251 254 255 257 260 262 262 265 266 267 277 278 278 280 282

Graphical Scripting Create and edit 2-dimensional plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding scripts to graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a legend to a graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating new graphs from scratch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Graphing elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Plotting functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting properties of an graphics frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Drawing lines, arrows, points, and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

285 287 288 288 289 289 293 293 294

v

9

302 303 304 305 305 306 307 307 309 310 312 312 313

3-D Scenes Scripting Three Dimensional Scenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About JSL 3-D Scenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JSL 3-D Scene Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scene Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Viewing Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up a Perspective Scene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting up an Orthographic Scene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Translate Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Rotate Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Look At Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The ArcBall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Graphics Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Primitives Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling the Appearance of Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other uses of Begin and End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Drawing Spheres, Cylinders, and Disks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Drawing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Text with Rotate and Translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Matrix Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lighting and Normals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Light Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lighting Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Normal Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

315 317 317 317 320 321 322 322 322 322 324 325 327 329 331 337 337 337 338 338 339 340 342 343 344 344

Contents

Adding text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fill patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Line types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Drawing with pixels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interactive graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MouseTrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Drag functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Picture Display Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Log (Windows and Linux) or Window > Log (Macintosh). Note that the Macintosh command won’t be enabled until something is written to the log. 3 In the JMP Starter window, click New Script. New scripts can also be created from the menus. On the Macintosh, hold Shift while selecting File > New Script. On Windows and Linux, select File > New > Script.

4 In the resulting script window, which is a script editor, type these lines: A="Hello, World"; Show(A);

5 From the Edit menu, select Run Script. Shortcut: press Control-R on Windows and Linux or a-R on Macintosh.

1 Tutorials and Examples

Hello, World

3

4

Tutorial and Examples Hello, World

Chapter 1

The result should show in a Log window. This window is also a script editor.

This is how you enter and submit JSL. You have just created a global variable, A, assigned a value to it, and shown its value. Notice that the log echoes your script first, and then echoes any results—in this case, the output for the Show(A) command. Go To Line As your scripts grow in size, it is handy to jump to specific lines in the script. Use the Go To Line command from the Edit menu to jump to a specific line. This command is also useful during the debugging process, since error messages frequently mention the line of the script where the error occurred.

Chapter 1

Tutorial and Examples Hello, World

5

Now try making this script do a little more work by adding a For-loop to greet the world not just once but four times. Also, Print this time instead of Show, and make a few other changes to see how the For-loop works. 1 In the script window, change the script to this: for(i=1, i? vehicleType; // conditional assignment ONLY if pattern matches if( patMatch( "Take this bus.", p ), show(vehicleType), print("no match") ); // don't use vehicleType in the ELSE because it is not set

You could pre-load vehicleType with a default value if you don’t want to check the outcome of the match with an if. The >? conditional assignment operator has two arguments, the first being a pattern and the second a JSL variable. >? constructs a pattern that matches the pattern (1st argument) and stores the result of the match in the JSL variable (2nd argument) after the pattern succeeds. Similarly, >> doesn’t wait for the pattern to succeed. As soon (and as often) as the >> pattern matches, the assignment is performed. findDelimString = patLen(3)>>beginDelim + patArb()>?middlePart + expr(beginDelim); testString = "SomeoneSawTheQuickBrownFoxJumpOverTheLazyDog'sBack"; rc = PatMatch( testString, findDelimString, "" ); show( rc, beginDelim, middlePart, testString );

The above example shows a third argument in the patMatch function: the replacement string. In this case, the replacement is formed from a concatenation ( || operator) of three strings; one of the three strings, middlePart, was extracted from the testString by >?, which was appropriate because the replacement can’t occur unless the pattern match succeeds (rc == 1). Look at the pattern assigned to findDelimString. It is a concatenation of 3 patterns. The first is a >> operator that matches 3 characters and assigns them to beginDelim. The second is a >? operator that matches an arbitrary number of characters and, when the entire match succeeds, assigns them to middlePart. The last is an unevaluated expression, consisting of whatever string is in beginDelim at the time the pattern is executing, not at the time the pattern is built. Just like expr(), the evaluation of its argument is postponed. That makes the pattern hunt for two identical three letter delimiters of the middle part. Other pattern functions may be faster and represent the problem you are trying to solve better than writing a lot of alternatives; for example, "a"|"b"|"c" is the same as patAny("abc"). The equivalent example for patNotAny("abc") is much harder. Similar to patSpan (above), patBreak("0123456789") will match up to, but not including, the first number.

3 Programming Basics

You define and use pattern variables just like any JMP variable:

106

Programming Basics Programming functions

Chapter 3

Here's a pattern that matches numbers with decimals and exponents and signs. It also matches some degenerate cases with no digits; look at the pattern assigned to digits. digits = patSpan("0123456789") | ""; number = ( patAny("+-") | "" ) >? signPart + ( digits ) >? wholePart + ( "." + digits | "" ) >? fractionPart + ( patAny("eEdD") + ( patAny("+-") | "" ) + digits | "" ) >? exponentPart; if( patMatch( "-123.456e-78", number ), show( signPart, wholePart, fractionPart, exponentPart ) );

Sometimes data is in fixed fields. The patTab, patRTab, patLen, patPos, and patRPos functions make it easy to split out the fields in a fixed field string. PatTab and patRTab work from the left and right end of the string and take a number as their argument. They succeed by matching forward to the specified tab position. For example: p = patPos(10) + patTab(15); PatPos(10) matches the null string if it is in position 10; so at match time, the matcher works its way forward to position 10, then patTab(15) matches text from the current position (10) forward to position 15. This pattern is equivalent to patPos(10)+patLen(5). Another example: p = patPos(0) + patRTab(0);

This example matches the entire string, from 0 characters from the start to 0 characters from the end. the patRem() function takes no argument and is shorthand for patRTab(0); it means the remainder of the string. Pattern matching can also be anchored to the beginning of the string like this: patMatch( "now is the time", patLen(15) + patRPos(0), NULL, ANCHOR );

The above pattern uses NULL rather than a replacement value, and ANCHOR as an option. Both are uppercase, as shown. NULL means no replacement is done. ANCHOR means the match is anchored to the beginning of the string. The default value is UNANCHORED. Patterns can be built up like this, but this is not recursive: p = "a" | "b"; // matches one character p = p + p; // two characters p = p + p; // four characters patMatch( "babb", patPos(0) + p + patRPos(0) );

A recursive pattern refers to its current definition using expr(): p = "" | "x"; patMatch( "", patPos(0) + p + patRPos(0) );

Remember, expr() is the procrastination operator; when the pattern is assigned to the variable p, expr() delays evaluating its argument (p) until later. In the next statement, patMatch performs the pattern match operation, and each time it encounters expr(), it looks for the current value of the argument (which, in this example, does not change during the match). So, if p is defined in terms of itself, how can this possibly work? p consists of two alternatives. The right hand choice is easy: a single letter x. The left side is harder: . Each p could be a single letter x, since that is one of the choices p could match, or it could be . (missing). The last few example have used patPos(0) + ... + patRPos(0) to make sure the pattern

Chapter 3

Programming Basics Programming functions

107

This example uses “Left” recursion: x =

expr(x) + "a" | "b"; // + binds tighter than |

If the pattern is used in FULLSCAN mode, it will eventually use up all memory as it expands; but, by default, the patMatch function is not using FULLSCAN and makes some assumptions that allow the recursion to stop and the match to succeed. The pattern matches either a “b”, or anything the pattern matches followed by an “a”. rc = patMatch( "baaaaa", x );

Dynamic Link Libraries (DLLs) (Windows Only) JSL can load a DLL and call a function exported by that DLL. There is one JSL command and two messages that implement this functionality: LoadDLL(pathToDLL) LoadDLL loads the DLL indicated by pathToDLL. CallDLL(exportedFcn, signatureOfFcn, argumentToFcn) The CallDLL message gets the proc address of exportedFcn from the DLL and then casts the fproc with a signature matching signatureOfFcn according to the Table 3.22 “signatureOfFct values,” p. 107 table shown here:

Table 3.22 signatureOfFct values signatureOfFcn

parameter to exportedFcn is of type

“v” “c” “n”

void string int

Then, it calls the fproc, passing in argumentToFcn as an argument to fproc. UnLoadDLL(void)

Finally, the UnLoadDLL message unloads the DLL. The following code snippet shows how to use these functions. // Load the DLL, given the specified path dll = LoadDLL("D:\Release\MyDLL.DLL"); // Call the function inside the DLL named MyExportedFcn. // This function takes one numeric as input and in this case, // the value of the input parameter is to be 654. dll Fit Y by X dialog box myChart=Chart(); // Graph->Chart dialog box

Whenever JMP encounters a script to launch a platform that lacks column assignments and column assignments are required for the platform, it produces the platform’s launch dialog box to get column assignments but continues with the script—that is, JMP does not wait for answers, as in the case of Open, Summary, and other modal dialog boxes. See the chapter “Scripting Platforms,” p. 205, for more about launching platforms. Using the pick dialogs You can prompt the user to pick a file or directory using the Pick File and Pick Directory commands. Both bring up a platform-specific dialog box that allows the user to navigate to a file (or directory) and store the path as a string. The Pick Directory command has an optional string that is presented as the prompt message.

Chapter 4

Utilities Dialog boxes

137

To obtain a list of file names in a specified directory, use the Files In Directory command. listOfFileNames = Files In Directory(path);

To obtain the full path names, use the concat operator. listOfFilePaths = path||Files In Directory(path);

The Files in Directory command accepts native and POSIX paths, as well as paths using path variables. It does not recurse by default, but does have an optional recursive argument. main_samples = Files In Directory (“$SAMPLE_DATA”); {“Abrasion.jmp”, “AdverseR.jmp”, “Alcohol.jmp”, ...”} all_samples = Files In Directory(“$SAMPLE_DATA”, recursive); {..., “Templates/Polar Coordinates.jsl, “Therm.jmp, “Time Series/ Air.jmp...}

General-purpose modal dialog boxes Inside the Dialog function’s parentheses, you can use any of its named arguments to create a user interface for setting values for variables. A bare bones dialog box might request a value for one variable. Dialog( "Set this value", variable=EditNumber(42), Button("OK"),Button("Cancel"));

Notice that the argument to EditNumber is the default value, 42. Also notice that a dialog box without at least one Button makes no sense, so JMP adds a button if you script a Dialog without one.

If you click OK, the list {variable=42,Button(1)} is returned and the script continues. If you click Cancel, the dialog is dismissed, it returns {Button(-1)}, and the script continues. See “Throwing and catching exceptions,” p. 98 in the “Programming Basics” chapter, if you need a way to cancel out of a script. In addition to Edit Number, you can use Edit Text, Radio Buttons, Check Box, Combo Box, and List Box.

4 Utilities

path = Pick Directory (); path = Pick File();

138

Utilities Dialog boxes

Chapter 4

List Boxes accept several kinds of arguments, including strings, names, literal lists, or globals containing lists. The following examples all result in the dialog box shown here. //---arguments as strings dlg = Dialog("Select Names", vlist( selection=listBox("KATIE", "LOUISE", "JANE", "JACLYN", "LILLIE", "KIRK", "LAWRENCE"), button("OK"))); //result is list of strings: {selection = {"LOUISE", "JACLYN"}, Button(1)} //---arguments as names dlg = Dialog("Select Names", vlist( selection=listBox(KATIE, LOUISE, JANE, JACLYN, LILLIE, KIRK, LAWRENCE), button("OK"))); //result is list of names: {selection = {LOUISE, JACLYN}, Button(1)} //---arguments as literal list dlg = Dialog("Select Names", vlist( selection=listBox({KATIE, LOUISE, JANE, JACLYN, LILLIE, KIRK, LAWRENCE}), button("OK"))); //---arguments as global containing list names = {KATIE, LOUISE, JANE, JACLYN, LILLIE, KIRK, LAWRENCE}; dlg = Dialog("Select Names", vlist( selection=listBox(names), button("OK")));

The next example is more elaborate and takes advantage of each type of dialog box element, all nicely arranged. Dialog( HList( VList( "Radio Frequency Embolism Projection", Lineup(2, "Lower Spec Limit", lsl=EditNumber(230), "Upper Spec Limit", usl=EditNumber(340), "Threshold", threshold=EditNumber(275)), HList( VList( "Type of Radio", type=RadioButtons("RCA", "Matsushita", "Zenith", "Sony")), VList( "Type of Antenna", antenna=RadioButtons( "Dish","Helical","Polarizing","Radiant Array"))),

Chapter 4

Utilities Dialog boxes

139

Clicking OK without changing any of the default choices returns this list: {lsl = 230, usl = 340, threshold = 275, type = 1, antenna = 1, synch = 0, title = "My projection", quality = 1, Button(1)}

The title of a dialog box can be set by adding a Title() statement to the Dialog() constructor. So, for example, Dialog( Title("Hello World"), Button("OK"), Button("Cancel"));

produces a dialog box with “Hello World” in the title bar. You can use 0, points[CurrentPoint,ix] = ortholeft; points[CurrentPoint,iy] = orthobottom; makepatch(); ); );

Chapter 9

ix, iy }, // ix,iy are the index of the the points matrix (x/boxwide) * (orthoright-ortholeft) + (y/boxhigh) * (orthotop-orthobottom) +

There are a pair of 2D functions and a pair of 3D functions. The first function is for clicking (mouse button is down) and the second is for tracking (mouse button is up). 2D functions are called before 3D functions. When a 2D function is called, the arguments are X, Y, M, K. • X and Y are the coordinates of the mouse. • M shows the state of the mouse and button. M=0 says the mouse button is up. M=1 says the button was just pressed. M=2 says the button is down and the mouse is moving. M=3 says the button was just released. • K is related to the keys Shift, Alt, and control. K=1 for the Shift key, K=2 for the Control (command) key, and K=3 for the Alt (Option) key. The 3D function is called similarly. The arguments are X, Y, M, K, hitlist, where hitlist is a list of matrices [znear, zfar, id1, id2, id3, ...] znear, zfar is the Z distance from the camera of the near and far edge of the object. The matrices are sorted from near to far by the midpoint of znear, zfar. The ids in the list are the pushname, loadname, and popname values you just put in the display list.

The drag functions use a return value to tell if mouse processing should continue. That’s the trailing “1” you see in the functions. Anything else stops the mouse tracking. This is needed because the 2D and 3D functions do not run in parallel. You might want the 2D to return 0 and the 3D to return 1 so the tracking would happen in 3D rather than 2D. Pick Commands This SceneBox callback gets 2D mouse coordinates, then uses pick to determine the “named” object under the mouse. For example, hitlist is a 5x5 pixel pick box around x,y; up to 1000 items returned, but just the leaf names. The format of the return is determined by the last parameter (1 returns a simple array, 0 returns a sorted (by depth) list of arrays) Track2d=function({x,y,m,k}, hitlist = theSceneBox