PreviousAdd Guide

User Routines

General Functions

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

Purpose:

Given an ET system on the same host, this routine will map the system's shared memory into the user's space. It also starts up a thread to produce a heartbeat and a second thread to monitor the ET system's heartbeat. If the ET system is remote, a network connection is made to it.

Arguments:

1.      id is a pointer that gets filled in with the unique id of the ET system being opened. It can be thought of as a pointer to a handle.

2.      filename is the unique filename of the ET system

3.      config is the desired configuration of the way the ET system is opened and is defined by routines starting with et_open_config_ ... .

Returns:

1.      ET_OK if successful

2.      ET_ERROR if failure to open the ET file

3.      ET_ERROR_TIMEOUT if the ET system is still not active before the routine returns.

4.      ET_ERROR_REMOTE for a remote client if it cannot get the server's port number, the host has a strange byteorder, the tcp connection fails, or there's not enough memory.

5.      ET_ERROR_READ for a remote client's network read error

6.      ET_ERROR_WRITE for a remote client's network write error

Notes:

The ET system is implemented as a single memory mapped file of the name filename. This routine should only be called once, before all other ET routines are used, or after a system has been closed with a call to et_close or et_forcedclose. A successful return from this routine assures connection to an ET system which is up and running. IT IS CRUCIAL THAT THE USER GET A RETURN VALUE OF "ET_OK" IF THE USER WANTS AN ET SYSTEM GUARANTEED TO FUNCTION.

The user may open an ET system on a remote host. ET decides whether the user is on the same as or a different machine than the system. If the determination is made that the user is on another computer, then network connections are made to that system.

int et_close (et_sys_id id)

Purpose:

Given a local ET system that has been opened with a call to et_open, this routine will stop all ET-related threads and unmap the system's memory from the user's space making it inaccessible. It also frees memory allocated in et_open to create the system's id. For a remote user, all this routine does is close the connection between the user and ET system as well as free the memory allocated in creating the system's id.

Arguments:

id is the id of the ET system being closed.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_REMOTE for a local user on a non-mutex-sharing system (none currently known), if cannot unmap shared memory

Notes:

This routine should only be called once for a particular ET system after the associated call to et_open. In addition, all attachments of the process calling this routine must be detached first or an error will be returned.

int et_forcedclose (et_sys_id id)

Purpose:

Given a local ET system that has been opened with a call to et_open, this routine will stop all ET-related threads and unmap the system's memory from the user's space making it inaccessible. For a remote user, this routine closes the connection between the user and ET system. But before it does any of this, it detaches all attachments belonging to the process calling it. It also frees memory allocated in et_open to create the system's id.

Arguments:

id is the id of the ET system being closed.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_DEAD for a local user if ET system is dead

4.      ET_ERROR_REMOTE for a local user on non-mutex-sharing system (none currently known), if cannot unmap shared memory

Notes:

This routine should only be called once for a particular ET system after the associated call to et_open.

int et_kill (et_sys_id id)

Purpose:

Given a local ET system that has been opened with et_open, this routine will do the same as et_forcedclose for the caller and will cause the ET system to delete its file and kill itself. For a remote user it does the equivalent of an et_close for the caller while telling the ET system to delete its file and kill itself.

Arguments:

id is the id of the ET system being closed.

Returns:

1.      ET_OK if successful, or if local client

2.    ET_ERROR_WRITE  if remote client and network writing error

3.    ET_ERROR_REMOTE for a local user on non-mutex-sharing system (none currently known), if cannot unmap shared memory

Notes:

This routine should only be called once for a particular ET system after the associated call to et_open.

int et_alive (et_sys_id id)

Purpose:

This routine tells the user whether the ET system is dead or alive.

Arguments:

id is the id of the ET system of interest

Returns:

1.      1 if ET system given by id is alive

2.      0 if ET system given by id is dead

Notes:

This routine behaves differently depending on whether it is run locally or remotely. If the user is running it locally, a thread of the user's process is constantly checking to see if the ET system is alive and provides a valid return value to et_alive when last it was monitored (up to three heartbeats ago). If the user is on a remote node, the ET system's server thread is contacted. If that communication succeeds, then the ET system is alive by definition, otherwise it is dead.

int et_wait_for_alive (et_sys_id id)

Purpose:

This routine waits until the ET system has a heartbeat before it returns. It checks once every minimum sleep period.

Arguments:

id is the id of the ET system of interest

Returns:

1.      ET_OK

2.      ET_ERROR_READ for a remote user's network read error

3.      ET_ERROR_WRITE for a remote user's network write error

Notes:

This routine behaves differently depending on whether it is run locally or remotely. If the user is running it locally, it constantly checks to see if the ET system is alive and waits before returning until it is. If the user is on a remote node, the ET system's server thread is contacted. If that communication succeeds, then the ET system is alive by definition, otherwise it immediately returns an error.

Open Configuration Functions

int et_open_config_init (et_openconfig *sconfig)

Purpose:

This routine initializes a configuration used by a process to open an ET system. This MUST be done prior to setting any configuration parameters or all setting routines will return an error.

Arguments:

sconfig is pointer to an open configuration variable

Returns:

1.      ET_OK if successful

2.      ET_ERROR if it fails to allocate memory for configuration data storage

int et_open_config_destroy (et_openconfig sconfig)

Purpose:

This routine frees the memory allocated when a configuration is initialized by et_open_config_init.

Arguments:

sconfig is an open configuration

Returns:

ET_OK

int et_open_config_setwait(et_openconfig sconfig, int val)

Purpose:

This routine sets the means to wait for a valid ET system to be detected.

Arguments:

1.      sconfig is an open configuration

2.      val is the method to wait for a valid ET system to be detected. Setting val to ET_OPEN_WAIT makes et_open block by waiting until the given ET system is fully functioning or a set time period has passed before returning. Setting val to ET_OPEN_NOWAIT makes et_open return immediately after determining whether the ET system is alive or not. The default is ET_OPEN_NOWAIT.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not ET_OPEN_WAIT or ET_OPEN_NOWAIT

Notes:

If the ET system is local, both ET_OPEN_WAIT and ET_OPEN_NOWAIT mean et_open will quickly send a UDP broad/multicast packet to see if the system responds. If it does not, it tries to detect a heartbeat which necessitates waiting at least one heartbeat. However, if the system is remote, broad/multicasting to find its location may take up to several seconds. Usually, if the ET system is up and running, this will only take a fraction of a second. If a direct remote connection is being made, it is only tried once in the ET_OPEN_NOWAIT mode, but it tries repeatedly at 10Hz until the set timeout in the ET_OPEN_WAIT mode.

int et_open_config_getwait (et_openconfig sconfig, int *val)

Purpose:

This routine gets the means to wait for a valid ET system to be detected.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with ET_OPEN_WAITor ET_OPEN_NOWAIT

Returns:

ET_OK

int et_open_config_settimeout (et_openconfig sconfig, struct timespec val)

Purpose:

This routine sets the maximum time to wait for a valid ET system to be detected.

Arguments:

1.      sconfig is an open configuration

2.      val is maximum amount of time to wait for an alive ET system to be detected if the wait mode is ET_OPEN_WAIT. If the time is set to zero (the default), an infinite time is indicated. Note that in local systems, et_open waits in integral units of the system's heartbeat time (ET_BEAT_SEC & ET_BEAT_NSEC set in et_private.h). If broad/multicasting to find a remote ET system, it is possible to take up to several seconds to determine whether the system is alive or not. In this case, the time limit may be exceeded.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized

int et_open_config_gettimeout (et_openconfig sconfig, struct timespec *val)

Purpose:

This routine gets the maximum time to wait for a valid ET system to be detected.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with the time

Returns:

ET_OK

int et_open_config_sethost (et_openconfig sconfig, char *val)

Purpose:

This routine sets host or computer on which the ET system is running.

Arguments:

1.      sconfig is an open configuration

2.      val is the name of the computer (or host) on which the ET system resides. For opening a local system only, set val to ET_HOST_LOCAL (the default) or "localhost" (including quotes). For opening a system on an unknown remote computer only, set it to ET_HOST_REMOTE. For an unknown host which may be local or remote, set it to ET_HOST_ANYWHERE. Otherwise set val to the name or dotted-decimal IP address of the desired host. If the ET_DIRECT option is taken in et_open_config_setcast, be aware that this routine must use the ET system's actual host name or "localhost" but must NOT be ET_HOST_LOCAL, ET_HOST_REMOTE, or ET_HOST_ANYWHERE.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is NULL or too long

int et_open_config_gethost (et_openconfig sconfig, char *val)

Purpose:

This routine gets the host or computer on which the ET system is running.

Arguments:

1.      sconfig is an open configuration

2.      val is a character array that gets filled with the host name

Returns:

ET_OK

int et_open_config_setmode (et_openconfig sconfig, int val)

Purpose:

This routine sets whether the ET system being opened treats the user running this routine as local (if it is local) or remote even if it is local.

Arguments:

1.      sconfig is an open configuration

2.      val can be set to ET_HOST_AS_REMOTE if the local user is to be treated as remote. This means all communication is done through the ET server using sockets. The alternative is to set val to ET_HOST_AS_LOCAL (default) which means local users are treated as local with the ET system memory being mapped into the user's space.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not equal to ET_HOST_AS_REMOTE or ET_HOST_AS_LOCAL 

int et_open_config_getmode (et_openconfig sconfig, int *val)

Purpose:

This routine gets the mode which tells whether local users are treated as local or remote.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with either ET_HOST_AS_REMOTE or ET_HOST_AS_LOCAL

Returns:

ET_OK

int et_open_config_setdebugdefault (et_openconfig sconfig, int val)

Purpose:

This routine sets the default level of debugging output.

Arguments:

1.      sconfig is an open configuration

2.      val can be set to ET_DEBUG_NONE which means no output, ET_DEBUG_SEVERE for output describing severe errors, ET_DEBUG_ERROR for output describing all errors, ET_DEBUG_WARN for output describing warnings and errors, and ET_DEBUG_INFO for output describing all information, warnings, and errors.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not equal to one of the listed values. 

int et_open_config_getdebugdefault (et_openconfig sconfig, int *val)

Purpose:

