ACEgr_np library

The library libacegr_np.a that comes with xmgr provides five functions:

    #include <acegr_np.h>

    int ACEgrOpen (const int buffsize)
    int ACEgrPrintf (const char* fmt, ...)
    int ACEgrCommand (const char* cmd)
    int ACEgrClose (void)
    int ACEgrFlush (void)

ACEgrOpen creates the global write buffer, launches xmgr, and establishes the pipe. It returns 0 on success and -1 on failure.

After having invoked ACEgrOpen, we can send commands to xmgr using ACEgrPrintf. The usage of ACEgrPrintf is the same as for printf, except that ACEgrPrintf automatically appends a line feed "\n". ACEgrPrintf returns the number of characters successfully appended to the write buffer.

Alternatively, one can use ACEgrCommand to send commands to xmgr. ACEgrCommand was introduced to facilitate writing a Fortran wrapper for the library. For C programs it is probably more convenient to use ACEgrPrintf instead. The argument for ACEgrCommand is a constant string, such as "autoscale". A newline "\n" is appended automatically. ACEgrCommand returns 0 on success and -1 on failure.

ACEgrClose should be called before exiting an application to flush and free the output buffer and to cleanly terminate xmgr. ACEgrClose returns 0 on success and -1 on failure.

ACEgrFlush forces flushing the output buffer. This involves waiting for a time window when xmgr listens to the pipe. That waiting period can be up to two seconds. Therefore, you should use ACEgrFlush only when there is really a need for it. ACEgrFlush returns 0 on success and EOF on failure.

If you write something to xmgr using ACEgrPrintf and the buffer is more than half-filled, ACEgrPrintf forces an ACEgrFlush. Therefore, the buffer should have a size that is larger than twice the maximum amount of data you want to write to xmgr within 2 seconds. There is no harm if the buffer size is smaller, but this would force waiting for xmgr and slow down the application.

To use the library, you should include the corresponding header file:

    #include <acegr_np.h>

Your C compiler needs to be called with the additional argument

    -I/usr/local/xmgr/include

and your linker needs

    -L/usr/local/xmgr/lib -lacegr_np

Here is a simple example:

gcc -I/usr/local/xmgr/include myprogram.c -L/usr/local/xmgr/lib -lacegr_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 xmgr to kill all sets and reread your entire file in regular intervals:

    ACEgrPrintf ("read block \"%s\"", fname);
    for (i = 0; i < ncurves; i++) {
        ACEgrPrintf ("kill s%d", i);
        ACEgrPrintf ("s%d color %d", i, i + 1);
        ACEgrPrintf ("with s%d", i);
        ACEgrPrintf ("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:

        ACEgrPrintf ("g0.s0 point %d, %d", x, y1);
        ACEgrPrintf ("g0.s1 point %d, %d", x, y2);

Here is a C example program.

Fortran Wrapper

    INTEGER ACEgrOpenf (INTEGER buffsize)
    INTEGER ACEgrCommandf (CHARACTER*(*) cmd)
    INTEGER ACEgrClosef ()
    INTEGER ACEgrFlushf ()
    

Here is an F77 example program.