TINE System API routines: More...

Functions
int	_SystemCycle (int chkcmd)
	Required call for the TINE engine to function property.
void	_SystemDelay (int msec)
	Blocks any activity inside a TINE task or equipment modules for the specified amount of time.
int	_SystemFireEvent (char eqm, char prp)
	Schedules an event for the given property for immediate delivery to all attached clients.
int	_SystemInit (int chkcmd)
	Required call for the TINE server engine to function property.
int	_SystemReset (int level)
	Flushes all entry tables and returns all counters and semaphores to their initial state.
int	_SystemScheduleProperty (char eqm, char prp)
	Schedules the given property for immediate delivery to all attached clients.
int	_SystemSchedulePropertyEx (char eqm, char prp, int scope)
	Schedules the given property for immediate delivery to all attached clients according scope specified.
void	_SystemStop (int exitOnFree)
	Free all system resources and optionally exit.
int	clslog (char context, char tag, char logger, int priority, int status, char text,...)
	Sends a logging entry to the central logging server.
int	feclog (char *text,...)
	Puts entries into a server's log file.
int	GetBackgroundThreadPriority (void)
	Returns the priority of the registered background threads.
int	GetBurstLimit (void)
	Gets the burst limit in number of packets which are allowed to be sent consecutively.
int	GetClientThreadPriority (void)
	Returns the priority of the client cycle thread as well as other associated client-side threads.
int	GetContractAccessRate (int id)
	Returns the access rate (interval) associated with the given contract.
int	GetContractId (const char *eqm)
	Returns the last contract identifier for the equipment module specified.
int	GetCycleDelay (void)
	Gets the delay time in milliseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().
int	GetCycleMicroDelay (void)
	Gets the delay time in microseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().
double	GetDataTimeStamp (void)
	Returns the last established data timestamp.
struct timeval *	GetDataTimeStampAsTimeval (void)
	Returns the last established data timestamp as a pointer to a struct timeval.
char *	GetDataTimeString (double ts, int useLongStringFormat)
	Returns the TINE data timestamp as a human-readable string.
char *	GetFecHome (void)
	Gets the current setting for the fec home database repository.
int	GetFeclogDepth (void)
	Returns the maximum size of the server's log file in lines.
char *	GetFeclogPath (void)
	Gets the current setting for the fec log repository.
int	GetLastContractId (void)
	Returns the last contract identifier.
int	GetLastContractTableId (void)
	Returns the last contract table identifier.
int	GetPutCommandsInFeclog (void)
	Returns the current setting for putCommandsInFeclog (which determines whether all in-coming WRITE access calls are automatically included in the server's log file)
int	GetServerIdleState (char *eqm)
	Gets the server's idle state.
int	GetServerThreadPriority (void)
	Returns the priority of the server cycle thread as well as other associated server-side threads.
int	GetServerWaiting (void)
	Gets the server's waiting state.
int	GetStreamTransportRetryLimit (void)
	Returns the stream transport retry limit.
char *	GetSystemErrorString (short cc, char *errstr)
	Gets the system error code in plain text.
int	GetSystemLogging (void)
	Returns the current system logging setting (TRUE or FALSE)
int	GetSystemRequireAcknowledgments (void)
	Gets the require acknowledgments flag to the value given.
int	GetSystemSchedulePropertyLazy (void)
	Gets the 'lazy' flag for scheduling properties.
int	GetSystemUseDataProtection (void)
	Gets the data protection flag to the value given.
char *	GetSystemUserName (void)
	Gets the current value for the application user.
int	GetUseGlobalSynchronization (void)
	Returns whether data timestamps are to be externally synchronized.
int	GetUseMultiThreadedBackgroundTasks (void)
	Returns whether equipment module background tasks are to run in separate threads (boolean).
int	GetUseMultiThreadedEquipmentFunctions (void)
	Returns whether an equipment module equipment function can run in a separate threads (boolean).
int	GetUseMultiThreadedStockFunctions (void)
	Returns whether stock propery calls can run in a separate threads (boolean).
UINT32	GetWorkAreaSize (void)
	Gets the server-side work area size which is coupled to the maximum transport size for supported by a single-threaded server.
int	IsServerRunning (void)
	Returns TRUE (non zero) if the server kernel is fully initialized and ready.
int	LockEquipmentModules (void)
	Locks all equipment modules.
double	MakeDataTimeStamp (void)
	Returns a data timestamp according to the current system time.
int	microsleep (int usecs)
	sleep for given number of micro-seconds
double	PutDataTimeStamp (double toffset, time_t tsec, int tmsec)
	Returns a data timestamp according to the input parameters given.
int	ResetMultiChannelProperty (char eqm, char prp)
	sends (schedules) a 'reset_mca_property' signal to any listening client
int	SetBackgroundThreadPriority (int priority)
	Determines the priority of any registered background threads.
int	SetBurstLimit (int npackets)
	Sets the burst limit in number of packets which are allowed to be set consecutively.
int	SetClientThreadPriority (int priority)
	Determines the priority of the client cycle thread as well as other associated client-side threads.
int	SetCycleDelay (int msecs)
	Sets the delay time in milliseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().
int	SetCycleMicroDelay (int usecs)
	Sets the delay time in microseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().
void	SetDataTimeStamp (double ts)
	Sets the intrinsic data timestamp to the value given.
int	SetFecHome (char *fecHomePath)
	Sets the current fec home database repository.
void	SetFeclogDepth (int value)
	Determines the approximate size of the server's log file in lines.
int	SetKernelPriority (int priority)
	Determines the priority of TINE kernel threads.
void	SetPostSystemInitFunction (SYSTSKP fcn)
	Sets a user-specific initialization routine to be executed following server initialization.
void	SetPreSystemInitFunction (SYSTSKP fcn)
	Sets a user-specific initialization routine to be executed prior to server initialization.
void	SetPutCommandsInFeclog (int value)
	Determines whether all in-coming WRITE access calls are automatically included in the server's log file.
void	SetServerIdleState (char *eqm, int value)
	Sets the server's idle state to the value given.
int	SetServerThreadPriority (int priority)
	Determines the priority of the server cycle thread as well as other associated server-side threads.
void	SetServerWaiting (int value)
	Sets the server's waiting state to the value given.
void	SetStreamTransportRetryLimit (int value)
	Sets the stream transport retry limit.
void	SetSystemCleanupFunction (SYSTSKP fcn)
	Sets a user-specific cleanup routine to be executed as a final step during a normal cleanup phase (e.g. typing 'quit' or 'exit' at the command prompt.
void	SetSystemDataStamp (int value)
	Sets the global system data stamp with which to tag outbound data sets.
void	SetSystemLogging (int value)
	Sets system logging (output to fec.log) to TRUE or FALSE.
void	SetSystemRequireAcknowledgments (int value)
	Sets the require acknowledgments flag to the value given.
void	SetSystemSchedulePropertyLazy (int value)
	Sets the 'lazy' flag for scheduling properties.
void	SetSystemUseDataProtection (int value)
	Sets the data protection flag to the value given.
int	SetSystemUserName (char *usr)
	Sets the current value for the application user.
void	SetUseGlobalSynchronization (int value)
	Determines whether data timestamps are to be externally synchronized.
void	SetUseMultiThreadedBackgroundTasks (int value)
	Determines whether equipment module background tasks are to run in separate threads (boolean).
void	SetUseMultiThreadedEquipmentFunctions (int value)
	Determines whether an equipment module equipment function can run in a separate threads (boolean).
void	SetUseMultiThreadedStockFunctions (int value)
	Determines whether stock propery calls can run in a separate threads (boolean).
UINT32	SetWorkAreaSize (UINT32 size)
	Sets the server-side work area size which is coupled to the maximum transport size for supported by a single-threaded server.
BYTE *	SystemVersion (void)
	Returns the system version as a 4-byte array containg the major and minor version numbers as the first two bytes and the current revision in the next two bytes.
int	UnlockEquipmentModules (void)
	Unlocks all equipment modules.
Variables
int	FeclogDepth = FECLOG_DEPTH
	Determines the approximate size of the server's log file in lines.
int	nofeclog = FALSE
	Determines whether a server is to keep a log file on the local disk.
int	putCommandsInFeclog = TRUE
	Determines whether all in-coming WRITE access calls are automatically included in the server's log file.
int	StartupDebug = 1
	Determines whether server initialization messages are displayed or not.
int	useGlobalSynchronization = GLOBAL_SYNCHRONIZATION
	Determines whether data timestamps are to be externally synchronized.

Detailed Description

TINE System API routines:

The API routines offered here generally refer to the TINE engine and have relevance for both client-side and server-side programming. Some routines such as _SystemCycle() are required. Others such as _SystemInit() are required for server operation. Many routines are optional and offer ways of setting and getting system timestamps for instance or making entries into the server's log file.

Function Documentation

int _SystemCycle ( int chkcmd )

Required call for the TINE engine to function property.

Should be called within an infinite loop. Prior to the start of this loop, all other device server registration should occur. Clients with asynchronous links must see to it that _SystemCycle() is called regularly (unless SystemDelay(-1) is used to block the main process).

Parameters:

chkcmd is used to signal the presence of a local command interpreter. Developers wishing to bypass the built-in command interpreter in favor of another should pass FALSE for this argument

Note:: SystemCycle does will in general NOT monopolize the CPU as for most Operating systems, blocking sockets are used and the TINE Engine will itself block on select() for a duration not greater than the SystemPollingRate. A noteable exception is DOS, where non-blocking sockets are used and the TINE engine becomes a defacto operating system.

Returns:: 0 under normal circumstances. A non-zero return values indicates an immediate need to re-enter (i.e. following a complete cycle, there are still incomplete data transfer pending).

Note:: SystemCycle is macro #defined as _SystemCycle(). If additional 'cycle' procedures need to be incorporated, one can re-#define the SystemCycle() macro.

See also:: _SystemInit(), _SystemDelay(),

Alias: SystemCycle

Example:

#include "tine.h"
#include "bpmeqm.h"

void PreSystemInit(void);
void PostSystemInit(void);
int main(int argc, char *argv[])
{
  int cc;
  /* TODO: modify command line input to suit your own needs. */
  /* Here: the debug level is set according to initial input */
  switch (argc)
  {
    case 2:
      tineDebug = atoi(argv[1]);
      break;
    default:
      tineDebug = 0;
  }
  /* To deviate from default settings, initialize */
  /* any system variables in PreSystemInit() */

  PreSystemInit();

  /* initialize RPC server: */

  if ((cc=SystemInit(TRUE)) != 0)
  {
    printf(erlst[cc]);
    exit(1);
  }

  /* Make all other registrations in PostSystemInit() */

  PostSystemInit();

  for(;;)
  {
    SystemCycle(TRUE);
  }
  return 0;
}

void _SystemDelay ( int msec )

Blocks any activity inside a TINE task or equipment modules for the specified amount of time.

The TINE engine will continue to run and process data which is not related to 1) the equipment module being blocked if _SystemDelay() is called inside an equipment module or 2) the background task if _SystemDelay() is called inside a backgroung task.