This routine gets the default level of debugging output.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with either ET_DEBUG_NONE, ET_DEBUG_SEVERE, ET_DEBUG_ERROR, ET_DEBUG_WARN, or ET_DEBUG_INFO.

Returns:

ET_OK

int et_open_config_setcast (et_openconfig sconfig, int val)

Purpose:

This routine sets the method for a remote user to discover the ET system to be opened.

Arguments:

1.      sconfig is an open configuration

2.      val is the name of the method for a remote user to discover the ET system to be opened. Set it to ET_BROADCAST for using UDP broadcasting (the default), ET_MULTICAST for using UDP multicasting, ET_BROADANDMULTICAST for using both, or ET_DIRECT for a direct connection to the ET system by specifying host and server (not UDP) port.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not equal to ET_BROADCAST, ET_MULTICAST, ET_BROADANDMULTICAST, or ET_DIRECT

Notes:

To avoid broad/multicasting to find the ET system (actually to find the port number of the tcp server thread), use the ET_DIRECT option. This does no broad/multicast and connects directly to the ET system. A possible reason for wanting to avoid broad/multicasting is if the ET system and user are on different subnets and routers will not pass the UDP packets between them. If the ET_DIRECT option is taken, be aware that et_open_config_sethost must use the ET system's actual host name or "localhost" but must NOT be ET_HOST_LOCAL, ET_HOST_REMOTE, or ET_HOST_ANYWHERE. Use et_open_config_setserverport to specify the port number of the ET server thread.

int et_open_config_getcast (et_openconfig sconfig, int *val)

Purpose:

This routine gets the method for a remote user to discover the ET system to be opened.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with either ET_BROADCAST, ET_MULTICAST, ET_BROADANDMULTICAST, or ET_DIRECT

Returns:

ET_OK

int et_open_config_addbroadcast (et_openconfig sconfig, char *val)

Purpose:

This routine adds an IP subnet broadcast address to a list of destinations used in broadcast discovery of the ET system to be opened. Broadcasting is only used if et_open_config_setcast is set to ET_BROADCAST or ET_BROADANDMULTICAST.

Arguments:

1.      sconfig is an open configuration

