Navigation:  Programmer's Reference > Sending data to DPlot from another application >

FileOpen macro command

Print this Topic Previous pageReturn to chapter overviewNext page

Macro commands may be used either in macros or by sending the commands to DPlot via dynamic data exchange (DDE). Some commands are valid only in macros (noted by Macros Only). Commands sent to DPlot via DDE must be enclosed by square brackets [     ]. Macro commands should not include the brackets.

Command parameters shown in the descriptions below are placeholders for the actual values. Command parameters are either numeric values, equations that evaluate to numbers, or character strings. Character string parameters are always bound by double quotation marks. Equations must be preceded by an equals sign (=).

The pipe symbol (|) in the command syntax indicates that a parameter is optional, and should not be included in your macro unless otherwise noted.

All indices into arrays are 1-based, e.g. Curve1=1 refers to the first curve in a plot.

A 0x prefix for numbers in the descriptions below indicates hexadecimal notation; e.g. 0x0010 = 16.

JR/Viewer indicates that the command is supported by DPlot Jr or DPlot Viewer.
JR/Viewer indicates that the command is NOT supported by DPlot Jr or DPlot Viewer.


(file import plugins only)

JR   Viewer

Opens and displays a file in a new or empty document window. If the file type is not a DPlot file, then the FileType command should be issued before the FileOpen command. Subsequent commands reference the document created by this command. The path to the file should either be absolute (as in "c:\datafiles\mydata.dat") or relative to the current directory. By default, the current directory is the My Documents\DPlot folder. The current directory can be changed with a Directory command. You can embed Windows' environment variables in filenames, delimited with percent (%) symbols. For example "%USERPROFILE%\My Documents\DPlot\test.csv" will be interpreted as "c:\Documents and Settings\<username>\My Documents\DPlot\test.csv" on most XP systems, and "c:\Users\<username>\My Documents\DPlot\test.csv" on Windows Vista and newer versions of Windows.

The filename argument may include the shortcuts |DPLOTDRIVE|, |DPLOTPATH|, or |DPLOTDOCS| to set the input drive or full path, respectively, to where DPlot is installed or, for |DPLOTDOCS|, to My Documents\DPlot. This is most often useful when DPlot is installed to a removable drive. All forms must be uppercase and surrounded by the pipe symbol (|) or will be ignored. For example:


will attempt to open the file myfile.grf located in the \datafiles folder on the drive where DPlot is installed.

The trailing colon will be included with |DPLOTDRIVE|; similarly the trailing backslash will be included with |DPLOTPATH|. The drive letter and colon are included in |DPLOTPATH|; there is no need to use, for example, "|DPLOTDRIVE||DPLOTPATH|filename".

The second form of this command is only useful for file import plugins that include the function plugin_readfileex. The interpretation of the options string is entirely up to the plugin and is passed unchanged to the plugin_readfileex function. Generally this options string is used to accept options for the plugin programmatically rather than forcing user input via a dialog box. Options for file import plugins distributed with DPlot are described below.

AMO Transient Recorder Files

Options are comma-separated values.

Option, Start_Time, Stop_Time

Option0=read entire record.
1=read 1st preview block.
2=read 2nd preview block.
3=read 3rd preview block.
4=read full record between Start_Time and Stop_Time (seconds). Start_Time and Stop_Time are optional and are ignored for all but Option=4.

ArcView Shapefiles

Only one option available: Separate

SeparateIf non-zero, different entities within the file will be treated as separate curves. If 0, different entities will be combined into the same curve, with a marker point with latitude = 100 degrees inserted between entities. For all shapefiles, the plugin turns on Mercator Projection scaling, which in turn forces Amplitude Limits to +/-85 degrees. For Separate = 0, this will in effect split the shapefile entities into separate pieces, though they will remain part of the same data set.
If a shapefile contains more entities than the maximum number of curves (100 minus the number of existing curves), this option is ignored and all entities will be combined.

Bitmap to 3D