Parameters:

msec	is the amount of time in milliseonds to suspend the calling routine.

Note:: The TINE engine is designed to run single-threaded. You are free to use threads and you can specify multi-threaded backgound tasks if you want the TINE engine itself to explicitly use threads. In such cases, calls to 'sleep()' would have their intended effect. Under single-threaded conditions (i.e. DOS, VMS, or you're avoided threads because they complicate things) you should not use 'sleep()' since you will block then entire TINE engine. Use _SystemDelay() instead if you want to wait at a specific spot in your code until some action has finished.; SystemDelay is macro #defined as _SystemDelay(). If additional 'delay' procedures need to be incorporated, one can re-#define the SystemDelay() macro.

See also:: _SystemCycle(), _SystemInit(),

Alias: SystemDelay

Example

...

WriteMyIOChannel(1,val);    // write something to channel 1
SystemDelay(50);            // give the hardware a bit of time
ReadMyIOChannel(1,&val);    // read it back 

...

int _SystemFireEvent	(	char *	eqm,
		char *	prp
	)

Schedules an event for the given property for immediate delivery to all attached clients.

Clients can attach to a particular property and reqest event notification only by applying the CM_EVENT polling mode. When a server schedules the property by calling either this routine of _SystemScheduleProperty() then the property handler is called and the attached clients receive the property's data (if any) and an event notification. This call is fully equivalent to _SystemScheduleProperty().

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prp	is (comma separated) list of properties which are to be scheduled.

Returns:: 0 upon success or a TINE error code.

See also:: _SystemScheduleProperty()

Alias: SystemFireEvent()

Example:

...
char errstr[256];

if ((rc = SystemScheduleProperty("EQM1","STATUS")) != 0)
{
  printf(“SystemScheduleProperty Failed: %s\n”,GetLastLinkError(rc,errstr));
}

...

References _SystemSchedulePropertyEx().

int _SystemInit ( int netchk )

Required call for the TINE server engine to function property.

Should be called prior to the start of the main TINE server engine. Any deviations from default system parameters should be made before any call to _SystemInit(). This might include server settings which fix the size of the local connection table entries, the maximum date transport size, etc. Note that _SystemInit() will begin be allocating space for its connection tables, so modifying these values away from their defaults will have no effect after _SystemInit() has been called. Also, if the FEC Name is given by calling RegisterFecInformation() or RegisterFecNameEx(), then this should also preceed a call to _SystemInit().

Parameters:

netchk is used only for MS-DOS servers and if TRUE will initialize a network SAP watchdog to check connectivity to a NetWare file server. For non-DOS servers it plays no role.

Note:: _SystemInit() does not and should not be called if you are writing a 'client-only' application. _SystemInit() will attempt to register various server settings which play no role, and will attempt to initiaze server sockets which could lead to confusing situations on the local computer. _SystemInit() does not initialize any client-side functioniality.

Returns:: 0 if successful, otherwise a TINE completion code which can be interpreted by a call to GetLastLinkError().

Note:: SystemInit is macro #defined as _SystemInit(). If additional 'init' procedures need to be incorporated, one can re-#define the SystemInit() macro.

See also:: _SystemCycle(), _SystemDelay(),

Alias: SystemInit

Example:

#include "tine.h"
#include "bpmeqm.h"

void PreSystemInit(void);
void PostSystemInit(void);
int main(int argc, char *argv[])
{
  int cc;
  /* TODO: modify command line input to suit your own needs. */
  /* Here: the debug level is set according to initial input */
  switch (argc)
  {
    case 2:
      tineDebug = atoi(argv[1]);
      break;
    default:
      tineDebug = 0;
  }
  /* To deviate from default settings, initialize */
  /* any system variables in PreSystemInit() */

  PreSystemInit();

  /* initialize RPC server: */

  if ((cc=SystemInit(TRUE)) != 0)
  {
    printf(erlst[cc]);
    exit(1);
  }

  /* Make all other registrations in PostSystemInit() */

  PostSystemInit();

  for(;;)
  {
    SystemCycle(TRUE);
  }
  return 0;
}

int _SystemReset ( int level )

Flushes all entry tables and returns all counters and semaphores to their initial state.

Useful under some circumstances, for instance following program suspension or interrupt due to CNTL-C, etc.

Parameters:

level is reserved for future use.

Returns:: 0 if successful, otherwise a TINE completion code which can be interpreted by a call to GetLastLinkError().

Note:: SystemReset is macro #defined as _SystemReset(). If additional 'reset' procedures need to be incorporated, one can re-#define the SystemReset() macro.

See also:: _SystemInit(), _SystemCycle(),

Alias: SystemReset

Example:

   if ((cc=SystemReset(0)) != 0) printf("Could not reset system : %s\n", cc2str(cc));

References feclog().

int _SystemScheduleProperty	(	char *	eqm,
		char *	prp
	)

Schedules the given property for immediate delivery to all attached clients.

When clients are attached to a particular property, they have specified a polling rate, which defines the maximum latency for receiving updates at the client side. This is usually fine. However, if a server knows that important data have changed and which properties depend on these data, it can signal the scheduler to call the given properties immediately and send the data to all attached callers, regardless of their registered polling rates. In this way, a server can signal an event to its attached clients.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prp	is (comma separated) list of properties which are to be scheduled.

Returns:: 0 upon success or a TINE error code.

Alias: SystemScheduleProperty()

Example:

...
char errstr[256];

if ((rc = SystemScheduleProperty("EQM1","STATUS")) != 0)
{
  printf(“SystemScheduleProperty Failed: %s\n”,GetLastLinkError(rc,errstr));
}

...

References _SystemSchedulePropertyEx().

int _SystemSchedulePropertyEx	(	char *	eqm,
		char *	prp,
		int	scope
	)

Schedules the given property for immediate delivery to all attached clients according scope specified.

When clients are attached to a particular property, they have specified a polling rate, which defines the maximum latency for receiving updates at the client side. This is usually fine. However, if a server knows that important data have changed and which properties depend on these data, it can signal the scheduler to call the given properties immediately and send the data to all attached callers, regardless of their registered polling rates. In this way, a server can signal an event to its attached clients. In this extended call, the caller can specify the 'scope' of the call : CA_NETWORK (all listening clients), CA_HIST (the local history subsystem) or CA_ALARM (the local alarm server).

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prp	is (comma separated) list of properties which are to be scheduled.
scope	is any of CA_NETWORK, CA_HIST, or CA_ALARM ORed together. Note: a call to _SystemScheduleProperty() is equivalent to supplying all bits.

Returns:: 0 upon success or a TINE error code.

Alias: SystemSchedulePropertyEx()

Example:

...
char errstr[256];

if ((rc = SystemScheduleProperty("EQM1","STATUS")) != 0)
{
  printf(“SystemScheduleProperty Failed: %s\n”,GetLastLinkError(rc,errstr));
}

...

References GetDeviceNumberEx().

Referenced by _SystemFireEvent(), _SystemScheduleProperty(), and ResetMultiChannelProperty().

void _SystemStop ( int exitOnFree )

Free all system resources and optionally exit.

Calling this routine will close down all client-side connections, call any registered equipment module exit routines, stop all registered background tasks, free up all system memory, close all system sockets and pipes, and call exit(0) if the 'exitOnFree' parameter is TRUE.

Parameters:

exitOnFree if TRUE will call exit(0) after freeing resources. Otherwise the process will remain active (for an additional startup sequence, for example).

Note:: SystemStop is macro #defined as _SystemStop(). If additional 'stop' procedures need to be incorporated, one can re-#define the SystemStop() macro.

References feclog().

int clslog	(	char *	context,
		char *	tag,
		char *	logger,
		int	priority,
		int	status,
		char *	text,
			...
	)

Sends a logging entry to the central logging server.

An application (be it client or server) can send an entry to the central logger at any time. As this will require WRITE access, the entry will only be accepted if the caller has WRITE privileges.

Parameters:

context	is the logging context. If NULL or empty, the currently defined TINE context will be used. Logging entries can be browsed or sorted according to context.
tag	is a brief logging tag. Logging entries can be browsed or sorted according to logging tag.
logger	is the user submitting the logging entry. This is typically the user name, but can be a fec name, or application name, for example. Logging entries can be browsed or sorted according the logger.
priority	is the logging entry priority. This should be one of CLOG_PRIORITY_NONE, CLOG_PRIORITY_USEFUL, CLOG_PRIORITY_IMPORTANT, or CLOG_PRIORITY_URGENT.
status	is the logging status. This should be one of CLOG_STATUS_NONE, CLOG_STATUS_INFO, CLOG_STATUS_WARN, or CLOG_STATUS_ERR.
text	is the logging entry. Variable argument ellipses (i.e. printf-style) is allowed.

Returns:: 0 upon success, otherwise a TINE error code.

See also:: feclog()

References AttachLink(), CLOG::context, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DTYPE::dTag, feclog(), CLOG::logger, CLOG::priority, CLOG::status, CLOG::tag, CLOG::text, CLOG::timeSent, and DUNION::vptr.

int feclog	(	char *	text,
			...
	)

Puts entries into a server's log file.

Server be default maintain a log file (fec.log) which contains system information at startup and shutdown time, as well as WRITE access command calls, as well as other notifications. The server can all place its own text in the server's log file by using this routine. All entries will be appended with a time stamp and a new-line character.

Parameters:

text	is the text string (up to 200 characters) to be logged.

Returns:: 0 if successful, otherwise a TINE error code.

See also:: GetCompletionStatus(); gFeclogPath; vfeclog(); SetFeclogDepth()

Referenced by _SystemAssignBufferSpace(), _SystemReset(), _SystemStop(), AddFieldToBitField(), AppendAlarmInfoTable(), AppendAlarmWatchTable(), AppendHistoryInformationEx(), clslog(), FindNameServerOnNetwork(), GetGroupMemberList(), OpenBitField(), RegisterCycleTriggerFunction(), RegisterDeviceName(), RegisterFecInformation(), RegisterPropertyInformation(), RemoveDeviceAlarm(), SealTaggedStruct(), sendNetGlobal(), SetAlarmCodeOscillationWindow(), SetAlarmOscillationWindow(), SetAllowNetworkAddressResolution(), SetBurstLimit(), SetExportedContext(), SetExportedSubSystem(), SetFailoverPollingInterval(), SetFailoverThreshold(), SetFecHome(), SetFeclogDepth(), SetGCastAddr(), SetGCastMask(), SetHistoryFilesRepository(), SetHistoryStaticFilesRepository(), SetLinkWatchdogPollingInterval(), SetMaxTcpMessageSize(), SetMCastAddr(), SetMCastMask(), SetMCastTTL(), SetMinimumAllowedPollingInterval(), SetMinimumDiskSpaceInBlocks(), SetPacketMTU(), SetServerTransportCeiling(), SetSizeDeviceCapacity(), SetSystemCycleDeadband(), SetSystemSubscriptionRenewalLength(), SetUseGlobalSynchronization(), SetUseStandardHistoryFiles(), SystemGetStartupCommand(), SystemKillCycleTimer(), and UnregisterCycleTriggerFunction().

int GetBackgroundThreadPriority ( void )

Returns the priority of the registered background threads.

Returns:: the background thread priority.

See also:: SetBackgroundThreadPriority().

int GetBurstLimit ( void )

Gets the burst limit in number of packets which are allowed to be sent consecutively.

For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the cycle delay and determines how many UDP packets (datagrams) are allowed to be sent consecutively within the transport loop before a brake is applies (cycle delay). If all clients and servers are on the same speed ethernet, this value can be adjusted to a much larger value. However, a fast server sending to a slow client (a remote client via a DSL link for instance) might send more datagrams in a burst than can be received. The default value should compensate for this effect.

Returns:: The current setting for the burst limit.

See also:: SetBurstLimit(), SetCycleDelay().

int GetClientThreadPriority ( void )

Returns the priority of the client cycle thread as well as other associated client-side threads.

Returns:: the client thread priority.

See also:: SetClientThreadPriority().

int GetContractAccessRate ( int id )

Returns the access rate (interval) associated with the given contract.

A server can retieve the access rate of the specified contract. If a negative number is passed, then the most recently invoked contract is assumed. This routine is most usefull however when used within a server's equipment module.

Parameters:

id	is the contract table indentifier whose access rate is desired

Note:: A contract table identifier is a dynamic thing, to the extent that if a contract comes and goes (is not persistent) it can have a different ID when it comes again.

Returns:: a valid contract ID or -1 if the contract table is empty.

int GetContractId ( const char * eqm )

Returns the last contract identifier for the equipment module specified.

A server can retieve the current contract identifier when the equipment module dispatch routine is being called. If this routine is called outside of the dispatch routine, the value returned will only represent the contract ID valid when the equipment module was last called.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".

Note:: A contract table identifier is a dynamic thing, to the extent that if a contract comes and goes (is not persistent) it can have a different ID when it comes again.

Returns:: a valid contract ID or -1 if there is an error (parameter is invalid).

int GetCycleDelay ( void )

Gets the delay time in milliseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().

For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the burst limit and determines how long to delay further datagram transmission when the burst limit has been reached. If all clients and servers are on the same speed ethernet, this value can be adjusted to 0. However, a fast server sending to a slow client (a remote client via a DSL link for instance) might send more datagrams in a burst than can be received. The default value should compensate for this effect.

Returns:: The current setting for the cycle delay.

See also:: SetBurstLimit(), SetCycleDelay().

int GetCycleMicroDelay ( void )

Gets the delay time in microseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().

For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the burst limit and determines how long to delay further datagram transmission when the burst limit has been reached. If all clients and servers are on the same speed ethernet, this value can left at its default value 0. However, when fine adjustments in flow control are necessary, a delay in the micro second region following each 'burst' of packets can be applied, where the delay in microseconds is given by this setting.

Returns:: The current setting for the cycle micro delay.

See also:: SetBurstLimit(), SetCycleDelay().

double GetDataTimeStamp ( void )

Returns the last established data timestamp.

A call to getDataTimeStamp() immediately following a call to ExecLink() or within a callback routine will yield the data timestamp of the call.

Note:: This call is not thread-safe. Synchronous data acquisition on two different threads could conceivably interfer with the value returned from this routine. A thread-safe way of obtaining the data timestamp associated with a call is to use the .dTimestamp field of the DTYPE object for synchronous calls such as ExecLink() or ExecLinkEx() or to use getCurrentDataTimeStampFromCallbackId() or getCurrentDataTimeStamp() (which take a link identifier as input parameter) for asynchronous links.

Returns:: The data timestamp currently in place.

See also:: MakeDataTimeStamp; GetDataTimeStampAsTimeval, GetCurrentDataTimeStamp, GetCurrentDataTimeStampFromCallbackId

struct timeval* GetDataTimeStampAsTimeval ( void ) [read]

Returns the last established data timestamp as a pointer to a struct timeval.

A call to getDataTimeStampAsTimeval() immediately following a call to ExecLink() or within a callback routine will yield the data timestamp of the call.

Note:: This call is not thread-safe. See the discussion in getDataTimeStamp() for details.

Returns:: A pointer to a struct timeval containing the data timestamp currently in place.

See also:: MakeDataTimeStamp; GetDataTimeStamp, GetCurrentDataTimeStamp, GetCurrentDataTimeStampFromCallbackId

char* GetDataTimeString	(	double	ts,
		int	useLongStringFormat
	)

Returns the TINE data timestamp as a human-readable string.

A call to getDataTimeStamp() returns an 8-byte double containing the current TINE system timestamp. This will be the UTC timestamp appended with milliseconds after the decimal (if available). This timestamp can be converted to a human readable string with this call. The format will depend on the value of the second parameter. If useLongStringFormat is non-zero, the a date of the form:

"Mon Jan 10 12:08:43.355 CET 2005"

will be returned. If useLongStringFormat is zero, then the date string will be of the form (dd.mm.yy hh:mm:ss.msec TZ):

"10.01.05 12:08:43.355 CET"

Parameters:

ts	is the TINE Data Timestamp for which the string conversion is to be applied.
useLongStringFormat	is a flag which if non-zero returns a longer representation of the timestamp.

Note:: This call is not thread-safe. See the discussion in getDataTimeStamp() for details.

Returns:: A pointer to a string containing the timestamp representation.

See also:: MakeDataTimeStamp; GetDataTimeStamp, GetCurrentDataTimeStamp, GetCurrentDataTimeStampFromCallbackId; ctime(); localtime(); findDaylight()

char* GetFecHome ( void )

Gets the current setting for the fec home database repository.

Returns:: A string pointing to the current setting for the fec home database repository

int GetFeclogDepth ( void )

Returns the maximum size of the server's log file in lines.

The server's log file, if located on the local disk, is a file called 'fec.log'. When it's length surpasses the FecLogDepth, this file is rotated to 'fec.bak' and a new 'fec.log' file is started. A call for the server's log file will always be able to scan both the 'fec.bak' file and 'fec.log', and will thus always be able to scan at least FeclogDepth entries.

Returns:: the current setting.

References FeclogDepth.

char* GetFeclogPath ( void )

Gets the current setting for the fec log repository.

Returns:: A string pointing to the current setting for the fec log repository

int GetLastContractId ( void )

Returns the last contract identifier.

A server can retieve the last contract identifier at any time.

Note:: A contract table identifier is a dynamic thing, to the extent that if a contract comes and goes (is not persistent) it can have a different ID when it comes again.

Returns:: a valid contract ID or -1 if the contract table is empty.

int GetLastContractTableId ( void )

Returns the last contract table identifier.

A server can retieve the last contract table identifier at any time. This routine is most usefull however when used within a server's equipment module.

Note:: A contract table identifier is a dynamic thing, to the extent that if a contract comes and goes (is not persistent) it can have a different ID when it comes again.

Returns:: a valid contract ID or -1 if the contract table is empty.

int GetPutCommandsInFeclog ( void )

Returns the current setting for putCommandsInFeclog (which determines whether all in-coming WRITE access calls are automatically included in the server's log file)

Returns:: the current setting for putCommandsInFeclog

See also:: SetPutCommandsInFeclog

int GetServerIdleState ( char * eqm )

Gets the server's idle state.

A Server can be set in an idle state where no background activity occurs and the server's equipment function is temporarily disabled. This call returns the current idle state of the equipment module specified.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".

Returns:: the value of the idle state.

See also:: SetServerIdleState()

int GetServerThreadPriority ( void )

Returns the priority of the server cycle thread as well as other associated server-side threads.

Returns:: the server thread priority.

See also:: SetServerThreadPriority().

int GetServerWaiting ( void )

Gets the server's waiting state.

A Server can be set in a wait state prior to initialization by passing a non-zero value as argument. In this state, the server will respond to all contract requests with the status code 'not_initialized'. This is useful, if the server needs to undergo a long initialization precedure before allowing clients access. The call retrieves the current wait state (0 = not waiting, non-zero = waiting). The server's wait state is, of course, FALSE (not waiting) by default.

Returns:: the value of the wait state.

See also:: SetServerWaiting()

int GetStreamTransportRetryLimit ( void )

Returns the stream transport retry limit.

When a server attempts to deliver data via a stream (TCP) connection to a client it attempts to find available TCP send buffers to deliver the data. This generally is successful upon the initial attempt but can fail due to network or buffering congestion. In such cases a delay of a clock tick and a retry will then succeed. The number of times these retries are allowed to happen are influenced by this parameter setting. The default value of '2' is generally correct, but under some conditions (one sluggish client) can impede transfer to other clients and in such cases it might be advisible to set this value to a lower value or even to '0' so as not to make all attached clients suffer.

Returns:: the current setting for the stream transport retry limit (default = 2).

See also:: SetStreamTransportRetryLimit().

char* GetSystemErrorString	(	short	cc,
		char *	errstr
	)

Gets the system error code in plain text.

This routine only returns the corresponding string for TINE system error codes. User defined error codes should use the routine GetLastLinkError().

Parameters:

cc	is the completion code or status code for which the internal system error string is desired.
errstr	is a string buffer capable of handling up to 32 characters.

Returns:: a pointer to the string buffer 'errstr' given (unless NULL).

See also:: GetLastLinkError()

int GetSystemLogging ( void )

Returns the current system logging setting (TRUE or FALSE)

See also:: SetSystemLogging().

int GetSystemRequireAcknowledgments ( void )

Gets the require acknowledgments flag to the value given.

A server normally requires an acknowledgment from clients being sent changed data if the client link is a data-change style monitor. Under some circumstances this extra acknowledgment network traffic might be unnecessary or undesireable. The current setting can be acquired with this function call.

Returns:: the current setting for the require acknowledgments flag.

See also:: SetSystemRequireAcknowledgments()

References RequireAcknowledgments.

int GetSystemSchedulePropertyLazy ( void )

Gets the 'lazy' flag for scheduling properties.

When a property is scheduled, the delivery can either occur immedidately (default) and thereby invoke the TINE scheduler withing the call to SystemScheduleProperty() or occur withing the next normal delivery cycle (lazy), which could add a latency of up to a clock tick to the delivery. This call reads the 'lazy flag'.

Returns:: the current setting of the schedule property 'lazy' flag.

See also:: _SystemScheduleProperty(), _SystemSchedulePropertyEx(), SetSystemSchedulePropertyLazy()

int GetSystemUseDataProtection ( void )

Gets the data protection flag to the value given.

Multi-threaded servers using background tasks can ensure the thread safety of any data sets used in both an equipment module's background thread and dispatch function handler by explicit coding. As an alternative, calling this routine at initialization time with a non-zero value will automatically generate a data protection mutex which will prevent concurrent exectution of a module's background task and dispatch handler.

Returns:: the current setting;

char* GetSystemUserName ( void )

Gets the current value for the application user.

Returns:: A string pointing to the current value of the application user, typically the logged in user or, if the application is a FEC, the FEC name.

int GetUseGlobalSynchronization ( void )

Returns whether data timestamps are to be externally synchronized.

Returns:: TRUE or FALSE

See also:: SetUseGlobalSynchronization()

References useGlobalSynchronization.

int GetUseMultiThreadedBackgroundTasks ( void )

Returns whether equipment module background tasks are to run in separate threads (boolean).

If set to TRUE, the server's background task will run in its own thread, where a multi-threaded build of the library is in use. Note that this could result in data concurrency issues if the background task is acquiring data which is to be used by an equipment module's equipment function.

Returns:: the current setting of this feature.

See also:: SetAllowBackgroundTaskReentrancy(), SetUseMultiThreadedBackgroundTasks().

int GetUseMultiThreadedEquipmentFunctions ( void )

Returns whether an equipment module equipment function can run in a separate threads (boolean).

If set to TRUE, the an equipment function will handle designated properties in a separate thread, where a multi-threaded build of the library is in use. Ordinarily an equipment function should be regarded as an interrupt service routine which should return 'promptly' after being called. All properties will be directed to the equipment function using the same thread as the server cycle, unless otherwise specified. On the other hand if a property is specifically registered to run the equipment module in a separate thread (because the action is known to require significant time to complete) then it will run in its own thread if this setting has been enabled. This will result in other calls to the equipment function receiving an 'operation busy' completion while the equipment function is handling the time-consuming call. Otherwise, concurrent calls will simply time out at the client side. To configure a property to be called in a separate thread one can either call SetCallPropertyInSeparateThread() following the property registration of supply an "MT" switch in the properties 'access' string which registering via file (either exports.csv or fec.xml).

Returns:: the current setting of this feature.

See also:: SetUseMultiThreadedEquipmentFunctions(), SetUseMultiThreadedStockFunctions(), SetCallPropertyInSeparateThread().

int GetUseMultiThreadedStockFunctions ( void )

Returns whether stock propery calls can run in a separate threads (boolean).

If set to TRUE, certain stock property calls will be handled in a separate thread, where a multi-threaded build of the library is in use. Ordinarily stock property calls return 'promptly' after being called, and make use of the same thread as the server cycle, unless otherwise specified. On the other hand certain stock properties which make heavy use of the local disk might require considerable time to complete, noteably calls to the local history subsystem or file retrieval calls. A calls to such property will run in its own thread if this setting has been enabled. This will result in other calls to the same stock property receiving an 'operation busy' completion while the system is handling the time-consuming call. Otherwise, concurrent calls will simply time out at the client side.

Returns:: the current setting of this feature.

See also:: SetUseMultiThreadedStockFunctions().

UINT32 GetWorkAreaSize ( void )

Gets the server-side work area size which is coupled to the maximum transport size for supported by a single-threaded server.

Server-side equipment function calls are double buffered, one buffer being a dynamic allocation of the caller's requested data size, the other buffer being in the case of single threaded servers, a temporary use of the server's work area. In order to allow transfer of 'large' data sets, this size needs to be adjusted accordingly prior to server initialization. Note that multi-threaded servers will dynamically allocate both buffers on a call by call basis.

Returns:: The current setting for the server's work area.

References MaxSystemTransportSize.

int IsServerRunning ( void )

Returns TRUE (non zero) if the server kernel is fully initialized and ready.

Returns:: 0 if not running

References SystemRunning.

int LockEquipmentModules ( void )

Locks all equipment modules.

Applying this call seizes a system mutex which will not allow the scheduler to cycle thru the equipment module dispatch routines. Consider setting the IDLE state of the module in lieu of locking and unlocking.

Returns:: 0 if successful, otherwise a TINE completion code

See also:: UnlockEquipmentModules().

double MakeDataTimeStamp ( void )

Returns a data timestamp according to the current system time.

Returns:: A tine data timestamp.

See also:: SetDataTimeStamp, PutDataTimeStamp, GetDataTimeStamp

Referenced by sendNetGlobal().

int microsleep ( int usecs )

sleep for given number of micro-seconds

If the input is less than 4 micro-seconds the delay is a 'hard-spin' where the OS system clock is examined in a loop without yielding the time slice. If the input is greater than 4 but less than 50 micro-seconds the delay is a 'soft-spin' where the OS system clock is examined in a loop but yielding the thread's time slice at each pass through the loop. If the input is greater than 50 micro-seconds the delay invokes a nanosleep or equivalent which yields the thread until the delay time expires. Unless a real-time clock is used (e.g. VxWorks) the granularity of this latter technique is never better than 50 micro-seconds (often more like a clock tick).

Parameters:

usecs the desired number of micro-seconds to sleep

Returns:: the number of micro seconds slept

double PutDataTimeStamp	(	double	toffset,
		time_t	tsec,
		int	tmsec
	)

Returns a data timestamp according to the input parameters given.

This call is has the same purpose as makeDataTimeStamp(), but can assign a TINE data timestamp according to the input seconds, milliseconds and system time offset. This call is used only under special circumstances.

Parameters:

toffset	is the systematic time offset to be applied.
tsec	is the data timestamp in seconds
tmsec	is the millisecond part of the data timestamp

Returns:: A tine data timestamp.

See also:: SetDataTimeStamp, MakeDataTimeStamp, GetDataTimeStamp

Referenced by ExecLinkEx(), GetCurrentDataTimeStamp(), GetCurrentDataTimeStampFromCallbackId(), and GetGroupMemberList().

int ResetMultiChannelProperty	(	char *	eqm,
		char *	prp
	)

sends (schedules) a 'reset_mca_property' signal to any listening client

A server with registered multi-channel array properties can inform any attached clients that the mutli-channel array configuration has changed (e.g. array elements have been added, removed, or otherwise edited) by using this call. Any listening clients with multi-channel array links will then return to the original client startup conditions and 're-learn' the new array indexing now in place.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prp	is (comma separated) list of properties which are to be reset at the client side.

Note:: This routine will call _SystemSchedulePropertyEx() to assure immediate notification at the client side.

Returns:: 0 upon success, otherwise a TINE return code.

See also:: SetEnforceMcaAcquisition

References _SystemSchedulePropertyEx().

int SetBackgroundThreadPriority ( int priority )

Determines the priority of any registered background threads.

The priority passed should be regarded as an offset to the 'normal' thread priorty for the operating system in use. That is, the TINE definition STD_THREAD_PRIORITY will be 'correct' for the target operating system (where a multi-threaded build of the library is in use). It is up to the developer to take the appropriate steps to ensure that this call in fact works as planned. For instance, using real-time priorities on Windows will require a call to the Windows function SetPriorityClass() using REALTIME_PRIORITY_CLASS prior to server initialization (otherwise the resulting thread priorities will not be as desired). Using any non-standard priorities on Unix will likely require running the application as root! VxWorks will take the initial task priority as a reference for the 'standard thread priority'.

Parameters:

priority is the desired thread priority (default STD_THREAD_PRIORITY).

Returns:: the assigned background thread priority.

See also:: GetBackgroundThreadPriority().

int SetBurstLimit ( int npackets )

Sets the burst limit in number of packets which are allowed to be set consecutively.

For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the cycle delay and determines how many UDP packets (datagrams) are allowed to be sent consecutively within the transport loop before a brake is applies (cycle delay). If all clients and servers are on the same speed ethernet, this value can be adjusted to a much larger value. However, a fast server sending to a slow client (a remote client via a DSL link for instance) might send more datagrams in a burst than can be received. The default value should compensate for this effect.

Parameters:

npackets is the number of packet allowed to be set consecutively for a given call (default: 1000).

Returns:: The current setting for the burst limit.

See also:: SetCycleDelay(), GetBurstLimit().

References feclog().

int SetClientThreadPriority ( int priority )

Determines the priority of the client cycle thread as well as other associated client-side threads.

The priority passed should be regarded as an offset to the 'normal' thread priorty for the operating system in use. That is, the TINE definition STD_THREAD_PRIORITY will be 'correct' for the target operating system (where a multi-threaded build of the library is in use). It is up to the developer to take the appropriate steps to ensure that this call in fact works as planned. For instance, using real-time priorities on Windows will require a call to the Windows function SetPriorityClass() using REALTIME_PRIORITY_CLASS prior to server initialization (otherwise the resulting thread priorities will not be as desired). Using any non-standard priorities on Unix will likely require running the application as root! VxWorks will take the initial task priority as a reference for the 'standard thread priority'.

Parameters:

priority is the desired thread priority (default STD_THREAD_PRIORITY).

Returns:: the assigned client thread priority.

See also:: GetClientThreadPriority().

int SetCycleDelay ( int msecs )

Sets the delay time in milliseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().

For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the burst limit and determines how long to delay further datagram transmission when the burst limit has been reached. If all clients and servers are on the same speed ethernet, this value can be adjusted to 0. However, a fast server sending to a slow client (a remote client via a DSL link for instance) might send more datagrams in a burst than can be received. The default value should compensate for this effect.

Parameters:

msec	is the time in milliseconds to delay before sending further ethernet packets. (default: 20 msec).

Returns:: The current setting for the cycle delay.

See also:: SetBurstLimit().

int SetCycleMicroDelay ( int usecs )

Sets the delay time in microseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().

For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the burst limit and determines how long to delay further datagram transmission when the burst limit has been reached. If all clients and servers are on the same speed ethernet, this value can be left at its default value 0. However, when fine adjustments in flow control are necessary, a delay in the micro second region following each 'burst' of packets can be applied, where the delay in microseconds is given by this setting.

Parameters:

usec	is the time in microseconds to delay before sending further ethernet packets. (default: 0 usec => use cycle delay in milliseconds).

Returns:: The current setting for the cycle micro delay.

See also:: SetCycleDelay(), SetBurstLimit().

void SetDataTimeStamp ( double ts )

Sets the intrinsic data timestamp to the value given.

This call is typically used inside an equipment function to set the data timestamp associated with the request being made. For instance, when the data are taken from the hardware IO loop, a call to makeDataTimeStamp() is made to get the current system timestamp. Then when a request for data is made the caller can know the precise time of data acquisition. If this routine is not called, then the current system time will be used to stamp the data.

Parameters:

ts	is the timestamp to be associated with the next data set.

See also:: PutDataTimeStamp, MakeDataTimeStamp

int SetFecHome ( char * fecHomePath )

Sets the current fec home database repository.

Returns:: A string pointing to the current setting for the fec home database repository

Note:: If the server has already been initialized, this function will return an error.

Returns:: 0 upon success or a TINE error code.

References feclog().

void SetFeclogDepth ( int value )

Determines the approximate size of the server's log file in lines.

The server's log file, if located on the local disk, is a file called 'fec.log'. When it's length surpasses the FecLogDepth, this file is rotated to 'fec.bak' and a new 'fec.log' file is started. A call for the server's log file will always be able to scan both the 'fec.bak' file and 'fec.log', and will thus always be able to scan at least FeclogDepth entries. The log file depth is controlled via this API call.

Parameters:

value is the desired log depth in lines of fec.log. Default: 100. Minimum: 100.

References feclog().

int SetKernelPriority ( int priority )

Determines the priority of TINE kernel threads.

Use this routine to set the priority of all TINE kernel threads (server-side, client-side, background tasks) to the desired value. This is primarily a convenience routine and is equivalent to calling SetServerThreadPriority(), SetClientThreadPriority() and SetBackgroundThreadPriority() individually.

Parameters:

priority is the desired thread priority (default STD_THREAD_PRIORITY).

Returns:: the assigned thread priority.

See also:: SetServerThreadPriority(), SetClientThreadPriority(), SetBackgroundThreadPriority()

void SetPostSystemInitFunction ( SYSTSKP fcn )

Sets a user-specific initialization routine to be executed following server initialization.

Parameters:

fcn	is the function to be called following system initialization. (prototype void fcn(void)). Typically one places registration calls such as RegisterEquipmentModule(), etc. in such a routine.

See also:: SetPreSystemInitFunction()

void SetPreSystemInitFunction ( SYSTSKP fcn )

Sets a user-specific initialization routine to be executed prior to server initialization.

Parameters:

fcn is the function to be called prior to system initialization. (prototype void fcn(void)). Typically one places parameter settings which differ from the default values in such a routine, so that they have an effect on the server initialization. Likewise, calls such as RegisterFecInformation() should be made in such a routine.

See also:: SetPostSystemInitFunction()

void SetPutCommandsInFeclog ( int value )

Determines whether all in-coming WRITE access calls are automatically included in the server's log file.

Parameters:

value is the desired setting (default = TRUE).

Note:: This is an exported routine which simply sets the global variable putCommandsInFeclog

See also:: GetPutCommandsInFeclog

void SetServerIdleState	(	char *	eqm,
		int	value
	)

Sets the server's idle state to the value given.

A Server can be set in an idle state where no background activity occurs and the server's equipment function is temporarily disabled. Calls to the equipment function will receive the status code 'server_idle' if this is the case.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
value	is the value of the idle state. Any non-zero sets the idle state to TRUE. A zero value sets the idle state to FALSE.

Note:: This call targets a specific equipment module and hence only applies to the specified server module.

See also:: GetServerIdleState()

int SetServerThreadPriority ( int priority )

Determines the priority of the server cycle thread as well as other associated server-side threads.

The priority passed should be regarded as an offset to the 'normal' thread priorty for the operating system in use. That is, the TINE definition STD_THREAD_PRIORITY will be 'correct' for the target operating system (where a multi-threaded build of the library is in use). It is up to the developer to take the appropriate steps to ensure that this call in fact works as planned. For instance, using real-time priorities on Windows will require a call to the Windows function SetPriorityClass() using REALTIME_PRIORITY_CLASS prior to server initialization (otherwise the resulting thread priorities will not be as desired). Using any non-standard priorities on Unix will likely require running the application as root! VxWorks will take the initial task priority as a reference for the 'standard thread priority'.

Parameters:

priority is the desired thread priority (default STD_THREAD_PRIORITY).

Returns:: the assigned server thread priority.

See also:: GetServerThreadPriority().

void SetServerWaiting ( int value )

Sets the server's waiting state to the value given.

A Server can be set in a wait state prior to initialization by passing a non-zero value as argument. In this state, the server will respond to all contract requests with the status code 'not_initialized'. This is useful, if the server needs to undergo a long initialization precedure before allowing clients access. Setting the wait state to TRUE before stating the server's cycle() and then later to FALSE when all properties and equipment modules are ready is a safe way to prevent premature access. The server's wait state is, of course, FALSE (not waiting) by default.

Parameters:

value is the value of the wait state.

Note:: This call does not target a specific equipment module and hence applies to all registered equipment modules on the FEC.

See also:: GetServerWaiting()

void SetStreamTransportRetryLimit ( int value )

Sets the stream transport retry limit.

When a server attempts to deliver data via a stream (TCP) connection to a client it attempts to find available TCP send buffers to deliver the data. This generally is successful upon the initial attempt but can fail due to network or buffering congestion. In such cases a delay of a clock tick and a retry will then succeed. The number of times these retries are allowed to happen are influenced by this parameter setting. The default value of '2' is generally correct, but under some conditions (one sluggish client) can impede transfer to other clients and in such cases it might be advisible to set this value to a lower value or even to '0' so as not to make all attached clients suffer. This value setting can be established by making use of this call.

See also:: GetStreamTransportRetryLimit().

void SetSystemCleanupFunction ( SYSTSKP fcn )

Sets a user-specific cleanup routine to be executed as a final step during a normal cleanup phase (e.g. typing 'quit' or 'exit' at the command prompt.

Parameters:

fcn	is the cleanup function to be called (prototype void fcn(void)).

void SetSystemDataStamp ( int value )

Sets the global system data stamp with which to tag outbound data sets.

A server can set a global data stamp value (e.g. cycle id or run number, etc.) which will accompany all data transactions.

Parameters:

value is the integer value to use as the system data stamp.

Returns:: void

void SetSystemLogging ( int value )

Sets system logging (output to fec.log) to TRUE or FALSE.

Parameters:

value should be TRUE (non zero) if logging is desired (DEFAULT) or FALSE if not.

void SetSystemRequireAcknowledgments ( int value )

Sets the require acknowledgments flag to the value given.

A server normally requires an acknowledgment from clients being sent changed data if the client link is a data-change style monitor. Under some circumstances this extra acknowledgment network traffic might be unnecessary or undesireable and can be disabled with the function call.

Parameters:

value is the desired setting (default = TRUE).

See also:: GetSystemRequireAcknowledgments()

References RequireAcknowledgments.

void SetSystemSchedulePropertyLazy ( int value )

Sets the 'lazy' flag for scheduling properties.

When a property is scheduled, the delivery can either occur immedidately (default) and thereby invoke the TINE scheduler withing the call to SystemScheduleProperty() or occur withing the next normal delivery cycle (lazy), which could add a latency of up to a clock tick to the delivery. This call sets the 'lazy' flag deteriming this behavior.

Parameters:

value will be interpreted in a boolean manner. If TRUE (non-zero) then calls to SystemScheduleProperty() will mark the associated properties for scheduling, which will duly occur during the next call to the scheduler (usually within a clock tick) by the TINE kernel. If FALSE (default) then scheduled properties will immediately invoke the TINE scheduler.

See also:: _SystemScheduleProperty(), _SystemSchedulePropertyEx(), GetSystemSchedulePropertyLazy()

void SetSystemUseDataProtection ( int value )

Sets the data protection flag to the value given.

Multi-threaded servers using background tasks can ensure the thread safety of any data sets used in both an equipment module's background thread and dispatch function handler by explicit coding. As an alternative, calling this routine at initialization time with a non-zero value will automatically generate a data protection mutex which will prevent concurrent exectution of a module's background task and dispatch handler.

Parameters:

value is the desired setting (default = FALSE).

int SetSystemUserName ( char * usr )

Sets the current value for the application user.

Parameters:

usr	The desired appliation's user name.

Returns:: 0 if successful, otherwise a TINE return code.

void SetUseGlobalSynchronization ( int value )

Determines whether data timestamps are to be externally synchronized.

Parameters:

value If set to TRUE, data timestamps will be synchronized to an externally supplied timestamp. This requires a TINE Time Server to be in operation and sending timestamps at regular intervals either as multicast or as broadcast (default TRUE);

See also:: GetUseGlobalSynchronization()

References feclog().

void SetUseMultiThreadedBackgroundTasks ( int value )

Determines whether equipment module background tasks are to run in separate threads (boolean).

If set to TRUE, the server's background task will run in its own thread, where a multi-threaded build of the library is in use. Note that this could result in data concurrency issues if the background task is acquiring data which is to be used by an equipment module's equipment function.

Parameters:

value should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. TRUE is the default.

See also:: SetAllowBackgroundTaskReentrancy(), GetUseMultiThreadedBackgroundTasks().

void SetUseMultiThreadedEquipmentFunctions ( int value )

Determines whether an equipment module equipment function can run in a separate threads (boolean).

If set to TRUE, the an equipment function will handle designated properties in a separate thread, where a multi-threaded build of the library is in use. Ordinarily an equipment function should be regarded as an interrupt service routine which should return 'promptly' after being called. All properties will be directed to the equipment function using the same thread as the server cycle, unless otherwise specified. On the other hand if a property is specifically registered to run the equipment module in a separate thread (because the action is known to require significant time to complete) then it will run in its own thread if this setting has been enabled. This will result in other calls to the equipment function receiving an 'operation busy' completion while the equipment function is handling the time-consuming call. Otherwise, concurrent calls will simply time out at the client side. To configure a property to be called in a separate thread one can either call SetCallPropertyInSeparateThread() following the property registration of supply an "MT" switch in the properties 'access' string which registering via file (either exports.csv or fec.xml).

Parameters:

value should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. FALSE is the default.

See also:: GetUseMultiThreadedEquipmentFunctions(), SetUseMultiThreadedStockFunctions(), SetCallPropertyInSeparateThread().

void SetUseMultiThreadedStockFunctions ( int value )

Determines whether stock propery calls can run in a separate threads (boolean).

If set to TRUE, certain stock property calls will be handled in a separate thread, where a multi-threaded build of the library is in use. Ordinarily stock property calls return 'promptly' after being called, and make use of the same thread as the server cycle, unless otherwise specified. On the other hand certain stock properties which make heavy use of the local disk might require considerable time to complete, noteably calls to the local history subsystem or file retrieval calls. A calls to such property will run in its own thread if this setting has been enabled. This will result in other calls to the same stock property receiving an 'operation busy' completion while the system is handling the time-consuming call. Otherwise, concurrent calls will simply time out at the client side.

Parameters:

value should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. TRUE is the default.

See also:: GetUseMultiThreadedStockFunctions().

UINT32 SetWorkAreaSize ( UINT32 size )

Sets the server-side work area size which is coupled to the maximum transport size for supported by a single-threaded server.

Server-side equipment function calls are double buffered, one buffer being a dynamic allocation of the caller's requested data size, the other buffer being in the case of single threaded servers, a temporary use of the server's work area. In order to allow transfer of 'large' data sets, this size needs to be adjusted accordingly prior to server initialization. Note that multi-threaded servers will dynamically allocate both buffers on a call by call basis.

Parameters:

size	is the size in bytes to be reserved for the server's work area and hence the maximum allowed transport size for any property supported by the server. (default: 64 KBytes on most operating systems).

Returns:: The current setting for the server's work area.

BYTE* SystemVersion ( void )

Returns the system version as a 4-byte array containg the major and minor version numbers as the first two bytes and the current revision in the next two bytes.

Returns:: The tine version in use.

Example:

BYTE *ver = SystemVersion();

//...

printf("Current version is %d.%02d.%04d\n",ver[0],ver[1],ver[2]*256 + ver[3]);
 
//...

int UnlockEquipmentModules ( void )

Unlocks all equipment modules.

If the equipment modules were locked by applying a call to LockEquipmentModules() then this call frees the lock state, allowing equipment module dispatch routines and background tasks to continue. Consider setting the IDLE state of the module in lieu of locking and unlocking.

Returns:: 0 if successful, otherwise a TINE completion code

See also:: LockEquipmentModules().

Variable Documentation

int FeclogDepth = FECLOG_DEPTH

Determines the approximate size of the server's log file in lines.

The server's log file, if located on the local disk, is a file called 'fec.log'. When it's length surpasses the FecLogDepth, this file is moved to 'fec.bak' and a new 'fec.log' file is started. A call for the server's log file will always be able to scan both the 'fec.bak' file and 'fec.log', and will thus always be able to scan at least FeclogDepth entries.

Default: 100

Referenced by GetFeclogDepth().

int nofeclog = FALSE

Determines whether a server is to keep a log file on the local disk.

The location of the log file is determined by the FECDB environment variable or, if not set, the current working directory is used. If set to TRUE, then no log file will be maintained on the local disk. A log file will nonetheless be maintained in a local ring-buffer, with the caveat that all entries will disappear upon server restart. To eliminate the log file entirely, 'nofeclog' should be set to TRUE and 'FeclogDepth' should be set to 0.

Default: FALSE for most operating systems. Exceptions: VxWorks, NIOS.

int putCommandsInFeclog = TRUE

Determines whether all in-coming WRITE access calls are automatically included in the server's log file.

Default: TRUE

int StartupDebug = 1

Determines whether server initialization messages are displayed or not.

A running server is quiet regarding information displayed on the standard output. An initializing server is however by default not quiet, and will echo various steps of the initialization process on the screen, including whether of not optional configuration files are found or not, etc. This information can be surpressed by setting StartupDebug to FALSE prior to calling SystemInit().

Note:: Critical errors will be displayed on the screen in all circumstances.

Default: TRUE

int useGlobalSynchronization = GLOBAL_SYNCHRONIZATION

Determines whether data timestamps are to be externally synchronized.

If set to TRUE, data timestamps will be synchronized to an externally supplied timestamp. This requires a TINE Time Server to be in operation and sending timestamps at regular intervals either as multicast or as broadcast.

Default: TRUE

Referenced by GetUseGlobalSynchronization().

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation