SYNOPSIS

gd [mode] [data_file [+n] [=t] [&] [@]]

DESCRIPTION

The gd command offers a variety of methods for entering data into C-PLOT. The modes for the gd command are as follows.

Mode
1	Enter data from terminal keyboard
2	Take data from ASCII file
3	Same as 2, but with columns specified
4	Break current data around points in file
5	Same as 4, but with columns specified
6	Reuse current data points
7	Modify current data points
8	Same as 1, but with columns specified
9	Digitize data from the pen plotter
10	Switch x and y
11	Take data from file to plot unlimited points
12	Same as 11, but with columns specified
13	Take data from a binary file
14	Take data from binary file to plot unlimited points
15	Erase current data

The +n option causes the first n lines of the file to be skipped. The =t option reads in at most t points from the file. The & option appends data from the indicated file to the data currently in memory. The @ option is used for real-time plotting. Entering gd . uses the same file as previously invoked.

Modes 1 and 8 - Enter data from keyboard

Under mode 1 of the gd command, you will be prompted to type in values for x, y, and (in 3D mode) z and, optionally, error-bar values for x and y or (in 3D mode) z and/or a line-control value.

It is unlikely that you would need to choose columns when you are typing in data at the keyboard, but mode 8 may be useful when constructing command files or if you want the x value to be simply the index number of the point (by entering a negative column number; see below).

Modes 2 and 3 - Getting data from ASCII files

Under mode 2, data will be read into C-PLOT from ASCII files --created independently or using the sa command described below-- containing columns of x, y, and (in 3D mode) z and, optionally, error-bar values for x and y, or (in 3D mode) z and/or a column for line-control information.

Mode 3 lets you specify which columns in the file to use for obtaining the data.

Modes 4 and 5 - Break data around points in a file

This option (only available in 2D mode) is useful if the current data is a dense set of points to be drawn as a line, and you wish to break the line around a sparser set of points drawn as discrete symbols. This situation occurs when you draw a fitted or theoretical curve through data.

Assume you have first drawn the axis and the data points from data_file, and the current data is to be the smooth curve. If you then type

gd 4 data_file

points near the sparse data points won't be drawn when pp or zp is executed with a line symbol.

The size of the masked area, the nearness, is proportional to the character size (see cs) of the symbol. To mask a larger area, increase the symbol width before typing gd 4. You must have a large number of points for the breaks in the line to be symmetric. If error-bar mode is on, the line will be broken around the error bars, too.

Mode 5 is like mode 4, but it allows you to specify columns.

These modes assign data values to the line-control column.

Mode 6 - Reuse current data points

Mode 6 is useful after reading in data with modes 11 or 12. Entering gd 6 keeps the current data in memory, but prevents the program from reading more points from the open-ended file when you draw the plot.

Mode 7 - Delete, insert, modify data.

This mode lets you edit your data points, using the commands shown in the table below. Only points in memory can be edited.

# g or <back>	Go to point #
v <return>	Change data to v, go to next value
v f	Change data to v, go to next point
v b or \	Change data to v, go to prior point
v <linefeed>	Change data to v, update display
a	Append a point
i	Insert a point
d	Delete current point
G	Go to the last point
^D	Done
^C or <break>	Exit without using changes

If there is no data present, the number of points is set to 1. This one point can be deleted with <d>.Inserted points are initialized to zeroes.

In PseudoGraphics mode, the data is displayed on the video terminal with the current point highlighted. The commands on the previous page work in the same way. In addition, the following commands control movement.

KEY	VT100	ACTION
Up	A	Turn on interactive mode
Down	B	Turn off interactive mode
Right	C	Scan forward through points
Left	D	Scan back through points

Hit any key to stop scans.

Mode 9 - Digitize data from the pen plotter

Mode 9 lets you use the pen plotter as a digitizer. If possible, the digitizing site should be installed in the plotter to make it easy to align the pen carriage over the desired points. To digitize, position the site over the appropriate points using the plotter's front panel controls. Press the plotter's enter control to send a point to the computer.

C-PLOT will first ask you to set three scaling points that will be used to translate the plotter's native coordinates to the coordinates of the plot you are digitizing. Since there are three scaling points, it is not necessary for the axes of the points being digitized to be perfectly aligned with the plotter motions. Choosing three points that are widely separated gives the least error when C-PLOT calculates the transformation factors. When setting the scaling points, move to each one using the plotter control panel and press the enter control. The computer prints out the plotter coordinates and asks you for the equivalent coordinates on your plot.

