DPlot_Command function

int DPlot_Command(int DocNum, LPSTR commands);

Parameters

DocNum

Document index returned by a previous call to DPlot_Plot (1-32) or 0 to send the command string to the currently active document window. This form (DocNum=0) should only be used for opening a new document window (with one of the various FileNew commands or a FileOpen command with the full version of DPlot) or for commands which have no effect on a plot (for example AppMaximize).

commands

Character string with zero or more DPlot commands. Valid commands and the syntax for those commands are described in the Executing DPlot Commands section of the DPlot Help file. In DPlot select Help>Search for Help On... and type "command syntax". A complete list of command strings is also available online. If using DPlot Jr, pay particular attention to which commands are supported/not supported by DPlot Jr. The command string is limited to 32768 characters and must be null-terminated.

Return Values

>0	Success. For DocNum = 0, the return value is the index of the active document (1-32). For DocNum > 0, success is always indicated by a return value of 1.
0	Generic error attempting to communicate with DPlot. This most often indicates that DPlot is currently busy, e.g. a modal dialog box is open, or that one or more commands in the commands parameter is invalid. (In the latter case, DPlot will show an "Error processing this command" MessageBox.
-1	Could not find/execute DPlot.
-2	Could not establish a DDE connection with DPlot. This error should never occur.

NOTES:

DPlot_Command opens a DDE conversation with DPlot, sends the command string, and then terminates the DDE conversation. Every time a conversation is opened, DPlot initializes several conversation-specific variables. For example the curve index associated with any commands dealing with XY curves is set to 1. So this:

DPlot_Command(DocNum,"[SelectCurve(2)]");

DPlot_Command(DocNum,"[XY(50,20)]");

will add a point at (50,20) to the 1st curve, not the 2nd as was most likely intended. If instead you use:

DPlot_Command(DocNum,"[SelectCurve(2)][XY(50,20)]");

then you will get the expected results. In short, always group related commands when possible.

2.	The entire command string is just that: a character string. All numeric values must be passed as ASCII text. For example, this:

width=0.5

DPlot_Command(DocNum,"[BarWidth(width)]")

will only result in a syntax error, since your development environment will attempt to read a number from the character string (that isn't a character string) "width". Instead, use something like (in VB):

DPlot_Command(DocNum,"[BarWidth(" & str$(width) & ")]"

3.	Character string arguments are always enclosed in double quotation marks. In C and Visual Basic this creates a bit of extra work since those marks are also used to delineate character strings, and the entire command is itself a character string. For example in C this:

DPlot_Command(DocNum,"[DateFormat("mm/dd/yy")]");

will only cause a compilation error. In C the solution is fairly simple: just use an escape sequence for the inner quotation marks:

DPlot_Command(DocNum,"[DateFormat(\"mm/dd/yy\")]");

in Visual Basic simply double the quotation marks:

ret=DPlot_Command(DocNum,"[DateFormat(""mm/dd/yy"")]")

in FORTRAN this is not an issue, as character strings are delineated by ' rather than ".

4.	Floating point values should not be localized. A "." should be used as the decimal point; thousand separators should not be used.

As mentioned previously, valid commands are shown in the DPlot Command Syntax section of the Help files of both DPlot and DPlot Jr. DPlot Jr does not support the full set of commands included with DPlot. In general, DPlot Jr will not open a file (no FileOpen command, for example), nor will it perform many of the data manipulation functions included in the full version. If you are distributing DPlot Jr with your own application you should always check the Help file to ensure that DPlot Jr will handle the desired commands.

Page url: http://www.dplot.com/lib/index.htm?dplot_command.htm