2.      val is a subnet broadcast IP address in dotted-decimal form. If this routine is never called, the list of addresses is automatically set to all the local subnet broadcast addresses. However, if finding these addresses fails, then the list is set to a single entry of ET_BROADCAST_ADDR (defined in et.h to be the author's subnet broadcast address). This argument may also be set to ET_SUBNET_ALL which specifies all the local subnet broadcast addresses, or to ET_SUBNET_DEFAULT which specifies the address associated with the hostname returned by the "uname" routine. There can be at most ET_MAXADDRESSES (defined in et_private.h as 10) addresses in the list.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is NULL or too long or too short

int et_open_config_removebroadcast (et_openconfig sconfig, char *val)

Purpose:

This routine removes an IP subnet broadcast address from a list of destinations used in broadcast discovery of the ET system to be opened.

Arguments:

1.      sconfig is an open configuration

2.      val is a subnet broadcast IP address in dotted-decimal form. If there is no such address on the list, it is ignored. This argument may also be set to ET_SUBNET_ALL which specifies all the local subnet broadcast addresses, or to ET_SUBNET_DEFAULT which specifies the address associated with the hostname returned by the "uname" routine.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is NULL or too long or too short

int et_open_config_addmulticast (et_openconfig sconfig, char *val)

Purpose:

This routine adds a multicast address to a list of destinations used in multicast discovery of the ET system to be opened. Multicasting is only used if et_open_config_setcast is set to ET_MULTICAST or ET_BROADANDMULTICAST.

Arguments:

1.      sconfig is an open configuration

2.      val is a multicast IP address in dotted-decimal form. There can be at most ET_MAXADDRESSES (defined in et_private.h as 10) addresses on the list. Duplicate entries are not added to the list.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, val is NULL, is too long or too short, or its first number is not between 224 and 239 inclusive.

int et_open_config_removemulticast (et_openconfig sconfig, char *val)

Purpose:

This routine removes a multicast address from a list of destinations used in multicast discovery of the ET system to be opened.

Arguments:

1.      sconfig is an open configuration

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

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, val is NULL, is too long or too short, or its first number is not between 224 and 239 inclusive.

DEPRECATED

int et_open_config_setaddress (et_openconfig sconfig, char *val)

Purpose:

This routine is replaced by et_open_config_addbroadcast and et_open_config_addmulticast. For compatibility purposes it is included though it is deprecated. Currently it adds an IP subnet broadcasting address or a multicasting address to the appropriate destination list used in discovering the ET system to be opened.

Arguments:

1.      sconfig is an open configuration

2.      val is the IP address for broadcast or multicast communications in dotted-decimal form. If the address starts with a number from 224 to 239, it's added to the multicast address list, else it's added to the broadcast list.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, val is NULL, or is too long or too short.

DEPRECATED

int et_open_config_getaddress (et_openconfig sconfig, char *val)

Purpose:

This routine has no replacement in this ET version and is included for compatibility purposes only, though it is deprecated. It returns the default IP subnet broadcast address unless et_open_config_setcast was set to ET_MULTICAST and there is at least one multicast address listed. In that case, the first listed multicast address is returned. These are the destination addresses of the ET system discovery process.

Arguments:

1.      sconfig is an open configuration

2.      val is a character array that gets filled with the dotted-decimal form IP address

Returns:

ET_OK

int et_open_config_setpolicy (et_openconfig sconfig, int val)

Purpose:

This routine sets the return policy from an et_open call. If an et_open generates more than one response from one or more ET systems, this policy can be set to return an error, open the first system to respond, or open the first local system to respond.

Arguments:

1.      sconfig is an open configuration

2.      val can be set to ET_POLICY_ERROR if the user wants et_open to return an error if more than one response is received from its broad or multicast attempt to find an ET system. Set val to ET_POLICY_FIRST if the first responding system is the one to be opened. Else, set val to ET_POLICY_LOCAL if the first responding local system is opened if there is one, and if not, the first responding system.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not equal to ET_POLICY_ERROR , ET_POLICY_FIRST , or ET_POLICY_LOCAL.

Notes:

One ET system may respond multiple times to a single et_open by a user if it is connected to more than one subnet or is listening to multicast addresses. It is also possible that if a user is configured for ET_HOST_REMOTE or ET_HOST_ANYWHERE, several ET systems may have the same name (eg. /tmp/my_et_system) and respond with their port numbers and host names. Thus, the user needs to determine the best way to respond to such situations.

int et_open_config_getpolicy (et_openconfig sconfig, int *val)

Purpose:

This routine gets the return policy from calls to et_open.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with either ET_POLICY_ERROR , ET_POLICY_FIRST , or ET_POLICY_LOCAL.

Returns:

ET_OK

int et_open_config_setport (et_openconfig sconfig, unsigned short val)

Purpose:

This routine sets the port number for the UDP broadcasting used to discover the ET system being opened.

Arguments:

1.      sconfig is an open configuration

2.      val is the port number of the broadcast communications. The default is ET_BROADCAST_PORT, defined in et.h as 11111, but may be set to any number > 1023 and < 65536.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is less than 1024

int et_open_config_getport (et_openconfig sconfig, unsigned short *val)

Purpose:

This routine gets the port number for the UDP broadcasting used to discover the ET system being opened.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with the port number

Returns:

ET_OK

int et_open_config_setmultiport (et_openconfig sconfig, unsigned short val)

Purpose:

This routine sets the port number for the UDP multicasting used to discover the ET system being opened. The multicasting port only needs to be different from the broadcast port on Java-based ET systems.

Arguments:

1.      sconfig is an open configuration

2.      val is the port number of the multicast communications. The default is ET_MULTICAST_PORT, defined in et.h as 11111, but may be set to any number > 1023 and < 65536.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is less than 1024

int et_open_config_getmultiport (et_openconfig sconfig, unsigned short *val)

Purpose:

This routine gets the port number for the UDP multicasting used to discover the ET system being opened.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with the port number

Returns:

ET_OK

int et_open_config_setserverport (et_openconfig sconfig, unsigned short val)

Purpose:

This routine sets the TCP port number for opening an ET system directly without broadcasting or multicasting. It is used in conjunction with setting the value in et_open_config_setcast to be ET_DIRECT. 

Arguments:

1.      sconfig is an open configuration

2.      val is the port number of the ET system's tcp server thread. The default value is ET_SERVER_PORT which is set to 11111 in et.h.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is less than 1024

Notes:

To avoid broadcasting or multicasting to find the ET system (actually to find the port number of the tcp server thread), use et_open_config_setcast set to the ET_DIRECT option. This does no broad/multicast and connects directly to the ET system. A possible reason for wanting to avoid broad/multicasting is if the ET system and user are on different subnets and routers will not pass the udp packets between them. Setting the server port value with this routine assumes that its value is known. One way to ensure this, is to use the routine et_system_config_setserverport in the program which is starting up the ET system (e.g. et_start.c). This will definitively set the port number to the requested value or exit the program if it cannot. In this way, the port can be set by the ET system and the information shared with the user for use in this routine.

int et_open_config_getserverport (et_openconfig sconfig, unsigned short *val)

Purpose:

This routine gets the TCP port number for opening an ET system directly without broadcasting or multicasting.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with the port number

Returns:

ET_OK

int et_open_config_setTTL (et_openconfig sconfig, int val)

Purpose:

This routine sets the "ttl" value for multicasting. This value determines how many "hops" through routers the packet makes.

Arguments:

1.      sconfig is an open configuration

2.      val is the "ttl" value for multicasting. It defaults to a value of 32 which should allow multicast packets to pass through local routers.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is less than 0 or greater than 254

int et_open_config_getTTL (et_openconfig sconfig, int *val)

Purpose:

This routine gets the "ttl" value for multicasting.

Arguments:

1.      sconfig is an open configuration

2.      val is a pointer that gets filled with the ttl value

Returns:

ET_OK

int et_open_config_setinterface (et_openconfig sconfig, char *val)

Purpose:

This routine sets the network interface to use when communicating over the network with the ET system (host is not local or mode is ET_HOST_AS_REMOTE or Java ET system).

Arguments:

1.      sconfig is an open configuration

2.      val is the IP address, in dotted decimal format, of the network interface to use.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is NULL or too long or not in dotted decimal form

int et_open_config_getinterface (et_openconfig sconfig, char *val)

Purpose:

This routine gets the network interface used when communicating over the network with the ET system.

Arguments:

1.      sconfig is an open configuration

2.      val is a character array that gets filled with the IP address used when communicating over the network with the ET system. If not set, then nothing is copied to val.

Returns:

ET_OK

int et_open_config_settcp (et_openconfig sconfig, int rBufSize, int sBufSize, int noDelay)

Purpose:

This routine sets the parameters of the TCP connection to the ET system. These include the TCP receiving buffer size in bytes, the TCP sending buffer size in bytes, and the TCP “no delay” value. If either of the buffer sizes are 0, then the operating system default values are used. Setting “noDelay” to 0, turns it off, anything else turns it on (which sends a write immediately over the network without waiting for further writes).

Arguments:

1.      sconfig is an open configuration

2.      rBufSize is the TCP receiving buffer size in bytes.

3.      sBufSize is the TCP sending buffer size in bytes

4.      noDelay  is a boolean value, which is true (non-zero) for no delay of TCP writes, else false (zero)

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or buffer sizes are negative values

int et_open_config_gettcp (et_openconfig sconfig, int *rBufSize, int *sBufSize, int *noDelay)

Purpose:

This routine gets the parameters of the TCP connection to the ET system. These include the TCP receiving buffer size in bytes, the TCP sending buffer size in bytes, and the TCP “no delay” value.

Arguments:

1.      sconfig is an open configuration

2.      rBufSize is a pointer that gets filled with the TCP receiving buffer size in bytes.

3.      sBufSize is a pointer that gets filled with the TCP sending buffer size in bytes

4.      noDelay  is a pointer that gets filled with a boolean value, which is true (1) for no delay of TCP writes, else false (0)

Returns:

ET_OK

System Functions

int et_system_start (et_sys_id *id, et_sysconfig sconfig)

Purpose:

This routine creates a new ET system. The process that executes this routine becomes the ET system process.

Arguments:

1.      id is a pointer to an ET system id - a value-result argument - in which is returned the id of the new system which gets created

2.      sconfig is the desired configuration of the new ET system (set by routines starting with et_system_config_ ...)

Returns:

1.      ET_OK

2.      ET_ERROR if the system could not be created

int et_system_close (et_sys_id id)

Purpose:

This routine closes an ET system that was started with a call to et_system_start. All ET system threads are stopped and the shared memory is unmapped. Only the ET system process may execute this routine.

Arguments:

id is the ET system id

Returns:

1.      ET_OK

2.      ET_ERROR if not ET system process

int et_system_getlocality (et_sys_id id, int *locality)

Purpose:

This routine returns a value indicating whether this routine is being executed on the same machine as the ET system or remotely.

Arguments:

1.      id is the id of the ET system of interest

2.      locality is a pointer to an integer that gets filled in with the value ET_LOCAL if the user is on the same machine as the ET system, ET_REMOTE if the user is on another machine, and ET_LOCAL_NOSHARE if the user is on the same machine but one whose operating system does not allow the sharing of pthread mutexes.

Returns:

1.      ET_OK

2.      ET_ERROR if locality is NULL

int et_system_setdebug (et_sys_id id, int debug)

Purpose:

This routine sets the debug output of the caller's process for a particular ET system.

Arguments:

1.      id is the id of the ET system of interest

2.      debug can be either ET_DEBUG_NONE which means no output, ET_DEBUG_SEVERE for output describing severe errors, ET_DEBUG_ERROR for output describing all errors, ET_DEBUG_WARN for output describing warnings and errors, and ET_DEBUG_INFO for output describing all information, warnings, and errors.

Returns:

1.      ET_OK

2.      ET_ERROR if debug is an invalid value

int et_system_getdebug (et_sys_id id, int *debug)

Purpose:

This routine gets the value of the caller's debug level for a particular ET system.

Arguments:

1.      id is the id of the ET system of interest

2.      debug is a pointer to an integer that gets filled in with the debug level of the ET system. See et_system_setdebug for possible values.

Returns:

1.      ET_OK

2.      ET_ERROR if debug is NULL

int et_system_getnumevents (et_sys_id id, int *numevents)

Purpose:

This routine tells the total number of events that an ET system has.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if numevents is NULL

int et_system_geteventsize (et_sys_id id, int *eventsize)

Purpose:

This routine tells the size in bytes of standard events in an ET system.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if eventsize is NULL

int et_system_gettempsmax (et_sys_id id, int *tempsmax)

Purpose:

This routine gives the maximum number of temporary events allowed in an ET system.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if tempsmax is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_getstationsmax (et_sys_id id, int *stationsmax)

Purpose:

This routine gives the maximum number of stations allowed in an ET system.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if stationsmax is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_getprocsmax (et_sys_id id, int *procsmax)

Purpose:

This routine gives the maximum number of processes that are allowed to open an ET system.

Arguments:

1.      id is the id of the ET system of interest

2.      procsmax is a pointer to an integer that gets filled in with the maximum number of processes that are allowed to open an ET system.

Returns:

1.      ET_OK

2.      ET_ERROR if procsmax is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_getattsmax (et_sys_id id, int *attsmax)

Purpose:

This routine gives the maximum number of attachments that are allowed in an ET system.

Arguments:

1.      id is the id of the ET system of interest

2.      attsmax is a pointer to an integer that gets filled in with the maximum number of attachments that are allowed in an ET system.

Returns:

1.      ET_OK

2.      ET_ERROR if attsmax is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_getheartbeat (et_sys_id id, int *heartbeat)

Purpose:

This routine gives the current value of the heartbeat of an ET system. For a healthy system, this value changes every heartbeat period.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if heartbeat is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_getpid (et_sys_id id, pid_t *pid)

Purpose:

This routine gives the pid of an ET system.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if pid is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_getprocs (et_sys_id id, int *procs)

Purpose:

This routine gives the number of processes that currently have an ET system open.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if procs is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_getattachments (et_sys_id id, int *atts)

Purpose:

This routine gives the number of attachments currently in an ET system.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if atts is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_getstations (et_sys_id id, int *stations)

Purpose:

This routine gives the current number of stations in an ET system that are either idle or active (but not unused or being created).

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if stations is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_gettemps (et_sys_id id, int *temps)

Purpose:

This routine gives the number of temporary events currently in an ET system.

Arguments:

1.      id is the id of the ET system of interest

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

Returns:

1.      ET_OK

2.      ET_ERROR if temps is NULL

3.      ET_ERROR_READ for a remote user's network read error

4.      ET_ERROR_WRITE for a remote user's network write error

int et_system_gethost (et_sys_id id, char *host)

Purpose:

This routine gives the fully qualified name of the ET system's host computer.

Arguments:

1.      id is the id of the ET system of interest

2.      host is a pointer to a character array that gets filled in with the ET system's host name. To be safe the array should be at least ET_MAXHOSTNAMELEN characters long.

Returns:

1.      ET_OK

2.      ET_ERROR if host is NULL

int et_system_getserverport (et_sys_id id, unsigned short *port)

Purpose:

This routine gives the port number of the ET system's TCP server thread.

Arguments:

1.      id is the id of the ET system of interest

2.      port is a pointer to an unsigned short integer that gets filled in with the port number of the ET system's TCP server thread.

Returns:

1.      ET_OK

2.      ET_ERROR if port is NULL

int et_system_setgroup (et_sys_id id, int group)

Purpose:

This routine sets the default group number of the ET client. When the group is set to 0, calls to et_events(s)_new gets events of any group. When the group number is set to a positive number, the same calls only get events from the given group.

Arguments:

1.      id is the id of the ET system of interest

2.      group is the default event group number of the ET client.

Returns:

1.      ET_OK

2.      ET_ERROR if group < 0 or group > maximum number of groups in the ET system

int et_system_getgroup (et_sys_id id, int *group)

Purpose:

This routine gets the default event group number of the ET client.

Arguments:

1.      id is the id of the ET system of interest

2.      group is a pointer to an integer that gets filled in with the default event group number of the ET client.

Returns:

1.      ET_OK

2.      ET_ERROR if group is NULL

System Configuration Functions

int et_system_config_init (et_sysconfig* sconfig)

Purpose:

This routine initializes a system configuration. This MUST be done prior to setting any configuration parameters or all setting routines will return an error.

Arguments:

sconfig is pointer to a system configuration variable

Returns:

1.      ET_OK if successful

2.      ET_ERROR if it fails to allocate memory for configuration data storage

3.      ET_ERROR_NOMEM if there is not enough memory allocated to store network info. Recompile code with bigger value of ET_MAXADDRESSES.

int et_system_config_destroy (et_sysconfig sconfig)

Purpose:

This routine frees the memory allocated when a configuration is initialized by et_system_config_init.

Arguments:

sconfig is a system configuration

Returns:

ET_OK

int et_system_config_setevents (et_sysconfig sconfig, int val)

Purpose:

This routine sets a system configuration's total number of events.

Arguments:

1.      sconfig is a system configuration

2.      val must be greater than zero

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not an allowed value

int et_system_config_getevents (et_sysconfig sconfig, int *val)

Purpose:

This routine gets a system configuration's current total number of events.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer that gets filled with the total number of events

Returns:

ET_OK

int et_system_config_setsize (et_sysconfig sconfig, int val)

Purpose:

This routine sets a system configuration's event size in bytes.

Arguments:

1.      sconfig is a system configuration

2.      val must be greater than zero

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not an allowed value

int et_system_config_getsize (et_sysconfig sconfig, int *val)

Purpose:

This routine gets a system configuration's current event size.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer that gets filled with the event size in bytes

Returns:

ET_OK

int et_system_config_settemps (et_sysconfig sconfig, int val)

Purpose:

This routine sets a system configuration's total number of temporary events.

Arguments:

1.      sconfig is a system configuration

2.      val must be greater than zero

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not greater than zero

Notes:

The number of temp events must not be greater than the total number of events. This in not checked in this routine, but is checked when attempting to create an ET system.

int et_system_config_gettemps (et_sysconfig sconfig, int *val)

Purpose:

This routine gets a system configuration's current total number of temporary events.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer that gets filled with the number of temporary events

Returns:

ET_OK

int et_system_config_setstations (et_sysconfig sconfig, int val)

Purpose:

This routine sets a system configuration's limit on how many stations can be created.

Arguments:

1.      sconfig is a system configuration

2.      val must be greater than zero

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not greater than zero

int et_system_config_getstations (et_sysconfig sconfig, int *val)

Purpose:

This routine gets a system configuration's limit on how many stations can be created.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer that gets filled with the maximum number of stations that can be created

Returns:

ET_OK

int et_system_config_setprocs (et_sysconfig sconfig, int val)

Purpose:

This routine sets a system configuration's limit on how many user processes can open the system.

Arguments:

1.      sconfig is a system configuration

2.      val must be > 0 and <= ET_PROCESSES_MAX

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not greater than zero or not <= ET_PROCESSES_MAX

Notes:

The default value of ET_PROCESSES_MAX is 20 but may be changed in et_private.h, requiring a recompilation of ET.

int et_system_config_getprocs (et_sysconfig sconfig, int *val)

Purpose:

This routine gets a system configuration's limit on how many user processes can open the system.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer that gets filled with the configuration's limit on the number of processes that can open the system.

Returns:

ET_OK

int et_system_config_setattachments (et_sysconfig sconfig, int val)

Purpose:

This routine sets a system configuration's limit on how many user attachments to stations can exist at one time.

Arguments:

1.      sconfig is a system configuration

2.      val must be > 0 and <= ET_ATTACHMENTS_MAX

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not greater than zero or not <= ET_ATTACHMENTS_MAX

Notes:

The default value of ET_ATTACHMENTS_MAX is 20 but may be changed in et_private.h, requiring a recompile of the ET system library.

int et_system_config_getattachments (et_sysconfig sconfig, int *val)

Purpose:

This routine gets a system configuration's limit on how many user attachments to stations are possible.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer that gets filled with the system configuration's limit on the number of attachments.

Returns:

ET_OK

int et_system_config_setfile (et_sysconfig sconfig, int *val)

Purpose:

This routine sets a system configuration's ET system file name.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer to a string or null-terminated character array containing the file name

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is NULL or too long

int et_system_config_getfile (et_sysconfig sconfig, int *val)

Purpose:

This routine gets a system configuration's ET system file name

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer to a char array that gets filled with the system file name.

Returns:

ET_OK

int et_system_config_addmulticast (et_sysconfig sconfig, char *val)

Purpose:

This routine adds a multicast address to a list, each address of which the ET system is listening on for UDP packets from users trying to find it.

Arguments:

1.      sconfig is an system configuration

2.      val is a multicast IP address in dotted-decimal form. There can be at most ET_MAXADDRESSES (defined in et_private.h as 10) addresses on the list. Duplicate entries are not added to the list.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, val is NULL, is too long or too short, or its first number is not between 224 and 239 inclusive.

int et_system_config_removemulticast (et_sysconfig sconfig, char *val)

Purpose:

This routine removes a multicast address from a list of addresses the ET system is listening on for UDP packets from users trying to find it.

Arguments:

1.      sconfig is an system configuration

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

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, val is NULL, is too long or too short, or its first number is not between 224 and 239 inclusive.

DEPRECATED

int et_system_config_setcast (et_sysconfig sconfig, int val)

Purpose:

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

Arguments:

1.      sconfig is a system configuration

2.      val is any integer

Returns:

1.      ET_OK

DEPRECATED

int et_system_config_getcast (et_sysconfig sconfig, int *val)

Purpose:

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

Arguments:

1.      sconfig is a system configuration

2.      val is an integer pointer

Returns:

1.      ET_OK

DEPRECATED

int et_system_config_setaddress (et_sysconfig sconfig, char *val)

Purpose:

This routine is replaced by et_system_config_addmulticast. For compatibility purposes it is included though it is deprecated. Currently it adds a multicasting address to the appropriate list, each address of which the ET system is listening on for UDP packets from users trying to find it.

Arguments:

1.      sconfig is an system configuration

2.      val is a multicast IP address in dotted-decimal format.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, val is NULL, is too long or too short, or its first number is not between 224 and 239 inclusive

DEPRECATED

int et_system_config_getaddress (et_sysconfig sconfig, char *val)

Purpose:

This routine has no replacement in this ET version and is included for compatibility purposes only, though it is deprecated. It returns the first multicast address listed unless there is none, in which case it returns the default IP subnet broadcast address. These are the destination addresses of the ET system discovery process.

Arguments:

1.      sconfig is an system configuration

2.      val is a character array that gets filled with the dotted-decimal form IP address

Returns:

ET_OK

int et_system_config_setport (et_sysconfig sconfig, unsigned short val)

Purpose:

This routine sets a system configuration's port number for the UDP broadcasting or multicasting used to discover this ET system by remote users.

Arguments:

1.      sconfig is a system configuration

2.      val is the port number of the broadcast or multicast communications. The default is ET_BROADCAST_PORT, defined in et.h as 11111. It may also be set to ET_MULTICAST_PORT or to any port number desired by the user.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is less than 1024

int et_system_config_getport (et_sysconfig sconfig, unsigned short *val)

Purpose:

This routine gets a system configuration's port number for the UDP broadcasting or multicasting used to discover this ET system by remote users.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer that gets filled with the port number

Returns:

ET_OK

int et_system_config_setserverport (et_sysconfig sconfig, unsigned short val)

Purpose:

This routine sets a system configuration's TCP  port number for the ET system (tcp server thread) used to communicate with remote users.

Arguments:

1.      sconfig is a system configuration

2.      val is the port number of the ET system server for remote users

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is less than 1024

Notes:

If this routine is called and used to explicitly set the ET system's TCP port, it either uses that port or the ET system process exits with an error. If this routine is NOT called, the system tries to use ET_SERVER_PORT (defined in et.h as 11111) as its port. If that fails it adds one to that value and tries again and so on until a couple thousand values have been tried at which time the process exits if not successful.

int et_system_config_getserverport (et_sysconfig sconfig, unsigned short *val)

Purpose:

This routine gets a system configuration's TCP port number for the ET system (tcp server thread) used to communicate with  remote users.

Arguments:

1.      sconfig is a system configuration

2.      val is a pointer that gets filled with the port number

Returns:

ET_OK

int et_system_config_setgroups (et_sysconfig sconfig, int groups[], int size)

Purpose:

This routine sets a system configuration's number of event groups and how many events are in each group. To prevent ET clients who grab new events from competing with each other for these new events, an ET system can divide events into groups. The given array specifies how many events are in each group. Groups are numbered sequentially from 1 (corresponding to the element group[0]). Clients may either call et_system_setgroup to specify which group to get events from when calling et_event(s)_new, or clients may call et_event(s)_new_group to obtain new events from a specific group regardless of any default group set by et_system_setgroup.

Arguments:

1.      config is a system configuration

2.      group  is the an array containing the number of events in each group. The index into the array plus one gives the group number. The first “size” number of elements must be positive integers. The sum of the first “size” elements must equal the total number of events in the system.

3.      size  is the number of array elements in group to be used.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, group is NULL,  size > ET_EVENT_GROUPS_MAX, or size < 1

Event Functions

int et_event_new (et_sys_id id, et_att_id att, et_event **pe, int wait, struct timespec *time, int size)

Purpose:

This routine is used when a user wants a blank or fresh event from the ET system into which it can place data.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id. This is obtained by attaching the user process to a station with et_station_attach.

3.      pe is a pointer to a pointer to an event. Declare it a pointer to an event such as "et_event *pe;". And pass it as "&pe".

4.      wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available before it returns and therefore may "hang". The timed option returns after a time set by the last argument. Finally, the async option returns immediately whether or not it was successful in obtaining a new event for the caller.

5.      time is used only with the wait = ET_TIMED option, where it gives the time to wait before returning. For other options it will be ignored.

6.      size is the number of bytes desired for the event's data

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad argument(s), attachment not active

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_REMOTE for a memory allocation error of a remote user

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

7.      ET_ERROR_DEAD if ET system is dead

8.      ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event

9.      ET_ERROR_TIMEOUT if timeout on ET_TIMED option

10.  ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.

11.  ET_ERROR_EMPTY if no events available in ET_ASYNC mode

Notes:

Performance will generally be best with the ET_SLEEP wait mode. It will slow with ET_TIMED, and will crawl with ET_ASYNC. All this routine does for a remote client is allocate memory in which to place event data. The error of ET_ERROR_WAKEUP is returned when the ET system dies, or a user calls et_wakeup_all or et_wakeup_attachment on the attachment, while waiting to read an event

int et_events_new (et_sys_id id, et_att_id att, et_event *pe[], int wait, struct timespec *time, int size, int num, int *nread)

Purpose:

This routine is used when a user wants an array of blank or fresh events from the ET system into which it can place data.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id. This is obtained by attaching the user process to a station with et_station_attach.

3.      pe is an array of pointers to events.

4.      wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available before it returns and therefore may "hang". The timed option returns after a time set by the last argument. Finally, the async option returns immediately whether or not it was successful in obtaining a new event for the caller.

5.      time is used only with the wait = ET_TIMED option, where it gives the time to wait before returning. For other options it will be ignored.

6.      size is the number of bytes desired for the event's data

7.      num is the number of desired events

8.      nread returns the number of events actually read

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad argument(s), attachment not active

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_REMOTE for a memory allocation error of a remote user

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

7.      ET_ERROR_DEAD if ET system is dead

8.      ET_ERROR_WAKEUP if told to stop sleeping while trying to get events

9.      ET_ERROR_TIMEOUT if timeout on ET_TIMED option

10.  ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.

11.  ET_ERROR_EMPTY if no events available in ET_ASYNC mode

Notes:

See et_event_new. If all processes in an ET system use block transfers such as this one, a speed increase of over 10X the single transfer rate is possible.

int et_event_new_group (et_sys_id id, et_att_id att, et_event **pe, int wait, struct timespec *time, int size, int group)

Purpose:

This routine is used when a user wants a blank or fresh event from the ET system into which it can place data and that event must belong to the given group.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id. This is obtained by attaching the user process to a station with et_station_attach.

3.      pe is a pointer to a pointer to an event. Declare it a pointer to an event such as "et_event *pe;". And pass it as "&pe".

4.      wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available before it returns and therefore may "hang". The timed option returns after a time set by the last argument. Finally, the async option returns immediately whether or not it was successful in obtaining a new event for the caller.

5.      time is used only with the wait = ET_TIMED option, where it gives the time to wait before returning. For other options it will be ignored.

6.      size is the number of bytes desired for the event's data

7.      group is the group number of event to be acquired

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad argument(s), attachment not active, group is < 1 or group > ET system’s highest group number

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_REMOTE for a memory allocation error of a remote user

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

7.      ET_ERROR_DEAD if ET system is dead

8.      ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event

9.      ET_ERROR_TIMEOUT if timeout on ET_TIMED option

10.  ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.

11.  ET_ERROR_EMPTY if no events available in ET_ASYNC mode

Notes:

Performance will generally be best with the ET_SLEEP wait mode. It will slow with ET_TIMED, and will crawl with ET_ASYNC. All this routine does for a remote client is allocate memory in which to place event data. The error of ET_ERROR_WAKEUP is returned when the ET system dies, or a user calls et_wakeup_all or et_wakeup_attachment on the attachment, while waiting to read an event

int et_events_new_group (et_sys_id id, et_att_id att, et_event *pe[], int wait, struct timespec *time, int size, int num, int group, int *nread)

Purpose:

This routine is used when a user wants an array of blank or fresh events from the ET system into which it can place data and those events must belong to the given group.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id. This is obtained by attaching the user process to a station with et_station_attach.

3.      pe is an array of pointers to events.

4.      wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available before it returns and therefore may "hang". The timed option returns after a time set by the last argument. Finally, the async option returns immediately whether or not it was successful in obtaining a new event for the caller.

5.      time is used only with the wait = ET_TIMED option, where it gives the time to wait before returning. For other options it will be ignored.

6.      size is the number of bytes desired for the event's data

7.      num is the number of desired events

8.      group is the group number of events to be acquired

9.      nread returns the number of events actually read

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad argument(s), attachment not active, group is < 1 or group > ET system’s highest group number

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_REMOTE for a memory allocation error of a remote user

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

7.      ET_ERROR_DEAD if ET system is dead

8.      ET_ERROR_WAKEUP if told to stop sleeping while trying to get events

9.      ET_ERROR_TIMEOUT if timeout on ET_TIMED option

10.  ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.

11.  ET_ERROR_EMPTY if no events available in ET_ASYNC mode

Notes:

See et_event_new. If all processes in an ET system use block transfers such as this one, a speed increase of over 10X the single transfer rate is possible.

int et_event_get (et_sys_id id, et_att_id att, et_event **pe, int wait, struct timespec *time)

Purpose:

This routine is used when a user wants to read a single event from the ET system.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id.

3.      pe is a pointer to a pointer to an event. Declare it a pointer to an event such as "et_event *pe;". And pass it as "&pe".

4.      wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available before it returns and therefore may "hang". The timed option returns after a time set by the last argument. Finally, the async option returns immediately whether or not it was successful in obtaining a new event for the caller. For remote users, the mentioned macros may be ORed with ET_MODIFY. This indicates to the ET server that the user intends to modify the data and so the server must NOT place the event immediately back into the ET system, but must do so only when et_event_put is called.

5.      time is used only with the wait = ET_TIMED option, where it gives the time to wait before returning. For other options it will be ignored.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_REMOTE for a memory allocation error of a remote user

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

7.      ET_ERROR_DEAD if ET system is dead

8.      ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event

9.      ET_ERROR_TIMEOUT if timeout on ET_TIMED option

10.  ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.

11.  ET_ERROR_EMPTY if no events available in ET_ASYNC mode

Notes:

For remote users, not specifying ET_MODIFY greatly increases ET system efficiency as extra communication between user & system and extra copying of the event data are avoided. The error of ET_ERROR_WAKEUP is returned when the ET system dies, or a user calls et_wakeup_all or et_wakeup_attachment on the attachment, while waiting to get an event.

int et_events_get (et_sys_id id, et_att_id att, et_event *pe[], int wait, struct timespec *time, int num, int *nread)

Purpose:

This routine is used when a user wants to read multiple events from the ET system.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id.

3.      pe is an array of pointers to events.

4.      wait is either ET_SLEEP, ET_ASYNC, or ET_TIMED. The sleep option waits until an event is available before it returns and therefore may "hang". The timed option returns after a time set by the last argument. Finally, the async option returns immediately whether or not it was successful in obtaining a new event for the caller. For remote users, the mentioned macros may be ORed with ET_MODIFY. This indicates to the ET server that the user intends to modify the data and so the server must NOT place the event immediately back into the ET system, but must do so only when et_events_put is called.

5.      time is used only with the wait = ET_TIMED option, where it gives the time to wait before returning. For other options it will be ignored.

6.      num is the number of events desired to be read.

7.      nread returns the number of events actually read

Returns:

1.      ET_OK, if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_REMOTE for a memory allocation error of a remote user

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

7.      ET_ERROR_DEAD if ET system is dead

8.      ET_ERROR_WAKEUP if told to stop sleeping while trying to get events

9.      ET_ERROR_TIMEOUT if timeout on ET_TIMED option

10.  ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.

11.  ET_ERROR_EMPTY if no events available in ET_ASYNC mode

Notes:

See et_event_get. If all processes in an ET system use block transfers such as this one, a speed increase of over 2X the single transfer rate is possible.

int et_event_put (et_sys_id id, et_att_id att, et_event *pe)

Purpose:

This routine is used when a user wants to return a single, previously read or new event into the ET system so processes downstream can use it or so it can be returned to GRAND_CENTRAL station.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id.

3.      pe is a pointer to an event. Declare it as "et_event *pe;", and pass it as "pe".

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

Notes:

Only the attachment (att) used to get an event can put that event into the ET system. If a process which did not get tries to put, an error will be returned. This is implemented in order to prevent a user from accidentally putting many identical events into the system thereby causing data and system corruption.

int et_events_put (et_sys_id id, et_att_id att, et_event *pe[], int num)

Purpose:

This routine is used when a user wants to return multiple, previously read or new events into the ET system so processes downstream can use it or so it can be returned to GRAND_CENTRAL station.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id.

3.      pe is an array of pointers to events.

4.      num is the number of events to be written.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_REMOTE for a memory allocation error of a remote user

6.      ET_ERROR_READ for a remote user's network read error

7.      ET_ERROR_WRITE for a remote user's network write error

Notes:

Only the attachment (att) used to get events can put those events into the ET system, otherwise an error will be returned. If any one of the events in the array is not owned by att, an error will result.

int et_event_dump (et_sys_id id, et_att_id att, et_event *pe)

Purpose:

This routine is used when a user wants to get rid of a single, previously read or new event so that no user processes downstream will ever see it. It is placed directly into the ET system's GRAND_CENTRAL station which recycles it.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id.

3.      pe is a pointer to an event. Declare it as "et_event *pe;", and pass it as "pe".

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_events_dump (et_sys_id id, et_att_id att, et_event *pe[], int num)

Purpose:

This routine is used when a user wants to get rid of multiple, previously read or new events so that no user processes downstream will ever see them. They are placed directly into the ET system's GRAND_CENTRAL station which recycles them.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id.

3.      pe is an array of pointers to events.

4.      num is the number of events to be written.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_REMOTE for a memory allocation error of a remote user

6.      ET_ERROR_READ for a remote user's network read error

7.      ET_ERROR_WRITE for a remote user's network write error

int et_event_getdata (et_event *pe, void **data)

Purpose:

This routine gets the pointer to an event's data.

Arguments:

1.      pe is a pointer to event.

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

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

int et_event_getdatastatus (et_event *pe, int *status)

Purpose:

This routine gets the status of an event's data.

Arguments:

1.      pe is a pointer to event.

2.      status is a pointer which gets filled with the status of an event's data. The status can be ET_DATA_OK, ET_DATA_CORRUPT, or ET_DATA_POSSIBLY_CORRUPT. Currently all data is ET_DATA_OK unless a user's process exits or crashes while having events obtained from the ET system but not put back. In that case, the ET system recovers the events and places them in either GRAND_CENTRAL station, the attachment's station's input list, or its output list depending on the station's configuration (see et_station_config_setrestore). If the events are NOT put back into GRAND_CENTRAL station to be recycled but are placed in the station's input or output list, the data status will become ET_DATA_POSSIBLY_CORRUPT. This simply warns the user that a process previously crashed with the event and may have corrupted its data.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

int et_event_setlength (et_event *pe, int len)

Purpose:

This routine records the length of data written into an event.

Arguments:

1.      pe is a pointer to event.

2.      len is the length in bytes of data written into the event.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if len is negative or bigger than the size of the memory buffer

int et_event_getlength (et_event *pe, int *len)

Purpose:

This routine gets the length of data written into an event in bytes.

Arguments:

1.      pe is a pointer to event.

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

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

int et_event_setpriority (et_event *pe, int pri)

Purpose:

This routine sets the priority of an event.

Arguments:

1.      pe is a pointer to event.

2.      pri is the priority of either ET_HIGH or ET_LOW.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

int et_event_getpriority (et_event *pe, int *pri)

Purpose:

This routine gets the priority of an event.

Arguments:

1.      pe is a pointer to event.

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

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

int et_event_setcontrol (et_event *pe, int con[], int num)

Purpose:

This routine sets the control array of an event.

Arguments:

1.      pe is a pointer to event.

2.      con is an integer array.

3.      num is the number of elements in the array.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

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

Purpose:

This routine gets the control array of an event.

Arguments:

1.      pe is a pointer to event.

2.      con is an integer array with at least ET_STATION_SELECT_INTS number of elements.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

int et_event_setendian (et_event *pe, int endian)

Purpose:

This routine sets the endian value of an event's data. Although an ET system automatically keeps track of the endianness of an event's data, this routine can override and directly set it.

Arguments:

1.      pe is a pointer to event.

2.      endian may be set to ET_ENDIAN_BIG, ET_ENDIAN_LITTLE, ET_ENDIAN_LOCAL (same endian as local host), ET_ENDIAN_NOTLOCAL (opposite endian as local host), or ET_ENDIAN_SWITCH (switch the endian from whatever it is).

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

int et_event_getendian (et_event *pe, int *endian)

Purpose:

This routine returns the endian value of an event's data.

Arguments:

1.      pe is a pointer to event.

2.      endian is a pointer which gets filled with the either ET_ENDIAN_BIG or ET_ENDIAN_LITTLE.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

int et_event_needtoswap (et_event *pe, int *swap)

Purpose:

This routine indicates whether an event's data needs to be swapped or not.

Arguments:

1.      pe is a pointer to event.

2.      swap is a pointer which gets filled in with either ET_SWAP or ET_NOSWAP.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

DEPRECATED

int et_event_CODAswap (et_event *pe)

Purpose:

This routine now does nothing and returns an error. It did an incomplete job of swapping evio data. To swap data properly, use the evio library’s provided function, void evioswap(uint32_t *buffer, int tolocal, uint32_t*dest), where if  tolocal = 0, buffer contains data of same endian as local host,  else buffer has data of opposite endian.

Arguments:

1.      pe is a pointer to event.

Returns:

1.      ET_ERROR

Station Functions

int et_station_create_at (et_sys_id id, et_stat_id *stat_id, char *stat_name, et_stat_config sconfig, int position, int parallelposition)

Purpose:

This routine creates a station provided that it does not already exist and the maximum number of stations has not been reached. The station's status is set to ET_STATION_IDLE. This changes to ET_STATION_ACTIVE when a process attaches to it. The ET system is immediately notified of the new station upon creation and will transfer events in and out as soon as it is active. It is placed at in the linked list of stations in the position given by the last argument or at the end if that argument is larger than the existing number of stations. The station may already exist, but if it has the same configuration, the id of the existing station is returned.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is a pointer to a station id number and returns the value of the newly created station's id.

3.      stat_name is the station name

4.      sconfig is a station configuration handle

5.      position is the position of the newly created station in the linked list of stations. It may have the value ET_END which specifies the end of that list. It may not have the value of zero which is the first position and reserved for GRAND_CENTRAL station.

6.      parallelposition is the position of the newly created station in the linked list of 1 group of parallel stations. It may have the value ET_END which specifies the end of that group. It may also have the value of ET_HEAD which specifies that a new group of parallel stations is being created and this is its head. However, if the head already exists, it may not have the value of zero, which is the first position, so that any existing head is never moved.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_EXISTS if station already exists and has a different configuration (stat_id is still set to the existing station's id)

6.      ET_ERROR_TOOMANY if the maximum number of stations already exist

7.      ET_ERROR_REMOTE for a memory allocation error of a remote user

8.      ET_ERROR_READ for a remote user's network read error

9.      ET_ERROR_WRITE for a remote user's network write error

int et_station_create (et_sys_id id, et_stat_id *stat_id, char *stat_name, et_stat_config sconfig)

Purpose:

This routine creates a station provided that it does not already exist and the maximum number of stations has not been reached. The station's status is set to ET_STATION_IDLE. This changes to ET_STATION_ACTIVE when a process attaches to it. The ET system is immediately notified of the new station upon creation and will transfer events in and out as soon as it is active. Its position is at the end of the linked list of stations. The station may already exist, but if it has the same configuration, the id of the existing station is returned.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is a pointer to a station id number and returns the value of the newly created station's id.

3.      stat_name is the station name

4.      sconfig is a station configuration handle

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_EXISTS if station already exist and has a different configurations (stat_id is still set to the existing station's id)

6.      ET_ERROR_TOOMANY if the maximum number of stations already exist

7.      ET_ERROR_REMOTE for a memory allocation error of a remote user

8.      ET_ERROR_READ for a remote user's network read error

9.      ET_ERROR_WRITE for a remote user's network write error

int et_station_remove (et_sys_id id, et_stat_id stat_id)

Purpose:

This routine deletes a station provided it is not GRAND_CENTRAL and provided there are no attached processes. The station's status is set to ET_STATION_UNUSED.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_attach (et_sys_id id, et_stat_id stat_id, et_att_id *att)

Purpose:

This routine will attach the user to a station - meaning that the user is free to read and write events from that station or to request new events. It returns a unique attachment id in the second argument which is to be used in all transactions with the station.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number

3.      att is a pointer to a attachment id which gets filled in by this routine.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_TOOMANY if the existing number of attachments is already equal to the station or system limit

5.      ET_ERROR_DEAD if ET system is dead

6.      ET_ERROR_REMOTE for a memory allocation error of a remote user

7.      ET_ERROR_READ for a remote user's network read error

8.      ET_ERROR_WRITE for a remote user's network write error

Notes:

When a user process attaches to a station, it is marked as an active station, which means it will start receiving events. To remove an attachment, call the routine et_station_detach.

int et_station_detach (et_sys_id id, et_att_id att)

Purpose:

This routine will detach a user attachment from a station meaning that the process can no longer read or write events from that station. It undoes what et_station_attach does.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

Notes:

If this routine detaches the last attachment to a station, it marks the station as idle. In other words, the station stops receiving events since no one is there to read them. All events remaining in the station's input list (after the detachment) will be moved to the output list and sent to other stations. One must detach all attachments to a station before the station can be removed.

int et_station_getposition (et_sys_id id, et_stat_id stat_id, int *position, int *parallelposition)

Purpose:

Gets the value of a station's position in the linked list of active and idle stations and its position within a group of parallel stations if it is one..

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      position is a pointer which gets filled in with the position

4.      parallelposition is a pointer which gets filled in with the parallel position, but only if it is a parallel station

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_setposition (et_sys_id id, et_stat_id stat_id, int position, int parallelposition)

Purpose:

Sets a station's position in the linked list of active and idle stations and the position within a group of parallel stations if it is one.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number. GRAND_CENTRAL station's position may not be changed.

3.      position is the position in the linked list of stations and must be greater than 0 as the first position (0) is reserved for GRAND_CENTRAL station. It may be ET_END to put it at the end of the list.

4.      parallelposition is the position within the group of a linked list of stations if it is one. It may be ET_HEAD to make it the head of a new group of parallel stations. It may be ET_END to put it at the end.  If the position parameter refers to an existing parallel station, this may be any value > 0 as it may not take the place of an existing head. Its configuration must also be compatible with existing parallel stations in the group.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or position argument values

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_isattached (et_sys_id id, et_stat_id stat_id, et_att_id att)

Purpose:

Is att attached to station stat_id?

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      att is the attachment id.

Returns:

1.      1 if attached

2.      0 if not attached

3.      ET_ERROR for bad argument(s)

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_exists (et_sys_id id, et_stat_id *stat_id, char *stat_name)

Purpose:

Given the name of a station, this routine tells whether the station exists or not. If it does, it gives a its id.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is a pointer to a station id which is filled if stat_name exists.

3.      stat_name is the station name

Returns:

1.      1 if station exists

2.      0 if station does not exist

3.      ET_ERROR for bad stat_name argument

4.      ET_ERROR_CLOSED if et_close already called

5.      ET_ERROR_DEAD if ET system is dead.

6.      ET_ERROR_REMOTE for a memory allocation error of a remote user

7.      ET_ERROR_READ for a remote user's network read error

8.      ET_ERROR_WRITE for a remote user's network write error

int et_station_name_to_id (et_sys_id id, et_stat_id *stat_id, char *stat_name)

Purpose:

Given the name of a station, this routine will return its id.

Arguments:

1.      id is the ET system id

2.      stat_id is a pointer that get filled in with the station's id number.

3.      stat_name is the station name

Returns:

1.      ET_OK

2.      ET_ERROR if no station by that name exists or stat_name is null

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_REMOTE for a memory allocation error of a remote user

6.      ET_ERROR_READ for a remote user's network read error

7.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getattachments (et_sys_id id, et_stat_id stat_id, int *numatts)

Purpose:

Gives the number of attachments to a station. This returns an error for unused stations.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      numatts is a pointer to int which gets filled in with the number of attachments

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getstatus (et_sys_id id, et_stat_id stat_id, int *status)

Purpose:

Return a station's status.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      status is a pointer which gets filled in with the status of the station

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead.

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getinputcount (et_sys_id id, et_stat_id stat_id, int *cnt)

Purpose:

Gives the number of events in a station's input list. This number changes rapidly and is likely to be out-of-date immediately.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      cnt is a pointer to int which gets filled in with the number of events in the station's input list

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead.

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getoutputcount (et_sys_id id, et_stat_id stat_id, int *cnt)

Purpose:

Gives the number of events in a station's output list. This number changes rapidly and is likely to be out-of-date immediately.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      cnt is a pointer which gets filled in with the number of events in the station's output list

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead.

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getblock (et_sys_id id, et_stat_id stat_id, int *block)

Purpose:

Gets the value of a station's blocking mode - whether all events pass through the station (blocking) or whether only a fixed size cue of events is filled with others by-passing the station..

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      block is a pointer which gets filled in with the blocking mode

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_setblock (et_sys_id id, et_stat_id stat_id, int block)

Purpose:

Sets a station's blocking mode. Determines whether all events pass through the station (blocking) or whether only a fixed size cue of events is filled while all others by-pass the station..

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      block must be either ET_STATION_BLOCKING or ET_STATION_NONBLOCKING

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or block argument values

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getuser (et_sys_id id, et_stat_id stat_id, int *user)

Purpose:

Gets the value of a station's user mode - the limit of how many users can attach to the station at one time.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      user is a pointer which gets filled in with the user mode

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_setuser (et_sys_id id, et_stat_id stat_id, int user)

Purpose:

Sets a station's user mode. Determines the limit of how many users can attach to the station at one time.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      user must be either ET_STATION_USER_MULTI, ET_STATION_USER_SINGLE, or a non-negative integer.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or user argument values

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getrestore (et_sys_id id, et_stat_id stat_id, int *restore)

Purpose:

Gets the value of a station's restore mode - whether, after an attached user process crashes, the events currently owned by that attachment are restored to the station's output list, input list, or to GRAND_CENTRAL station's input list.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      restore is a pointer which gets filled in with the restore mode

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_setrestore (et_sys_id id, et_stat_id stat_id, int restore)

Purpose:

Sets a station's restore mode. Determines whether, after an attached user process crashes, the events currently owned by that attachment are restored to the station's output list, input list, or to GRAND_CENTRAL station's input list.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      restore must be either ET_STATION_RESTORE_OUT, ET_STATION_RESTORE_IN, or ET_STATION_RESTORE_GC.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or restore argument values

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getcue (et_sys_id id, et_stat_id stat_id, int *cue)

Purpose:

Gets a station's cue value - the size of the input event list for nonblocking stations.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      cue is a pointer which gets filled in with the cue value

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_setcue (et_sys_id id, et_stat_id stat_id, int cue)

Purpose:

Sets a station's cue size. For a nonblocking station, the size of the input event cue (list) is set.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      cue must be an integer from 1 to the total number of events in the system.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or cue argument values

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getprescale (et_sys_id id, et_stat_id stat_id, int *prescale)

Purpose:

Gets a station's prescale value - the selection of every Nth event in blocking stations.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      prescale is a pointer which gets filled in with the prescale value

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_setprescale (et_sys_id id, et_stat_id stat_id, int prescale)

Purpose:

Sets a station's prescale value, thereby selecting every Nth event in blocking stations.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      prescale must be an integer greater than 0.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or prescale argument values

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getlib (et_sys_id id, et_stat_id stat_id, char *lib)

Purpose:

Gets the name of the shared library containing an event selection function provided by the user.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      lib is a character array which gets filled in with the lib name

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

Notes:

A station has a shared library name associated with it only in the ET_STATION_SELECT_USER select mode in which the user supplies his own function to select events.

int et_station_getfunction (et_sys_id id, et_stat_id stat_id, char *function)

Purpose:

Gets the name of the user-defined selection function provided when using the ET_STATION_SELECT_USER select mode.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      function is a character array which gets filled in with the function name

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

Notes:

A station has a function name associated with it only in the ET_STATION_SELECT_USER select mode in which the user supplies his own function to select events.

int et_station_getclass (et_sys_id id, et_stat_id stat_id, char *class)

Purpose:

For Java ET systems, gets the class containing the event selection method provided by the user.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      class is a character array which gets filled in with the class name

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

Notes:

A station has a function name associated with it only in the ET_STATION_SELECT_USER select mode in which the user supplies his own function to select events.

int et_station_getselectwords (et_sys_id id, et_stat_id stat_id, int select[])

Purpose:

Gets a station's array of selection integers (words) used to select events.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      select is an integer array with at least ET_STATION_SELECT_INTS number of elements which gets filled in with the station's selection array

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_setselectwords (et_sys_id id, et_stat_id stat_id, int select[])

Purpose:

Sets a station's array of selection integers (words) used to select events.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      select is an integer array that must have at least ET_STATION_SELECT_INTS number of elements.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is GRAND_CENTRAL or if bad stat_id or select argument values

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

int et_station_getselect (et_sys_id id, et_stat_id stat_id, int *select)

Purpose:

Gets the value of a station's select mode.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

3.      select is a pointer which gets filled in with the select mode

Returns:

1.      ET_OK if successful

2.      ET_ERROR if station is unused or bad stat_id argument

3.      ET_ERROR_CLOSED if et_close already called

4.      ET_ERROR_DEAD if ET system is dead

5.      ET_ERROR_READ for a remote user's network read error

6.      ET_ERROR_WRITE for a remote user's network write error

Station Configuration Functions

int et_station_config_init (et_statconfig* sconfig)

Purpose:

This routine initializes a station configuration. This MUST be done prior to setting any configuration parameters or all setting routines will return an error.

Arguments:

sconfig is pointer to a station configuration variable

Returns:

1.      ET_OK if successful

2.      ET_ERROR if it fails to allocate memory for configuration data storage

int et_station_config_destroy (et_statconfig sconfig)

Purpose:

This routine frees the memory allocating when a configuration is initialized by et_station_config_init.

Arguments:

sconfig is a station configuration

Returns:

ET_OK

int et_station_config_setblock (et_statconfig sconfig, int val)

Purpose:

This routine sets a station configuration's block mode.

Arguments:

1.      sconfig is a station configuration

2.      val must be either ET_STATION_BLOCKING or ET_STATION_NONBLOCKING

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not one of the allowed values

int et_station_config_getblock (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's current block mode value.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer that gets filled with the current value of the configuration block mode

Returns:

ET_OK

int et_station_config_setselect (et_statconfig sconfig, int val)

Purpose:

This routine sets a station configuration's select mode.

Arguments:

1.      sconfig is a station configuration

2.      val must be either ET_STATION_SELECT_ALL or ET_STATION_SELECT_MATCH, or ET_STATION_SELECT_USER

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not one of the allowed values

int et_station_config_getselect (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's current select mode value.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer that gets filled with the current value of the configuration select mode

Returns:

ET_OK

int et_station_config_setuser (et_statconfig sconfig, int val)

Purpose:

This routine sets a station configuration's user mode.

Arguments:

1.      sconfig is a station configuration

2.      val must be either ET_STATION_USER_MULTI or ET_STATION_USER_SINGLE

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not one of the allowed values

int et_station_config_getuser (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's current user mode value.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer that gets filled with the current value of the configuration user mode

Returns:

ET_OK

int et_station_config_setrestore (et_statconfig sconfig, int val)

Purpose:

This routine sets a station configuration's restore mode.

Arguments:

1.      sconfig is a station configuration

2.      val must be either ET_STATION_RESTORE_OUT or ET_STATION_RESTORE_IN, or ET_STATION_RESTORE_GC

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not one of the allowed values

int et_station_config_getrestore (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's current restore mode value.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer that gets filled with the current value of the configuration restore mode

Returns:

ET_OK

int et_station_config_setcue (et_statconfig sconfig, int val)

Purpose:

This routine sets the size of a station configuration's input list cue when the block mode is ET_STATION_NONBLOCKING.

Arguments:

1.      sconfig is a station configuration

2.      val must be greater than zero

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not an allowed value

Notes:

The value of the cue must not exceed the total number of events in the system. This is not checked until a station is created with this configuration - at which time cue is set to the total number of events in the system if it is set too high in this routine. Take notice that setting the value of the cue to the total # of events will, in essence, change the station into one which blocks (block mode of ET_STATION_BLOCKING). The reason for this is that all events will now pass through this station.

int et_station_config_getcue (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's current cue value.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer that gets filled with the current cue value

Returns:

ET_OK

int et_station_config_setprescale (et_statconfig sconfig, int val)

Purpose:

This routine sets the station configuration's prescale when the block mode is ET_STATION_BLOCKING.

Arguments:

1.      sconfig is a station configuration

2.      val must be greater than zero

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not an allowed value

int et_station_config_getprescale (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's current prescale value.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer that gets filled with the current prescale value

Returns:

ET_OK

int et_station_config_setselectwords (et_statconfig sconfig, int val[])

Purpose:

This routine sets the values of integers in the station configuration's array used to select events.

Arguments:

1.      sconfig is a station configuration

2.      val is an array of integers with at least ET_STATION_SELECT_INTS number of elements.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized

int et_station_config_getselectwords (et_statconfig sconfig, int val[])

Purpose:

This routine gets a station configuration's current select values.

Arguments:

1.      sconfig is a station configuration

2.      val is an array with at least ET_STATION_SELECT_INTS number of elements that gets filled with the current select values

Returns:

ET_OK

int et_station_config_setlib (et_statconfig sconfig, int *val)

Purpose:

This routine sets the value of a station configuration's shared library name - used for loading a user's function to select events.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer to a string or null-terminated char array containing the shared library name

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, or val is NULL, or val is too long

int et_station_config_getlib (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's current shared library name.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer to a char array that gets filled with the current shared library name

Returns:

ET_OK

int et_station_config_setfunction (et_statconfig sconfig, int *val)

Purpose:

This routine sets the value of a station configuration's function name - loaded from the shared library and used for allowing the user to select events.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer to a string or null-terminated char array containing the function name

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, or val is NULL, or val is too long

int et_station_config_getfunction (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's current function name.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer to a char array that gets filled with the current function's name

Returns:

ET_OK

int et_station_config_setclass (et_statconfig sconfig, int *val)

Purpose:

This routine sets the value of a station configuration's Java class name - used for loading a user's method to select events. Of course, this is applicable only when creating a station on a Java-based ET system.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer to a string or null-terminated char array containing the class name

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized, or val is NULL, or val is too long

int et_station_config_getclass (et_statconfig sconfig, int *val)

Purpose:

This routine gets a station configuration's Java class name. Of course, this is only applicable for stations on a Java-based ET system.

Arguments:

1.      sconfig is a station configuration

2.      val is a pointer to a char array that gets filled with the current class name

Returns:

ET_OK

Attachment Functions

int et_wakeup_attachment (et_sys_id id, et_att_id att)

Purpose:

This routine will wake up a single attachment that is blocked, waiting to read events from a station.

Arguments:

1.      id is the id of the ET system of interest

2.      att is the attachment id.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad att argument

3.      ET_ERROR_WRITE if a remote user's network write error

int et_wakeup_all (et_sys_id id, et_stat_id stat_id)

Purpose:

This routine will wake up all attachments that are blocked, waiting to read events from a station.

Arguments:

1.      id is the id of the ET system of interest

2.      stat_id is the station's id number.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad stat_id argument

3.      ET_ERROR_WRITE if a remote user's network write error

int et_attach_geteventsput (et_sys_id id, et_att_id att_id, int *highint, int *lowint)

Purpose:

This routine gets the number of events put into a station by an attachment. The number is returned in 2 integers for a total of 64 bits.

Arguments:

1.      id is the id of the ET system of interest

2.      att_id is the attachment's id number.

3.      highint is a pointer which gets filled in with the most significant 32 bits.

4.      lowint is a pointer which gets filled in with the least significant 32 bits.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad att_id argument

3.      ET_ERROR_DEAD if ET system is dead.

4.      ET_ERROR_READ for a remote user's network read error

5.      ET_ERROR_WRITE for a remote user's network write error

int et_attach_geteventsget (et_sys_id id, et_att_id att_id, int *highint, int *lowint)

Purpose:

This routine gets the number of events gotten from a station by an attachment. The number is returned in 2 integers for a total of 64 bits.

Arguments:

1.      id is the id of the ET system of interest

2.      att_id is the attachment's id number.

3.      highint is a pointer which gets filled in with the most significant 32 bits.

4.      lowint is a pointer which gets filled in with the least significant 32 bits.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad att_id argument

3.      ET_ERROR_DEAD if ET system is dead.

4.      ET_ERROR_READ for a remote user's network read error

5.      ET_ERROR_WRITE for a remote user's network write error

int et_attach_geteventsdump (et_sys_id id, et_att_id att_id, int *highint, int *lowint)

Purpose:

This routine gets the number of events dumped by an attachment. The number is returned in 2 integers for a total of 64 bits.

Arguments:

1.      id is the id of the ET system of interest

2.      att_id is the attachment's id number.

3.      highint is a pointer which gets filled in with the most significant 32 bits.

4.      lowint is a pointer which gets filled in with the least significant 32 bits.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad att_id argument

3.      ET_ERROR_DEAD if ET system is dead.

4.      ET_ERROR_READ for a remote user's network read error

5.      ET_ERROR_WRITE for a remote user's network write error

int et_attach_geteventsmake (et_sys_id id, et_att_id att_id, int *highint, int *lowint)

Purpose:

This routine gets the number of new events gotten from a station by an attachment. The number is returned in 2 integers for a total of 64 bits.

Arguments:

1.      id is the id of the ET system of interest

2.      att_id is the attachment's id number.

3.      highint is a pointer which gets filled in with the most significant 32 bits.

4.      lowint is a pointer which gets filled in with the least significant 32 bits.

Returns:

1.      ET_OK if successful

2.      ET_ERROR if bad att_id argument

3.      ET_ERROR_DEAD if ET system is dead.

4.      ET_ERROR_READ for a remote user's network read error

5.      ET_ERROR_WRITE for a remote user's network write error

Bridge Functions

int et_events_bridge (et_sys_id id_from, et_sys_id id_to, et_att_id att_from, et_att_id att_to, et_bridgeconfig bconfig, int num, int *ntransferred)

Purpose:

This routine transfers events between two ET systems. Events are copied from the "from" ET system and placed into the "to" ET system. A function may be provided to swap the data during the transfer.

Arguments:

1.      id_from is the ID of the ET system from which the events are copied

2.      id_to is the ID of the ET system in which the events are placed

3.      att_from is the attachment to a station on the "from" ET system

4.      att_to is the attachment to a station on the "to" ET system (usually GRAND_CENTRAL)

5.      bconfig is the configuration of the remaining transfer parameters

6.      num is the total number of events desired to be transferred

7.      ntransferred is the total number of events that were actually transferred at the routine's return

Returns:

1.      ET_OK if successful

2.      ET_ERROR if error

3.      ET_ERROR_REMOTE for a memory allocation error of a remote user

4.      ET_ERROR_READ for a remote user's network read error

5.      ET_ERROR_WRITE for a remote user's network write error

6.      ET_ERROR_DEAD if ET system is dead

7.      ET_ERROR_WAKEUP if told to stop sleeping while trying to get an event

8.      ET_ERROR_TIMEOUT if timeout on ET_TIMED option

9.      ET_ERROR_BUSY if cannot get access to events due to activity of other processes when in ET_ASYNC mode.

10.  ET_ERROR_EMPTY if no events available in ET_ASYNC mode

Notes:

For the best performance, the process calling this routine should be on the same machine as either the "from" or "to" ET systems. Some experimentation is in order to determine which of the two machines will run the bridging faster. The author's experience suggests that placing the process on the machine with the most processors or computing power will probably give the best results. 

int et_bridge_config_init (et_bridgeconfig *config)

Purpose:

This routine initializes a configuration used by the routine et_events_bridge in transferring events between two  ET systems. This MUST be done prior to setting any configuration parameters or all setting routines will return an error.

Arguments:

config is pointer to an bridge configuration variable

Returns:

1.      ET_OK if successful

2.      ET_ERROR if it fails to allocate memory for configuration data storage

int et_bridge_config_destroy (et_bridgeconfig config)

Purpose:

This routine frees the memory allocated when a configuration is initialized by et_bridge_config_init.

Arguments:

config is an bridge configuration

Returns:

ET_OK

int et_bridge_config_setmodefrom (et_bridgeconfig config, int val)

Purpose:

This routine sets the mode of getting events from the "from" ET system.

Arguments:

1.      config is a bridge configuration

2.      val is set to either ET_SLEEP, ET_TIMED, or ET_ASYNC and determines the mode of getting events from the "from" ET system. The default is ET_SLEEP.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not ET_SLEEP, ET_TIMED, or ET_ASYNC

int et_bridge_config_getmodefrom (et_bridgeconfig config, int *val)

Purpose:

This routine gets the mode of getting events from the "from" ET system.

Arguments:

1.      config is a bridge configuration

2.      val is a pointer that gets filled with ET_SLEEP, ET_TIMED, or ET_ASYNC

Returns:

ET_OK

int et_bridge_config_setmodeto (et_bridgeconfig config, int val)

Purpose:

This routine sets the mode of getting new events from the "to" ET system.

Arguments:

1.      config is a bridge configuration

2.      val is set to either ET_SLEEP, ET_TIMED, or ET_ASYNC and determines the mode of getting new events from the "to" ET system. The default is ET_SLEEP.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val is not ET_SLEEP, ET_TIMED, or ET_ASYNC

int et_bridge_config_getmodeto (et_bridgeconfig config, int *val)

Purpose:

This routine gets the mode of getting new events from the "to" ET system.

Arguments:

1.      config is a bridge configuration

2.      val is a pointer that gets filled with ET_SLEEP, ET_TIMED, or ET_ASYNC

Returns:

ET_OK

int et_bridge_config_setchunkfrom (et_bridgeconfig config, int val)

Purpose:

This routine sets the maximum number of events to get from the "from" ET system in a single call to et_events_get - the number of events to get in one chunk.

Arguments:

1.      config is a bridge configuration

2.      val is any integer greater than one. The default is 100.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val less than one

int et_bridge_config_getchunkfrom (et_bridgeconfig config, int *val)

Purpose:

This routine gets the maximum number of events to get from the "from" ET system in a single call to et_events_get.

Arguments:

1.      config is a bridge configuration

2.      val is a pointer that gets filled with the number

Returns:

ET_OK

int et_bridge_config_setchunkto (et_bridgeconfig config, int val)

Purpose:

This routine sets the maximum number of new events to get from the "to" ET system in a single call to et_events_new - the number of events to get in one chunk.

Arguments:

1.      config is a bridge configuration

2.      val is any integer greater than one. The default is 100.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized or val less than one

int et_bridge_config_getchunkto (et_bridgeconfig config, int *val)

Purpose:

This routine gets the maximum number of new events to get from the "to" ET system in a single call to et_events_new.

Arguments:

1.      config is a bridge configuration

2.      val is a pointer that gets filled with the number

Returns:

ET_OK

int et_bridge_config_settimeoutfrom (et_bridgeconfig config, struct timespec val)

Purpose:

This routine sets the time to wait for the "from" ET system during all et_events_get calls when the mode is set to ET_TIMED.

Arguments:

1.      config is a bridge configuration

2.      val is the time to wait. The default is 0 seconds.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized

int et_bridge_config_gettimeoutfrom (et_bridgeconfig config, struct timespec *val)

Purpose:

This routine gets the time to wait for the "from" ET system during all et_events_get calls when the mode is set to ET_TIMED.

Arguments:

1.      config is a bridge configuration

2.      val is a pointer that gets filled with the time

Returns:

ET_OK

int et_bridge_config_settimeoutto (et_bridgeconfig config, struct timespec val)

Purpose:

This routine sets the time to wait for the "to" ET system during all et_events_new calls when the mode is set to ET_TIMED.

Arguments:

1.      config is a bridge configuration

2.      val is the time to wait. The default is 0 seconds.

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized

int et_bridge_config_gettimeoutto (et_bridgeconfig config, struct timespec *val)

Purpose:

This routine gets the time to wait for the "to" ET system during all et_events_new calls when the mode is set to ET_TIMED.

Arguments:

1.      config is a bridge configuration

2.      val is a pointer that gets filled with the time

Returns:

ET_OK

int et_bridge_config_setfunc (et_bridgeconfig config, ET_SWAP_FUNCPTR func)

Purpose:

This routine sets the function used to automatically swap data from one endian to another when bridging events between two ET systems.

Arguments:

1.      config is a bridge configuration

2.      func is the name of the function or function pointer. The default is NULL (no swapping).

Returns:

1.      ET_OK

2.      ET_ERROR if the sconfig was not initialized

Notes:

The function must be of the form: int func(et_event *src, et_event *dest, int bytes, int same_endian) . It returns ET_OK if successful otherwise ET_ERROR. The arguments consists of: src which is a pointer to the event whose data is to be swapped, dest which is a pointer to the event where the swapped data goes, bytes which tells the length of the data in bytes, and same_endian which is a flag equalling one if the machine and the data are of the same endian and zero otherwise. This function must be able to work with src and dest being the same event. With this as a prototype, the user can write a routine which swaps data in the appropriate manner. Notice that the first two arguments are pointers to events and not data buffers. This allows the writer of such a routine to have access to any of the event's header information. In general, such functions should NOT call et_event_setendian in order to change the registered endian value of the data. This is already taken care of  in et_events_bridge.

DEPRECATED

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

Purpose:

This routine now does nothing and returns an error. It did an incomplete job of swapping evio data. To swap data properly, use the evio library’s provided function, void evioswap(uint32_t *buffer, int tolocal, uint32_t*dest), where if  tolocal = 0, buffer contains data of same endian as local host,  else buffer has data of opposite endian.

This function was used as an argument in the routine et_bridge_config_setfunc to provide automatic swapping of CODA format data when bridging events between two ET systems.

Arguments:

1.      src is a pointer to an event whose data is to be swapped

2.      dest is a pointer to an event where the swapped data goes

3.      bytes is the length of the data in bytes

4.      same_endian is a flag equaling one if the machine and the data are of the same endian and zero otherwise

Returns:

1.      ET_ERROR

PreviousAdd Guide