After setting the three scaling points, site each point to be digitized in turn and press the enter control on the plotter. As each point is digitized, your coordinates appear on the terminal. To finish, type ^C.

If line-control mode is on (using lc),the line-control status for each point will reflect the pen up/down status when each data point is entered.

Mode 10 - Switch x and y

In 2D mode, values for x and y and for x- and y-error bars are switched. In 3D mode, only x and y values are switched.

Modes 11 and 12 - Take data from a file, with unlimited points

These modes let you plot unlimited data using only one gd command. When the command is entered, the first group of points from the file are read into memory. (The number of points is given by the NPTS parameter in the startup configuration file.) When you plot the points or error bars using the p, pz, zz, pb or zb commands, those first points are plotted. The next group is then automatically read from the file and plotted and so on until the file is exhausted or a limit set with the =t option is reached. At the conclusion of the point plotting, the points in memory will be the last points read. If you plot the points again, however, the first points in the file will be read and all the points will be plotted.

All other commands that use data points only use those currently in memory. Only the p, pz, pp, pb and similar z commands will access the entire file using gd 11 or 12. (If you enter gd 6,the current points in memory will continue to be available, and only those points will be drawn when you enter the commands to draw points.)

The append option cannot be used with modes 11 and 12.

Modes 13 and 14 - Take data from binary files

The fastest way to read data into C-PLOT is from a binary file. The format of the file is set by the struct pt given in the include file p_plot.h. That structure is::

struct  pt {
    /* flags for this point */
    int    p_flags;
    /* x, y, error bars for x, y (2D mode) */
    /* x, y, z, error bars for z (3D mode) */
    float  p_d[4];
};

Presently, p_flags contains only line-control status in the low-order two bits. The general gd command options can be used with these modes.

Mode 14 reads from an indefinitely long file, just like modes 11 and 12.

Mode 15 - Erase current data

You may wish to erase the current data before calling user functions that will ignore the current data. Erasing the current data does not change the current ranges.

General Options

The +n option causes the first n lines of the file to be skipped. All lines are included in the skip count, even comment lines.

The =t option reads in at most t points from the file.

The & option causes the new data points to be appended to the data currently in memory.

The @ option is used for real-time plotting. As with modes 11 and 12, only the in-core number of points are read initially. When data is plotted, C-PLOT will first draw the points currently in the file. The program will then continue to check the file to see if more points have been added and plot those as they appear. If the end-of-file character (ASCII \004)or the two characters ^D are read from the file after a newline, the program stops reading the file and proceeds to the next command if running from a command file, or to the PLOT-> prompt if running interactively. You also can use a ^C to interrupt the reading. In the present implementation, the program sleeps for one second between checks for new data.

Up to 65,536 points can be handled at a time, except in mode 7, which is limited to the in-core numbers of points set in the startup configuration file. Of course, modes 11, 12 and 14 can be used to plot an unlimited number of points, as explained above.

There may be up to 2,048 characters on an input line. Anything past that is discarded. There is no limit on the number of columns on an input line for modes 3, 5, 8 or 12, as long as the data is within the first 2,048 characters of the input line.

Entering a negative column number for x, y or z (in 3D mode) in modes 3, 5, 8 or 12 causes each value associated with that column to be assigned the index number of the point rather than a number from the file. Entering zero for the column number will retain the current value for each x, y or z (in 3D mode).

Comment Lines

In a data file, lines beginning with a # are considered comments and not scanned for data. Text following a #% will be printed out on the terminal as the file is scanned. Comment lines are included in the line count used for the +n (skip lines) option.

Error Bars

Values for error bars will be read in with modes 1 and 2 only if the error-bar mode has been turned on using the eb command or if a positive number is entered for the error-bar column.

The end-to-end length of the plotted error bars is twice the magnitude of the numbers read.

Line Control

Values for line control are scanned for in modes 1 and 2 only if line-control mode is turned on using the lc command. Also, you are only prompted for a column for line control in modes 3 and 8 if line-control mode is on.

When scanning for line-control values, a missing value is set to 0.

Line-control values only have an effect on plotting data when line-control mode is on or data is obtained using modes 4 or 5. Also, the plot symbol must be one of the line types. A line-control value of zero means move to the point with the pen down (except the first point). A value of one means move to the associated point with the pen up. A value of two means to fill the connected points with the current white fill color.

Modes 4 and 5 assign line-control values but turn off line-control mode. Instead, an internal flag is set so that the lines drawn will use the line-control values. However, when saving data or on subsequent get-data commands, line-control mode will be off.