User Routines
General Functions
int et_open
(et_sys_id *id, char *filename, et_openconfig config)
Purpose:
Given an ET system on the same host, this routine will map the system's shared memory into the user's space. It also starts up a thread to produce a heartbeat and a second thread to monitor the ET system's heartbeat. If the ET system is remote, a network connection is made to it.
Arguments:
1. id is a pointer that gets
filled in with the unique id of the ET system being opened. It can be thought
of as a pointer to a handle.
2. filename is the unique filename of
the ET system
3. config is the desired configuration
of the way the ET system is opened and is defined by routines starting with et_open_config_
... .
Returns:
1. ET_OK if successful
2. ET_ERROR if failure to open the ET
file
3. ET_ERROR_TIMEOUT if the ET system is still
not active before the routine returns.
4. ET_ERROR_REMOTE for a remote client if it
cannot get the server's port number, the host has a strange byteorder, the tcp
connection fails, or there's not enough memory.
5. ET_ERROR_READ for a remote client's
network read error
6. ET_ERROR_WRITE for a remote client's network
write error
Notes:
The ET system is implemented as a single memory mapped file of the name filename. This routine should only be called once, before all other ET routines are used, or after a system has been closed with a call to et_close or et_forcedclose. A successful return from this routine assures connection to an ET system which is up and running. IT IS CRUCIAL THAT THE USER GET A RETURN VALUE OF "ET_OK" IF THE USER WANTS AN ET SYSTEM GUARANTEED TO FUNCTION.
The user may open an ET system on a remote host. ET decides whether the user is on the same as or a different machine than the system. If the determination is made that the user is on another computer, then network connections are made to that system.
int et_close (et_sys_id id)
Purpose:
Given a local ET system that has been opened with a call to et_open, this routine will stop all ET-related threads and unmap the system's memory from the user's space making it inaccessible. It also frees memory allocated in et_open to create the system's id. For a remote user, all this routine does is close the connection between the user and ET system as well as free the memory allocated in creating the system's id.
Arguments:
id is the id of the ET system being closed.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
3. ET_ERROR_REMOTE for a local user on a
non-mutex-sharing system (none currently known), if cannot unmap shared memory
Notes:
This routine should only be called once for a particular ET system after the associated call to et_open. In addition, all attachments of the process calling this routine must be detached first or an error will be returned.
int et_forcedclose (et_sys_id
id)
Purpose:
Given a local ET system that has been opened with a call to et_open, this routine will stop all ET-related threads and unmap the system's memory from the user's space making it inaccessible. For a remote user, this routine closes the connection between the user and ET system. But before it does any of this, it detaches all attachments belonging to the process calling it. It also frees memory allocated in et_open to create the system's id.
Arguments:
id is the id of the ET system being closed.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
3. ET_ERROR_DEAD for a local user if ET
system is dead
4. ET_ERROR_REMOTE for a local user on
non-mutex-sharing system (none currently known), if cannot unmap shared memory
Notes:
This routine should only be called once for a particular ET system after the associated call to et_open.
int et_kill (et_sys_id id)
Purpose:
Given a local ET system that has been opened with et_open, this routine will do the same as et_forcedclose for the caller and will cause the ET system to delete its file and kill itself. For a remote user it does the equivalent of an et_close for the caller while telling the ET system to delete its file and kill itself.
Arguments:
id is the id of the ET system being closed.
Returns:
1. ET_OK if successful, or if local
client
2. ET_ERROR_WRITE if remote client and network writing
error
3. ET_ERROR_REMOTE for a local user on
non-mutex-sharing system (none currently known), if cannot unmap shared memory
Notes:
This routine should only be called once for a particular ET system after the associated call to et_open.
int et_alive (et_sys_id id)
Purpose:
This routine tells the user whether the ET system is dead or alive.
Arguments:
id is the id of the ET system of interest
Returns:
1. 1 if ET system given by id is
alive
2. 0 if ET system given by id is
dead
Notes:
This routine behaves differently depending on whether it is run locally or remotely. If the user is running it locally, a thread of the user's process is constantly checking to see if the ET system is alive and provides a valid return value to et_alive when last it was monitored (up to three heartbeats ago). If the user is on a remote node, the ET system's server thread is contacted. If that communication succeeds, then the ET system is alive by definition, otherwise it is dead.
int et_wait_for_alive (et_sys_id
id)
Purpose:
This routine waits until the ET system has a heartbeat before it returns. It checks once every minimum sleep period.
Arguments:
id is the id of the ET system of interest
Returns:
1. ET_OK
2. ET_ERROR_READ for a remote user's network
read error
3. ET_ERROR_WRITE for a remote user's network
write error
Notes:
This routine behaves differently depending on whether it is run locally or remotely. If the user is running it locally, it constantly checks to see if the ET system is alive and waits before returning until it is. If the user is on a remote node, the ET system's server thread is contacted. If that communication succeeds, then the ET system is alive by definition, otherwise it immediately returns an error.
Open Configuration
Functions
int et_open_config_init (et_openconfig *sconfig)
Purpose:
This routine initializes a configuration used by a process to open an ET system. This MUST be done prior to setting any configuration parameters or all setting routines will return an error.
Arguments:
sconfig is pointer to an open configuration variable
Returns:
1. ET_OK if successful
2. ET_ERROR if it fails to allocate
memory for configuration data storage
int et_open_config_destroy (et_openconfig sconfig)
Purpose:
This routine frees the memory allocated when a configuration is initialized by et_open_config_init.
Arguments:
sconfig is an open configuration
Returns:
ET_OK
int et_open_config_setwait(et_openconfig sconfig, int
val)
Purpose:
This routine sets the means to wait for a valid ET system to be detected.
Arguments:
1. sconfig is an open configuration
2. val is the method to wait for a
valid ET system to be detected. Setting val to ET_OPEN_WAIT makes et_open
block by waiting until the given ET system is fully functioning or a set time
period has passed before returning. Setting val to ET_OPEN_NOWAIT
makes et_open return immediately after determining whether the ET
system is alive or not. The default is ET_OPEN_NOWAIT.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not ET_OPEN_WAIT or ET_OPEN_NOWAIT
Notes:
If the ET system is local, both ET_OPEN_WAIT and ET_OPEN_NOWAIT mean et_open will quickly send a UDP broad/multicast packet to see if the system responds. If it does not, it tries to detect a heartbeat which necessitates waiting at least one heartbeat. However, if the system is remote, broad/multicasting to find its location may take up to several seconds. Usually, if the ET system is up and running, this will only take a fraction of a second. If a direct remote connection is being made, it is only tried once in the ET_OPEN_NOWAIT mode, but it tries repeatedly at 10Hz until the set timeout in the ET_OPEN_WAIT mode.
int et_open_config_getwait (et_openconfig sconfig, int
*val)
Purpose:
This routine gets the means to wait for a valid ET system to be detected.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with ET_OPEN_WAITor ET_OPEN_NOWAIT
Returns:
ET_OK
int et_open_config_settimeout (et_openconfig sconfig,
struct timespec val)
Purpose:
This routine sets the maximum time to wait for a valid ET system to be detected.
Arguments:
1. sconfig is an open configuration
2. val is maximum amount of time to
wait for an alive ET system to be detected if the wait mode is ET_OPEN_WAIT. If
the time is set to zero (the default), an infinite time is indicated. Note that
in local systems, et_open waits in integral units of the system's
heartbeat time (ET_BEAT_SEC & ET_BEAT_NSEC set in et_private.h).
If broad/multicasting to find a remote ET system, it is possible to take up to
several seconds to determine whether the system is alive or not. In this case,
the time limit may be exceeded.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized
int et_open_config_gettimeout (et_openconfig sconfig,
struct timespec *val)
Purpose:
This routine gets the maximum time to wait for a valid ET system to be detected.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with the time
Returns:
ET_OK
int et_open_config_sethost (et_openconfig sconfig, char
*val)
Purpose:
This routine sets host or computer on which the ET system is running.
Arguments:
1. sconfig is an open configuration
2. val is the name of the computer
(or host) on which the ET system resides. For opening a local system only, set val
to ET_HOST_LOCAL (the default) or "localhost" (including quotes). For
opening a system on an unknown remote computer only, set it to ET_HOST_REMOTE.
For an unknown host which may be local or remote, set it to ET_HOST_ANYWHERE.
Otherwise set val to the name or dotted-decimal IP address of the
desired host. If the ET_DIRECT option is taken in et_open_config_setcast,
be aware that this routine must use the ET system's actual host name or
"localhost" but must NOT be ET_HOST_LOCAL,
ET_HOST_REMOTE, or ET_HOST_ANYWHERE.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is NULL or too long
int et_open_config_gethost (et_openconfig sconfig, char
*val)
Purpose:
This routine gets the host or computer on which the ET system is running.
Arguments:
1. sconfig is an open configuration
2. val is a character array that
gets filled with the host name
Returns:
ET_OK
int et_open_config_setmode (et_openconfig sconfig, int
val)
Purpose:
This routine sets whether the ET system being opened treats the user running this routine as local (if it is local) or remote even if it is local.
Arguments:
1. sconfig is an open configuration
2. val can be set to
ET_HOST_AS_REMOTE if the local user is to be treated as remote. This means all
communication is done through the ET server using sockets. The alternative is
to set val to ET_HOST_AS_LOCAL (default) which means local
users are treated as local with the ET system memory being mapped into the
user's space.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not equal to ET_HOST_AS_REMOTE or ET_HOST_AS_LOCAL
int et_open_config_getmode (et_openconfig sconfig, int
*val)
Purpose:
This routine gets the mode which tells whether local users are treated as local or remote.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with either ET_HOST_AS_REMOTE or ET_HOST_AS_LOCAL
Returns:
ET_OK
int et_open_config_setdebugdefault (et_openconfig sconfig, int
val)
Purpose:
This routine sets the default level of debugging output.
Arguments:
1. sconfig is an open configuration
2. val can be set to ET_DEBUG_NONE
which means no output, ET_DEBUG_SEVERE for output describing severe errors,
ET_DEBUG_ERROR for output describing all errors, ET_DEBUG_WARN for output
describing warnings and errors, and ET_DEBUG_INFO for output describing all
information, warnings, and errors.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not equal to one of the listed values.
int et_open_config_getdebugdefault (et_openconfig sconfig, int
*val)
Purpose:
This routine gets the default level of debugging output.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with either ET_DEBUG_NONE, ET_DEBUG_SEVERE, ET_DEBUG_ERROR,
ET_DEBUG_WARN, or ET_DEBUG_INFO.
Returns:
ET_OK
int et_open_config_setcast (et_openconfig sconfig, int
val)
Purpose:
This routine sets the method for a remote user to discover the ET system to be opened.
Arguments:
1. sconfig is an open configuration
2. val is the name of the method
for a remote user to discover the ET system to be opened. Set it to
ET_BROADCAST for using UDP broadcasting (the default), ET_MULTICAST for using
UDP multicasting, ET_BROADANDMULTICAST for using both, or ET_DIRECT for a
direct connection to the ET system by specifying host and server (not UDP)
port.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not equal to ET_BROADCAST, ET_MULTICAST,
ET_BROADANDMULTICAST, or ET_DIRECT
Notes:
To avoid broad/multicasting to find the ET system (actually to find the port number of the tcp server thread), use the ET_DIRECT option. This does no broad/multicast and connects directly to the ET system. A possible reason for wanting to avoid broad/multicasting is if the ET system and user are on different subnets and routers will not pass the UDP packets between them. If the ET_DIRECT option is taken, be aware that et_open_config_sethost must use the ET system's actual host name or "localhost" but must NOT be ET_HOST_LOCAL, ET_HOST_REMOTE, or ET_HOST_ANYWHERE. Use et_open_config_setserverport to specify the port number of the ET server thread.
int et_open_config_getcast (et_openconfig sconfig, int
*val)
Purpose:
This routine gets the method for a remote user to discover the ET system to be opened.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with either ET_BROADCAST, ET_MULTICAST, ET_BROADANDMULTICAST, or
ET_DIRECT
Returns:
ET_OK
int et_open_config_addbroadcast
(et_openconfig sconfig, char *val)
Purpose:
This routine adds an IP subnet broadcast address to a list of destinations used in broadcast discovery of the ET system to be opened. Broadcasting is only used if et_open_config_setcast is set to ET_BROADCAST or ET_BROADANDMULTICAST.
Arguments:
1. sconfig is an open configuration
2. val is a subnet broadcast IP
address in dotted-decimal form. If this routine is never called, the list of
addresses is automatically set to all the local subnet broadcast addresses.
However, if finding these addresses fails, then the list is set to a single
entry of ET_BROADCAST_ADDR (defined in et.h to be the author's subnet
broadcast address). This argument may also be set to ET_SUBNET_ALL which
specifies all the local subnet broadcast addresses, or to ET_SUBNET_DEFAULT
which specifies the address associated with the hostname returned by the
"uname" routine. There can be at most ET_MAXADDRESSES (defined in et_private.h
as 10) addresses in the list.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is NULL or too long or too short
int et_open_config_removebroadcast (et_openconfig sconfig, char
*val)
Purpose:
This routine removes an IP subnet broadcast address from a list of destinations used in broadcast discovery of the ET system to be opened.
Arguments:
1. sconfig is an open configuration
2. val is a subnet broadcast IP
address in dotted-decimal form. If there is no such address on the list, it is
ignored. This argument may also be set to ET_SUBNET_ALL which specifies all the
local subnet broadcast addresses, or to ET_SUBNET_DEFAULT which specifies the
address associated with the hostname returned by the "uname" routine.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is NULL or too long or too short
int et_open_config_addmulticast
(et_openconfig sconfig, char *val)
Purpose:
This routine adds a multicast address to a list of destinations used in multicast discovery of the ET system to be opened. Multicasting is only used if et_open_config_setcast is set to ET_MULTICAST or ET_BROADANDMULTICAST.
Arguments:
1. sconfig is an open configuration
2. val is a multicast IP address in
dotted-decimal form. There can be at most ET_MAXADDRESSES (defined in et_private.h
as 10) addresses on the list. Duplicate entries are not added to the list.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized, val is NULL, is too long or too short, or its first
number is not between 224 and 239 inclusive.
int et_open_config_removemulticast (et_openconfig sconfig, char
*val)
Purpose:
This routine removes a multicast address from a list of destinations used in multicast discovery of the ET system to be opened.
Arguments:
1. sconfig is an open configuration
2. val is a multicast IP address in
dotted-decimal form. If there is no such address on the list, it is ignored.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized, val is NULL, is too long or too short, or its first
number is not between 224 and 239 inclusive.
DEPRECATED
int et_open_config_setaddress (et_openconfig sconfig, char
*val)
Purpose:
This routine is replaced by et_open_config_addbroadcast and et_open_config_addmulticast. For compatibility purposes it is included though it is deprecated. Currently it adds an IP subnet broadcasting address or a multicasting address to the appropriate destination list used in discovering the ET system to be opened.
Arguments:
1. sconfig is an open configuration
2. val is the IP address for
broadcast or multicast communications in dotted-decimal form. If the address
starts with a number from 224 to 239, it's added to the multicast address list,
else it's added to the broadcast list.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized, val is NULL, or is too long or too short.
DEPRECATED
int et_open_config_getaddress (et_openconfig sconfig, char
*val)
Purpose:
This routine has no replacement in this ET version and is included for compatibility purposes only, though it is deprecated. It returns the default IP subnet broadcast address unless et_open_config_setcast was set to ET_MULTICAST and there is at least one multicast address listed. In that case, the first listed multicast address is returned. These are the destination addresses of the ET system discovery process.
Arguments:
1. sconfig is an open configuration
2. val is a character array that
gets filled with the dotted-decimal form IP address
Returns:
ET_OK
int et_open_config_setpolicy (et_openconfig sconfig, int
val)
Purpose:
This routine sets the return policy from an et_open call. If an et_open generates more than one response from one or more ET systems, this policy can be set to return an error, open the first system to respond, or open the first local system to respond.
Arguments:
1. sconfig is an open configuration
2. val can be set to
ET_POLICY_ERROR if the user wants et_open to return an error if more
than one response is received from its broad or multicast attempt to find an ET
system. Set val to ET_POLICY_FIRST if the first
responding system is the one to be opened. Else, set val
to ET_POLICY_LOCAL if the first responding local system is opened if there is
one, and if not, the first responding system.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not equal to ET_POLICY_ERROR
, ET_POLICY_FIRST , or ET_POLICY_LOCAL.
Notes:
One ET system may respond multiple times to a single et_open by a user if it is connected to more than one subnet or is listening to multicast addresses. It is also possible that if a user is configured for ET_HOST_REMOTE or ET_HOST_ANYWHERE, several ET systems may have the same name (eg. /tmp/my_et_system) and respond with their port numbers and host names. Thus, the user needs to determine the best way to respond to such situations.
int et_open_config_getpolicy (et_openconfig sconfig, int
*val)
Purpose:
This routine gets the return policy from calls to et_open.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with either ET_POLICY_ERROR , ET_POLICY_FIRST , or ET_POLICY_LOCAL.
Returns:
ET_OK
int et_open_config_setport (et_openconfig sconfig,
unsigned short val)
Purpose:
This routine sets the port number for the UDP broadcasting used to discover the ET system being opened.
Arguments:
1. sconfig is an open configuration
2. val is the port number of the
broadcast communications. The default is ET_BROADCAST_PORT, defined in et.h
as 11111, but may be set to any number > 1023 and < 65536.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is less than 1024
int et_open_config_getport (et_openconfig sconfig,
unsigned short *val)
Purpose:
This routine gets the port number for the UDP broadcasting used to discover the ET system being opened.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with the port number
Returns:
ET_OK
int et_open_config_setmultiport
(et_openconfig sconfig, unsigned short val)
Purpose:
This routine sets the port number for the UDP multicasting used to discover the ET system being opened. The multicasting port only needs to be different from the broadcast port on Java-based ET systems.
Arguments:
1. sconfig is an open configuration
2. val is the port number of the
multicast communications. The default is ET_MULTICAST_PORT, defined in et.h
as 11111, but may be set to any number > 1023 and < 65536.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is less than 1024
int et_open_config_getmultiport
(et_openconfig sconfig, unsigned short *val)
Purpose:
This routine gets the port number for the UDP multicasting used to discover the ET system being opened.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with the port number
Returns:
ET_OK
int et_open_config_setserverport
(et_openconfig sconfig, unsigned short val)
Purpose:
This routine sets the TCP port number for opening an ET system directly without broadcasting or multicasting. It is used in conjunction with setting the value in et_open_config_setcast to be ET_DIRECT.
Arguments:
1. sconfig is an open configuration
2. val is the port number of the ET
system's tcp server thread. The default value is ET_SERVER_PORT which is set to
11111 in et.h.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is less than 1024
Notes:
To avoid broadcasting or multicasting to find the ET system (actually to find the port number of the tcp server thread), use et_open_config_setcast set to the ET_DIRECT option. This does no broad/multicast and connects directly to the ET system. A possible reason for wanting to avoid broad/multicasting is if the ET system and user are on different subnets and routers will not pass the udp packets between them. Setting the server port value with this routine assumes that its value is known. One way to ensure this, is to use the routine et_system_config_setserverport in the program which is starting up the ET system (e.g. et_start.c). This will definitively set the port number to the requested value or exit the program if it cannot. In this way, the port can be set by the ET system and the information shared with the user for use in this routine.
int et_open_config_getserverport
(et_openconfig sconfig, unsigned short *val)
Purpose:
This routine gets the TCP port number for opening an ET system directly without broadcasting or multicasting.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with the port number
Returns:
ET_OK
int et_open_config_setTTL (et_openconfig sconfig, int
val)
Purpose:
This routine sets the "ttl" value for multicasting. This value determines how many "hops" through routers the packet makes.
Arguments:
1. sconfig is an open configuration
2. val is the "ttl" value
for multicasting. It defaults to a value of 32 which should allow multicast
packets to pass through local routers.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is less than 0 or greater than 254
int et_open_config_getTTL (et_openconfig sconfig, int
*val)
Purpose:
This routine gets the "ttl" value for multicasting.
Arguments:
1. sconfig is an open configuration
2. val is a pointer that gets
filled with the ttl value
Returns:
ET_OK
int et_open_config_setinterface (et_openconfig sconfig, char
*val)
Purpose:
This routine sets the network interface to use when communicating over the network with the ET system (host is not local or mode is ET_HOST_AS_REMOTE or Java ET system).
Arguments:
1.
sconfig is an open configuration
2.
val is the IP address, in dotted decimal format, of the network
interface to use.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is NULL or too long or not in dotted decimal form
int et_open_config_getinterface
(et_openconfig sconfig, char *val)
Purpose:
This routine gets the network interface used when communicating over the network with the ET system.
Arguments:
1.
sconfig is an open configuration
2.
val is a character array that gets filled with the IP address
used when communicating over the network with the ET system. If not set, then nothing is copied to val.
Returns:
ET_OK
int et_open_config_settcp (et_openconfig sconfig, int
rBufSize, int sBufSize, int noDelay)
Purpose:
This routine sets the parameters of the TCP connection to the ET system.
These include the TCP receiving buffer size in bytes, the TCP sending buffer
size in bytes, and the TCP “no delay” value. If either of the
buffer sizes are 0, then the operating system default values are used. Setting “noDelay”
to 0, turns it off, anything else turns it on (which sends a write immediately
over the network without waiting for further writes).
Arguments:
1.
sconfig is an open configuration
2.
rBufSize is the TCP receiving buffer size in bytes.
3.
sBufSize is the TCP sending buffer size in bytes
4.
noDelay is a boolean value,
which is true (non-zero) for no delay of TCP writes, else false (zero)
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or buffer sizes are negative values
int et_open_config_gettcp (et_openconfig sconfig, int *rBufSize,
int *sBufSize, int *noDelay)
Purpose:
This routine gets the parameters of the TCP connection to the ET system.
These include the TCP receiving buffer size in bytes, the TCP sending buffer
size in bytes, and the TCP “no delay” value.
Arguments:
1.
sconfig is an open configuration
2.
rBufSize is a pointer that gets filled with the TCP receiving buffer
size in bytes.
3.
sBufSize is a pointer that gets filled with the TCP sending buffer
size in bytes
4.
noDelay is a pointer that
gets filled with a boolean value, which is true (1) for no delay of TCP writes,
else false (0)
Returns:
ET_OK
System Functions
int et_system_start (et_sys_id
*id, et_sysconfig sconfig)
Purpose:
This routine creates a new ET system. The process that executes this routine becomes the ET system process.
Arguments:
1. id is a pointer to an ET system
id - a value-result argument - in which is returned the id of the new system
which gets created
2. sconfig is the desired configuration
of the new ET system (set by routines starting with et_system_config_ ...)
Returns:
1. ET_OK
2. ET_ERROR if the system could not be
created
int et_system_close (et_sys_id
id)
Purpose:
This routine closes an ET system that was started with a call to et_system_start. All ET system threads are stopped and the shared memory is unmapped. Only the ET system process may execute this routine.
Arguments:
id is the ET system id
Returns:
1. ET_OK
2. ET_ERROR if not ET system process
int et_system_getlocality (et_sys_id
id, int *locality)
Purpose:
This routine returns a value indicating whether this routine is being executed on the same machine as the ET system or remotely.
Arguments:
1. id is the id of the ET system
of interest
2. locality is a pointer to an integer
that gets filled in with the value ET_LOCAL if the user is on the same machine
as the ET system, ET_REMOTE if the user is on another machine, and
ET_LOCAL_NOSHARE if the user is on the same machine but one whose operating
system does not allow the sharing of pthread mutexes.
Returns:
1. ET_OK
2. ET_ERROR if locality is NULL
int et_system_setdebug (et_sys_id
id, int debug)
Purpose:
This routine sets the debug output of the caller's process for a particular ET system.
Arguments:
1. id is the id of the ET system
of interest
2. debug can be either ET_DEBUG_NONE
which means no output, ET_DEBUG_SEVERE for output describing severe errors,
ET_DEBUG_ERROR for output describing all errors, ET_DEBUG_WARN for output
describing warnings and errors, and ET_DEBUG_INFO for output describing all
information, warnings, and errors.
Returns:
1. ET_OK
2. ET_ERROR if debug is an
invalid value
int et_system_getdebug (et_sys_id
id, int *debug)
Purpose:
This routine gets the value of the caller's debug level for a particular ET system.
Arguments:
1. id is the id of the ET system
of interest
2. debug is a pointer to an integer
that gets filled in with the debug level of the ET system. See et_system_setdebug
for possible values.
Returns:
1. ET_OK
2. ET_ERROR if debug is NULL
int et_system_getnumevents (et_sys_id
id, int *numevents)
Purpose:
This routine tells the total number of events that an ET system has.
Arguments:
1. id is the id of the ET system
of interest
2. numevents is a pointer to an integer
that gets filled in with the total number of events that the ET system has.
Returns:
1. ET_OK
2. ET_ERROR if numevents is
NULL
int et_system_geteventsize (et_sys_id
id, int *eventsize)
Purpose:
This routine tells the size in bytes of standard events in an ET system.
Arguments:
1. id is the id of the ET system
of interest
2. eventsize is a pointer to an integer
that gets filled in with the size in bytes of standard events in the ET system.
Returns:
1. ET_OK
2. ET_ERROR if eventsize is
NULL
int et_system_gettempsmax (et_sys_id
id, int *tempsmax)
Purpose:
This routine gives the maximum number of temporary events allowed in an ET system.
Arguments:
1. id is the id of the ET system
of interest
2. tempsmax is a pointer to an integer
that gets filled in with the maximum number of temporary events allowed in an
ET system.
Returns:
1. ET_OK
2. ET_ERROR if tempsmax is NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_getstationsmax (et_sys_id
id, int *stationsmax)
Purpose:
This routine gives the maximum number of stations allowed in an ET system.
Arguments:
1. id is the id of the ET system
of interest
2. stationsmax is a pointer to an integer
that gets filled in with the maximum number of stations allowed in an ET
system.
Returns:
1. ET_OK
2. ET_ERROR if stationsmax is
NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_getprocsmax (et_sys_id
id, int *procsmax)
Purpose:
This routine gives the maximum number of processes that are allowed to open an ET system.
Arguments:
1. id is the id of the ET system
of interest
2. procsmax is a pointer to an integer
that gets filled in with the maximum number of processes that are allowed to
open an ET system.
Returns:
1. ET_OK
2. ET_ERROR if procsmax is NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_getattsmax (et_sys_id
id, int *attsmax)
Purpose:
This routine gives the maximum number of attachments that are allowed in an ET system.
Arguments:
1. id is the id of the ET system
of interest
2. attsmax is a pointer to an integer
that gets filled in with the maximum number of attachments that are allowed in
an ET system.
Returns:
1. ET_OK
2. ET_ERROR if attsmax is NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_getheartbeat (et_sys_id
id, int *heartbeat)
Purpose:
This routine gives the current value of the heartbeat of an ET system. For a healthy system, this value changes every heartbeat period.
Arguments:
1. id is the id of the ET system
of interest
2. heartbeat is a pointer to an integer
that gets filled in with the current heartbeat of an ET system.
Returns:
1. ET_OK
2. ET_ERROR if heartbeat is
NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_getpid (et_sys_id
id, pid_t *pid)
Purpose:
This routine gives the pid of an ET system.
Arguments:
1. id is the id of the ET system
of interest
2. pid is a pointer that gets
filled in with the pid of an ET system.
Returns:
1. ET_OK
2. ET_ERROR if pid is NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_getprocs (et_sys_id
id, int *procs)
Purpose:
This routine gives the number of processes that currently have an ET system open.
Arguments:
1. id is the id of the ET system
of interest
2. procs is a pointer to an integer
that gets filled in with the number of processes currently open to an ET
system.
Returns:
1. ET_OK
2. ET_ERROR if procs is NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_getattachments (et_sys_id
id, int *atts)
Purpose:
This routine gives the number of attachments currently in an ET system.
Arguments:
1. id is the id of the ET system
of interest
2. atts is a pointer to an integer
that gets filled in with the number of attachments currently in an ET system.
Returns:
1. ET_OK
2. ET_ERROR if atts is NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_getstations (et_sys_id
id, int *stations)
Purpose:
This routine gives the current number of stations in an ET system that are either idle or active (but not unused or being created).
Arguments:
1. id is the id of the ET system
of interest
2. stations is a pointer that gets
filled in with the number of stations in an ET system that are either idle or
active.
Returns:
1. ET_OK
2. ET_ERROR if stations is NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_gettemps (et_sys_id
id, int *temps)
Purpose:
This routine gives the number of temporary events currently in an ET system.
Arguments:
1. id is the id of the ET system
of interest
2. temps is a pointer to an integer
that gets filled in with the number of temporary events currently in an ET
system.
Returns:
1. ET_OK
2. ET_ERROR if temps is NULL
3. ET_ERROR_READ for a remote user's network
read error
4. ET_ERROR_WRITE for a remote user's network
write error
int et_system_gethost (et_sys_id
id, char *host)
Purpose:
This routine gives the fully qualified name of the ET system's host computer.
Arguments:
1. id is the id of the ET system
of interest
2. host is a pointer to a character
array that gets filled in with the ET system's host name. To be safe the array
should be at least ET_MAXHOSTNAMELEN characters long.
Returns:
1. ET_OK
2. ET_ERROR if host is NULL
int et_system_getserverport (et_sys_id
id, unsigned short *port)
Purpose:
This routine gives the port number of the ET system's TCP server thread.
Arguments:
1. id is the id of the ET system
of interest
2. port is a pointer to an unsigned
short integer that gets filled in with the port number of the ET system's TCP
server thread.
Returns:
1. ET_OK
2. ET_ERROR if port is NULL
int et_system_setgroup (et_sys_id
id, int group)
Purpose:
This routine sets the default group number of the ET client. When the group is set to 0, calls to et_events(s)_new gets events of any group. When the group number is set to a positive number, the same calls only get events from the given group.
Arguments:
1. id is the id of the ET system
of interest
2. group is the default event group
number of the ET client.
Returns:
1. ET_OK
2. ET_ERROR if group < 0 or group > maximum number of groups in
the ET system
int et_system_getgroup (et_sys_id
id, int *group)
Purpose:
This routine gets the default event group number of the ET client.
Arguments:
1. id is the id of the ET system
of interest
2. group is a pointer to an integer
that gets filled in with the default event group number of the ET client.
Returns:
1. ET_OK
2. ET_ERROR if group is NULL
System
Configuration Functions
int et_system_config_init (et_sysconfig*
sconfig)
Purpose:
This routine initializes a system configuration. This MUST be done prior to setting any configuration parameters or all setting routines will return an error.
Arguments:
sconfig is pointer to a system configuration variable
Returns:
1. ET_OK if successful
2. ET_ERROR if it fails to allocate
memory for configuration data storage
3. ET_ERROR_NOMEM if there is not enough
memory allocated to store network info. Recompile code with bigger value of
ET_MAXADDRESSES.
int et_system_config_destroy (et_sysconfig
sconfig)
Purpose:
This routine frees the memory allocated when a configuration is initialized by et_system_config_init.
Arguments:
sconfig is a system configuration
Returns:
ET_OK
int et_system_config_setevents (et_sysconfig
sconfig, int val)
Purpose:
This routine sets a system configuration's total number of events.
Arguments:
1. sconfig is a system configuration
2. val must be greater than zero
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not an allowed value
int et_system_config_getevents (et_sysconfig
sconfig, int *val)
Purpose:
This routine gets a system configuration's current total number of events.
Arguments:
1. sconfig is a system configuration
2. val is a pointer that gets filled
with the total number of events
Returns:
ET_OK
int et_system_config_setsize (et_sysconfig
sconfig, int val)
Purpose:
This routine sets a system configuration's event size in bytes.
Arguments:
1. sconfig is a system configuration
2. val must be greater than zero
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not an allowed value
int et_system_config_getsize (et_sysconfig
sconfig, int *val)
Purpose:
This routine gets a system configuration's current event size.
Arguments:
1. sconfig is a system configuration
2. val is a pointer that gets
filled with the event size in bytes
Returns:
ET_OK
int et_system_config_settemps (et_sysconfig
sconfig, int val)
Purpose:
This routine sets a system configuration's total number of temporary events.
Arguments:
1.
sconfig is a system configuration
2.
val must be greater than zero
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not greater than zero
Notes:
The number of temp events must not be greater than the total number of events. This in not checked in this routine, but is checked when attempting to create an ET system.
int et_system_config_gettemps (et_sysconfig
sconfig, int *val)
Purpose:
This routine gets a system configuration's current total number of temporary events.
Arguments:
1. sconfig is a system configuration
2. val is a pointer that gets
filled with the number of temporary events
Returns:
ET_OK
int et_system_config_setstations (et_sysconfig
sconfig, int val)
Purpose:
This routine sets a system configuration's limit on how many stations can be created.
Arguments:
1. sconfig is a system configuration
2. val must be greater than zero
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not greater than zero
int et_system_config_getstations (et_sysconfig
sconfig, int *val)
Purpose:
This routine gets a system configuration's limit on how many stations can be created.
Arguments:
1. sconfig is a system configuration
2. val is a pointer that gets
filled with the maximum number of stations that can be created
Returns:
ET_OK
int et_system_config_setprocs (et_sysconfig
sconfig, int val)
Purpose:
This routine sets a system configuration's limit on how many user processes can open the system.
Arguments:
1. sconfig is a system configuration
2. val must be > 0 and <=
ET_PROCESSES_MAX
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not greater than zero or not <= ET_PROCESSES_MAX
Notes:
The default value of ET_PROCESSES_MAX is 20 but may be changed in et_private.h, requiring a recompilation of ET.
int et_system_config_getprocs (et_sysconfig
sconfig, int *val)
Purpose:
This routine gets a system configuration's limit on how many user processes can open the system.
Arguments:
1.
sconfig is a system configuration
2.
val is a pointer that gets filled with the configuration's
limit on the number of processes that can open the system.
Returns:
ET_OK
int et_system_config_setattachments (et_sysconfig sconfig, int
val)
Purpose:
This routine sets a system configuration's limit on how many user attachments to stations can exist at one time.
Arguments:
1.
sconfig is a system configuration
2.
val must be > 0 and <= ET_ATTACHMENTS_MAX
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not greater than zero or not <=
ET_ATTACHMENTS_MAX
Notes:
The default value of ET_ATTACHMENTS_MAX is 20 but may be changed in et_private.h, requiring a recompile of the ET system library.
int et_system_config_getattachments (et_sysconfig sconfig, int
*val)
Purpose:
This routine gets a system configuration's limit on how many user attachments to stations are possible.
Arguments:
1. sconfig is a system configuration
2. val is a pointer that gets
filled with the system configuration's limit on the number of attachments.
Returns:
ET_OK
int et_system_config_setfile (et_sysconfig
sconfig, int *val)
Purpose:
This routine sets a system configuration's ET system file name.
Arguments:
1.
sconfig is a system configuration
2.
val is a pointer to a string or null-terminated character array
containing the file name
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is NULL or too long
int et_system_config_getfile (et_sysconfig
sconfig, int *val)
Purpose:
This routine gets a system configuration's ET system file name
Arguments:
1.
sconfig is a system configuration
2.
val is a pointer to a char array that gets filled with the
system file name.
Returns:
ET_OK
int et_system_config_addmulticast (et_sysconfig sconfig, char *val)
Purpose:
This routine adds a multicast address to a list, each address of which the ET system is listening on for UDP packets from users trying to find it.
Arguments:
1. sconfig is an system configuration
2. val is a multicast IP address in
dotted-decimal form. There can be at most ET_MAXADDRESSES (defined in et_private.h
as 10) addresses on the list. Duplicate entries are not added to the list.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized, val
is NULL, is too long or too short, or its first number is not between 224 and
239 inclusive.
int et_system_config_removemulticast (et_sysconfig sconfig, char
*val)
Purpose:
This routine removes a multicast address from a list of addresses the ET system is listening on for UDP packets from users trying to find it.
Arguments:
1. sconfig is an system configuration
2. val is a multicast IP address in
dotted-decimal form. If there is no such address on the list, it is ignored.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized, val is NULL, is too long or too short, or its first
number is not between 224 and 239 inclusive.
DEPRECATED
int et_system_config_setcast (et_sysconfig sconfig, int
val)
Purpose:
This routine does nothing in this version of ET. It's here for backwards compatibility.
Arguments:
1. sconfig is a system configuration
2. val is any integer
Returns:
1.
ET_OK
DEPRECATED
int et_system_config_getcast (et_sysconfig sconfig, int
*val)
Purpose:
This routine does nothing in this version of ET. It's here for backwards compatibility.
Arguments:
1.
sconfig is a system configuration
2.
val is an integer pointer
Returns:
1. ET_OK
DEPRECATED
int et_system_config_setaddress (et_sysconfig sconfig, char
*val)
Purpose:
This routine is replaced by et_system_config_addmulticast. For compatibility purposes it is included though it is deprecated. Currently it adds a multicasting address to the appropriate list, each address of which the ET system is listening on for UDP packets from users trying to find it.
Arguments:
1.
sconfig is an system configuration
2.
val is a multicast IP address in dotted-decimal format.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized, val is NULL, is too long or too short, or its first
number is not between 224 and 239 inclusive
DEPRECATED
int et_system_config_getaddress (et_sysconfig sconfig, char
*val)
Purpose:
This routine has no replacement in this ET version and is included for compatibility purposes only, though it is deprecated. It returns the first multicast address listed unless there is none, in which case it returns the default IP subnet broadcast address. These are the destination addresses of the ET system discovery process.
Arguments:
1.
sconfig is an system configuration
2.
val is a character array that gets filled with the
dotted-decimal form IP address
Returns:
ET_OK
int et_system_config_setport (et_sysconfig sconfig,
unsigned short val)
Purpose:
This routine sets a system configuration's port number for the UDP broadcasting or multicasting used to discover this ET system by remote users.
Arguments:
1. sconfig is a system configuration
2. val is the port number of the broadcast
or multicast communications. The default is ET_BROADCAST_PORT, defined in et.h
as 11111. It may also be set to ET_MULTICAST_PORT or to any port number desired
by the user.
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is less than 1024
int et_system_config_getport (et_sysconfig sconfig, unsigned
short *val)
Purpose:
This routine gets a system configuration's port number for the UDP broadcasting or multicasting used to discover this ET system by remote users.
Arguments:
1. sconfig is a system configuration
2. val is a pointer that gets
filled with the port number
Returns:
ET_OK
int et_system_config_setserverport (et_sysconfig sconfig,
unsigned short val)
Purpose:
This routine sets a system configuration's TCP port number for the ET system (tcp server thread) used to communicate with remote users.
Arguments:
1. sconfig is a system configuration
2. val is the port number of the ET
system server for remote users
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is less than 1024
Notes:
If this routine is called and used to explicitly set the ET system's TCP port, it either uses that port or the ET system process exits with an error. If this routine is NOT called, the system tries to use ET_SERVER_PORT (defined in et.h as 11111) as its port. If that fails it adds one to that value and tries again and so on until a couple thousand values have been tried at which time the process exits if not successful.
int et_system_config_getserverport (et_sysconfig sconfig,
unsigned short *val)
Purpose:
This routine gets a system configuration's TCP port number for the ET system (tcp server thread) used to communicate with remote users.
Arguments:
1. sconfig is a system configuration
2. val is a pointer that gets
filled with the port number
Returns:
ET_OK
int et_system_config_setgroups (et_sysconfig sconfig, int
groups[], int size)
Purpose:
This routine sets a system configuration's number of event groups and how many events are in each group. To prevent ET clients who grab new events from competing with each other for these new events, an ET system can divide events into groups. The given array specifies how many events are in each group. Groups are numbered sequentially from 1 (corresponding to the element group[0]). Clients may either call et_system_setgroup to specify which group to get events from when calling et_event(s)_new, or clients may call et_event(s)_new_group to obtain new events from a specific group regardless of any default group set by et_system_setgroup.
Arguments:
1.
config is a system configuration
2.
group is the an array containing the
number of events in each group. The index into the array plus one gives the
group number. The first “size” number of elements must be positive
integers. The sum of the first “size” elements must equal the total
number of events in the system.
3.
size is the number of array elements
in group to be used.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized, group is
NULL, size > ET_EVENT_GROUPS_MAX, or size < 1
Event Functions
int et_event_new (et_sys_id id, et_att_id att,
et_event **pe, int wait, struct timespec *time, int size)
Purpose:
This routine is used when a user wants a blank or fresh event from the ET system into which it can place data.
Arguments:
1. id is the id of the ET system
of interest
2. att is the attachment id. This
is obtained by attaching the user process to a station with et_station_attach.
3. pe is a pointer to a pointer to
an event. Declare it a pointer to an event such as "et_event *pe;". And pass it as "&pe".
4. wait is either ET_SLEEP,
ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available
before it returns and therefore may "hang". The timed option returns
after a time set by the last argument. Finally, the async option returns
immediately whether or not it was successful in obtaining a new event for the
caller.
5. time is used only with the wait
= ET_TIMED option, where it gives the time to wait before returning. For other
options it will be ignored.
6. size is the number of bytes
desired for the event's data
Returns:
1. ET_OK if successful
2. ET_ERROR if bad argument(s),
attachment not active
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_REMOTE for a memory allocation
error of a remote user
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
7. ET_ERROR_DEAD if ET system is dead
8. ET_ERROR_WAKEUP if told to stop sleeping
while trying to get an event
9. ET_ERROR_TIMEOUT if timeout on ET_TIMED
option
10. ET_ERROR_BUSY if cannot get access to
events due to activity of other processes when in ET_ASYNC mode.
11. ET_ERROR_EMPTY if no events available in ET_ASYNC
mode
Notes:
Performance will generally be best with the ET_SLEEP wait mode. It will slow with ET_TIMED, and will crawl with ET_ASYNC. All this routine does for a remote client is allocate memory in which to place event data. The error of ET_ERROR_WAKEUP is returned when the ET system dies, or a user calls et_wakeup_all or et_wakeup_attachment on the attachment, while waiting to read an event
int et_events_new (et_sys_id
id, et_att_id att, et_event *pe[], int wait, struct timespec *time, int size,
int num, int *nread)
Purpose:
This routine is used when a user wants an array of blank or fresh events from the ET system into which it can place data.
Arguments:
1.
id is the id of the ET system of interest
2.
att is the attachment id. This is obtained by attaching the
user process to a station with et_station_attach.
3.
pe is an array of pointers to events.
4.
wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option
waits until an event is available before it returns and therefore may
"hang". The timed option returns after a time set by the last
argument. Finally, the async option returns immediately whether or not it was
successful in obtaining a new event for the caller.
5.
time is used only with the wait = ET_TIMED option,
where it gives the time to wait before returning. For other options it will be
ignored.
6.
size is the number of bytes desired for the event's data
7.
num is the number of desired events
8.
nread returns the number of events actually read
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad argument(s), attachment not active
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_REMOTE for a memory allocation error of a remote user
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
7.
ET_ERROR_DEAD if ET system is dead
8.
ET_ERROR_WAKEUP if told to stop sleeping while trying to get events
9.
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
10. ET_ERROR_BUSY if cannot get access to
events due to activity of other processes when in ET_ASYNC mode.
11. ET_ERROR_EMPTY if no events available in
ET_ASYNC mode
Notes:
See et_event_new. If all processes in an ET system use block transfers such as this one, a speed increase of over 10X the single transfer rate is possible.
int et_event_new_group (et_sys_id
id, et_att_id att, et_event **pe, int wait, struct timespec *time, int size,
int group)
Purpose:
This routine is used when a user wants a blank or fresh event from the ET system into which it can place data and that event must belong to the given group.
Arguments:
1.
id is the id of the ET system of interest
2.
att is the attachment id. This is obtained by attaching the
user process to a station with et_station_attach.
3.
pe is a pointer to a pointer to an event. Declare it a pointer
to an event such as "et_event *pe;". And
pass it as "&pe".
4.
wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option
waits until an event is available before it returns and therefore may
"hang". The timed option returns after a time set by the last
argument. Finally, the async option returns immediately whether or not it was
successful in obtaining a new event for the caller.
5.
time is used only with the wait = ET_TIMED option,
where it gives the time to wait before returning. For other options it will be
ignored.
6.
size is the number of bytes desired for the event's data
7.
group is the group number of event to be acquired
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad argument(s), attachment not active, group is < 1
or group > ET system’s highest group number
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_REMOTE for a memory allocation error of a remote user
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
7.
ET_ERROR_DEAD if ET system is dead
8.
ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event
9.
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
10. ET_ERROR_BUSY if cannot get access to
events due to activity of other processes when in ET_ASYNC mode.
11. ET_ERROR_EMPTY if no events available in
ET_ASYNC mode
Notes:
Performance will generally be best with the ET_SLEEP wait mode. It will slow with ET_TIMED, and will crawl with ET_ASYNC. All this routine does for a remote client is allocate memory in which to place event data. The error of ET_ERROR_WAKEUP is returned when the ET system dies, or a user calls et_wakeup_all or et_wakeup_attachment on the attachment, while waiting to read an event
int et_events_new_group (et_sys_id
id, et_att_id att, et_event *pe[], int wait, struct timespec *time, int size,
int num, int group, int *nread)
Purpose:
This routine is used when a user wants an array of blank or fresh events from the ET system into which it can place data and those events must belong to the given group.
Arguments:
1.
id is the id of the ET system of interest
2.
att is the attachment id. This is obtained by attaching the
user process to a station with et_station_attach.
3.
pe is an array of pointers to events.
4.
wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option
waits until an event is available before it returns and therefore may
"hang". The timed option returns after a time set by the last
argument. Finally, the async option returns immediately whether or not it was
successful in obtaining a new event for the caller.
5.
time is used only with the wait = ET_TIMED option,
where it gives the time to wait before returning. For other options it will be
ignored.
6.
size is the number of bytes desired for the event's data
7.
num is the number of desired events
8.
group is the group number of events to be acquired
9.
nread returns the number of events actually read
Returns:
1. ET_OK if successful
2. ET_ERROR if bad argument(s),
attachment not active, group is < 1 or group > ET system’s highest
group number
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_REMOTE for a memory allocation
error of a remote user
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
7. ET_ERROR_DEAD if ET system is dead
8. ET_ERROR_WAKEUP if told to stop sleeping
while trying to get events
9. ET_ERROR_TIMEOUT if timeout on ET_TIMED
option
10. ET_ERROR_BUSY if cannot get access to
events due to activity of other processes when in ET_ASYNC mode.
11. ET_ERROR_EMPTY if no events available in
ET_ASYNC mode
Notes:
See et_event_new. If all processes in an ET system use block transfers such as this one, a speed increase of over 10X the single transfer rate is possible.
int et_event_get (et_sys_id id, et_att_id att,
et_event **pe, int wait, struct timespec *time)
Purpose:
This routine is used when a user wants to read a single event from the ET system.
Arguments:
1. id is the id of the ET system
of interest
2. att is the attachment id.
3. pe is a pointer to a pointer to
an event. Declare it a pointer to an event such as "et_event *pe;". And pass it as "&pe".
4. wait is either ET_SLEEP,
ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available
before it returns and therefore may "hang". The timed option returns
after a time set by the last argument. Finally, the async option returns
immediately whether or not it was successful in obtaining a new event for the
caller. For remote users, the mentioned macros may be ORed with ET_MODIFY. This
indicates to the ET server that the user intends to modify the data and so the
server must NOT place the event immediately back into the ET system, but must
do so only when et_event_put is called.
5. time is used only with the wait
= ET_TIMED option, where it gives the time to wait before returning. For other
options it will be ignored.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_REMOTE for a memory allocation
error of a remote user
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
7. ET_ERROR_DEAD if ET system is dead
8. ET_ERROR_WAKEUP if told to stop sleeping
while trying to get an event
9. ET_ERROR_TIMEOUT if timeout on ET_TIMED
option
10. ET_ERROR_BUSY if cannot get access to
events due to activity of other processes when in ET_ASYNC mode.
11. ET_ERROR_EMPTY if no events available in
ET_ASYNC mode
Notes:
For remote users, not specifying ET_MODIFY greatly increases ET system efficiency as extra communication between user & system and extra copying of the event data are avoided. The error of ET_ERROR_WAKEUP is returned when the ET system dies, or a user calls et_wakeup_all or et_wakeup_attachment on the attachment, while waiting to get an event.
int et_events_get (et_sys_id
id, et_att_id att, et_event *pe[], int wait, struct timespec *time, int num,
int *nread)
Purpose:
This routine is used when a user wants to read multiple events from the ET system.
Arguments:
1. id is the id of the ET system
of interest
2. att is the attachment id.
3. pe is an array of pointers to
events.
4. wait is either ET_SLEEP,
ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available
before it returns and therefore may "hang". The timed option returns
after a time set by the last argument. Finally, the async option returns
immediately whether or not it was successful in obtaining a new event for the
caller. For remote users, the mentioned macros may be ORed with ET_MODIFY. This
indicates to the ET server that the user intends to modify the data and so the
server must NOT place the event immediately back into the ET system, but must
do so only when et_events_put is called.
5. time is used only with the wait
= ET_TIMED option, where it gives the time to wait before returning. For other
options it will be ignored.
6. num is the number of events
desired to be read.
7. nread returns the number of events
actually read
Returns:
1.
ET_OK, if successful
2.
ET_ERROR if error
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_REMOTE for a memory allocation error of a remote user
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
7.
ET_ERROR_DEAD if ET system is dead
8.
ET_ERROR_WAKEUP if told to stop sleeping while trying to get events
9.
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
10. ET_ERROR_BUSY if cannot get access to
events due to activity of other processes when in ET_ASYNC mode.
11. ET_ERROR_EMPTY if no events available in
ET_ASYNC mode
Notes:
See et_event_get. If all processes in an ET system use block transfers such as this one, a speed increase of over 2X the single transfer rate is possible.
int et_event_put (et_sys_id id, et_att_id att,
et_event *pe)
Purpose:
This routine is used when a user wants to return a single, previously read or new event into the ET system so processes downstream can use it or so it can be returned to GRAND_CENTRAL station.
Arguments:
1.
id is the id of the ET system of interest
2.
att is the attachment id.
3.
pe is a pointer to an event. Declare it as "et_event
*pe;", and pass it as "pe".
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
Notes:
Only the attachment (att) used to get an event can put that event into the ET system. If a process which did not get tries to put, an error will be returned. This is implemented in order to prevent a user from accidentally putting many identical events into the system thereby causing data and system corruption.
int et_events_put (et_sys_id
id, et_att_id att, et_event *pe[], int num)
Purpose:
This routine is used when a user wants to return multiple, previously read or new events into the ET system so processes downstream can use it or so it can be returned to GRAND_CENTRAL station.
Arguments:
1.
id is the id of the ET system of interest
2.
att is the attachment id.
3.
pe is an array of pointers to events.
4.
num is the number of events to be written.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_REMOTE for a memory allocation error of a remote user
6.
ET_ERROR_READ for a remote user's network read error
7.
ET_ERROR_WRITE for a remote user's network write error
Notes:
Only the attachment (att) used to get events can put those events into the ET system, otherwise an error will be returned. If any one of the events in the array is not owned by att, an error will result.
int et_event_dump (et_sys_id
id, et_att_id att, et_event *pe)
Purpose:
This routine is used when a user wants to get rid of a single, previously read or new event so that no user processes downstream will ever see it. It is placed directly into the ET system's GRAND_CENTRAL station which recycles it.
Arguments:
1. id is the id of the ET system
of interest
2. att is the attachment id.
3. pe is a pointer to an event.
Declare it as "et_event *pe;", and pass it as "pe".
Returns:
1. ET_OK if successful
2. ET_ERROR if error
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_events_dump (et_sys_id
id, et_att_id att, et_event *pe[], int num)
Purpose:
This routine is used when a user wants to get rid of multiple, previously read or new events so that no user processes downstream will ever see them. They are placed directly into the ET system's GRAND_CENTRAL station which recycles them.
Arguments:
1.
id is the id of the ET system of interest
2.
att is the attachment id.
3.
pe is an array of pointers to events.
4.
num is the number of events to be written.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_REMOTE for a memory allocation
error of a remote user
6. ET_ERROR_READ for a remote user's network
read error
7. ET_ERROR_WRITE for a remote user's network
write error
int et_event_getdata (et_event
*pe, void **data)
Purpose:
This routine gets the pointer to an event's data.
Arguments:
1.
pe is a pointer to event.
2.
data is a pointer to a pointer to the event's data
Returns:
1. ET_OK if successful
2. ET_ERROR if error
int et_event_getdatastatus (et_event
*pe, int *status)
Purpose:
This routine gets the status of an event's data.
Arguments:
1. pe is a pointer to event.
2. status is a pointer which gets
filled with the status of an event's data. The status can be ET_DATA_OK,
ET_DATA_CORRUPT, or ET_DATA_POSSIBLY_CORRUPT. Currently all data is ET_DATA_OK
unless a user's process exits or crashes while having events obtained from the
ET system but not put back. In that case, the ET system recovers the events and
places them in either GRAND_CENTRAL station, the attachment's station's input
list, or its output list depending on the station's configuration (see et_station_config_setrestore). If the
events are NOT put back into GRAND_CENTRAL station to be recycled but are
placed in the station's input or output list, the data status will become
ET_DATA_POSSIBLY_CORRUPT. This simply warns the user that a process previously
crashed with the event and may have corrupted its data.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
int et_event_setlength (et_event
*pe, int len)
Purpose:
This routine records the length of data written into an event.
Arguments:
1.
pe is a pointer to event.
2.
len is the length in bytes of data written into the event.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if len is negative or bigger than the size of the memory
buffer
int et_event_getlength (et_event
*pe, int *len)
Purpose:
This routine gets the length of data written into an event in bytes.
Arguments:
1.
pe is a pointer to event.
2.
len is a pointer which gets filled with the length in bytes of
data written into the event.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
int et_event_setpriority (et_event
*pe, int pri)
Purpose:
This routine sets the priority of an event.
Arguments:
1.
pe is a pointer to event.
2.
pri is the priority of either ET_HIGH or ET_LOW.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
int et_event_getpriority (et_event
*pe, int *pri)
Purpose:
This routine gets the priority of an event.
Arguments:
1. pe is a pointer to event.
2. pri is a pointer which gets
filled with the priority of the event.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
int et_event_setcontrol (et_event
*pe, int con[], int num)
Purpose:
This routine sets the control array of an event.
Arguments:
1.
pe is a pointer to event.
2.
con is an integer array.
3.
num is the number of elements in the array.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
int et_event_getcontrol (et_event
*pe, int con[])
Purpose:
This routine gets the control array of an event.
Arguments:
1. pe is a pointer to event.
2. con is an integer array with at
least ET_STATION_SELECT_INTS number of elements.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
int et_event_setendian (et_event
*pe, int endian)
Purpose:
This routine sets the endian value of an event's data. Although an ET system automatically keeps track of the endianness of an event's data, this routine can override and directly set it.
Arguments:
1.
pe is a pointer to event.
2.
endian may be set to ET_ENDIAN_BIG, ET_ENDIAN_LITTLE,
ET_ENDIAN_LOCAL (same endian as local host), ET_ENDIAN_NOTLOCAL (opposite
endian as local host), or ET_ENDIAN_SWITCH (switch the endian from whatever it
is).
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
int et_event_getendian (et_event
*pe, int *endian)
Purpose:
This routine returns the endian value of an event's data.
Arguments:
1. pe is a pointer to event.
2. endian is a pointer which gets
filled with the either ET_ENDIAN_BIG or ET_ENDIAN_LITTLE.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
int et_event_needtoswap (et_event
*pe, int *swap)
Purpose:
This routine indicates whether an event's data needs to be swapped or not.
Arguments:
1.
pe is a pointer to event.
2.
swap is a pointer which gets filled in with either ET_SWAP or
ET_NOSWAP.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
DEPRECATED
int et_event_CODAswap (et_event
*pe)
Purpose:
This routine now does nothing and returns an error. It did an incomplete job of swapping evio data. To swap data properly, use the evio library’s provided function, void evioswap(uint32_t *buffer, int tolocal, uint32_t*dest), where if tolocal = 0, buffer contains data of same endian as local host, else buffer has data of opposite endian.
Arguments:
1. pe is a pointer to event.
Returns:
1. ET_ERROR
Station Functions
int et_station_create_at (et_sys_id id, et_stat_id *stat_id, char *stat_name,
et_stat_config sconfig, int position, int parallelposition)
Purpose:
This routine creates a station provided that it does not already exist and the maximum number of stations has not been reached. The station's status is set to ET_STATION_IDLE. This changes to ET_STATION_ACTIVE when a process attaches to it. The ET system is immediately notified of the new station upon creation and will transfer events in and out as soon as it is active. It is placed at in the linked list of stations in the position given by the last argument or at the end if that argument is larger than the existing number of stations. The station may already exist, but if it has the same configuration, the id of the existing station is returned.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is a pointer to a station id number and returns the value
of the newly created station's id.
3.
stat_name is the station name
4.
sconfig is a station configuration handle
5.
position is the position of the newly created station in the linked
list of stations. It may have the value ET_END which specifies the end of that
list. It may not have the value of zero which is the first position
and reserved for GRAND_CENTRAL station.
6.
parallelposition is the position of the newly created station in the linked
list of 1 group of parallel stations. It may have the value ET_END which
specifies the end of that group. It may also have the value of ET_HEAD which
specifies that a new group of parallel stations is being created and this is
its head. However, if the head already exists, it may not have the
value of zero, which is the first position, so that any existing head is never
moved.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_EXISTS if station already exists
and has a different configuration (stat_id is still set to the
existing station's id)
6. ET_ERROR_TOOMANY if the maximum number of
stations already exist
7. ET_ERROR_REMOTE for a memory allocation
error of a remote user
8. ET_ERROR_READ for a remote user's network
read error
9. ET_ERROR_WRITE for a remote user's network
write error
int et_station_create (et_sys_id
id, et_stat_id *stat_id, char *stat_name, et_stat_config sconfig)
Purpose:
This routine creates a station provided that it does not already exist and the maximum number of stations has not been reached. The station's status is set to ET_STATION_IDLE. This changes to ET_STATION_ACTIVE when a process attaches to it. The ET system is immediately notified of the new station upon creation and will transfer events in and out as soon as it is active. Its position is at the end of the linked list of stations. The station may already exist, but if it has the same configuration, the id of the existing station is returned.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is a pointer to a station id number and returns the value
of the newly created station's id.
3.
stat_name is the station name
4.
sconfig is a station configuration handle
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_EXISTS if station already exist and has a different configurations
(stat_id is still set to the existing station's id)
6.
ET_ERROR_TOOMANY if the maximum number of stations already exist
7.
ET_ERROR_REMOTE for a memory allocation error of a remote user
8.
ET_ERROR_READ for a remote user's network read error
9.
ET_ERROR_WRITE for a remote user's network write error
int et_station_remove (et_sys_id
id, et_stat_id stat_id)
Purpose:
This routine deletes a station provided it is not GRAND_CENTRAL and provided there are no attached processes. The station's status is set to ET_STATION_UNUSED.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_attach (et_sys_id
id, et_stat_id stat_id, et_att_id *att)
Purpose:
This routine will attach the user to a station - meaning that the user is free to read and write events from that station or to request new events. It returns a unique attachment id in the second argument which is to be used in all transactions with the station.
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is the station's id number
3. att is a pointer to a attachment
id which gets filled in by this routine.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_TOOMANY if the existing number of attachments is already equal to
the station or system limit
5.
ET_ERROR_DEAD if ET system is dead
6.
ET_ERROR_REMOTE for a memory allocation error of a remote user
7.
ET_ERROR_READ for a remote user's network read error
8.
ET_ERROR_WRITE for a remote user's network write error
Notes:
When a user process attaches to a station, it is marked as an active station, which means it will start receiving events. To remove an attachment, call the routine et_station_detach.
int et_station_detach (et_sys_id
id, et_att_id att)
Purpose:
This routine will detach a user attachment from a station meaning that the process can no longer read or write events from that station. It undoes what et_station_attach does.
Arguments:
1. id is the id of the ET system
of interest
2. att is the attachment id.
Returns:
1. ET_OK if successful
2. ET_ERROR if error
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
Notes:
If this routine detaches the last attachment to a station, it marks the station as idle. In other words, the station stops receiving events since no one is there to read them. All events remaining in the station's input list (after the detachment) will be moved to the output list and sent to other stations. One must detach all attachments to a station before the station can be removed.
int et_station_getposition (et_sys_id
id, et_stat_id stat_id, int *position, int *parallelposition)
Purpose:
Gets the value of a station's position in the linked list of active and idle stations and its position within a group of parallel stations if it is one..
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is the station's id number.
3. position is a pointer which gets
filled in with the position
4.
parallelposition is a pointer which gets filled in with the
parallel position, but only if it is a parallel station
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is unused or bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_setposition (et_sys_id
id, et_stat_id stat_id, int position, int parallelposition)
Purpose:
Sets a station's position in the linked list of active and idle stations and the position within a group of parallel stations if it is one.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number. GRAND_CENTRAL station's
position may not be changed.
3.
position is the position in the linked list of stations and must be
greater than 0 as the first position (0) is reserved for GRAND_CENTRAL station.
It may be ET_END to put it at the end of the list.
4.
parallelposition is the position within the group of a linked list of
stations if it is one. It may be ET_HEAD to make it the head of a new group of
parallel stations. It may be ET_END to put it at the end. If the position parameter refers to an
existing parallel station, this may be any value > 0 as it may not take the
place of an existing head. Its configuration must also be compatible with
existing parallel stations in the group.
Returns:
1. ET_OK if successful
2. ET_ERROR if station is GRAND_CENTRAL
or if bad stat_id or position argument values
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_isattached (et_sys_id
id, et_stat_id stat_id, et_att_id att)
Purpose:
Is att attached to station stat_id?
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is the station's id number.
3. att is the attachment id.
Returns:
1.
1
if attached
2.
0
if not attached
3.
ET_ERROR for bad argument(s)
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_exists (et_sys_id
id, et_stat_id *stat_id, char *stat_name)
Purpose:
Given the name of a station, this routine tells whether the station exists or not. If it does, it gives a its id.
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is a pointer to a station id
which is filled if stat_name exists.
3. stat_name is the station name
Returns:
1. 1 if station exists
2. 0 if station does not exist
3. ET_ERROR for bad stat_name
argument
4. ET_ERROR_CLOSED if et_close already called
5. ET_ERROR_DEAD if ET system is dead.
6. ET_ERROR_REMOTE for a memory allocation
error of a remote user
7. ET_ERROR_READ for a remote user's network
read error
8. ET_ERROR_WRITE for a remote user's network
write error
int et_station_name_to_id (et_sys_id
id, et_stat_id *stat_id, char *stat_name)
Purpose:
Given the name of a station, this routine will return its id.
Arguments:
1.
id is the ET system id
2.
stat_id is a pointer that get filled in with the station's id
number.
3.
stat_name is the station name
Returns:
1.
ET_OK
2.
ET_ERROR if no station by that name exists or stat_name is
null
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_REMOTE for a memory allocation error of a remote user
6.
ET_ERROR_READ for a remote user's network read error
7.
ET_ERROR_WRITE for a remote user's network write error
int et_station_getattachments (et_sys_id
id, et_stat_id stat_id, int *numatts)
Purpose:
Gives the number of attachments to a station. This returns an error for unused stations.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
numatts is a pointer to int which gets filled in with the number of
attachments
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is unused or bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_getstatus (et_sys_id
id, et_stat_id stat_id, int *status)
Purpose:
Return a station's status.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
status is a pointer which gets filled in with the status of the
station
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead.
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_getinputcount (et_sys_id
id, et_stat_id stat_id, int *cnt)
Purpose:
Gives the number of events in a station's input list. This number changes rapidly and is likely to be out-of-date immediately.
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is the station's id number.
3. cnt is a pointer to int which
gets filled in with the number of events in the station's input list
Returns:
1. ET_OK if successful
2. ET_ERROR if bad stat_id
argument
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead.
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_getoutputcount (et_sys_id
id, et_stat_id stat_id, int *cnt)
Purpose:
Gives the number of events in a station's output list. This number changes rapidly and is likely to be out-of-date immediately.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
cnt is a pointer which gets filled in with the number of events
in the station's output list
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead.
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_getblock (et_sys_id
id, et_stat_id stat_id, int *block)
Purpose:
Gets the value of a station's blocking mode - whether all events pass through the station (blocking) or whether only a fixed size cue of events is filled with others by-passing the station..
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is the station's id number.
3. block is a pointer which gets
filled in with the blocking mode
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is unused or bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_setblock (et_sys_id
id, et_stat_id stat_id, int block)
Purpose:
Sets a station's blocking mode. Determines whether all events pass through the station (blocking) or whether only a fixed size cue of events is filled while all others by-pass the station..
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is the station's id number.
3. block must be either
ET_STATION_BLOCKING or ET_STATION_NONBLOCKING
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or block
argument values
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_getuser (et_sys_id
id, et_stat_id stat_id, int *user)
Purpose:
Gets the value of a station's user mode - the limit of how many users can attach to the station at one time.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
user is a pointer which gets filled in with the user mode
Returns:
1. ET_OK if successful
2. ET_ERROR if station is unused or bad stat_id
argument
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_setuser (et_sys_id
id, et_stat_id stat_id, int user)
Purpose:
Sets a station's user mode. Determines the limit of how many users can attach to the station at one time.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
user must be either ET_STATION_USER_MULTI,
ET_STATION_USER_SINGLE, or a non-negative integer.
Returns:
1. ET_OK if successful
2. ET_ERROR if station is GRAND_CENTRAL
or if bad stat_id or user argument values
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_getrestore (et_sys_id
id, et_stat_id stat_id, int *restore)
Purpose:
Gets the value of a station's restore mode - whether, after an attached user process crashes, the events currently owned by that attachment are restored to the station's output list, input list, or to GRAND_CENTRAL station's input list.
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is the station's id number.
3. restore is a pointer which gets filled
in with the restore mode
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is unused or bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_setrestore (et_sys_id
id, et_stat_id stat_id, int restore)
Purpose:
Sets a station's restore mode. Determines whether, after an attached user process crashes, the events currently owned by that attachment are restored to the station's output list, input list, or to GRAND_CENTRAL station's input list.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
restore must be either ET_STATION_RESTORE_OUT,
ET_STATION_RESTORE_IN, or ET_STATION_RESTORE_GC.
Returns:
1. ET_OK if successful
2. ET_ERROR if station is GRAND_CENTRAL
or if bad stat_id or restore argument values
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_getcue (et_sys_id
id, et_stat_id stat_id, int *cue)
Purpose:
Gets a station's cue value - the size of the input event list for nonblocking stations.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
cue is a pointer which gets filled in with the cue value
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is unused or bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_setcue (et_sys_id
id, et_stat_id stat_id, int cue)
Purpose:
Sets a station's cue size. For a nonblocking station, the size of the input event cue (list) is set.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
cue must be an integer from 1 to the total number of events in
the system.
Returns:
1. ET_OK if successful
2. ET_ERROR if station is GRAND_CENTRAL
or if bad stat_id or cue argument values
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_getprescale (et_sys_id
id, et_stat_id stat_id, int *prescale)
Purpose:
Gets a station's prescale value - the selection of every Nth event in blocking stations.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
prescale is a pointer which gets filled in with the prescale value
Returns:
1. ET_OK if successful
2. ET_ERROR if station is unused or bad stat_id
argument
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_setprescale (et_sys_id
id, et_stat_id stat_id, int prescale)
Purpose:
Sets a station's prescale value, thereby selecting every Nth event in blocking stations.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
prescale must be an integer greater than 0.
Returns:
1. ET_OK if successful
2. ET_ERROR if station is GRAND_CENTRAL
or if bad stat_id or prescale argument values
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_getlib (et_sys_id
id, et_stat_id stat_id, char *lib)
Purpose:
Gets the name of the shared library containing an event selection function provided by the user.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
lib is a character array which gets filled in with the lib name
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is unused or bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
Notes:
A station has a shared library name associated with it only in the ET_STATION_SELECT_USER select mode in which the user supplies his own function to select events.
int et_station_getfunction (et_sys_id
id, et_stat_id stat_id, char *function)
Purpose:
Gets the name of the user-defined selection function provided when using the ET_STATION_SELECT_USER select mode.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
function is a character array which gets filled in with the function
name
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is unused or bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
Notes:
A station has a function name associated with it only in the ET_STATION_SELECT_USER select mode in which the user supplies his own function to select events.
int et_station_getclass (et_sys_id
id, et_stat_id stat_id, char *class)
Purpose:
For Java ET systems, gets the class containing the event selection method provided by the user.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
class is a character array which gets filled in with the class
name
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is unused or bad stat_id argument
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
Notes:
A station has a function name associated with it only in the ET_STATION_SELECT_USER select mode in which the user supplies his own function to select events.
int et_station_getselectwords (et_sys_id
id, et_stat_id stat_id, int select[])
Purpose:
Gets a station's array of selection integers (words) used to select events.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
select is an integer array with at least ET_STATION_SELECT_INTS
number of elements which gets filled in with the station's selection array
Returns:
1. ET_OK if successful
2. ET_ERROR if station is unused or bad stat_id
argument
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
int et_station_setselectwords (et_sys_id
id, et_stat_id stat_id, int select[])
Purpose:
Sets a station's array of selection integers (words) used to select events.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
select is an integer array that must have at least
ET_STATION_SELECT_INTS number of elements.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or select
argument values
3.
ET_ERROR_CLOSED if et_close already called
4.
ET_ERROR_DEAD if ET system is dead
5.
ET_ERROR_READ for a remote user's network read error
6.
ET_ERROR_WRITE for a remote user's network write error
int et_station_getselect (et_sys_id
id, et_stat_id stat_id, int *select)
Purpose:
Gets the value of a station's select mode.
Arguments:
1.
id is the id of the ET system of interest
2.
stat_id is the station's id number.
3.
select is a pointer which gets filled in with the select mode
Returns:
1. ET_OK if successful
2. ET_ERROR if station is unused or bad stat_id
argument
3. ET_ERROR_CLOSED if et_close already called
4. ET_ERROR_DEAD if ET system is dead
5. ET_ERROR_READ for a remote user's network
read error
6. ET_ERROR_WRITE for a remote user's network
write error
Station
Configuration Functions
int et_station_config_init (et_statconfig*
sconfig)
Purpose:
This routine initializes a station configuration. This MUST be done prior to setting any configuration parameters or all setting routines will return an error.
Arguments:
sconfig is pointer to a station configuration variable
Returns:
1. ET_OK if successful
2. ET_ERROR if it fails to allocate
memory for configuration data storage
int et_station_config_destroy (et_statconfig
sconfig)
Purpose:
This routine frees the memory allocating when a configuration is initialized by et_station_config_init.
Arguments:
sconfig is a station configuration
Returns:
ET_OK
int et_station_config_setblock (et_statconfig
sconfig, int val)
Purpose:
This routine sets a station configuration's block mode.
Arguments:
1. sconfig is a station configuration
2. val must be either
ET_STATION_BLOCKING or ET_STATION_NONBLOCKING
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized or val is not one of the allowed values
int et_station_config_getblock (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's current block mode value.
Arguments:
1.
sconfig is a station configuration
2.
val is a pointer that gets filled with the current value of the
configuration block mode
Returns:
ET_OK
int et_station_config_setselect (et_statconfig
sconfig, int val)
Purpose:
This routine sets a station configuration's select mode.
Arguments:
1.
sconfig is a station configuration
2.
val must be either ET_STATION_SELECT_ALL or
ET_STATION_SELECT_MATCH, or ET_STATION_SELECT_USER
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not one of the allowed values
int et_station_config_getselect (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's current select mode value.
Arguments:
1.
sconfig is a station configuration
2.
val is a pointer that gets filled with the current value of the
configuration select mode
Returns:
ET_OK
int et_station_config_setuser (et_statconfig
sconfig, int val)
Purpose:
This routine sets a station configuration's user mode.
Arguments:
1. sconfig is a station configuration
2. val must be either
ET_STATION_USER_MULTI or ET_STATION_USER_SINGLE
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not one of the allowed values
int et_station_config_getuser (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's current user mode value.
Arguments:
1. sconfig is a station configuration
2. val is a pointer that gets
filled with the current value of the configuration user mode
Returns:
ET_OK
int et_station_config_setrestore (et_statconfig
sconfig, int val)
Purpose:
This routine sets a station configuration's restore mode.
Arguments:
1.
sconfig is a station configuration
2.
val must be either ET_STATION_RESTORE_OUT or
ET_STATION_RESTORE_IN, or ET_STATION_RESTORE_GC
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not one of the allowed values
int et_station_config_getrestore (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's current restore mode value.
Arguments:
1. sconfig is a station configuration
2. val is a pointer that gets
filled with the current value of the configuration restore mode
Returns:
ET_OK
int et_station_config_setcue (et_statconfig
sconfig, int val)
Purpose:
This routine sets the size of a station configuration's input list cue when the block mode is ET_STATION_NONBLOCKING.
Arguments:
1.
sconfig is a station configuration
2.
val must be greater than zero
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not an allowed value
Notes:
The value of the cue must not exceed the total number of events in the system. This is not checked until a station is created with this configuration - at which time cue is set to the total number of events in the system if it is set too high in this routine. Take notice that setting the value of the cue to the total # of events will, in essence, change the station into one which blocks (block mode of ET_STATION_BLOCKING). The reason for this is that all events will now pass through this station.
int et_station_config_getcue (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's current cue value.
Arguments:
1.
sconfig is a station configuration
2.
val is a pointer that gets filled with the current cue value
Returns:
ET_OK
int et_station_config_setprescale (et_statconfig
sconfig, int val)
Purpose:
This routine sets the station configuration's prescale when the block mode is ET_STATION_BLOCKING.
Arguments:
1.
sconfig is a station configuration
2.
val must be greater than zero
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not an allowed value
int et_station_config_getprescale (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's current prescale value.
Arguments:
1.
sconfig is a station configuration
2.
val is a pointer that gets filled with the current prescale
value
Returns:
ET_OK
int et_station_config_setselectwords (et_statconfig sconfig, int
val[])
Purpose:
This routine sets the values of integers in the station configuration's array used to select events.
Arguments:
1.
sconfig is a station configuration
2.
val is an array of integers with at least
ET_STATION_SELECT_INTS number of elements.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized
int et_station_config_getselectwords (et_statconfig sconfig, int
val[])
Purpose:
This routine gets a station configuration's current select values.
Arguments:
1.
sconfig is a station configuration
2.
val is an array with at least ET_STATION_SELECT_INTS number of
elements that gets filled with the current select values
Returns:
ET_OK
int et_station_config_setlib (et_statconfig
sconfig, int *val)
Purpose:
This routine sets the value of a station configuration's shared library name - used for loading a user's function to select events.
Arguments:
1.
sconfig is a station configuration
2.
val is a pointer to a string or null-terminated char array
containing the shared library name
Returns:
1. ET_OK
2. ET_ERROR if the sconfig was
not initialized, or val is NULL, or val is too long
int et_station_config_getlib (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's current shared library name.
Arguments:
1.
sconfig is a station configuration
2.
val is a pointer to a char array that gets filled with the
current shared library name
Returns:
ET_OK
int et_station_config_setfunction (et_statconfig
sconfig, int *val)
Purpose:
This routine sets the value of a station configuration's function name - loaded from the shared library and used for allowing the user to select events.
Arguments:
1.
sconfig is a station configuration
2.
val is a pointer to a string or null-terminated char array
containing the function name
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized, or val
is NULL, or val is too long
int et_station_config_getfunction (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's current function name.
Arguments:
1. sconfig is a station configuration
2. val is a pointer to a char array
that gets filled with the current function's name
Returns:
ET_OK
int et_station_config_setclass (et_statconfig
sconfig, int *val)
Purpose:
This routine sets the value of a station configuration's Java class name - used for loading a user's method to select events. Of course, this is applicable only when creating a station on a Java-based ET system.
Arguments:
1.
sconfig is a station configuration
2.
val is a pointer to a string or null-terminated char array
containing the class name
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized, or val
is NULL, or val is too long
int et_station_config_getclass (et_statconfig
sconfig, int *val)
Purpose:
This routine gets a station configuration's Java class name. Of course, this is only applicable for stations on a Java-based ET system.
Arguments:
1. sconfig is a station configuration
2. val is a pointer to a char array
that gets filled with the current class name
Returns:
ET_OK
Attachment
Functions
int et_wakeup_attachment (et_sys_id
id, et_att_id att)
Purpose:
This routine will wake up a single attachment that is blocked, waiting to read events from a station.
Arguments:
1.
id is the id of the ET system of interest
2.
att is the attachment id.
Returns:
1. ET_OK if successful
2. ET_ERROR if bad att argument
3. ET_ERROR_WRITE if a remote user's network write
error
int et_wakeup_all (et_sys_id
id, et_stat_id stat_id)
Purpose:
This routine will wake up all attachments that are blocked, waiting to read events from a station.
Arguments:
1. id is the id of the ET system
of interest
2. stat_id is the station's id number.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad stat_id argument
3.
ET_ERROR_WRITE if a remote user's network write error
int et_attach_geteventsput (et_sys_id
id, et_att_id att_id, int *highint, int *lowint)
Purpose:
This routine gets the number of events put into a station by an attachment. The number is returned in 2 integers for a total of 64 bits.
Arguments:
1. id is the id of the ET system
of interest
2. att_id is the attachment's id
number.
3. highint is a pointer which gets
filled in with the most significant 32 bits.
4. lowint is a pointer which gets
filled in with the least significant 32 bits.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad att_id argument
3.
ET_ERROR_DEAD if ET system is dead.
4.
ET_ERROR_READ for a remote user's network read error
5.
ET_ERROR_WRITE for a remote user's network write error
int et_attach_geteventsget (et_sys_id
id, et_att_id att_id, int *highint, int *lowint)
Purpose:
This routine gets the number of events gotten from a station by an attachment. The number is returned in 2 integers for a total of 64 bits.
Arguments:
1.
id is the id of the ET system of interest
2.
att_id is the attachment's id number.
3.
highint is a pointer which gets filled in with the most significant
32 bits.
4.
lowint is a pointer which gets filled in with the least
significant 32 bits.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad att_id argument
3.
ET_ERROR_DEAD if ET system is dead.
4.
ET_ERROR_READ for a remote user's network read error
5.
ET_ERROR_WRITE for a remote user's network write error
int et_attach_geteventsdump (et_sys_id
id, et_att_id att_id, int *highint, int *lowint)
Purpose:
This routine gets the number of events dumped by an attachment. The number is returned in 2 integers for a total of 64 bits.
Arguments:
1.
id is the id of the ET system of interest
2.
att_id is the attachment's id number.
3.
highint is a pointer which gets filled in with the most significant
32 bits.
4.
lowint is a pointer which gets filled in with the least
significant 32 bits.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad att_id argument
3.
ET_ERROR_DEAD if ET system is dead.
4.
ET_ERROR_READ for a remote user's network read error
5.
ET_ERROR_WRITE for a remote user's network write error
int et_attach_geteventsmake (et_sys_id
id, et_att_id att_id, int *highint, int *lowint)
Purpose:
This routine gets the number of new events gotten from a station by an attachment. The number is returned in 2 integers for a total of 64 bits.
Arguments:
1.
id is the id of the ET system of interest
2.
att_id is the attachment's id number.
3.
highint is a pointer which gets filled in with the most significant
32 bits.
4.
lowint is a pointer which gets filled in with the least significant
32 bits.
Returns:
1.
ET_OK if successful
2.
ET_ERROR if bad att_id argument
3.
ET_ERROR_DEAD if ET system is dead.
4.
ET_ERROR_READ for a remote user's network read error
5.
ET_ERROR_WRITE for a remote user's network write error
Bridge Functions
int et_events_bridge (et_sys_id id_from,
et_sys_id id_to, et_att_id att_from, et_att_id att_to, et_bridgeconfig bconfig,
int num, int *ntransferred)
Purpose:
This routine transfers events between two ET systems. Events are copied from the "from" ET system and placed into the "to" ET system. A function may be provided to swap the data during the transfer.
Arguments:
1. id_from is the ID of the ET system
from which the events are copied
2. id_to is the ID of the ET system
in which the events are placed
3. att_from is the attachment to a
station on the "from" ET system
4. att_to is the attachment to a
station on the "to" ET system (usually GRAND_CENTRAL)
5. bconfig is the configuration of the
remaining transfer parameters
6. num is the total number of
events desired to be transferred
7. ntransferred is the total number of
events that were actually transferred at the routine's return
Returns:
1.
ET_OK if successful
2.
ET_ERROR if error
3.
ET_ERROR_REMOTE for a memory allocation error of a remote user
4.
ET_ERROR_READ for a remote user's network read error
5.
ET_ERROR_WRITE for a remote user's network write error
6.
ET_ERROR_DEAD if ET system is dead
7.
ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event
8.
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
9.
ET_ERROR_BUSY if cannot get access to events due to activity of other
processes when in ET_ASYNC mode.
10. ET_ERROR_EMPTY if no events available in
ET_ASYNC mode
Notes:
For the best performance, the process calling this routine should be on the same machine as either the "from" or "to" ET systems. Some experimentation is in order to determine which of the two machines will run the bridging faster. The author's experience suggests that placing the process on the machine with the most processors or computing power will probably give the best results.
int et_bridge_config_init (et_bridgeconfig *config)
Purpose:
This routine initializes a configuration used by the routine et_events_bridge in transferring events between two ET systems. This MUST be done prior to setting any configuration parameters or all setting routines will return an error.
Arguments:
config is pointer to an bridge configuration variable
Returns:
1.
ET_OK if successful
2.
ET_ERROR if it fails to allocate memory for configuration data
storage
int et_bridge_config_destroy (et_bridgeconfig config)
Purpose:
This routine frees the memory allocated when a configuration is initialized by et_bridge_config_init.
Arguments:
config is an bridge configuration
Returns:
ET_OK
int et_bridge_config_setmodefrom (et_bridgeconfig
config, int val)
Purpose:
This routine sets the mode of getting events from the "from" ET system.
Arguments:
1. config is a bridge configuration
2. val is set to either ET_SLEEP,
ET_TIMED, or ET_ASYNC and determines the mode of getting events from the
"from" ET system. The default is ET_SLEEP.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not ET_SLEEP, ET_TIMED, or ET_ASYNC
int et_bridge_config_getmodefrom
(et_bridgeconfig config, int *val)
Purpose:
This routine gets the mode of getting events from the "from" ET system.
Arguments:
1.
config is a bridge configuration
2.
val is a pointer that gets filled with ET_SLEEP, ET_TIMED, or
ET_ASYNC
Returns:
ET_OK
int et_bridge_config_setmodeto (et_bridgeconfig
config, int val)
Purpose:
This routine sets the mode of getting new events from the "to" ET system.
Arguments:
1.
config is a bridge configuration
2.
val is set to either ET_SLEEP, ET_TIMED, or ET_ASYNC and
determines the mode of getting new events from the "to" ET system. The
default is ET_SLEEP.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
is not ET_SLEEP, ET_TIMED, or ET_ASYNC
int et_bridge_config_getmodeto (et_bridgeconfig config, int
*val)
Purpose:
This routine gets the mode of getting new events from the "to" ET system.
Arguments:
1.
config is a bridge configuration
2.
val is a pointer that gets filled with ET_SLEEP, ET_TIMED, or
ET_ASYNC
Returns:
ET_OK
int et_bridge_config_setchunkfrom (et_bridgeconfig
config, int val)
Purpose:
This routine sets the maximum number of events to get from the "from" ET system in a single call to et_events_get - the number of events to get in one chunk.
Arguments:
1.
config is a bridge configuration
2.
val is any integer greater than one. The default is 100.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
less than one
int et_bridge_config_getchunkfrom (et_bridgeconfig config, int *val)
Purpose:
This routine gets the maximum number of events to get from the "from" ET system in a single call to et_events_get.
Arguments:
1.
config is a bridge configuration
2.
val is a pointer that gets filled with the number
Returns:
ET_OK
int et_bridge_config_setchunkto (et_bridgeconfig
config, int val)
Purpose:
This routine sets the maximum number of new events to get from the "to" ET system in a single call to et_events_new - the number of events to get in one chunk.
Arguments:
1. config is a bridge configuration
2. val is any integer greater than
one. The default is 100.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized or val
less than one
int et_bridge_config_getchunkto
(et_bridgeconfig config, int *val)
Purpose:
This routine gets the maximum number of new events to get from the "to" ET system in a single call to et_events_new.
Arguments:
1. config is a bridge configuration
2. val is a pointer that gets
filled with the number
Returns:
ET_OK
int et_bridge_config_settimeoutfrom (et_bridgeconfig config,
struct timespec val)
Purpose:
This routine sets the time to wait for the "from" ET system during all et_events_get calls when the mode is set to ET_TIMED.
Arguments:
1.
config is a bridge configuration
2.
val is the time to wait. The default is 0 seconds.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized
int et_bridge_config_gettimeoutfrom (et_bridgeconfig config,
struct timespec *val)
Purpose:
This routine gets the time to wait for the "from" ET system during all et_events_get calls when the mode is set to ET_TIMED.
Arguments:
1.
config is a bridge configuration
2.
val is a pointer that gets filled with the time
Returns:
ET_OK
int et_bridge_config_settimeoutto (et_bridgeconfig
config, struct timespec val)
Purpose:
This routine sets the time to wait for the "to" ET system during all et_events_new calls when the mode is set to ET_TIMED.
Arguments:
1.
config is a bridge configuration
2.
val is the time to wait. The default is 0 seconds.
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized
int et_bridge_config_gettimeoutto (et_bridgeconfig config, struct timespec *val)
Purpose:
This routine gets the time to wait for the "to" ET system during all et_events_new calls when the mode is set to ET_TIMED.
Arguments:
1.
config is a bridge configuration
2.
val is a pointer that gets filled with the time
Returns:
ET_OK
int et_bridge_config_setfunc (et_bridgeconfig
config, ET_SWAP_FUNCPTR func)
Purpose:
This routine sets the function used to automatically swap data from one endian to another when bridging events between two ET systems.
Arguments:
1.
config is a bridge configuration
2.
func is the name of the function or function pointer. The
default is NULL (no swapping).
Returns:
1.
ET_OK
2.
ET_ERROR if the sconfig was not initialized
Notes:
The function must be of the form: int func(et_event *src, et_event *dest, int bytes, int same_endian) . It returns ET_OK if successful otherwise ET_ERROR. The arguments consists of: src which is a pointer to the event whose data is to be swapped, dest which is a pointer to the event where the swapped data goes, bytes which tells the length of the data in bytes, and same_endian which is a flag equalling one if the machine and the data are of the same endian and zero otherwise. This function must be able to work with src and dest being the same event. With this as a prototype, the user can write a routine which swaps data in the appropriate manner. Notice that the first two arguments are pointers to events and not data buffers. This allows the writer of such a routine to have access to any of the event's header information. In general, such functions should NOT call et_event_setendian in order to change the registered endian value of the data. This is already taken care of in et_events_bridge.
DEPRECATED
int et_bridge_CODAswap (et_event *src, et_event
*dest, int bytes, int same_endian)
Purpose:
This routine now does nothing and returns an error. It did an incomplete job of swapping evio data. To swap data properly, use the evio library’s provided function, void evioswap(uint32_t *buffer, int tolocal, uint32_t*dest), where if tolocal = 0, buffer contains data of same endian as local host, else buffer has data of opposite endian.
This function was used as an argument in the routine et_bridge_config_setfunc to provide automatic swapping of CODA format data when bridging events between two ET systems.
Arguments:
1. src is a pointer to an event
whose data is to be swapped
2. dest is a pointer to an event
where the swapped data goes
3. bytes is the length of the data in
bytes
4. same_endian is a flag equaling one if
the machine and the data are of the same endian and zero otherwise
Returns:
1.
ET_ERROR