Options are comma-separated values. All entries are optional and are read in the order Scale,Black_Value,White_Value,Filter,Left,Top,Right,Bottom,Xlo,Ylo,Xhi,Yhi

ScaleInteger from 10 to 100. Controls how many columns and rows the surface plot will have. At 100, the number of data columns will be equal to the width of the selected part of the image; the number of data rows will be equal to the height. Default=100.
Black_ValueZ value mapped to color index 0 in the (possibly converted) 8-bit gray scale image. Default=0.
White_ValueZ value mapped to color index 255 in the image. Default=255.
FilterFor scales less than 100%, specifies the resampling filter to use on the image. 0=bilinear, 1=B-spline, 2=bicubic. Default=2.
Left,Top,Right,BottomSpecifies the 0-based extents of the portion of the image to use, in pixels. 0,0 is the top left corner of the image. Default is to use entire image.
Xlo,Ylo,Xhi,YhiMaps Left,Bottom,Right,Top image pixels to X and Y values in the generated surface plot. Default is 0,0 to width-1,height-1.

All entries are optional, but you must include all previous options. For example you cannot specify Filter without also specifying Scale,Black_Value, and White_Value. If at least one option is specified then the default options shown above are used for any omitted options.

Pacific Instruments EU Files

Options are comma-separated values. All entries are optional and are read in the order Start_Channel,Stop_Channel,Sample_Count,UseFireSwitch,TimeStartsAt0

Start_Channel0-based index of the first channel to read. Ignored for Stop_Channel < 0. Default=0.
Stop_Channel0-based index of the last channel to read. For values less than 0, all channels will be included. Default=-1.
Sample_CountNumber of samples to read, starting from the start of the file. Use -1 to read all samples. Default=-1.
UseFireSwitchNon-zero to use fire switch time - first time = -fire switch time. If 0, first time is retrieved from the file header. Default=0.
TimeStartsAt0If non-zero and UseFireSwitch = 0, first time = 0. Default=0.

All entries are optional, but you must include all previous options. For example you cannot specify Sample_Count without also specifying Start_Channel and Stop_Channel. If at least one option is specified then the default options shown above are used for any omitted options.

Multiple-column text files (2 or 3D)

The Pick Columns to Plot option on the Open dialog is persistent, and if checked then the Specify Columns to Plot dialog will always appear after a FileOpen (or FileAppend or ForFilesIn) command is issued. If your file has the default layout and you do not want to display the Specify Columns to Plot dialog, use a ColumnsAre command before FileOpen. For example [ColumnsAre(3)] will force FileOpen to assume X is in column 1, Y is in column 2, and Z is in column 3 without prompting the user for that information.



Please note:

Character string arguments require a bit of care, depending on your development environment. Character string arguments in all DPlot commands are always enclosed by double quotation marks. In some environments (Visual Basic and all flavors of C, for example), double quotation marks are also used to delineate all character strings (including the command itself). The following example will always cause a syntax error in Visual Basic:

ret = DPlot_Command(docnum,"[FileOpen("myfile.grf")]")

Instead, use:

ret = DPlot_Command(docnum,"[FileOpen(""myfile.grf"")]")

in C, C++, C# you'd accomplish the same thing with:

ret = DPlot_Command(docnum,"[FileOpen(\"myfile.grf\")]");

If a character string argument is a variable, as in (VB):

Dim arg as string
arg = "myfile.grf"

... then you can build the command in VB as:

ret = DPlot_Command(docnum,"[FileOpen(" & chr$(34) & arg & chr$(34) & ")]")

In all flavors of C, the same can be accomplished with

char arg[256];
char cmd[512];
ret = DPlot_Command(docnum,cmd);

This does not apply to the DPlot macro editor, in which each line is by definition a character string and does not require delineators, nor to FORTRAN and possibly other languages, in which the delineator for character strings is a single quote, e.g. '[FileOpen("...")]'

To embed a double quotation mark within a character string which is itself delineated by double quotation marks, use the Symbol font equivalent instead. For example, "Radius=6{\s²}" inches will be processed as





Page url: