Grace_np library

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

What Commands Should I Send to Xmgr?

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.

Fortran Wrapper

You can call the grace_np library functions from Fortran programs, too.
The corresponding functions are

    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.