File Functions

Copies one file to a new file using the same or a different name.

Returns 1 if the file is copied; otherwise, returns 0.

Specifies the path and file name to copy to the new file.

from path

to path

Specifies the path and file name for the new file.

Create Database Connection( (string, <DriverPrompt(1)>) | "Connect Dialog");

Creates a connection to the specified database or prompts the user to provide database log in information.

A handle to the database connection.

The server connection string that contains information such as the data source name and user name.

string

Driver Prompt

An optional Boolean argument that enables the ODBC driver to prompt for the connection information if necessary.

"Connect Dialog"

A string that opens the Select Data Source window, from which the user selects the database.

Examples

Specify the data source name, user name, and password:

Create Database Connection( "dsn=Books;UID=johnsmith;password=Christmas" );

Request that the ODBC driver prompt the user to enter connection information, because the connection string does not specify the password:

Create Database Connection( "dsn=Books;UID=johnsmith", Driver Prompt( 1 ) );

Enable the user to select the data source, specify "Connect Dialog":

Create Database Connection( "Connect Dialog" );

Create Directory("path")

Creates a new directory at the specified path location.

Returns 1 if the directory is created; otherwise, returns 0.

Specifies the path where the new directory should be located.

Creation Date("path")

Returns the creation date for the specified file or directory.

Specifies the directory or path and file name for the query.

Delete Directory("path")

Deletes the specified directory and its contents and any subdirectories.

Returns 1 if the directory is deleted; otherwise, returns 0.

Specifies the path and directory for deletion.

Delete File("path")

Deletes the specified file.

Returns 1 if the file is deleted; otherwise, returns 0.

Specifies the path and file name for deletion.

Directory Exists("path")

Verifies the specified directory exists.

Returns 1 if the directory exists; otherwise returns 0.

Specifies the path and directory for verification.

File Exists("path")

Verifies the specified file name exists at the specified path.

Returns 1 if the file exists; otherwise returns 0.

Specifies the path and file name for verification.

Files In Directory(path, <"recursive">)

Returns a list of filenames in the path given.

An optional quoted keyword that causes all folders in the path (and all folders that they contain, and so on) to be searched for files.

List of filenames. If "recursive" is not specified, directory names are included in the list.

Get Current Directory()

See Set Current Directory("path").

Retrieves the current directory, which is used in the Open File window. Note: The operating system can change the current directory outside of JMP. The function is deprecated. On Macintosh and Windows, the initial current directory is the user’s Documents folder. Previously, Windows returned the folder that contained jmp.exe or the working folder set by the operating system when JMP is launched.

–

If JMP was opened using the JMP shortcut, the function returns the JMP Installation directory. For example, on Windows, the current directory is "/C:/Program Files/SAS/JMPPRO/13/" or "/C:/Program Files/SAS/JMP/13/".

–

If JMP was opened by double-clicking a JMP file (.jmp, .jsl, .jrn, and so on), the command returns the path of the opened file.

–

If the current directory was configured using the Set Current Directory() function, JMP returns the specified path.

The absolute pathname as a string.

none

Get Default Directory()

Retrieves the user’s default directory. This path is used for subsequent relative paths.

If the default directory was set using Set Default Directory(), JMP returns the specified path as long as Get Default Directory() and Set Default Directory() are in the same script.

See Set Default Directory("path").

The absolute pathname as a string.

Get Excel Worksheets("absolute path")

none

Retrieves a list of worksheets that are in the specified Microsoft Excel workbook. If no worksheets are found, an empty list is returned.

The function supports .xlsx and Excel 1997 or later workbooks.

Get File Search Path()

Retrieves the current list of directories to search for opening files.

This list is configured using the Set File Search Path() function. See Set File Search Path({path or list of paths}).

A list of pathnames as strings.

Get Path Variable("name")

Retrieves the value of name, a path variable.

The absolute pathname as a string.

Argument

name

A quoted string that contains a path variable. (Examples: SAMPLE_DATA, SAMPLE_SCRIPTS)

Is Directory(path)

Returns 1 if the path argument is a directory and 0 otherwise.

Is Directory Writable(path)

Returns 1 if the directory specified in the path argument is writable and 0 otherwise.

Is File(path)

Returns 1 if the path argument is a file and 0 otherwise.

Is File Writable(path)

Returns 1 if the file specified in the path argument is writable and 0 otherwise.

Is Log Open()

Returns a Boolean value that indicates whether the log window is open.

Last Modification Date("path")

Returns the last modification date of the specified file or directory.

Last modification date.

Specifies the directory or file name.

Load Text File(path, <arguments>)

A pathname that points to a text file. The path can be a URL.

Reads the text file at path into a JSL variable.

Charset

Optional argument that determines the character set. Arguments include the following:

–

"best guess" attempts to detect the character set.

–

force("throw"|"alert"|"silent") is an optional argument that determines what happens if the character set cannot be detected.

Line Separator("character")

Optional argument that specifies the end-of-line character. For example, "\!n" specifies a line feed character. "\!t" specifies a tab.

XMLParse

Optional argument that converts an XML file into JSL.

SASODSXML

Optional argument that parses the text file as SAS ODS default XML.

BLOB(<arguments>)

Optional argument that returns data from the file as a blob rather than a string. The following optional arguments are for reading parts of the file:

–

ReadOffsetFromBegin(n) specifies the zero-based offset to begin reading from the beginning of the file.

–

ReadOffsetFromEnd(n) specifies the zero-based offset to begin reading from the end of the file.

–

ReadLength(n) specifies the number of bytes to read from the file, either from the beginning of the file or from one of the offset values.

–

Base64Compressed(0|1) specifies how the blob is converted to a printable representation. 0, the default and recommended setting, uses JMP’s ASCII~HEX representation. 1 means the blob is compressed and converted to base 64 when printed.

Move Directory("from path", "to path")

Moves a directory and its contents (including subdirectories) from the specified path to another specified path.

Returns 1 if the directory is moved; otherwise returns 0.

Specifies the path and directory for relocation.

from path

to path

Specifies the destination path and directory.

Move File("from path", "to path")

Moves a file from the specified path to another specified path with the same or different file name.

Returns 1 if the file is moved; otherwise returns 0.

Specifies the path and file name for relocation.

from path

to path

Specifies the destination path and file name.

On Windows, when you move a file to a folder that does not exist, Windows creates the folder and returns 1. On Macintosh, the folder is not created, and an error is returned.

Open("path", <arguments>)

Opens the data table or other JMP file or object created from a file named by the path. If no path is specified, the Open window appears. Also opens JSON and HDF5 files. Refer to the examples in the JMP Scripting Index for details about which arguments apply to specific file types.

Add to Recent Files(Boolean)

Determines whether the file is added to the Recent Files list in the Home Window.

Charset("option")

The available character set options for importing text files are Best Guess, utf-8, utf-16, us-ascii, windows-1252, x-max-roman, x-mac-japanese, shift-jis, euc-jp, utf-16be, and gb2312.

Column Names Start(n) | Column Names are on line(n)

Specifies the line number that column names start in the imported text file. If the text file uses returns between cells, column names could be on multiple lines.

Columns(colName = colType(colWidth),...)

Specifies the columns by name in the text file to import into a data table where:

–

colName: Specifies the column name used in the imported text file.

–

colType(Character | Numeric): Indicates whether the specified column contains character or numeric data.

–

colWidth(n): indicates the integer width of the specified column.

Columns(<arguments>)

For ESRI shapefiles (.shp), this argument and its settings indicate the following:

–

Shape=numeric(n): Indicates the column number in the imported ESRI shapefile that contains the shape number.

–

Part=numeric(n): Indicates the column number in the imported ESRI shapefile that contains the part number.

–

