The library libgrace_np.a
that comes with grace provides five
functions:
#include <grace_np.h> int GraceOpen (const int buffsize) int GracePrintf (const char* fmt, ...) int GraceCommand (const char* cmd) int GraceClose (void) int GraceFlush (void)
GraceOpen
creates the global write buffer, launches grace, and
establishes the pipe. It returns 0
on success and -1
on failure.
After having invoked GraceOpen
, we can send commands to grace using GracePrintf
. The
usage of GracePrintf
is the same as for printf
,
except that GracePrintf
automatically appends a line feed
"\n"
. GracePrintf
returns the number of characters
successfully appended to the write buffer.
Alternatively, one can use GraceCommand
to send commands to grace.
GraceCommand
was introduced to facilitate writing a
Fortran wrapper for the library. For C programs it is
probably more convenient to use GracePrintf
instead. The argument
for GraceCommand
is a constant string, such as
"autoscale"
. A newline "\n"
is appended
automatically. GraceCommand
returns 0
on success and
-1
on failure.
GraceClose
should be called before exiting an application to flush
and free the output buffer and to cleanly terminate grace.
GraceClose
returns 0
on success and -1
on failure.
GraceFlush
forces flushing the output buffer. This involves
waiting for a time window when grace listens to the pipe. That waiting period
can be up to two seconds. Therefore, you should use GraceFlush
only when there is really a need for it. GraceFlush
returns
0
on success and EOF
on failure.
If you write something to grace using GracePrintf
and the buffer is
more than half-filled, GracePrintf
forces an
GraceFlush
. Therefore, the buffer should have a size that is
larger than twice the maximum amount of data you want to write to grace within 2
seconds. There is no harm if the buffer size is smaller, but this would force
waiting for grace and slow down the
application.
To use the library, you should include the corresponding header file:
#include <grace_np.h>
and your linker needs
-lgrace_np
Here is a simple example:
gcc myprogram.c -lgrace_np
That depends on the amount of data your program generates. If your data files are small, you can tell grace to kill all sets and reread your entire file in regular intervals:
GracePrintf ("read block \"%s\"", fname); for (i = 0; i < ncurves; i++) { GracePrintf ("kill s%d", i); GracePrintf ("s%d color %d", i, i + 1); GracePrintf ("with s%d", i); GracePrintf ("block xy \"%d:%d\"", 1, i + 2); }
However, if your program generates large data files, it is probably better to just add the new points to the corresponding sets:
GracePrintf ("g0.s0 point %d, %d", x, y1); GracePrintf ("g0.s1 point %d, %d", x, y2);
Here is a C example program.
INTEGER GraceOpenf (INTEGER buffsize) INTEGER GraceCommandf (CHARACTER*(*) cmd) INTEGER GraceClosef () INTEGER GraceFlushf ()Each function returns 0 on success and -1 on failure.
Here is an F77 example program.