| |
int DPlot_Request(int DocNum, LPSTR item, LPSTR value, DWORD *maxcount);
Parameters
| DocNum | Document index returned by a previous call to DPlot_Plot (1-32) or 0 to request system information from DPlot (see Remarks). |
| item | Item that you want to request the value of. Must be null-terminated. |
| value | Address of buffer for text. Returned text will be null-terminated. |
| maxcount | Specifies the maximum number of characters to copy to value, including the NULL character. If the text exceeds this limit, value is undefined and an error code is returned. |
Return Values
| >0 | Success. Size, in bytes, of the value character string, not including the terminating null character. |
| 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. |
| -2 | Could not establish a DDE connection with DPlot. Either DPlot is not open (user might have closed it) or you requested information from a document that does not exist (which might happen, for example, if the user closes the document window). |
| -3 | Length of the requested information is larger than maxcount. In this case the required length is returned in maxcount. |
| -4 | Unrecognized item. |
Remarks
For a full description of the information that can be retrieved from DPlot, see the Transferring DPlot data to other applications section of DPlot's Help file. The most common uses for DPlot_Request are shown here:
For DocNum=0, valid items and typical return values are:
| item | Description |
| Status | "Ready" or "Busy". This gives an indication of whether DPlot may currently accept commands from DPLOTLIB or other DDE sources. |
| ActiveDocument | Index of the currently active document window (1-32). Note that this window might have been activated either by DPLOTLIB.DLL or the user. |
| NumberOfDocuments | Current number of open document windows. These windows do not necessarily contain a plot. |
| NumUsedDocuments | Number of document windows containing a plot. This information is used, for example, by DPlot_Stop to determine whether DPlot should be shut down. |
| LastNewCaption | Returns the caption of the last document created. |
| LastNewDocNum | Returns the document index (1-32) of the last document created. |
For DocNum > 0:
| item | Description |
| DocumentType | Returns the data type for the referenced document. 0=XY plot, 3=3D surface plot, points on a rectangular grid, 4=3D surface plot, randomly-spaced points, 6=1D box-and-whisker plot or dot graph, 7=3D scatter plot. |
| ListPeaks | Output is identical to that of the List Peak Values menu command for XY plots. Not valid for 1D and 3D plots. |
| MaxCurves | Allocated number of curves or data sets for the current plot. Meaningless for 3D surface plots. |
| MaxPoints | Allocated number of points per curve or data set for the current plot. Meaningless for 3D surface plots. |
| NumberOfCurves | Number of curves in the current XY plot or number of groups in the current 1D plot. Always returns 1 for 3D plots. |
| NumberOfPoints | Tab-separated list of the number of points in each curve, surface, or 1D group. |
| PlotMetrics | Returns scaling information for the plot: XlowDisplay, YlowDisplay, XhighDisplay, YhighDisplay, XlowData, YlowData, XhighData, YhighData, where:
| XlowDisplay = | | Horizontal 0-based pixel index of the left side of the plot. |
| YlowDisplay = | | Vertical 0-based pixel index of the bottom side of the plot (0=top of display). |
| XhighDisplay = | | Horizontal 0-based pixel index of the right side of the plot. |
| YhighDisplay = | | Vertical 0-based pixel index of the top of the plot. |
| XlowData = | | Left side of the plot in X units (data space). |
| YlowData = | | Bottom side of the plot in Y units. |
| XhighData = | | Right side of the plot in X units. |
| YhighData = | | Top side of the plot in Y units. |
|
| PlotMetricsEx | Same as PlotMetrics, with additional parameters that have meaning only
for 3D plots: XlowDisplay, YlowDisplay, XhighDisplay, YhighDisplay, XlowData, YlowData, XhighData, YhighData, XScale, YScale, ZScale, Scale, Azimuth, Elevation, where:
| XScale = | | X Scale factor (set with [ContourScales()] or on Contour Options dialog. |
| YScale = | | Y Scale factor |
| ZScale = | | Z Scale factor |
| Scale = | | Scale factor used to transform horizontal and vertical projections to pixel coordinates. |
| Azimuth = | | View angle around the Z axis, radians. |
| Elevation = | | Elevation angle of the view point, radians. |
|
| ZFromXY | For 3D plots, returns the interpolated Z value for the X,Y coordinates set with a call to DPlot_Command with the [SetXY()] command. |
|