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:

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.
filename is the unique filename of the ET system
config is the desired configuration of the way the ET system is opened and is defined by routines starting with et_open_config_ ... .

Returns:

ET_OK if successful
ET_ERROR if failure to open the ET file
ET_ERROR_TIMEOUT if the ET system is still not active before the routine returns.
ET_ERROR_REMOTE for a remote consumer 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.
ET_ERROR_READ for a remote consumer's network read error
ET_ERROR_WRITE for a remote consumer'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:

ET_OK if successful
ET_ERROR if error
ET_ERROR_REMOTE for a local user on Linux (or other non-mutex-sharing system) 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:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD for a local user if ET system is dead
ET_ERROR_REMOTE for a local user on Linux (or other non-mutex-sharing system) 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 if ET system given by id is alive
0 if ET system given by id is dead

Notes:

This routine behaves differently depending on whether it is run locally on Solaris, locally on Linux, or remotely. If the user is running it locally on Solaris, 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. If the user is local on Linux, a hybrid approach is used. First the ET system's server thread is contacted. If that fails, the actual heartbeat in the shared memory is monitored (taking 1.5 times the heartbeat time).

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:

ET_OK
ET_ERROR_READ for a remote user's network read error
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:

ET_OK if successful
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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.

Arguments:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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:

ET_OK
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.

Arguments:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
val is a multicast IP address in dotted-decimal form. If there is no such address on the list, it is ignored.

Returns:

ET_OK
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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:

sconfig is an open configuration
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:

ET_OK
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:

sconfig is an open configuration
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 is different from the broadcast port only on Java-based ET systems.

Arguments:

sconfig is an open configuration
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:

ET_OK
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. The multicasting port is different from the broadcast port only on Java-based ET systems.

Arguments:

sconfig is an open configuration
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 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:

sconfig is an open configuration
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:

ET_OK
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 port number for opening an ET system directly without broadcasting or multicasting.

Arguments:

sconfig is an open configuration
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:

sconfig is an open configuration
val is the "ttl" value for multicasting. It defaults to a value of one which restricts multicasting to the local subnet.

Returns:

ET_OK
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:

sconfig is an open configuration
val is a pointer that gets filled with the ttl value

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:

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
sconfig is the desired configuration of the new ET system (set by routines starting with et_system_config_ ...)

Returns:

ET_OK
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:

ET_OK
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:

id is the id of the ET system of interest
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 (eg. Linux).

Returns:

ET_OK
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:

id is the id of the ET system of interest
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:

ET_OK
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:

id is the id of the ET system of interest
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:

ET_OK
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:

id is the id of the ET system of interest
numevents is a pointer to an integer that gets filled in with the total number of events that the ET system has.

Returns:

ET_OK
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:

id is the id of the ET system of interest
eventsize is a pointer to an integer that gets filled in with the size in bytes of standard events in the ET system.

Returns:

ET_OK
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:

id is the id of the ET system of interest
tempsmax is a pointer to an integer that gets filled in with the maximum number of temporary events allowed in an ET system.

Returns:

ET_OK
ET_ERROR if tempsmax is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stationsmax is a pointer to an integer that gets filled in with the maximum number of stations allowed in an ET system.

Returns:

ET_OK
ET_ERROR if stationsmax is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
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:

ET_OK
ET_ERROR if procsmax is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
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:

ET_OK
ET_ERROR if attsmax is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
heartbeat is a pointer to an integer that gets filled in with the current heartbeat of an ET system.

Returns:

ET_OK
ET_ERROR if heartbeat is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
pid is a pointer that gets filled in with the pid of an ET system.

Returns:

ET_OK
ET_ERROR if pid is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
procs is a pointer to an integer that gets filled in with the number of processes currently open to an ET system.

Returns:

ET_OK
ET_ERROR if procs is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
atts is a pointer to an integer that gets filled in with the number of attachments currently in an ET system.

Returns:

ET_OK
ET_ERROR if atts is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stations is a pointer that gets filled in with the number of stations in an ET system that are either idle or active.

Returns:

ET_OK
ET_ERROR if stations is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
temps is a pointer to an integer that gets filled in with the number of temporary events currently in an ET system.

Returns:

ET_OK
ET_ERROR if temps is NULL
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
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:

ET_OK
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:

id is the id of the ET system of interest
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:

ET_OK
ET_ERROR if port 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:

ET_OK if successful
ET_ERROR if it fails to allocate memory for configuration data storage

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:

sconfig is a system configuration
val must be greater than zero

Returns:

ET_OK
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:

sconfig is a system configuration
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:

sconfig is a system configuration
val must be greater than zero

Returns:

ET_OK
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:

sconfig is a system configuration
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:

sconfig is a system configuration
val must be greater than zero

Returns:

ET_OK
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:

sconfig is a system configuration
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:

sconfig is a system configuration
val must be greater than zero

Returns:

ET_OK
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:

sconfig is a system configuration
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:

sconfig is a system configuration
val must be > 0 and <= ET_PROCESSES_MAX

Returns:

ET_OK
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:

sconfig is a system configuration
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:

sconfig is a system configuration
val must be > 0 and <= ET_ATTACHMENTS_MAX

Returns:

ET_OK
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:

sconfig is a system configuration
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:

sconfig is a system configuration
val is a pointer to a string or null-terminated character array containing the file name

Returns:

ET_OK
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:

sconfig is a system configuration
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:

sconfig is an system configuration
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:

ET_OK
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:

sconfig is an system configuration
val is a multicast IP address in dotted-decimal form. If there is no such address on the list, it is ignored.

Returns:

ET_OK
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 (4) of ET. It's here for backwards compatibility.

Arguments:

sconfig is a system configuration
val is any integer

Returns:

ET_OK

DEPRECATED

int et_system_config_getcast (et_sysconfig sconfig, int *val)

Purpose:

This routine does nothing in this version (4) of ET. It's here for backwards compatibility.

Arguments:

sconfig is a system configuration
val is an integer pointer

Returns:

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:

sconfig is an system configuration
val is a multicast IP address in dotted-decimal format.

Returns:

ET_OK
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:

sconfig is an system configuration
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 IP broadcasting or multicasting used to discover this ET system by remote users.

Arguments:

sconfig is a system configuration
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:

ET_OK
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 IP broadcasting or multicasting used to discover this ET system by remote users.

Arguments:

sconfig is a system configuration
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 port number for the ET system (tcp server thread) used to communicate with remote users.

Arguments:

sconfig is a system configuration
val is the port number of the ET system server for remote users

Returns:

ET_OK
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 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 port number for the ET system (tcp server thread) used to communicate with remote users.

Arguments:

sconfig is a system configuration
val is a pointer that gets filled with the port number

Returns:

ET_OK

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:

id is the id of the ET system of interest
att is the attachment id. This is obtained by attaching the user process to a station with et_station_attach.
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".
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.
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.
size is the number of bytes desired for the event's data

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
ET_ERROR_WRITE for a remote user's network write error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.
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 consumer 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 event from the ET system into which it can place data.

Arguments:

id is the id of the ET system of interest
att is the attachment id. This is obtained by attaching the user process to a station with et_station_attach.
pe is an array of pointers to events.
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.
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.
size is the number of bytes desired for the event's data
num is the number of desired events
nread returns the number of events actually read

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
ET_ERROR_WRITE for a remote user's network write error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_WAKEUP if told to stop sleeping while trying to get events
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.
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 2X the single transfer rate is likely. On Linux a 10 fold increase 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:

id is the id of the ET system of interest
att is the attachment id.
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".
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.
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:

ET_OK if successful
ET_ERROR if error
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
ET_ERROR_WRITE for a remote user's network write error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.
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:

id is the id of the ET system of interest
att is the attachment id.
pe is an array of pointers to events.
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.
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.
num is the number of events desired to be read.
nread returns the number of events actually read

Returns:

ET_OK, if successful
ET_ERROR if error
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
ET_ERROR_WRITE for a remote user's network write error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_WAKEUP if told to stop sleeping while trying to get events
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.
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 grandcentral station.

Arguments:

id is the id of the ET system of interest
att is the attachment id.
pe is a pointer to an event. Declare it as "et_event *pe;", and pass it as "pe".

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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 grandcentral station.

Arguments:

id is the id of the ET system of interest
att is the attachment id.
pe is an array of pointers to events.
num is the number of events to be written.

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
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 grandcentral station which recycles it.

Arguments:

id is the id of the ET system of interest
att is the attachment id.
pe is a pointer to an event. Declare it as "et_event *pe;", and pass it as "pe".

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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 grandcentral station which recycles them.

Arguments:

id is the id of the ET system of interest
att is the attachment id.
pe is an array of pointers to events.
num is the number of events to be written.

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
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:

pe is a pointer to event.
data is a pointer to a pointer to the event's data

Returns:

ET_OK if successful
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:

pe is a pointer to event.
status is a pointer which gets filled with the status of an event'sdata. 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 GrandCentral station, the attachment's station's input list, or its output list depending on the station's configuration (see et_station_config_setrestore or ). If the events are NOT put back into GrandCentral 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:

ET_OK if successful
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:

pe is a pointer to event.
len is the length in bytes of data written into the event.

Returns:

ET_OK if successful
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:

pe is a pointer to event.
len is a pointer which gets filled with the length in bytes of data written into the event.

Returns:

ET_OK if successful
ET_ERROR if error

int et_event_setpriority (et_event *pe, int pri)

Purpose:

This routine sets the priority of an event.

Arguments:

pe is a pointer to event.
pri is the priority of either ET_HIGH or ET_LOW.

Returns:

ET_OK if successful
ET_ERROR if error

int et_event_getpriority (et_event pe, int pri)

Purpose:

This routine gets the priority of an event.

Arguments:

pe is a pointer to event.
pri is a pointer which gets filled with the priority of the event.

Returns:

ET_OK if successful
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:

pe is a pointer to event.
con is an integer array.
num is the number of elements in the array.

Returns:

ET_OK if successful
ET_ERROR if error

int et_event_getcontrol (et_event *pe, int con[])

Purpose:

This routine gets the control array of an event.

Arguments:

pe is a pointer to event.
con is an integer array with at least ET_STATION_SELECT_INTS number of elements.

Returns:

ET_OK if successful
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:

pe is a pointer to event.
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:

ET_OK if successful
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:

pe is a pointer to event.
endian is a pointer which gets filled with the either ET_ENDIAN_BIG or ET_ENDIAN_LITTLE.

Returns:

ET_OK if successful
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:

pe is a pointer to event.
swap is a pointer which gets filled in with either ET_SWAP or ET_NOSWAP.

Returns:

ET_OK if successful
ET_ERROR if error

int et_event_CODAswap (et_event *pe)

Purpose:

This routine swaps the data of an event in CODA format. The data is swapped in the event's data buffer and therefore irreversibly mangles the data. It also takes care of header information concerning the data's endian value so et_event_setendian does NOT need to be called.

Arguments:

pe is a pointer to event.

Returns:

ET_OK if successful
ET_ERROR if 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)

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:

id is the id of the ET system of interest
stat_id is a pointer to a station id number and returns the value of the newly created station's id.
stat_name is the station name
sconfig is a station configuration handle
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.

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_EXISTS if station already exists and has a different configuration (stat_id is still set to the existing station's id)
ET_ERROR_TOOMANY if the maximum number of stations already exist
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is a pointer to a station id number and returns the value of the newly created station's id.
stat_name is the station name
sconfig is a station configuration handle

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_EXISTS if station already exist and has a different configurations (stat_id is still set to the existing station's id)
ET_ERROR_TOOMANY if the maximum number of stations already exist
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
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 grandcentral and provided there are no attached processes. The station's status is set to ET_STATION_UNUSED.

Arguments:

id is the id of the ET system of interest
stat_id is the station's id number.

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number
att is a pointer to a attachment id which gets filled in by this routine.

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_TOOMANY if the existing number of attachments is already equal to the station or system limit
ET_ERROR_DEAD if ET system is dead
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
att is the attachment id.

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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)

Purpose:

Gets the value of a station's position in the linked list of active and idle stations.

Arguments:

id is the id of the ET system of interest
stat_id is the station's id number.
position is a pointer which gets filled in with the position

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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)

Purpose:

Sets a station's position in the linked list of active and idle stations.

Arguments:

id is the id of the ET system of interest
stat_id is the station's id number. GRAND_CENTRAL station's position may not be changed.
position is the position in the linked listed and must be greater than 0 as the first position (0) is reserved for GRAND_CENTRAL station.

Returns:

ET_OK if successful
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or position argument values
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
att is the attachment id.

Returns:

1 if attached
0 if not attached
ET_ERROR for bad argument(s)
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is a pointer to a station id which is filled if stat_name exists.
stat_name is the station name

Returns:

1 if station exists
0 if station does not exist
ET_ERROR for bad stat_name argument
ET_ERROR_DEAD if ET system is dead.
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
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:

id is the ET system id
stat_id is a pointer that get filled in with the station's id number.
stat_name is the station name

Returns:

ET_OK
ET_ERROR if no station by that name exists or stat_name is null
ET_ERROR_DEAD if ET system is dead
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
numatts is a pointer to int which gets filled in with the number of attachments

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
status is a pointer which gets filled in with the status of the station