X=numeric(n): Indicates the column number in the imported ESRI shapefile that contains the decimal degree for the longitude (range of ±180°).

–

Y=numeric(n): Indicates the column number in the imported ESRI shapefile that contains the decimal degree for the latitude (range of ±90°).

Compress Allow List Check(Boolean)

Indicates that JMP can compress data table created from the imported text file.

Compress Character Columns(Boolean)

Indicates that JMP should compress data table columns that contain character data from the imported text file.

Compress Numeric Columns(Boolean)

Indicates that JMP should compress data table columns that contain numeric data from the imported text file.

Concatenate Worksheets(Boolean)

Indicates that JMP should combine the imported Excel worksheets into one data table.

Create Concatenation Column(Boolean)

Indicates that JMP should combine columns from an imported Excel file into one column.

Data Starts(n) | Data Starts on Line(n)

Specifies the line number where data starts in the imported text file.

Debug JSL(Boolean)

Opens the specified JSL script in the Debugger instead of opening it.

Specifies the character used to delimit the end of a field in the imported text file. To specify multiple characters, separate each character designation by a comma. If you use “Other”, designate the delimiter with EOF Other() argument.

End Of Line(CRLF|CR|LF|Semicolon|Other)

Specifies the character used to delimit the end of a line in the imported text file. To specify multiple characters, separate each character designation by a comma. If you use “Other”, designate the delimiter with EOL Other() argument.

EOF Other("char")

If the imported text file uses an end of field character other than the one specified by End of Field, this argument specifies the character used.

EOL Other("char")

If the imported text file uses an end of line character other than the one specified by End of Line, this argument specifies the character used.

Excel Wizard

Opens Microsoft Excel worksheets in the Excel Import Wizard. If you omit this argument, the worksheets open directly as a data table.

File Type

An optional string that specifies the type of file that you are opening (for example, xls, bmp, jpg, or gif). If you do not specify this string, the file opens in the default program for the file type.

Note: The path argument should be used for a zip archive. The extension (.zip) is not required. See Zip Archives in JSL Messages for the messages that you can send to a zip archive. The basic functionality is to get a list of files in the zip archive, to read a file in the zip archive into either a string or a blob, and to write files into the zip archive. Note that reading a zip archive temporarily puts the contents into memory. Reading very large zip archives can cause errors.

Force Refresh

Closes the specified JMP (.jrn, .jsl, .jrp, or .jmpappsource) file without saving and tries to reopen the file from disk. This argument deletes any changes made since the last time the file was opened.

HTML Table(n, ColumnNames(n), DataStarts(n))

To import a table from an HTML web page, use the URL as the filepath. The optional n argument specifies which table number, n, on the web page to open. If you omit the value, only the first table on the page is imported. The optional ColumnNames(n) specifies the row that contains column names. The optional DataStarts(n) specifies the row on which the data begins.

Tip: If the table you are importing contains images, they are first imported as text. To load the images in your JMP data table, run the automatically generated table script named Load Pictures. A new expression column containing the images is created. See Expression Role in the Using JMP book for details about expression columns.

Ignore Columns( "col", ... )

Indicates the column names in the JMP data table or other JMP file that should not be included in the data table.

Invisible

Opens the file as invisible. This quoted keyword applies to the files: data table, JMP file, external, text, Excel, SAS, ESRI shapefile, or HTML. The data table appears only in the JMP Home Window and the Window menu.

Labels(Boolean)

Indicates the imported text file contains labels or column headers as the first line in the file. The default value is True.

Lines to Read(n)

Specifies the number of lines in the text file to import. JMP starts counting lines after column names are read.

Number of Columns(n)

Specifies the number of columns contained in the imported text file.

Run JSL(Boolean)

Runs the specified JSL file instead of opening it. Include a Boolean argument or an expression that contains a Boolean value. If the script begins with //!, which automatically runs the script, include the Boolean value (0) to open the script instead.

Password( "password" )

