The FORTRAN spy library

The FORTRAN spy library provides a unique interface to acquire events:

• from a circular buffer between a farm builder and a farm recorder
• from a remote farm machine (via the farm spy daemon )
• from a YBOS file

The library itself can get the events only from a circular buffer. However, if on the system runs a spy daemon that comunicates with the remote machine (via the farm spy daemon ) or reads from a YBOS file, the library can access also that type of events.

In order to use the library, three (plus one) steps are needed:

1. connection to the circular buffer

   This step is normally done once at the startup.

   The syntax of the command is:
   INTEGER spyf_open(STRING keyname, INT keyname_len, INT spyf_nr)

   where:

   • keyname is the name of the circular buffer (i.e. "/tmp/B_1_1")
   • keyname_len is the length of the keyname (nr. of chars) (i.e. 10 for "/tmp/B_1_1")
   • spyf_nr is a spy ID that is used inside other spy routines

   The return value of the routine is SPY_ERROR_OK if everything went OK, any other value should be treated as an error.

2. information retrieval

   This step is repeated several times during the execution of the application.

   The syntax of the command is:
   INTEGER spyf_get_el(INT spyf_nr, ARRAY, MAXLEN)

   where:

   • spyf_id is the spy ID obtained during the connection to the circular buffer
   • ARRAY is an array of size MAXLEN bytes, that will be filled with the event data if everything goes OK
   • MAXSIZE is the size of the ARRAY

   The return value of the routine is:

   • SPY_ERROR_OK if everything went OK
   • SPY_ERROR_EMPTY if no new events are currently available
   • any other value should be treated as an error.

   If everything went OK, the buffer returned by the routine contains the data of an event.

3. internal buffer flushing

   This step is seldom used. It is useful only if you don't use the spy for a long period you want be sure the next event you get is a fresh one.

   The syntax of the command is:
   INTEGER spyf_refresh(INT spyf_nr)

   where:

   • spyf_nr is the spy ID obtained during the connection to the circular buffer

   The return value of the routine is:

   • SPY_ERROR_OK if everything went OK
   • any other value should be treated as an error.

4. disconnection from the circular buffer

   This step is normally done once before exiting.

   The syntax of the command is:
   INTEGER spyf_close(INT spyf_nr)

   where:

   • spyf_nr is the spy ID obtained during the connection to the circular buffer

   The return value of the routine is SPY_ERROR_OK if everything went OK, any other value should be treated as an error. However, since this is the disconnecting phase, most of the time you can ignore the result.

The applications using this library should include spy_f77.inc and be linked with libspyf77.a and libspy.a.