# 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

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

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

Each function returns 0 on success and -1 on failure.

Here is an F77 example program.