Specifies the password for a password-protected SAS file to avoid entering it manually. The password is not encrypted. (Password-protected Microsoft Excel files cannot be imported.)

Private

Opens the table as invisible and without showing it in the JMP Home Window or Window menu. For example, you might create a private data table to hold temporary data that the user does not need to see. This quoted keyword applies to the following files: data table, JMP file, external, text, Excel, SAS, ESRI shapefile, or HTML.

Scan Whole File(Boolean)

Specifies how long JMP scans the text file to determine data types for the columns. This is a Boolean value. The default value is true; the entire file is scanned until the data type is determined. To import large files, consider setting the value to false, which scans the file for five seconds.

Select Columns( "col", ... )

Indicates the column names in the JMP data table or other JMP file that should be included in the data table.

Strip Quotes | Strip Enclosing Quotes (Boolean)

If the fields in the text file are quoted, setting this to True removes the quotes, and setting it to False does not remove the quotes. The default value is True.

Table Contains Column Headers (Boolean)

Indicates the imported text file contains labels or column headers as the first line in the file. The default value is True.

Text Wizard

Opens the text file in the text import window, where you can select import options. Otherwise, the Text Data Files options in the JMP preferences apply, and the text file is automatically imported as a data table.

Treat Empty Columns as Numeric(Boolean)

Indicates that JMP should import text file columns of missing data as numeric rather than character. Possible missing value indicators are a period, a Unicode dot, NaN, or a blank string. The default value is False.

Use Apostrophe as Quotation Mark(Boolean)

Declares apostrophes as quotation marks in importing text files. This option is not recommended unless your data comes from a nonstandard source that places apostrophes around data fields rather than quotation marks. The default value is False.

Use Labels for Var Names(Boolean)

For SAS data sets, this option specifies to use SAS labels as JMP columns names. The default value is False.

Use for all sheets(Boolean)

Indicates that JMP should use the Worksheets settings for all worksheets in the Excel file to be opened as a data table.

Worksheet Settings(Boolean, <options>)

Specifies options for importing an Excel file into a JMP data table. Available options are:

–

Has Column Headers(Boolean) - Indicates the Excel file has column headers in the first row.

–

Number of Rows in Headers(n) - Specifies the number of rows in the Excel file used as column headers.

–

Headers Start on Row(n) - Specifies the row number in the Excel file where the column headers begin. Default is row 1.

–

Data Starts on Row(n) - Specifies the row number in the Excel file where the data begins.

–

Data Starts on Column(n) - Specifies the column number in the Excel file where the data begins.

–

Data Ends on Row(n) - Specifies the row number in the Excel file where data ends.

–

Data Ends on Column(n) - Specifies the column number in the Excel file where the data ends.

–

Replicated Spanned Rows(Boolean) - Indicates the Excel file contains spanned columns that should be imported into JMP as spanned columns.

–

Suppress Hidden Rows(Boolean) - Indicates that JMP should not import rows hidden in the Excel file.

–

Suppress Hidden Columns(Boolean) - Indicates that JMP should not import columns hidden in the Excel file.

–

Treat as Hierarchy(Boolean) - Indicates that JMP should treat multiple column headers (merged cells) as hierarchies when importing an Excel file. If True, the Excel file opens with the merged columns stacked (Tables > Stacked).

Worksheets ("sheet name"|{"sheet name", "sheet name",...}|”n”)

Opens the specified Excel file worksheet by name, all worksheets in a list of names, or the indexed number of the worksheet. If the worksheets are not specified, all worksheets in the spreadsheet open as separate data tables.

Year Rule | Two digit year rule ("1900-1999"|"1910-2009"|"1920-2019"|"1930-2029"|"1940-2039"| "1950-2049"|"1960-2059"|"1970-2069"|"1980-2079"|"1990-2089"|"2000-2099")

Indicates the year format used in the imported text file. For example, if the earliest date is 1979, use “1970-2069”.

Open Database("connectInfo" "sqlStatement", "outputTableName")

