General

These routines are called by a programmer wishing to open, close, kill, or interact in a general way with an ET system. More...

Functions
int	et_open (et_sys_id *id, const char *filename, et_openconfig openconfig)
	This routine opens an ET system for client use. More...
int	et_close (et_sys_id id)
	This routine closes an open ET system. More...
int	et_forcedclose (et_sys_id id)
	This routine closes an open ET system but differs from et_close in that it automatically closes all attachments. More...
int	et_kill (et_sys_id id)
	This routine kills an open ET system. More...
int	et_alive (et_sys_id id)
	This routine tells if an open ET system is alive (heartbeat is going). More...
int	et_wait_for_alive (et_sys_id id)
	This routine waits until given ET system is alive. More...

Detailed Description

These routines are called by a programmer wishing to open, close, kill, or interact in a general way with an ET system.

Function Documentation

int et_alive

(

et_sys_id

id

)

This routine tells if an open ET system is alive (heartbeat is going).

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.

Parameters

id	ET system id.

Returns

1 if ET system is alive.

0 if ET system is dead or bad arg.

References ET_LOCAL_NOSHARE, ET_REMOTE, etl_alive(), etn_alive(), etr_alive(), and et_id_t::locality.

Referenced by et_attach_geteventsdump(), et_attach_geteventsget(), et_attach_geteventsmake(), et_attach_geteventsput(), et_event_dump(), et_event_get(), et_event_new(), et_event_put(), et_events_dump(), et_events_get(), et_events_new(), et_events_new_group(), et_events_put(), et_station_attach(), et_station_create_at(), et_station_detach(), et_station_exists(), et_station_getattachments(), et_station_getblock(), et_station_getclass(), et_station_getcue(), et_station_getfunction(), et_station_getinputcount(), et_station_getlib(), et_station_getoutputcount(), et_station_getposition(), et_station_getprescale(), et_station_getrestore(), et_station_getselect(), et_station_getselectwords(), et_station_getstatus(), et_station_getuser(), et_station_isattached(), et_station_remove(), et_station_setblock(), et_station_setcue(), et_station_setposition(), et_station_setprescale(), et_station_setrestore(), et_station_setselectwords(), and et_station_setuser().

int et_close

(

et_sys_id

id

)

This routine closes an open ET system.

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.

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.

Parameters

id	ET system id.

Returns

ET_OK if successful

ET_ERROR if bad arg, not detached from all stations.

ET_ERROR_REMOTE for a local user on a non-mutex-sharing system (MacOS), if cannot unmap shared memory

References ET_ERROR, ET_LOCAL_NOSHARE, ET_REMOTE, etl_close(), etn_close(), etr_close(), and et_id_t::locality.

int et_forcedclose

(

et_sys_id

id

)

This routine closes an open ET system but differs from et_close in that it automatically closes all attachments.

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.

Parameters

id	ET system id.

Returns

ET_OK if successful

ET_ERROR if bad arg.

ET_ERROR_REMOTE for a local user on a non-mutex-sharing system (MacOS), if cannot unmap shared memory

References ET_ERROR, ET_LOCAL_NOSHARE, ET_REMOTE, etl_forcedclose(), etn_forcedclose(), etr_forcedclose(), and et_id_t::locality.

int et_kill

(

et_sys_id

id

)

This routine kills an open ET system.

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.

Parameters

id	ET system id.

Returns

ET_OK if successful, or if local client

ET_ERROR if bad arg.

ET_ERROR_WRITE if remote client and network writing error

ET_ERROR_REMOTE for a local user on a non-mutex-sharing system (MacOS), if cannot unmap shared memory

References ET_ERROR, ET_LOCAL_NOSHARE, ET_REMOTE, etl_kill(), etn_kill(), etr_kill(), and et_id_t::locality.

int et_open	(	et_sys_id *	id,
		const char *	filename,
		et_openconfig	openconfig
	)

This routine opens an ET system for client use.

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.

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.

Parameters

id	pointer to ET system id which gets filled in if ET system successfully opened.
filename	name of ET system file.
openconfig	ET system open configuration.

Returns

ET_OK if successful

ET_ERROR if bad arg, ET name too long, cannot initialize id, creating/using shared memory, incompatible values for ET_STATION_SELECT_INTS, or ET system is 32 bit and this program is 64 bit,

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

ET_ERROR_TOOMANY if broad/multicasting and too many responses

ET_ERROR_REMOTE if broad/multicasting and cannot find/connect to ET system or cannot allocate memory or ET system & user use different versions of ET, or the host has a strange byte order.

ET_ERROR_READ if network read error.

ET_ERROR_WRITE if network write error.

References ET_DEBUG_ERROR, ET_ERROR, ET_ERROR_JAVASYS, ET_ERROR_TOOMANY, ET_FILENAME_LENGTH, et_findlocality(), et_id_destroy(), et_id_init(), ET_LOCAL, ET_LOCAL_NOSHARE, et_logmsg(), ET_MUTEX_SHARE, ET_OK, et_open_config_destroy(), et_open_config_getdebugdefault(), et_open_config_init(), ET_POLICY_ERROR, ET_REMOTE, et_sharedmutex(), ET_STRUCT_OK, et_system_setdebug(), etl_open(), etn_open(), etr_open(), et_open_config_t::init, and et_open_config_t::policy.

int et_wait_for_alive

(

et_sys_id

id

)

This routine waits until given ET system is alive.

Parameters

id	ET system id.

Returns

ET_OK if successful and ET is alive.

ET_ERROR_WRITE if remote client and network writing error.

ET_ERROR_READ if remote client and network reading error.

References ET_LOCAL_NOSHARE, ET_REMOTE, etl_wait_for_alive(), etn_wait_for_alive(), etr_wait_for_alive(), and et_id_t::locality.