Returns:

ET_OK if successful
ET_ERROR if bad stat_id argument
ET_ERROR_DEAD if ET system is dead.
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
cnt is a pointer to int which gets filled in with the number of events in the station's input list

Returns:

ET_OK if successful
ET_ERROR if bad stat_id argument
ET_ERROR_DEAD if ET system is dead.
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
cnt is a pointer which gets filled in with the number of events in the station's output list

Returns:

ET_OK if successful
ET_ERROR if bad stat_id argument
ET_ERROR_DEAD if ET system is dead.
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
block is a pointer which gets filled in with the blocking mode

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
block must be either ET_STATION_BLOCKING or ET_STATION_NONBLOCKING

Returns:

ET_OK if successful
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or block argument values
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
user is a pointer which gets filled in with the user mode

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
user must be either ET_STATION_USER_MULTI, ET_STATION_USER_SINGLE, or a non-negative integer.

Returns:

ET_OK if successful
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or user argument values
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
restore is a pointer which gets filled in with the restore mode

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
restore must be either ET_STATION_RESTORE_OUT, ET_STATION_RESTORE_IN, or ET_STATION_RESTORE_GC.

Returns:

ET_OK if successful
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or restore argument values
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
cue is a pointer which gets filled in with the cue value

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
cue must be an integer from 1 to the total number of events in the system.

Returns:

ET_OK if successful
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or cue argument values
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
prescale is a pointer which gets filled in with the prescale value

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
prescale must be an integer greater than 0.

Returns:

ET_OK if successful
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or prescale argument values
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
lib is a character array which gets filled in with the lib name

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
function is a character array which gets filled in with the function name

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
class is a character array which gets filled in with the class name

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
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:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
select is an integer array that must have at least ET_STATION_SELECT_INTS number of elements.

Returns:

ET_OK if successful
ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or select argument values
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
stat_id is the station's id number.
select is a pointer which gets filled in with the select mode

Returns:

ET_OK if successful
ET_ERROR if station is unused or bad stat_id argument
ET_ERROR_DEAD if ET system is dead
ET_ERROR_READ for a remote user's network read error
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:

ET_OK if successful
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:

sconfig is a station configuration
val must be either ET_STATION_BLOCKING or ET_STATION_NONBLOCKING

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val must be either ET_STATION_SELECT_ALL or ET_STATION_SELECT_MATCH, or ET_STATION_SELECT_USER

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val must be either ET_STATION_USER_MULTI or ET_STATION_USER_SINGLE

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val must be either ET_STATION_RESTORE_OUT or ET_STATION_RESTORE_IN, or ET_STATION_RESTORE_GC

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val must be greater than zero

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val must be greater than zero

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val is an array of integers with at least ET_STATION_SELECT_INTS number of elements.

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val is a pointer to a string or null-terminated char array containing the shared library name

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val is a pointer to a string or null-terminated char array containing the function name

Returns:

ET_OK
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:

sconfig is a station configuration
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:

sconfig is a station configuration
val is a pointer to a string or null-terminated char array containing the class name

Returns:

ET_OK
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:

sconfig is a station configuration
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:

id is the id of the ET system of interest
att is the attachment id.

Returns:

ET_OK if successful
ET_ERROR if bad att argument
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:

id is the id of the ET system of interest
stat_id is the station's id number.

Returns:

ET_OK if successful
ET_ERROR if bad stat_id argument
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:

id is the id of the ET system of interest
att_id is the attachment's id number.
highint is a pointer which gets filled in with the most significant 32 bits.
lowint is a pointer which gets filled in with the least significant 32 bits.

Returns:

ET_OK if successful
ET_ERROR if bad att_id argument
ET_ERROR_DEAD if ET system is dead.
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
att_id is the attachment's id number.
highint is a pointer which gets filled in with the most significant 32 bits.
lowint is a pointer which gets filled in with the least significant 32 bits.

Returns:

ET_OK if successful
ET_ERROR if bad att_id argument
ET_ERROR_DEAD if ET system is dead.
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
att_id is the attachment's id number.
highint is a pointer which gets filled in with the most significant 32 bits.
lowint is a pointer which gets filled in with the least significant 32 bits.

Returns:

ET_OK if successful
ET_ERROR if bad att_id argument
ET_ERROR_DEAD if ET system is dead.
ET_ERROR_READ for a remote user's network read error
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:

