Utility Functions

Add(a, b, ...)

a+b+...

Description

Adds the values of the listed arguments. No arguments are changed.

Returns

The sum.

Arguments

For Add(), a comma-separated list of variables, numbers, or matrices.

For a+b, any number of variables, numbers, or matrices.

Notes

Any number of arguments is permitted. If no argument is specified, Add() returns 0.

Add() returns missing if any arguments are missing. To ignore missing values, use Sum(). See Sum(var1, var2, ...).

See Also

List Operators and Functions in the Scripting Guide.

Beep()

Description

Produces an alert sound.

Returns

Null.

BLOB MD5(blob)

Description

Converts the blob argument into a 16-byte blob.

Note

The 16-byte blob is the MD5 checksum, or the hash, of the source blob.

BLOB Peek(blob, offset, length)

Description

Creates a new blob from a subrange of bytes of the blob argument.

Returns

A blob object.

Arguments

blob

a binary large object.

offset

An integer that specifies how many bytes into the blob to begin construction. The first byte is at offset 0, the second byte at offset 1.

length

An integer that specifies how many bytes to copy into the new blob, starting at the offset.

Build Information()

Description

Returns the build date and time, whether it’s a release or debug build, and the product name in a comma-delimited string.

Caption({h, v}, "text", <Delayed(seconds)>, <Font(font)>, <Font Size(size)>, <Text Color("color")>, <Back Color("color")>, <Spoken(Boolean)

Description

Displays a caption window at the location described by {h, v} that displays text. The caption can be delayed before being displayed by seconds, or can be spoken. You can also specify the font type, size, and color and background color.

Returns

Null.

Arguments

{h, v}

a list with two values. h is the horizontal displacement from the top left corner of the monitor in pixels. v is the vertical displacement from the top left corner in pixels.

text

A quoted string or a reference to a string that is to be displayed in the caption.

Delayed(seconds)

seconds is optional delay before displaying the caption. Setting this option causes this caption and all subsequent captions to be delayed by the specified number of seconds.

Font(font)

Specify the font type.

Font Size(size)

Specify the font size.

Text Color("color")

Specify the color of text.

Back Color("color")

Specify the background color.

Spoken(Boolean)

Causes text to be spoken as well as displayed. The current setting (on or off) remains in effect until switched by another Caption statement that includes a Spoken setting.

Datafeed()

See Open Datafeed().

Debug Break()

When the JSL Debugger is open, this function stops a JSL script from executing at that point in the script. This function is useful for tracking in the debugger under user-specified conditions. If the JSL Debugger is not running, this function does not execute.

Decode64 BLOB("string")

Description

Decodes a printable string of base 64 text into a blob.

Returns

A blob.

Arguments

string

a base 64 encoded string.

Example

Decode64 BLOB( "dGhlIHF1aWNrIGJyb3duIGZveA==" );

Char To BLOB( "the quick brown fox", "ascii~hex" )

Decode64 Double("string")

Description

Creates a floating point number from a base 64 encoded string.

Returns

A floating point number.

Arguments

string

a base 64 encoded string.

Divide(a, b)

Divide(x)

a/b

Description

Divides a by b. If only one argument is given (divide(x)), divides 1 by x.

Returns

The quotient of a/b; or the reciprocal of x (1/x) if only one argument is provided.

Arguments

a, b, x

Can be a variable, number, or matrix.

Notes

If both arguments are matrices, it does matrix division.

See Also

List Operators and Functions in the Scripting Guide.

Empty()

Description

Does nothing. Used in the formula editor for making empty boxes.

Returns

Missing.

Arguments

None.

Encode64 BLOB(x)

Description

Encodes a blob into a printable string of base 64 text.

Returns

A base 64 encoded string.

Example

Encode64 BLOB( Char To BLOB( "the quick brown fox" ) );

"dGhlIHF1aWNrIGJyb3duIGZveA=="

Encode64 Double(n)

Description

Creates a base 64 encoded string from a floating point number.

Returns

A base 64 encoded string.

Arguments

n

A floating point number.

Faure Quasi Random Sequence(nDim, nRow)

Description

Generates a sequence of spacefilling quasi random numbers using the Faure sequence.

Get Addin("id")

Description

Retrieves a registered add-in by id.

Returns

A scriptable object for the add-in. Returns empty if no add-in with the specified ID was found.

Argument

"id"

The ID of an installed add-in.

Get Addins()

Returns

A list of all registered add-ins.

Get Addr Info("address", <port>)

Description

Converts a name to its numeric address.

Returns

A list of strings. The first element is the command (Get Addr Info). The second is the results (for example, “ok” if the command was successful). The third is a list of strings of information. Included in that information is the address that corresponds to the name that was supplied.

Arguments

address

A quoted string that specifies the name (for example, "www.sas.com").

port

The port of the address.

Get Clipboard()

Description

Returns text from the computer’s clipboard. If the content is not text, the result is null.

Example

dt = Open( "$SAMPLE_DATA/Big Class.jmp" );

dt << Copy Table Script( "Distribution" );

s = Get Clipboard();

nw = New Window( "Script", Script Box( s ) );

Get Name Info("address", <port>)

Description

Converts a numeric address to its name.

Returns

A list of strings. The first element is the command (GetNameInfo). The second is the results (for example, “ok” if the command was successful). The third is a list of strings of information. Included in that information is the port name that corresponds to the address that was supplied.

Arguments

address

A quoted string that specifies the numeric address (for example, "149.173.5.120").

port

The port of the address.

Get Platform Preferences(<platform <(option, ...)> ... >)

Get Platform Preference(<platform <(option, ...)> ... >)

Description

Returns the preferences for the specified platforms.

Returns

A list of platform preferences.

Argument

platform

(Optional) Specifies the platform name. If not specified, all platform preferences are returned. You can specify one or more preferences for a platform.

option

(Optional) Specifies the preference value. If not specified, all platform preference values are returned.

Notes

Table 2.3 describes the syntax for getting platform preferences.

Examples

Suppose that the user modified several platform preferences through the JMP Platforms window or a script.

Platform Preferences(

	Distribution( Set Bin Width( 2 ), Horizontal Layout( 1 ) ),

	Model Dialog( Keep Dialog Open( 1 ) ),

	Graph Builder( Legend Position( "Bottom" ) )

);

To return all of the modified platform preferences, use Get Platform Preferences( <<Changed ):

Get Platform Preferences( <<Changed );

Platform Preferences(

Distribution( Horizontal Layout( 1 ), Set Bin Width( 2, <<On ) ),

Graph Builder( Legend Position( "Bottom", <<On ) ),

Model Dialog( Keep dialog open( 1 ) )

);

Get Preferences(<preference_name>)

Get Preference(<preference_name>)

Description

Returns the settings for the specified preferences.

Returns

A list of preference settings.

Argument

preference_name

(Optional) If no preference is specified, all preferences are returned. Otherwise, the settings for the specified preference are returned.

Notes

The preferences for the following areas are not accessible in JSL: Text Data Files, Windows Specific, Mac OS Settings, Fonts, Communications, Script Editor, and JMP Updates. For more information about getting platform preferences, see Get Platform Preferences(<platform <(option, ...)> ... >).

Glue(expr1, expr2, ...)

expr1; expr2

Description

Evaluates each argument in turn.

Returns

The result of the last argument evaluated.

Arguments

One or more valid JSL expressions.

Note

A semicolon placed between expressions is the more commonly used form for Glue().

Gzip Compress(blob)

Description

Compresses a blog of data into a gzip blob.

Example

Gzip Compress(

	Char To BLOB(

		"random data does not usually compress well and may get larger"

	)

);

Char To BLOB(

"~1F~8B~08~00~00~00~00~00~00~0A~0D~CA~C1~0D~00~21~08~04~C0V~B6~B5~CDA~FC~80~5C~00c~EC^~E7=~C9)~E1~106~21~A1~85~19~8DU~8Bf~07_~F8~9FZ~85~ADfx~13~CE~83~A1~0Dc~0E~CD~0B~94*~16~1E=~00~00~00",

"ascii~hex"

Gzip Uncompress(blob)

Description

Uncompresses a blob of gzip data into a blob.

Example

Gzip Uncompress( /*typically this data might come from Gzip Compress() but might also come from a .gz file using Load Text File() with the blob option*/

	Char To BLOB(

		"~1F~8B~08~00~00~00~00~00~00~0A~0D~CA~C1~0D~00~21~08~04~C0V~B6~B5~CDA~FC~80~5C~00c~EC^~E7=~C9)~E1~106~21~A1~85~19~8DU~8Bf~07_~F8~9FZ~85~ADfx~13~CE~83~A1~0Dc~0E~CD~0B~94*~16~1E=~00~00~00",

		"ascii~hex"

	)

);

Char To BLOB(

"random data does not usually compress well and may get larger",

"ascii~hex"

)

Host Is("argument")

Description

Determines whether the host environment is the specified OS.

Returns

True (1) if the current host environment matches the argument, false (0) otherwise.

Argument

Argument

Windows" or "Mac" tests for the specified operating system.

Is Alt Key()

Description

Returns 1 if the Alt key is being pressed, or 0 otherwise.

Note

On a macOS, Is Alt Key() tests for the Option key.

Is Command Key()

Description

Returns 1 if the Command key is being pressed, or 0 otherwise.

Is Context Key()

Description

Returns 1 if the Context key is being pressed, or 0 otherwise.

Is Control Key()

Description

Returns 1 if the Control key is being pressed, or 0 otherwise.

Note

On a macOS, Is Control Key() tests for the Command key.

Is Option Key()

Description

Returns 1 if the Option key is being pressed, or 0 otherwise.

Is Shift Key()

Description

Returns 1 if the Shift key is being pressed, or 0 otherwise.

JMP Product Name()

Description

Returns either "Standard", "Pro", or "Student", depending on which version of JMP is licensed.

JMP Version()

Description

Returns the version number of JMP that you are running.

Returns

release.revision<.fix>

Arguments

none

Load DLL("path" <,AutoDeclare(Boolean | Quiet | Verbose)>)

Load DLL("path" <, Quiet | Verbose>)

Description

Loads the DLL in the specified path.

Arguments

path

A pathname that specifies where to load the DLL.

AutoDeclare(Boolean | Quiet | Verbose)

Optional argument. AutoDeclare(1) and AutoDeclare(Verbose) write verbose messages to the log. AutoDeclare(Quiet) turns off log window messages. If you omit this option, verbose messages are written to the log.

Quiet | Verbose

Optional argument. When you use Declare Function(), this option turns off log window messaging (Quiet) or turns on log window messaging (Verbose).

See Also

Once a DLL is loaded, you send the DLL object messages to interact with it. See Dynamic Link Libraries (DLLs) in the JSL Messages section for more information about these messages. Dynamic Link Libraries (DLLs) in the Scripting Guide also includes examples.

Mail("address"|"addresses", "subject", "message", <"attachment filepath" | {"attachment 1 filepath", "attachment 2 filepath", ...}>)

Description

(Windows) Sends e-mail (using MAPI) to the address with the specified subject and message texts. Sends one or more attachments specified by the optional attachment argument. The attachment argument can evaluate to a string or list of strings.

(macOS) Creates an e-mail in the user’s Mail application. The user must click Send in the e-mail. In Microsoft Outlook, you must manually add attachments to the e-mail.

Examples

To send an email with multiple attachments on Windows:

Mail(

	"yourname@company.com",

	"New data and script",

	"Today’s updated data table and script are attached.",

	{"$DOCUMENTS/wd.jsl", "$DOCUMENTS/survey.jmp"}

);

or:

list = {"$DOCUMENTS/wd.jsl", "$DOCUMENTS/survey.jmp"};

Mail(

	"yourname@company.com",

	"New data and script",

	"Today’s updated data table and script are attached.",

	list

);

To send an email to multiple recipients:

Mail(

	{"hername@company.com", "hisname@company.com"},

	"Database updates",

	"Today’s sales database contains the numbers from last month."

);

Notes

On macOS, Mail() works on Yosemite and later operating systems.

Main Menu("string", <"string">)

Description

Execute the command found on JMP’s menu named by the quoted string.

Arguments

string

The internal path name as shown in the menu editor for items. For example, “NEW” is the internal name for the New subcommand in the File menu.

string

(Optional) The name of the window to send the command to.

Examples

Main Menu() accepts either a full path or a partial path. If a partial name is used, and there are other menu items with the same name, the first menu item found is executed. JMP searches the top-level menu (File, Tables, DOE, and so on) first for the partial name and then searches inside each of those menus in order.

Main Menu( "File:New:Data Table" ); // full path

Main Menu( "Data Table" ); // partial path

Minus(a)

-a

Description

Reverses the sign of a.

Returns

-a if a is positive (a=3; -a=-3; Minus(a)=-3).

a if a is negative (a=-3; -a=3; Minus(a)=3).

0 if a is 0 (a=0; -a=0; Minus(a)=0).

Missing if a is missing.

Argument

a

Can be variable or a number. A variable must contain a number or a matrix.

Multiple File Import(arguments)

Description

Imports one or more files into a data table. You can create this JSL by selecting Save Script to Script Window from the Multiple File Import window.

Returns

Creates a Multiple File Import Object. The object accepts messages to set a folder, filter files, and specify import options.

Arguments

<<Set Folder

Specifies the folder that contains the files you want to import.

<<Set Name Filter

(Optional) Specifies the file name or extension of the files. The name filter uses * to represent zero-or-more characters ? to represent exactly one character. * and ? also match a period. The default setting is *.*, or all files.

<<Set Name Enable(Boolean)

Enables the name filter. The setting is off by default.

<<Set Size Filter

(Optional) Filters the file list by file size. Specify the sizes by kB (kilobytes, or 1000 bytes) in a list. The default values are based on the size range of the files in the file list.

<<Set Size Enable(Boolean)

(Optional) Enables the size filter. The default setting is off.

<<Set Date Filter

(Optional) Filters the file list by date and time. Specify the date and time in a list in seconds. The default values are based on the date and time range of the files in the file list.

<<Set Date Enable(Boolean)

(Optional) Enables the date filter. The default setting is off.

<<Set Add File Name Column(Boolean)

(Optional) Includes a column that contains the imported file name. The default setting is off.

<<Set Add File Size Column(Boolean)

(Optional) Includes a column that contains the size of the imported file. The default setting is off.

<<Set Add File Date(Boolean)

(Optional) Includes a column that contains the time and date stamp of the imported file. The default setting is off.

<<Set Import Mode(Row Per File|Row Per Line|CSV Data)

(Optional) Specifies the format of the file that is imported: whole file on one row, one line on one row, and CSV. CSV Data is the default setting.

<<Set Charset(Best Guess|utf-8|utf-16|us-ascii|windows-1252|x-mac-roman|x-mac-japanese|shift-jis|euc-jp|utf-16be|gb2312)

(Optional) The character set in the imported file. The character set specified in the General preferences (Open Text File Charset) is set by default.

<<Set Stack Mode(Stack Similar|TablePerFile)

(Optional) Specifies how the files are combined. Stack Similar is the default setting. (When JMP detects that the files have the same columns, the files are concatenated into a single data table.)

<<Set CSV Has Headers(Boolean)

(Optional) Specifies whether the CSV file contains a header row. The setting is on by default.

<<Set CSV Allow Numeric(Boolean)

(Optional) Sets the data type to numeric. The setting is on by default.

<<Set CSV First Header Line(n)

(Optional) Specifies the header row number. 1 is the default setting.

<<Set CSV Number of Header Lines(n)

(Optional) Specifies the number of header rows. 1 is the default setting.

<<Set CSV First Data Line(n)

(Optional) Specifies the first line that contains data. 2 is the default setting.

<<Set CSV EOF Comma(Boolean)

(Optional) Specifies a comma delimiter. The setting is on by default.

<<Set CSV EOF Tab(Boolean)

(Optional) Specifies a tab delimiter.

<<Set CSV EOF Space(Boolean)

(Optional) Specifies a space delimiter.

<<Set CSV EOF Spaces(Boolean)

(Optional) Specifies spaces as the delimiter.

<<Set CSV EOF Other("")

(Optional) Specifies a custom delimiter.

<<Set CSV EOF CRLF(Boolean)

(Optional) Specifies carriage return and line feed end-of-line characters. The setting is on by default.

<<Set CSV EOF CR(Boolean)

(Optional) Specifies a carriage return end-of-line character. The setting is on by default.

<<Set CSV EOF LF(Boolean)

(Optional) Specifies a line feed end-of-line character.

<<Set CSV Semicolon(Boolean)

(Optional) Specifies a semicolon end-of-line character. The setting is off by default.

<<Set CSV EOL Other("")

(Optional) Specifies a custom end-of-line character.

<<Set CSV Quote("")

(Optional) Specifies the character used as a quote. The default setting is \!", a double quotation mark.

<<Set CSV Escape("")

(Optional) Specifies the escape sequence such as a backlash instead of doubling the quotation mark.

<<Import Data

Imports the data.

Example

mfi = Multiple File Import(

	<<Set Folder( "$SAMPLE_IMPORT_DATA" ),

	<<Set Name Filter( "UN*.csv" ), // import files with this name

	<<Set Name Enable( 1 ) // display the file name in a column

)

<<Import Data();

Multiply(a, b, ...)

a*b*...

Description

Multiplies all values. No arguments are changed.

Returns

The product.

Arguments

Any number of variables, numbers, or matrices.

Notes

Any number of arguments is permitted. If no argument is specified, Multiply() returns 1.

See Also

List Operators and Functions in the Scripting Guide.

Name("string")

Description

A name is something to call an item.

– If the name begins with an alphabetic character or underscore, and continues with alphanumeric characters, whitespace, Unicode mathematical symbols and certain punctuation (apostrophes, percentage signs, periods, backslashes, and underscores, then you can use the name directly in scripts.

– You can use names that do not follow these rules with the Name() keyword.

New OAuth 2 Token(user(yourgoogleaccount@gmail.com), client ID("string"), client secret("string"), refresh token("string"), token URL("string"))

Description

Creates an OAuth2 token for securely accessing data across different web APIs.

Arguments (Required)

user

The user name, email, or personal identifier for the account being accessed.

client ID

The public identifier that acts as an API key.

client secret

The private identifier that corresponds to Client ID.

refresh token

A token used to get access tokens.

token URL

The URL that access tokens are received from. Unique to every service and accessible through their API or OAuth page.

Arguments (Authorization Code Grant)

redirect URL( "https://app.getpostman.com/oauth2/callback" )

The URL that an access code is sent back to. Unless your company or the service provides one, we recommended that you create a free Postman account and use this redirect.

client secret( "1aB893cdDeFf2D" )

The private identifier that corresponds to Client ID.

request auth( ... )

Extra parameters indicating that you’ll use an Authorization Code flow. Requires Auth URL(). Some services require scope. You can add custom fields with Fields.

scope( "spreadsheets email docs" )

A space-separated list of scopes. Unique to every service, and accessible through their API or OAuth page. Only usable in Request Auth().

auth URL( "https://www.example.com/oauth2/v1/authorize" )

The URL for requesting authorization. Unique to every service, and accessible through their API or OAuth page. Only usable in Request Auth().

Arguments (Implicit Grant)

redirect URL( "https://app.getpostman.com/oauth2/callback" )

The URL that an access code is sent back to. Unless your company or the service provides one, it’s recommended to create a free Postman account and use this redirect.

Arguments (Resource Owner)

password( "wordpass123" )

The password that corresponds to the username.

client secret( "1aB893cdDeFf2D" )

The private identifier that corresponds to Client ID.

Arguments (Custom Data)

fields( fields )

Custom fields that are equivalent to HTTP Request’s Form( fields( fields ) ). Can be specified both in New OAuth2 Token() and in Request Auth(). Only necessary if the service requires information that is not defined in the OAuth 2.0 standard.

headers( headers )

Custom headers that are equivalent to HTTP Request’s Headers( headers ). Can only be specified in New OAuth2 Token(). Only necessary if the service requires information not defined in the OAuth 2.0 standard.

Example

token = New OAuth 2 Token (

	User( "yourgoogleaccount@gmail.com" ),

	Refresh Token( "1a2b3c4e5F" ),

	Token URL( "https://www.example.com/oauth2/token" ),

	Client ID( "12ab" ),

	Client Secret( "3456dEfG" )

);

Notes

• See your API documentation for more information about how to get values such as the client secret and token URL.

• See OAuth 2.0 for Web APIs in the JSL Syntax Reference for more information about OAuth 2.0.

Open Datafeed()

Datafeed()

Description

Creates a Datafeed object and window.

Returns

A reference to the Datafeed object.

Arguments

No arguments are required. You usually set up the basic operation of the data feed within the Open Datafeed() command, however.

Open Help("Help"|"Statistics Index"|"Scripting Index", ...)

Description

Opens the specified help window.

Parse XML("string", On Element("tagname", Start Tag(expr), End Tag(expr), Text))

Description

Parses an XML expression using the On Element expressions for the specified XML tags.

Example

XMLData =

"

<Book name='Foods'>All you want to know

       <Chapter num='1'>Fruit

             <kind>Apple</kind>

             <kind>Cherry</kind>

             <ps>I love dessert!</ps>

       </Chapter>

       <Chapter num='2'>Bread

             <kind>Wheat</kind>

             <kind>Corn</kind>

             <ps>I love sandwiches!</ps>

       </Chapter>

       <Chapter num='3'>Veggy

             <kind>Squash</kind>

             <kind>Cabbage</kind>

             <ps>I love anything else!</ps>

       </Chapter>

			and more.

</Book>

";

// variables are initialized so text can be concatenated

title = "";

subtitle = "";

chap = "";

chapnum = "";

ps = "";

Parse XML( XMLData,

      On Element( "Book",

            // capture the name attribute during the start of the Book

            Start Tag( title = XML Attr( "name" ) ),

            /* this book has split the subtitle and needs to join the text;

					the joined text will be used by endTag.

					Text(...) supplies the JSL.*/

            Text( subtitle = subtitle || " -- " || Trim( XML Text() ) ),

            /* after endTag processes the variables, set them back

					to their initial state, just in case there is a second book

					to process in the same XML. */

            endTag( Write( "\!n", title, " ", subtitle ); title = ""; subtitle = ""; )

      ),

      On Element( "Chapter",

            // capture the chapter number during the start of the Chapter

            Start Tag( chapnum = XML Attr( "num" ) ),

            /* the chapter text is joined together, newlines

					and extra space is trimmed, and a single space is used to

					separate the separated texts. The <kind> tag is ignored by

					this ParseXML specification. The <kind> text is processed

					by this Text(...) because it wasn't consumed by any other

					On Element. */

            Text( chap = chap || Trim( XML Text() ) || " " ),

            /* after endTag processes the variables, set them back to

					their initial state, because there is another chapter

					that needs to start with a clean slate.*/

            endTag( Write( "\!n", chapnum, " ", chap, " ps: ", ps ); chapnum = ""; chap = ""; ps = ""; )

      ),

      On Element( "ps", End Tag( ps = XML Text() ) )

);

1 Fruit Apple Cherry ps: I love dessert!

2 Bread Wheat Corn ps: I love sandwiches!

3 Veggy Squash Cabbage ps: I love anything else!

Foods -- All you want to know -- and more.

Platform Preferences(platform(option(value)), ...)

Platform Preference(platform(option(value)), ...)

Set Platform Preferences(platform(option(value)), ...)

Set Platform Preference(platform(option(value)), ...)

Description

Sets and resets values for platform options and turns the options on and off.

Arguments

platform

Specifies the platform of the preference.

option

Specifies the preference name.

value

Specifies the preference value.

Notes

Table 2.4 describes the syntax for setting platform preferences.

Example

The following expression selects (or turns on) Set Bin Width in the Distribution platform preferences and sets the value to 2:

Platform Preferences( Distribution( Set Bin Width( 2 ) ) );

The following expression changes the Set Bin Width value and turns the option off:

Platform Preferences( Distribution( Set Bin Width( 2, <<Off ) ) );

The following expression resets the default Set Bin Width value and deselects the preference:

Platform Preferences( Distribution( Set Bin Width( <<Default ) ) );

Polytope Uniform Random(samples, A, b, L, U, neq, nle, nge, <nwarm=200>, <nstride=25>)

Description

Generates random uniform points over a convex polytope.

Arguments

Samples

The number of random points to be generated.

A

The constraint coefficient matrix.

B

The right hand side values of constraints.

L, U

The lower and upper bounds for the variables.

neq

The number of equality constraints.

nle

The number of less than or equal inequalities.

nge

The number of greater than or equal inequalities.

nwarm

(Optional) The number of warm-up repetitions before points are written to the output matrix.

nstride

(Optional) The number of repetitions between each point that is written to the output matrix.

Note

The constraints must be listed as equalities first, less than or equal inequalities next, and greater than or equal inequalities last.

Preferences(pref1(value1), ...)

Preference(pref1(value1), ...)

Pref(pref1(value1), ...)

Prefs(pref1(value1), ...)

Set Preferences(pref1(value1), ...)

Set Preference(pref1(value1), ...)

Description

Sets preferences for JMP.

Arguments

Add Files Opened by Scripts to the Recent Files List(Boolean)

Determines whether a file that is opened by a script is added to the Home Window’s Recent Files list.

Analysis Destination(window)

Specifies where to route new analyses.

Annotation Font("font", size, "style")

Font choice for annotations in reports.

Axis Font("font", size, "style")

Font choice for axis labels.

Axis Title Font("font", size, "style")

Font choice for axis titles.

Background Color( {R, G, B} | <color> )

Sets the background color for windows.

Calculator Boxing(Boolean)

Turns on boxing to show hierarchy of expressions.

Conditional Formatting Rules

Creates rules for conditionally formatting text in reports. See Examples for an example.

Data Table Font("font", size, "style")

Font choice for data tables.

Data Table Title on Output(Boolean)

Titles reports with name of data table.

Date Title on Output(Boolean)

Titles reports with current date.

Disable JMP Server

Specifies a blacklist of JMP Public URLs that users cannot publish to. If a URL is in both the Disable JMP Server() and Enable JMP Server() lists, the URL is blacklisted. This preference must be added to jmpStartAdmin.jsl. The following is an example:

Preferences( Disable JMP Server( "\[

	{

		"http://public.jmp.com" // blacklists JMP Public

	}

	]\" )

);

See Run a Script at Start Up in the Scripting Guide for details about the location of jmpStartAdmin.jsl.

Enable JMP Server

Specifies a whitelist of JMP Public URLs that users cannot publish to. If a URL is in both the Enable JMP Server() and Disable JMP Server() lists, the URL is blacklisted. This preference must be added to jmpStartAdmin.jsl. The following is an example:

Preferences( Enable JMP Server( "\[

	{

		"http://public.jmp.com",

		"mysite.*"

	}

	]\" )

);

See Run a Script at Start Up in the Scripting Guide for details about the location of jmpStartAdmin.jsl.

Evaluate OnOpen Scripts("always"|"never"|"prompt")

Determines whether an On Open table script is run after the user opens the data table. By default, the user is prompted. Their choice is remembered each time they open the data table in the current JMP session. Scripts that execute other programs are never run.

Excel Has Labels(Boolean)

When on, forces JMP to interpret the first row of data as column headings.

Excel Selection(Boolean)

When on, the user is prompted for which non-blank Excel worksheets should be imported from an Excel workbook.

File Location Settings(<Directory Type>("<path>"<,"initial directory">))

Valid directory types are:

Data Files Directory Sets the default location for data files.

Help Files Directory Sets the default location for help files.

Installation Directory By default, this location is set to the JMP installation folder on Windows:

"C:/Program Files/SAS/JMP/15" or "C:/Program Files/SAS/JMPPro/15"

License File Path Sets the default location for JMP license file.

Preferences File Directory Sets the default location for the preferences settings file.

Save As Directory Sets the default location for Save As file operations.

Foreground Color(color)

Sets the foreground color for windows.

Formula Font("font", size, "style")

Font choice for the formula editor.

Graph Background Color(color)

Sets the color for the background area inside the graph frame.

Graph Marker Size(size)

Default size for drawing markers.

Heading Font("font", size, "style")

Font choice for table column headings in reports.

Initial JMP Starter Window(Boolean)

Specifies whether the JMP Starter window is shown at launch.

Initial Splash Window(Boolean)

Enables you to show or suppress the initial splash screen.

Maximum JMP Call Depth(size)

Sets the default for the maximum call depth (or stack size) for JMP in which JSL built-in functions, user-defined functions, or Recurse() function calls can be made. By default, the maximum call depth is set to 256KB.

Each thread that JMP creates has a 2MB stack by default. Increasing the maximum call depth can cause a physical runtime stack overflow, so incrementally increase this preference in small amounts until you find the best value that works for your JSL script.

Marker Font("font", size, "style")

Font choice for markers used in plots.

Monospaced Font("font", size, "style")

Font choice for monospaced text.

ODBC Suppress Internal Quoting(Boolean)

Prevents internal quoting in SQL statements that contain table and variable names with mixed case and spaces.

Outline Connecting Lines(Boolean)

Draws lines between titles for same-level outline nodes.

Print Settings(option(value), ... )

Changes print options on the Page Setup window:

Margins( <n>, <n>, <n>, <n>) sets the left, top, right, and bottom margins. Margins are in inches.

Margins(<n>) sets all margins to the same value in inches.

Orientation("portrait" | "landscape") changes the page’s print orientation.

Headers(<"char">, <"char">, <"char">) specifies text that appears in the left, middle, and right header.

Headers(<"char">) specifies the only text in the header.

Footers(<"char">, <"char">, <"char">) specifies text that appears in the left, middle, and right footer.

Footers(<"char">) specifies the only text in the footer.

Scale(<n>) decreases or increases the percentage at which the content prints.

Show Explanations(Boolean)

Some analyses have optional text that explains the output.

Show Menu Tips(Boolean)

Turns menu tips on or off.

Show Status Bar(Boolean)

Turns display of the status bar on or off.

Small Font("font", size, "style")

Font choice for small text.

Text Font("font", size, "style")

Font choice for general text in reports.

Thin Postscript Lines(Boolean)

macOS only. Specifies that line widths drawn to a Postscript printer be narrower than otherwise.

Title Font("font", size, "style")

Font choice for titles. Arguments are name of font (for example, "Times"), size in points, and style ("bold", "plain", "underline", "italic").

Use Triple-S Labels as Headings(Boolean)

When on, this argument forces JMP to interpret label names as column headings. Example: Pref(Name("Use Triple-S Labels as Headings")(0) ); turns off the preference.

Examples

The following expressions reset all preferences to their default values.

Preferences( "Default" );

Preferences( "Factory Default" );

The following script creates conditions for formatting text in reports.

Preferences(

    Conditional Formatting Rules(

        RuleSet(

				RuleName( "Warning" ),

				// if the value is not equal to 0, format the text as 80% gray

				NotEqualTo( Value( 0 ), Format( TextAlpha( 0.8 ) ) )

			 )

    )

);

Notes

The preferences for the following areas are not accessible in JSL: Text Data Files, Windows Specific, Mac OS Settings, Fonts, Communications, Script Editor, and JMP Updates. See Platform Preferences(platform(option(value)), ...) for information about setting platform preferences.

Register Addin("unique_id", "home_folder", <named_arguments>)

Description

Register a JMP Add-In and load the add-in if it registers successfully.

Returns

If successful, returns a scriptable object representing the registered add-in. If unsuccessful, returns Empty.

Arguments

unique_id

A quoted string that contains the unique identifier for the add-in. The string can contain up to 64 characters. The string must begin with a letter and contain only letters, numbers, periods, and underscores. Reverse-DNS names are recommended to increase the likelihood of uniqueness.

home_folder

A quoted string that contains the filepath for the folder containing the add-in files. The filepath must conform to the valid pathname requirement for the host operating system.

DisplayName( "name" )

An optional, quoted string that contains a name that can be displayed in the JMP user interface wherever add-in names are displayed, instead of the unique ID.

JMPVersion("version")

An optional string that contains a specific version of JMP. The default value is "All", which enables the add-in to be loaded and run in any version of JMP that supports add-ins. "Current" restricts the use of the add-in to only the current version. Any quoted version number (for example, "7" or "9") restricts the add-in to a single specific version of JMP.

LoadsAtStartup(Boolean)

An optional Boolean. The default value is True (1), which causes the add-in to be loaded when JMP is started. If the value is False (0), the add-in is not loaded automatically.

LoadNow(Boolean)

Loads the add-in immediately.

Note

If a file named addin.def is found in the specified home folder, values from that file are used for any optional arguments that are not included in the Register Addin() function.

Example

In the following example, the first argument is the unique identifier. The second argument identifies where the add-in is installed. The third argument is the name that appears where add-in names are displayed (for example, the View > Add-Ins menu on Windows).

Register Addin("com.company.lee.dan.MyAddIn","$DOCUMENTS/myaddin", displayname( "Calculator Addin" ));

The second argument becomes the $ADDIN_HOME path variable definition. When you refer to the add-in scripts, be sure to include a trailing slash after the path variable.

Include("$ADDIN_HOME(com.jmp.jperk.texttocols)/texttocols.jsl");

Revert Menu()

Description

Resets your JMP menus to factory defaults.

Run Program(Executable("path/filename.exe"), Options({"/a", "/b", "..."}), Read Function(expression), Write Function(expression), Parameter(expression))

Description

Runs the external program specified by the Executable argument, with the command line arguments specified by the Options argument.

Results

Returns either a string, a blob, or a Run Program object as controlled by the Read Function argument.

Arguments

Executable

The path to the executable. On macOS, type the full path to the executable.

Options

Command line arguments for the executable.

Read Function

If Read Function( "text" ) is specified, a text string is returned. If Read Function( "blob" ) is specified, a blob is returned. The script waits until the external program closes its stdout. Run Program then returns all data that the external program has written to its stdout as a string or a blob.

If Read Function is not specified, a Run Program object is returned.

Write Function

Optional argument that accepts a function as its value; it does not accept "text" or "blob".

Parameter

Optional argument to read and write the expression in Read Function.

Notes:

• Use global variables when Run Program() is inside a function.

• The Run Program object, which is returned if Read Function is not specified, accepts the following messages to read data from the external program’s stdout:

– <<Read: reads any available data as a string. If no data is available, an empty string is returned.

– <<Can Read: returns true if there is data available to be read.

– <<Is ReadEOF: returns true when the external program has completed and all its data has been read.

You can use these messages to poll for data and process the data as it is produced by the external program.

• A Run Program object accepts the following messages to write data to the external program’s stdin:

– <<Write( "text" ): sends data to the external program’s stdin.

– <<Can Write: returns true if the external program will accept data immediately; otherwise, calling <<Write causes your script to block.

– <<WriteEOF: signals to the external program that you are done sending data to it.

• Instead of sending messages to the returned Run Program object, you can specify the Read Function argument as an inline function. RP is the Run Program object.

RP = Run Program(

	Executable( ... ),

	Read Function(

		Function( {RP},

         <your code here>

			RP << Read

		)

	)

);

The Parameter(optParm) argument is optional in Read Function. If specified, the functions defined for Read Function and Write Function can receive a second argument, which is the value of optParm.

Examples

The following script is an example of the Write Function argument. RP is the Run Program object. In this context, it accepts the <<Write and <<WriteEOF messages.

RP = Run Program(

	Executable( ... ),

	Write Function(

		Function( {RP},

			<your code here>

			RP << Write( "Program finished." )

		)

	)

);

The following script shows an example of Parameter(optParm) argument:

RP = Run Program(

	Executable( ... ),

	Parameter( x ),

	Read Function( Function( {RP, optParm},... ) )

);

Within the Read Function, optParm contains the value of x. Do not attempt to access the optParm argument in your function if you have not specified a Parameter argument.

Schedule(n, script)

Description

Queues an event to run the script after n seconds.

Set Clipboard("string")

Description

Evaluates the "string" argument looking for a character result, and then places the string on the clipboard.

Example

Set Clipboard( "copy me" );

SetJVMOption( Version("<version number>") )

Description

Sets the Java Runtime Environment (JRE) version that you want JMP to use (rather than the version installed with JMP). This script must be run before JMP connects to the JRE.

Argument

version

(Windows only) In the Windows registry, there are two requirements for the JavaSoft/Java Runtime Environment key: the key must include a string called “RuntimeLib” that points to a valid jvm.dll. And the Java Runtime Environment key must include a key named after the quoted JVM version number.

Set Platform Preference()

Set Platform Preferences()

See Platform Preferences(platform(option(value)), ...).

Set Preference()

Set Preferences()

See Preferences(pref1(value1), ...).

Set Toolbar Visibility( "toolbar name" | default | all, window type | all, "true" | "false" )

Description

On Windows, shows or hides a toolbar based on the window type or for all windows.

Arguments

toolbar name | default | all

The internal name of the toolbar (see the View > Toolbars list in JMP), the default toolbar for the specified window type, or all toolbars. Include quotes around "toolbar name".

window type | all

Data table, script, report, journal, or all windows.

true | false

Quoted string that shows or hides the toolbar.

Shortest Edit Script( A, B )

Shortest Edit Script( strings( A, B, <matrix( 0|1 )>, <limit( number )> ) )

Shortest Edit Script( lines( A, B, <matrix( 0|1 )>, <limit( number )>, <separators( characters )>, <ignore( characters )|ignore white space( )> ) )

Shortest Edit Script( sequences( nA, nB, Function( {iA, iB}, adata[iA] == bdata[ib] ) ) )

Description

Compares two strings, lines, or sequences.

Returns

Returns a list or a matrix of edit commands. The simplest form returns a list. strings and lines return a matrix (if set to 1) or a list. sequences returns a matrix.

There are three possible commands: common data in both strings, delete data from the first string, and keep data from the second string.

Optional Strings Arguments

matrix

Indicates whether the returned value is a matrix.

limit

Stops the evaluation when the edit list exceeds the specified number of inserted or deleted items. Two random strings have a lot of common characters in a lot of distinct sections. The function runs for a long time trying to find a best match. limit stops the function sooner.

Optional Lines Arguments

matrix

Indicates whether the returned value is a matrix.

limit

Stops the evaluation when the edit list exceeds the specified number of inserted or deleted items. Two random strings have a lot of common characters in a lot of distinct sections. The function runs for a long time trying to find a best match. limit stops the function sooner.

separators

A character that separates words.

ignore

Ignores the specified spaces or characters in a line.

ignore white space

Ignores white space in a line.

Optional Sequences Argument

Function

A user-defined function.

Examples

The following example compares two strings with three common sequences of characters between them.

Shortest Edit Script( "abcdef", "abdezgh" );

{{"Common", "ab"}, {"Remove", "c"}, {"Common", "de"}, {"Insert", "zgh"}, {"Remove", "f"}}

The following example examines each line in string aa and bb:

aa = "this is

a test of

shortest

edit script

lines with several words";

bb = "this is

a test 2 of

shortest

edit ?., script

lineswithseveral words";

Shortest Edit Script( lines( aa, bb, separators( "\!n" ),

	// quote and newline separators

	ignore( "?., " ) ) ); // ignore these characters and spaces

{{"Common", "this is // lines in aa and bb contain "this is"

"}, {"Remove", "a test of // only on line 2 of aa

"}, {"Insert", "a test 2 of // only on line 2 of bb

"},

{"Common", "shortest

edit script

lines with several words"}}

// lines in aa and bb contain "shortest", "edit script", and "lines with several words"

For more information, see Identifying Differences Between Strings, Lines, or Sequences in the Scripting Guide.

Show Addin Builder Dialog()

Description

Opens a window in which you can make custom add-ins.

Show Addins Dialog()

Description

Opens the Add-In Status window (View > Add-Ins).

Arguments

None.

Show Commands()

Description

Lists scriptable objects and operators. Arguments are All, DisplayBoxes, Scriptables, Scriptable Objects, StatTerms, Translations.

Show Preferences(<"all">)

Description

Shows current preferences. If no argument is specified, preferences that have been changed are shown. If "all" is given as the argument, all preferences are shown.

Show Properties(object)

Description

Shows the messages that the given object can interpret, along with some basic syntax information.

Sobol Quasi Random Sequence(nDim, nRow)

Description

Generates a sequence of space-filling quasi random numbers using the Sobol sequence in up to 4000 dimensions.

Socket(<STREAM | DGRAM>)

Description

Creates a socket.

Returns

The socket that was created.

Arguments

STREAM | DGRAM

Optional argument to specify whether the socket is a stream or datagram socket. If no argument is supplied, a stream socket is created.

Speak(text, <wait(Boolean)>)

Description

Calls system’s speech facilities to read aloud the text. If Wait is turned on, script execution pauses until speaking is done.

Status Msg("message")

Description

Writes the message string to the status bar.

Subtract(a, b)

a-b-...

Description

Subtracts the values of the listed arguments, left to right. No arguments are changed.

Returns

The difference.

Arguments

Two or more variables, numbers, or matrices.

Notes

Two or more arguments are permitted.

See Also

List Operators and Functions in the Scripting Guide.

Unregister Addin("unique_id")

Description

Unregisters (removes) a previously registered add-in.

Argument

unique_id

A quoted string that contains the unique identifier for the add-in to unregister.

Web("string", <JMP Window>)

Description

Opens the URL stored in string in the default web browser.

The http:// prefix in the URL is optional.

Examples

url = "www.jmp.com"; // open the URL in the default web browser

Web( url );

Web( "www.jmp.com" ); // open the URL in the default web browser

Web( "www.jmp.com", JMP Window ); // open the URL in the JMP browser window

XML Attr("attr name")

Description

Extracts the string value of an xml argument in the context of evaluating a Parse XML command

XML Decode("xml")

Description

Decodes symbols in XML to ordinary text. For example, &amp; becomes &, and &lt; becomes <.

Argument

xml

A quoted string containing XML.

XML Encode("text")

Description

Prepares text for embedding in XML. For example, & becomes &amp;, and < becomes &lt;.

Argument

xml

A quoted string containing plain text.

XML Text()

Description

Extracts the string text of the body of an XML tag in the context of evaluating a Parse XML command.

Want more information? Have questions? Get answers in the JMP User Community (community.jmp.com).