Pick Directory(<"prompt">, <path>, <Show Files>)

Opens the database indicated by connectInfo with the sqlStatement, returning a data table named outputTableName.

Prompts the user for a directory, returning the directory path as a string.

The path for the directory that the user selects.

An optional quoted string. If provided, that string appears at the top of the Browse window on Windows.

prompt

path An optional quoted string that specifies the initial directory that appears in the Pick Directory window.

Show Files (Boolean) Specify 1 to show files in the Pick Directory window, or zero to hide files. The default is zero.

Pick File(<"prompt">, <"initial directory">, <{filter list}>, <first filter>, <save flag>, <"default file">), <multiple>

Prompts the user to select one or more files in the Open window.

The path of the file that the user selects.

An optional quoted string. If provided, that string appears at the top of the Open window.

prompt

initial directory

An optional quoted string that is a valid filepath to a folder. If provided, it specifies where the Open window begins. If not provided, or if it’s an empty string, the JMP Default Directory is used.

filter list

An optional list of quoted strings that define the filetypes to show in the Open window. See the following example for syntax.

first filter

An optional integer that specifies which of the filters in the filter list to use initially. If you use an integer that is too large or small for the list (for example, 4 for a list of 3), the first filter in the list is used.

save flag

An optional Boolean that specifies whether the Open window or Save window is used. 0 lets the user select a file to open in JMP. 1 lets the user save a new, empty file of the selected type in the selected folder. The default value is 0.

default file

The name of the file that appears in the window by default.

multiple

An optional argument that lets the user select multiple files if the save flag is 0.

Although all arguments are optional, they are also positional. For example, you cannot specify a filter list without also specifying the caption and the initial directory.

The buffer size in the computer’s physical memory affects the number of files the user can open.

Example

The following script assigns Select JMP File as the window title; shows the JMP Samples/Data directory; shows JMP Files and All Files in the File name list and selects JMP Files; displays the Open window; and shows the sample data file name Hollywood Movies.jmp.

Pick File(

	"Select JMP File",

	"$SAMPLE_DATA",

	{"JMP Files|jmp;jsl;jrn", "All Files|*"},

1,

0,

	"Hollywood Movies.jmp"

);

Rename Directory("old path name", "new directory name")

Renames a directory without moving or copying it.

Returns 1 if the directory is renamed; otherwise, returns 0.

Specifies the path and old directory name.

old path name

new name

Specifies the new directory name.

Rename File("old path name", "new name")

When you specify the new directory name, include only the directory name, not the entire path.

Renames a file without moving or copying it.

Returns 1 if the file is renamed; otherwise, returns 0.

Specifies the path and old file name.

old path name

new name

Specifies the new file name.

Save Text File(path, text)

When you specify the new name, include only the file name, not the entire path.

Saves the JSL variable text into the file specified by path.

Set Current Directory("path")

See Get Current Directory().

Sets the current directory for Open File operations. Note: The operating system can change the current directory outside of JMP. The function is deprecated. Setting the current directory saves or returns the new value for backwards compatibility though the value is not used.

To avoid having to set the current directory for each file operation, define a filepath string and concatenate it with the filename. See the Path Variables section in the Scripting Guide for details.

Set Default Directory("path")

Sets the default directory, which is used for resolving relative paths.

See Get Default Directory().

Set File Search Path({path or list of paths})

Sets the current list of directories to search for opening files. Using {"."} as the path configures JMP to use the current directory.

See Get File Search Path().

Example

Set File Search Path( {"C:/JMP/13/source", "C:/Program Files/SAS/JMPPRO/13/Samples"} );

Set Path Variable("name", <value>)

Sets the path stored in the variable.

The name of the variable.

name

value

The path.

TripleS Import("path", <arguments>)

Imports the specified Triple-S Survey (SSS) file. The SSS format consists of a pair of files: .xml or .sss, and a .csv, .dat, or .asc file. Both sets of files must have the same root name and be in the same folder.