id is the id of the ET system of interest
att_id is the attachment's id number.
highint is a pointer which gets filled in with the most significant 32 bits.
lowint is a pointer which gets filled in with the least significant 32 bits.

Returns:

ET_OK if successful
ET_ERROR if bad att_id argument
ET_ERROR_DEAD if ET system is dead.
ET_ERROR_READ for a remote user's network read error
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:

id_from is the ID of the ET system from which the events are copied
id_to is the ID of the ET system in which the events are placed
att_from is the attachment to a station on the "from" ET system
att_to is the attachment to a station on the "to" ET system (usually GrandCentral)
bconfig is the configuration of the remaining transfer parameters
num is the total number of events desired to be transferred
ntransferred is the total number of events that were actually transferred at the routine's return

Returns:

ET_OK if successful
ET_ERROR if error
ET_ERROR_REMOTE for a memory allocation error of a remote user
ET_ERROR_READ for a remote user's network read error
ET_ERROR_WRITE for a remote user's network write error
ET_ERROR_DEAD if ET system is dead
ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event
ET_ERROR_TIMEOUT if timeout on ET_TIMED option
ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.
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:

ET_OK if successful
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:

config is a bridge configuration
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:

ET_OK
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:

config is a bridge configuration
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:

config is a bridge configuration
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:

ET_OK
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:

config is a bridge configuration
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:

config is a bridge configuration
val is any integer greater than one. The default is 100.

Returns:

ET_OK
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:

config is a bridge configuration
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:

config is a bridge configuration
val is any integer greater than one. The default is 100.

Returns:

ET_OK
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:

config is a bridge configuration
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:

config is a bridge configuration
val is the time to wait. The default is 0 seconds.

Returns:

ET_OK
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:

config is a bridge configuration
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:

config is a bridge configuration
val is the time to wait. The default is 0 seconds.

Returns:

ET_OK
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:

config is a bridge configuration
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:

config is a bridge configuration
func is the name of the function or function pointer. The default is NULL (no swapping).

Returns:

ET_OK
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.

int et_bridge_CODAswap (et_event src, et_event dest, int bytes, int same_endian)

Purpose:

This function can be 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:

src is a pointer to an event whose data is to be swapped
dest is a pointer to an event where the swapped data goes
bytes is the length of the data in bytes
same_endian is a flag equalling one if the machine and the data are of the same endian and zero otherwise

Returns:

ET_OK

User Routines

General Functions

int et_open (et_sys_id *id, char *filename, et_openconfig config)

Purpose:

Arguments:

Returns:

Notes:

int et_close (et_sys_id id)

Purpose:

Arguments:

Returns:

Notes:

int et_forcedclose (et_sys_id id)

Purpose:

Arguments:

Returns:

Notes:

int et_alive (et_sys_id id)

Purpose:

Arguments:

Returns:

Notes:

int et_wait_for_alive (et_sys_id id)

Purpose:

Arguments:

Returns:

Notes:

Open Configuration Functions

int et_open_config_init (et_openconfig *sconfig)

Purpose:

Arguments:

Returns:

int et_open_config_destroy (et_openconfig sconfig)

Purpose:

Arguments:

Returns:

int et_open_config_setwait(et_openconfig sconfig, int val)

Purpose:

Arguments:

Returns:

Notes:

int et_open_config_getwait (et_openconfig sconfig, int *val)

Purpose:

Arguments:

Returns:

int et_open_config_settimeout (et_openconfig sconfig, struct timespec val)

Purpose:

Arguments:

Returns:

int et_open_config_gettimeout (et_openconfig sconfig, struct timespec *val)

Purpose:

Arguments:

Returns:

int et_open_config_sethost (et_openconfig sconfig, char *val)

Purpose:

Arguments:

Returns:

int et_open_config_gethost (et_openconfig sconfig, char *val)

Purpose:

Arguments:

Returns:

int et_open_config_setmode (et_openconfig sconfig, int val)

Purpose:

Arguments:

Returns:

int et_open_config_getmode (et_openconfig sconfig, int *val)

Purpose:

Arguments:

Returns:

int et_open_config_setdebugdefault (et_openconfig sconfig, int val)

Purpose:

Arguments:

Returns:

int et_open_config_getdebugdefault (et_openconfig sconfig, int *val)

Purpose:

Arguments:

Returns:

int et_open_config_setcast (et_openconfig sconfig, int val)

Purpose:

Arguments:

int et_open (et_sys_id id, char filename, et_openconfig config)