srvcore.h File Reference

#include "project.def"
#include "prolog.h"
#include "tinetype.h"
#include "errors.h"
#include "almlib.h"
#include "threader.h"

Data Structures
struct	ClnInfoStruct
	Client Information Structure used in GetCallerInformation. More...
struct	DeviceInfoStruct
struct	ExportListTag
	Linked list structure used to hold equipment module information. More...

Typedefs
typedef struct ClnInfoStruct	ClnInfo
	Client Information Structure used in GetCallerInformation. More...
typedef struct DeviceInfoStruct	DeviceInfoStruct
typedef struct ExportListTag	ExportListStruct
	Linked list structure used to hold equipment module information. More...

Functions
int	datacmp (BYTE *d1, BYTE *d2, int siz, int fmt, double t)
TINE_EXPORT int	FindServerOnNetwork (char *context, char *eqmName, char *exportName, FecAddrStruct *fec, ExpDataStruct *srv)
	Issues a multicast (or broadcast) to which configured TINE central servers respond. More...
TINE_EXPORT int	GetAllowBackgroundTaskReentrancy (void)
	Returns whether equipment module background tasks may be re-entered (boolean). More...
TINE_EXPORT int	GetBackgroundThreadPriority (void)
	Returns the priority of the registered background threads. More...
TINE_EXPORT GrpTblEntry *	GetCallbackGroup (size_t id)
	Returns a reference to the callback Group Table Entry associated with the identifier supplied. More...
TINE_EXPORT int	GetCallerInformation (char *eqm, ClnInfo *clnInfoList, int *num)
	Returns the user name, network address and other information of all callers interested in the current contract. More...
TINE_EXPORT int	GetClientThreadPriority (void)
	Returns the priority of the client cycle thread as well as other associated client-side threads. More...
TINE_EXPORT int	GetConnectionList (char *lstbuf, int bufsize)
	Gets the current connection table. More...
TINE_EXPORT int	GetConnectionTable (ConTblInfo *tbl, int *tblSize)
	Gets the current connection table. More...
TINE_EXPORT void **	GetContractDataReference (ExportListStruct *el)
	returns a pointer to a useable reference pointer associated with the contract currently being accessed. More...
TINE_EXPORT void **	GetContractDataReferenceByEqmName (char *eqm)
	returns a pointer to a useable reference pointer associated with the contract currently being accessed. More...
TINE_EXPORT int	GetDefaultTransportMode (void)
	Gets the default TINE transport mode used in client-side links. More...
TINE_EXPORT ExportListStruct *	GetExportListItem (char *eqm)
	Returns a reference to the Export List Structure of the given equipment module. More...
TINE_EXPORT GrpMember *	GetGroupMemberList (GrpTblEntry *grp)
	Returns a linked list of the group members for the callback group supplied. More...
TINE_EXPORT int	GetInterpretConsoleCommands (void)
	Returns the setting for whether console commands will be interpreted or not. More...
TINE_EXPORT int	GetNumberDataOutputBuffers (void)
	gets the number of allocated buffers to use in contract access of a a registered property. More...
ExportPropertyListStruct *	GetPropertyListStruct (char *eqm, char *prpName, char *devName)
TINE_EXPORT int	GetPropertySubscriptionRenewalLength (char *eqm, char *prpName, int *value)
	Gets the current subscription renewal length for the property specified. More...
TINE_EXPORT int	GetRespondToServiceRequests (void)
	Returns whether a server can respond to multicast queries for its address. More...
TINE_EXPORT int	GetRunServerCycleInSeparateThread (void)
	Returns whether the server cycle is run in its own thread (boolean). More...
TINE_EXPORT int	GetRunTransportInSeparateThread (void)
	Returns whether the (tcp) transport is run in its own thread (boolean). More...
TINE_EXPORT int	GetServerCycleState (char *cycleStateString)
	Returns the current server cycle state. More...
TINE_EXPORT int	GetServerThreadPriority (void)
	Returns the priority of the server cycle thread as well as other associated server-side threads. More...
TINE_EXPORT int	GetServerTransportCeiling (void)
	Gets the server-side transport ceiling (in bytes) which gives the maximum transport size for supported by calls to a multi-threaded server. More...
TINE_EXPORT int	GetStreamTransportRetryLimit (void)
	Returns the stream transport retry limit. More...
TINE_EXPORT int	GetSubscriptionRenewalThreshold (int linkId, int *thresholdInPercent)
	Gets the current client-side subscription threshold for the link in question. More...
TINE_EXPORT char *	GetSystemAlias (char *name)
	Gets the alias for either a registered property or registered device. More...
TINE_EXPORT int	GetSystemStampDelay (void)
	Returns the registered system cycle delay. More...
TINE_EXPORT int	GetSystemStampOffset (void)
	Returns the registered system cycle offset. More...
TINE_EXPORT int	GetSystemSubscriptionRenewalLength (void)
	Gets the current contract subscription renewal length. More...
TINE_EXPORT int	GetUseCycleTrigger (void)
	Returns whether a server listens for a CycleNumber trigger from a CYCLER. More...
TINE_EXPORT int	GetUseMultiThreadedBackgroundTasks (void)
	Returns whether equipment module background tasks are to run in separate threads (boolean). More...
TINE_EXPORT int	GetUseMultiThreadedEquipmentFunctions (void)
	Returns whether an equipment module equipment function can run in a separate threads (boolean). More...
TINE_EXPORT int	GetUseMultiThreadedStockFunctions (void)
	Returns whether stock propery calls can run in a separate threads (boolean). More...
TINE_EXPORT int	LockEquipmentModules (void)
	Locks all equipment modules. More...
TINE_EXPORT int	microsleep (int usecs)
	sleep for given number of micro-seconds More...
TINE_EXPORT int	RegisterCycleTriggerFunction (CYCBFCNP fcn, char *eqm, char *prpLst, void *reference)
	Registers a cycle trigger callback dispatch function. More...
TINE_EXPORT int	RegisterStateChangeCallback (SCCBFCNP fcn, const char *eqm, const char *stateKey, void *reference)
	Registers a state change callback dispatch function. More...
TINE_EXPORT char *	ResolveSystemAlias (char *alias)
	Gets the registered property or registered device name for the given alias. More...
TINE_EXPORT void	SetAllowBackgroundTaskReentrancy (int value)
	Determines whether equipment module background tasks may be re-entered (boolean). More...
TINE_EXPORT int	SetBackgroundThreadPriority (int priority)
	Determines the priority of any registered background threads. More...
TINE_EXPORT int	SetClientThreadPriority (int priority)
	Determines the priority of the client cycle thread as well as other associated client-side threads. More...
TINE_EXPORT void	SetDefaultTransportMode (int value)
	Sets the default TINE transport mode used in client-side links. More...
TINE_EXPORT int	SetKernelPriority (int priority)
	Determines the priority of TINE kernel threads. More...
TINE_EXPORT int	SetNumberDataOutputBuffers (int value)
	sets the number of allocated buffers to use in contract access of a a registered property. More...
TINE_EXPORT void	SetPostSystemInitFunction (SYSTSKP fcn)
	Sets a user-specific initialization routine to be executed following server initialization. More...
TINE_EXPORT void	SetPreSystemInitFunction (SYSTSKP fcn)
	Sets a user-specific initialization routine to be executed prior to server initialization. More...
TINE_EXPORT int	SetPropertySubscriptionRenewalLength (char *eqm, char *prpName, int value)
	Sets the current subscription renewal length for the property specified. More...
TINE_EXPORT void	SetRespondToServiceRequests (int value)
	Establishes whether a server can respond to multicast queries for its address. More...
TINE_EXPORT void	SetRunServerCycleInSeparateThread (int value)
	Determines whether the server cycle is run in its own thread (boolean). More...
TINE_EXPORT void	SetRunTransportInSeparateThread (int value)
	Determines whether the (tcp) transport is run in its own thread (boolean). More...
TINE_EXPORT int	SetServerThreadPriority (int priority)
	Determines the priority of the server cycle thread as well as other associated server-side threads. More...
TINE_EXPORT void	SetServerTransportCeiling (int value)
	Sets the server-side transport ceiling (in bytes) which gives the maximum transport size for supported by calls to a multi-threaded server. More...
TINE_EXPORT void	SetStreamTransportRetryLimit (int value)
	Sets the stream transport retry limit. More...
TINE_EXPORT int	SetSubscriptionRenewalThreshold (int linkId, int thresholdInPercent)
	Gets the current client-side subscription threshold for the link in question. More...
TINE_EXPORT int	SetSystemAlias (char *alias, char *name)
	Sets an alias for either a registered property or registered device. More...
TINE_EXPORT int	SetSystemAttribute (char *attribute, void *value, int format)
TINE_EXPORT 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. More...
TINE_EXPORT void	SetSystemStampDelay (int cycleDelay)
	Establishes the system cycle delay. More...
TINE_EXPORT void	SetSystemStampOffset (int cycleOffset)
	Establishes a system cycle offset. More...
TINE_EXPORT void	SetSystemSubscriptionRenewalLength (int value)
	Sets the contract subscription renewal length. More...
TINE_EXPORT void	SetUseCycleTrigger (int value)
	Establishes whether a server listens for a CycleNumber trigger from a CYCLER. More...
TINE_EXPORT void	SetUseMultiThreadedBackgroundTasks (int value)
	Determines whether equipment module background tasks are to run in separate threads (boolean). More...
TINE_EXPORT void	SetUseMultiThreadedEquipmentFunctions (int value)
	Determines whether an equipment module equipment function can run in a separate threads (boolean). More...
TINE_EXPORT void	SetUseMultiThreadedStockFunctions (int value)
	Determines whether stock propery calls can run in a separate threads (boolean). More...
TINE_EXPORT int	UnlockEquipmentModules (void)
	Unlocks all equipment modules. More...
TINE_EXPORT int	UnregisterCycleTriggerFunction (CYCBFCNP fcn, void *reference)
	Unregisters a previously registered cycle trigger callback dispatch function. More...

Variables
SOCKET	dcsEvnSck
SOCKET	glbClnSck
TINE_EXPORT int	gRequireAcknowledgments
	Determines whether acknowledgements are expected following data changes where contracts use CM_DATACHANGE mode. More...
SOCKET	mcastClnSck
SOCKET	netSrvSck
SOCKET	udpClnSck
SOCKET	udpSrvSck
SOCKET	udpSyncSck

Detailed Description

server-side (and client-side) transport definitions and prototypes.

Typedef Documentation

ClnInfo

typedef struct ClnInfoStruct ClnInfo

Client Information Structure used in GetCallerInformation.

DeviceInfoStruct

typedef struct DeviceInfoStruct DeviceInfoStruct

Device info structure used in queries

ExportListStruct

typedef struct ExportListTag ExportListStruct

Linked list structure used to hold equipment module information.

Function Documentation

datacmp()

int datacmp	(	BYTE *	d1,
		BYTE *	d2,
		int	siz,
		int	fmt,
		double	t
	)

\intern compares array d1[siz] against d2[siz] with given format and absolute tolerance

FindServerOnNetwork()

TINE_EXPORT int FindServerOnNetwork	(	char *	context,
		char *	eqmName,
		char *	exportName,
		FecAddrStruct *	fec,
		ExpDataStruct *	srv
	)

Issues a multicast (or broadcast) to which configured TINE central servers respond.

Diskless (or otherwise 'in-a-box') servers which need to find central servers such as the Equipment Name Server, Central Alarm Server, or Post-Mortem Server, etc. can issue this call to ascertain the address.

Parameters

context	(optional) the Context of the desired central server
eqmName	the local equipment module name of the desired central server (e.g. "ENSEQM")
exportName	the exported device server name of the desired central server. Note either exportName or eqmName, but not both are optional input parameters.
fec	(optional) is the returned FEC address structure of the server responding to the call
srv	(optional) is the returned Device Server Data address structure of the server responding to the call.

Returns

0 if successful, otherwise a TINE completion code

Note

A route for the services multicast group from the target server to the host using this call must exist in order for this call to be successful.

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), link_timeout, NAME16::name, NAME32::name, and DUNION::vptr.

GetAllowBackgroundTaskReentrancy()

TINE_EXPORT int GetAllowBackgroundTaskReentrancy

(

void

)

Returns whether equipment module background tasks may be re-entered (boolean).

If set to TRUE, the server's background task will allow re-entrancy which might occur if the task rate instructs the background task to be called even though the previous call has not yet returned. In such cases the programmer must deal with whatever reentrancy issues there might be. This routine returns the current setting.

Returns

the current setting of this feature.

See also

SetAllowBackgroundTaskReentrancy().

GetBackgroundThreadPriority()

TINE_EXPORT int GetBackgroundThreadPriority

(

void

)

Returns the priority of the registered background threads.

Returns

the background thread priority.

See also

SetBackgroundThreadPriority().

GetCallbackGroup()

TINE_EXPORT GrpTblEntry* GetCallbackGroup

(

size_t

id

)

Returns a reference to the callback Group Table Entry associated with the identifier supplied.

Parameters

id	is the group callback id (effectively the reference pointer to the callback function associated with the group.

Returns

a reference to the group table entry (GrpTblEntry *) if the given id corresponds to a registered callback group, or NULL if not found.

See also

GetGroupMemberList(), GrpTblEntry, GrpMember

GetCallerInformation()

TINE_EXPORT int GetCallerInformation	(	char *	eqm,
		ClnInfo *	clnInfoList,
		int *	num
	)

Returns the user name, network address and other information of all callers interested in the current contract.

Parameters

eqm	(in) is the equipment function name (local name) for which the exported name is desired.
clnInfoList	(out) if non-NULL is a reference to an array of ClnInfo objects to be filled with the caller list
num	(in/out) is a reference to an int value which initially contains the size of the ClnInfoList array used in the parameter list. Upon return of the call, it contains the actual number of callers.

Note

The clnInfoList supplied must point to buffer with enough room to hold at least the input 'num' entries, otherwise a system crash is likely.

Returns

0 if successful, or a TINE completion code

See also

GetCaller()

Example:

 
  /* other equipment module code omitted ... */
  char str[256];
  ClnInfo clninf[20];
  int i, ncln;
 
  ncln = 20;
  GetCallerInformation("SINEQM",clninf,&ncln);
  printf("there are %d clients attached to this contract\n",ncln);
  for (i=0; i<ncln; i++)
  {
    GetInetAddress(clninf[i].addr,str); /* get the ip address as a string */
    printf("caller %d: %s %s (access mode %x inet transfer protocol %x)\n",
      i,clninf[i].userName,str,clninf[i].accessMode,clninf[i].inetProtocol);
  }
 

GetClientThreadPriority()

TINE_EXPORT 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().

GetConnectionList()

TINE_EXPORT int GetConnectionList	(	char *	lstbuf,
		int	bufsize
	)

Gets the current connection table.

A client's connections are managed and maintained in a connection table. You can retrieve the current connection table by using this call

Parameters

lstbuf	is a reference to a string buffer which will hold the connection table list
bufsize	gives the size in bytes of the string buffer passed in the first argument.

Returns

0 upon success or a TINE return code.

References argument_list_error, and buffer_too_small.

GetConnectionTable()

TINE_EXPORT int GetConnectionTable	(	ConTblInfo *	tbl,
		int *	tblSize
	)

Gets the current connection table.

A client's connections are managed and maintained in a connection table. You can retrieve the current connection table by using this call

Parameters

tbl	is a reference to block of memory which will hold the ConTblInfo array giving the current client connection table.
tblSize	(input) is a pointer to an integer value containing the maximum size (number of entries) the the tbl reference can hold. (output) will contain the size of the current connection table.

Returns

0 upon success or a TINE return code.

See also

GetConnectionTableCapacity(), SetConnectionTableCapacity()

References argument_list_error.

GetContractDataReference()

TINE_EXPORT void** GetContractDataReference

(

ExportListStruct *

el

)

returns a pointer to a useable reference pointer associated with the contract currently being accessed.

If some persistence is desired over the lifetime of a registered contract, this function may be used to associate a specific reference. A contract will provide a reference pointer initialized to a NULL pointer. By obtaining the pointer to this reference, a specific pointer can then be assigned. This is expected to be entirely managed by the user, who is then responsible for all cleanup activity when the contract goes out of scope.

Parameters

el	is a reference to the targeted Export List Structure (obtained via a call to GetExportListItem()).

Returns

a pointer to the specific reference of the currently executing contract, or NULL if the contract is NOT being currently executed or the given equipment module name does not refer to a registered equipment module.

See also

GetContractDataReferenceByEqmName

Referenced by GetContractDataReferenceByEqmName().

GetContractDataReferenceByEqmName()

TINE_EXPORT void** GetContractDataReferenceByEqmName

(

char *

eqm

)

returns a pointer to a useable reference pointer associated with the contract currently being accessed.

If some persistence is desired over the lifetime of a registered contract, this function may be used to associate a specific reference. A contract will provide a reference pointer initialized to a NULL pointer. By obtaining the pointer to this reference, a specific pointer can then be assigned. This is expected to be entirely managed by the user, who is then responsible for all cleanup activity when the contract goes out of scope.

Parameters

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

Returns

a pointer to the specific reference of the currently executing contract, or NULL if the contract is NOT being currently executed or the given equipment module name does not refer to a registered equipment module.

See also

GetContractDataReference

References GetContractDataReference().

GetDefaultTransportMode()

TINE_EXPORT int GetDefaultTransportMode

(

void

)

Gets the default TINE transport mode used in client-side links.

Returns

the default TINE transport mode (either 'TCP' or 'UDP').

See also

SetDefaultTransportMode()

GetExportListItem()

TINE_EXPORT ExportListStruct* GetExportListItem

(

char *

eqm

)

Returns a reference to the Export List Structure of the given equipment module.

Parameters

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

Returns

a reference to the the Export List Structure of the given equipment module or NULL if the equipment module name is not found in the registry.

See also

ExportListStruct for details

GetGroupMemberList()

TINE_EXPORT GrpMember* GetGroupMemberList

(

GrpTblEntry *

grp

)

Returns a linked list of the group members for the callback group supplied.

Parameters

grp	is a reference to the group table entry (GrpTblEntry *) whose member list is desired.

Returns

a reference to a linked list of the group members for the callback group supplied

See also

GetCallbackGroup(), GrpTblEntry, GrpMember

GetInterpretConsoleCommands()

TINE_EXPORT int GetInterpretConsoleCommands

(

void

)

Returns the setting for whether console commands will be interpreted or not.

Console commands such as setting the debug level or dumping statistics can be given at the application's console if it is running in the foreground if this setting is TRUE. This routine has no effect if the system is not running on a UNIX or UNIX-like OS. WINDOWS console applications are always able to parse and interpret any console input.

Returns

the current setting.

GetNumberDataOutputBuffers()

TINE_EXPORT int GetNumberDataOutputBuffers

(

void

)

gets the number of allocated buffers to use in contract access of a a registered property.

Returns

the number of allocated buffers used.

GetPropertyListStruct()

ExportPropertyListStruct* GetPropertyListStruct	(	char *	eqm,
		char *	prpName,
		char *	devName
	)

\intern Finds the 'first in the list' (i.e. last registered) 'default' property. Overloads are not considered.

Referenced by GetPropertySubscriptionRenewalLength(), GetRegisteredPropertyListStruct(), RegisterPropertyAccessDeadband(), RegisterPropertyAlias(), SetCallPropertyInSeparateThread(), and SetPropertySubscriptionRenewalLength().

GetPropertySubscriptionRenewalLength()

TINE_EXPORT int GetPropertySubscriptionRenewalLength	(	char *	eqm,
		char *	prpName,
		int *	value
	)

Gets the current subscription renewal length for the property specified.

Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The default value for subscription renewals can be retrieved with this call.

Parameters

eqm	(input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prpName	is the registered property for the buffer is to be assigned.
value	is a reference to the integer variable to hold the returned setting.

Returns

0 upon success of a TINE error code

See also

GetSystemSubscriptionRenewalLength()

References argument_list_error, GetPropertyListStruct(), and invalid_property.

GetRespondToServiceRequests()

TINE_EXPORT int GetRespondToServiceRequests

(

void

)

Returns whether a server can respond to multicast queries for its address.

Normally a client acquires the address of a targeted server via consulting the ENS (or its local address cache). In some cases it may not be possible to guarantee the availability of a running ENS. A server capable of responding to a 'where-are-you' multicast from a client application will have enabled this feature.

Returns

the current setting (default = FALSE)

See also

SetRespondToServiceRequests()

GetRunServerCycleInSeparateThread()

TINE_EXPORT int GetRunServerCycleInSeparateThread

(

void

)

Returns whether the server cycle is run in its own thread (boolean).

If set to TRUE (default for multi-threaded builds), the server cycle will run in its own thread, separate from the client cycle. If set to FALSE, both cycles will run in a round-robin fashion, where all socket descriptor sets are 'select()ed' on to assure a prompt response. This is usually fine. However under extreme scenarios where performance is of primary concern, then leaving this setting in its default TRUE state is the best policy. This of course only applies to multi-threaded builds of the TINE library.

Returns

the current setting of this feature.

See also

SetRunServerCycleInSeparateThread().

GetRunTransportInSeparateThread()

TINE_EXPORT int GetRunTransportInSeparateThread

(

void

)

Returns whether the (tcp) transport is run in its own thread (boolean).

If set to TRUE (default for most multi-threaded builds), connected sockets will each have their own thread where prompt data transport is assured. If set to FALSE, all transport delivery will follow the server contract access. This (setting to FALSE) is generally an okay solution and is not very resource intensive. Setting this to TRUE will cause multiple buffering of data payloads for each connected peer, which could cause memory problems on some OSes such as VxWorks or other systems whether there is more concern about memory than speed. The default setting is TRUE for windows, unix, and macos builds, and FALSE for VxWorks.

Returns

the current setting of this feature.

See also

SetRunTransportInSeparateThread().

GetServerCycleState()

TINE_EXPORT int GetServerCycleState

(

char *

cycleStateString

)

Returns the current server cycle state.

This routine can be polled or otherwise called at any time to determine what state the server cycle is in.

Parameters

cycleStateString

is an optional string buffer which if present will be filled with the current cycle state as a representative sting. The parameter passed must reference a character buffer of at least 64 characters.

Returns

a reference to the the Export List Structure of the given equipment module or NULL if the equipment module name is not found in the registry.

See also

ExportListStruct for details

GetServerThreadPriority()

TINE_EXPORT 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().

GetServerTransportCeiling()

TINE_EXPORT int GetServerTransportCeiling

(

void

)

Gets the server-side transport ceiling (in bytes) which gives the maximum transport size for supported by calls to a multi-threaded server.

Server-side equipment function calls are double buffered, one buffer being a dynamic allocation of the caller's requested data size to be used in data comparisons, the other buffer being in the case of multi-threaded servers, another dynamic allocation of the data size to be used in dispatch calls. In order to allow transfer of 'large' data sets, this size size needs to be adjusted accordingly. If not set, the setting given by the server work area size will be used. This call returns the current setting of this value. If the call returns '-1' this indicates that there is no setting and in such cases the server work area size is used as the allowed output data size in bytes.

Note

This setting essentially establishes a limit on the allowed output data size of client requests to multi-threaded servers, and prevents errant client calls from monopolizing server memory.

Returns

The size in bytes to be used as the transport ceiling for any property supported by the server. If the call returns '-1' this indicates that there is no setting and in such cases the server work area size is used as the allowed output data size in bytes.

See also

SetServerTransportCeiling(), GetWorkAreaSize()

GetStreamTransportRetryLimit()

TINE_EXPORT 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().

GetSubscriptionRenewalThreshold()

TINE_EXPORT int GetSubscriptionRenewalThreshold	(	int	linkId,
		int *	thresholdInPercent
	)

Gets the current client-side subscription threshold for the link in question.

Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant.

Parameters

linkId	is the link id for the link in question (returned from the original call to AttachLink().
thesholdInPercent	is a reference to hold the current setting.

Returns

0 upon success of a TINE error code

See also

SetSubscriptionRenewalThreshold()

GetSystemAlias()

TINE_EXPORT char* GetSystemAlias

(

char *

name

)

Gets the alias for either a registered property or registered device.

A client can make use of an alias in place of either a registered device name or a registered property name in any call. The alias name will be replaced by its target within the contract tables. Property aliases are also returned in queries to obtain the registered property list.

Parameters

name	is the name of the alias target (either a registered device or a registered property).

Returns

the registered alias for the given input or NULL if there is no registered alias.

GetSystemStampDelay()

TINE_EXPORT int GetSystemStampDelay

(

void

)

Returns the registered system cycle delay.

If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the application of the cycle tag needs to be delayed by some value, then this routine may be used to obtain the currently registered cycle delay value (in milliseconds).

Returns

The currently registered system cycle delay (default = 0 msec).

See also

SetSystemStampDelay

GetSystemStampOffset()

TINE_EXPORT int GetSystemStampOffset

(

void

)

Returns the registered system cycle offset.

If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the cycle tag needs to be offset by some value, then this routine may be used to obtain the currently registered cycle offset.

Returns

The currently registered system cycle offset (default = 0).

See also

SetSystemStampOffset

GetSystemSubscriptionRenewalLength()

TINE_EXPORT int GetSystemSubscriptionRenewalLength

(

void

)

Gets the current contract subscription renewal length.

Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The default value for subscription renewals can be retrieved with this call.

Returns

the current setting of the contract renewal length

See also

SetSystemSubscriptionRenewalLength()

GetUseCycleTrigger()

TINE_EXPORT int GetUseCycleTrigger

(

void

)

Returns whether a server listens for a CycleNumber trigger from a CYCLER.

If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number.

Returns

whether the server will listen for CycleNumber multicasts from a CYCLER (default: TRUE).

See also

SetUseCycleTrigger

GetUseMultiThreadedBackgroundTasks()

TINE_EXPORT 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().

GetUseMultiThreadedEquipmentFunctions()

TINE_EXPORT 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().

GetUseMultiThreadedStockFunctions()

TINE_EXPORT 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().

LockEquipmentModules()

TINE_EXPORT 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().

microsleep()

TINE_EXPORT 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

RegisterCycleTriggerFunction()

TINE_EXPORT int RegisterCycleTriggerFunction	(	CYCBFCNP	fcn,
		char *	eqm,
		char *	prpLst,
		void *	reference
	)

Registers a cycle trigger callback dispatch function.

If a CYCLER is running in a server's context, then the server will receive 'Cycle Number' events scheduled by the designated CYCLER server. The cycle number will make use of the 'System Data Stamp' to tag all data sets obtained from the server. A server can also register a trigger function dispatch routine (or routines) to be called when a 'Cycle Number' event occurs. The dispatch routines will be called prior to setting the 'System Stamp' to the new Cycle Number, which will be set following the execution of all dispatch routines. Optionally, the server can provide a property (or list of properties) to be scheduled following the dispatch execution. This will ensure that such properties will be called immediately following dispatch execution AND contain the most recent Cycle Number as the 'System Data Stamp'.

Parameters

fcn	is a reference to the cycle trigger dispatch routine to be called following the reception of a new Cycle Number. This must have the prototype: void (*fcn)(int cycleNumber,int cycleStatus,void *reference). Thus, the dispatch routine will be called with the current cycle number, the cycle status (possibly 'link_timeout' if no cycle is received within the assigned globals heartbeat (see SetGlobalsHeartbeat)), and an optional 'reference', which is a void pointer of the caller's choosing (and will be returned to the caller in the dispatch routine).
eqm	the local equipment module name of the desired central server (e.g. "BPMEQM")
prpLst	is the property or properties which are to be 'scheduled' following the execution of the dispatch routine. If more than a single property is to be scheduled, this should be a string containing a comma separated list.
reference	is a caller supplied void pointer which will be returned to the called in the dispatch routine.

Returns

0 if successful, otherwise a TINE completion code

Example:

#define EQMTAG "TSTEQM"
#define PRP_CYCLE      1
int cycleNumber = 0;
int tsteqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access);
void tstinit(void);
void tstbkg(void);
 
typedef void (*HDWIOFCNP)(int);
void hdwIoCycle(int cycle)
{
  /* read relevant hardware (here we just print something out) */
  printf("read hardware for cycle %d\n",cycle);
}
void onCycleTrigger1(int cycle,int cc,void *ref)
{
  printf("received cycle %d <%d>\n",cycle,cc);
  cycleNumber = cycle;
}
void onCycleTrigger2(int cycle,int cc,void *ref)
{ /* call the referenced function */
  if (cc == 0) ((HDWIOFCNP)ref)(cycle);
}
void PreSystemInit(void)
{
  SetSystemUseDataProtection(TRUE);
  SetPacketMTU(64000);
  RegisterFecInformation("CYCCATCH.8","TST","TEST","Cycle catcher tester","My Office","none","me",8);
}
void PostSystemInit(void)
{
  /* register the equipment module: */
  RegisterEquipmentModule("CycleCatcher",EQMTAG,1,tsteqm,tstinit,tstbkg,100,NULL);
  /* register a cycle trigger function with no scheduling and no reference */
  RegisterCycleTriggerFunction(onCycleTrigger1,EQMTAG,NULL,NULL);
  /* register another cycle trigger function with a scheduled property and a reference to another function */
  RegisterCycleTriggerFunction(onCycleTrigger2,EQMTAG,"CycleNumber",(void *)hdwIoCycle);
}
void tstbkg(void)
{
}
void tstinit(void)
{
  int cc = 0;
  DTYPE dout;
 
  memset(&dout,0,sizeof(DTYPE));
  dout.dFormat = CF_INT32;
  dout.dArrayLength = 1;
  RegisterPropertyInformation(EQMTAG,"CycleNumber",&dout,NULL,CA_READ,AT_SCALAR,0,"current system cycle number",PRP_CYCLE,NULL);
  RegisterDeviceName(EQMTAG,"keyword",0);
}
int tsteqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  int devnr,prpid,cc;
 
  devnr = GetDeviceNumber(EQMTAG,devName);
  prpid = GetPropertyId(EQMTAG,devProperty);
 
  switch (prpid)
  {
    case PRP_CYCLE:
      if (access&CA_WRITE) return illegal_read_write;
      if ((cc=putValuesFromLong(dout,&cycleNumber,1)) != 0) return cc;
      return 0;
    default:
      break;
  }
  return illegal_property;
}

See also

UnregisterCycleTriggerFunction

RegisterStateChangeCallback()

TINE_EXPORT int RegisterStateChangeCallback	(	SCCBFCNP	fcn,
		const char *	eqm,
		const char *	stateKey,
		void *	reference
	)

Registers a state change callback dispatch function.

If STATE and GLOBALS servers are running, a server can receive state change notifications and react accordingly by calling this routine and passing a callback dispatch routine. The callback routine will be called only upon change of state. In the event of any i/o errors which prevent the server from receiving the state information, the state will be changed automatically to 'unavailable' following 5 consecutive readback errors.

Parameters

fcn	is a reference to the state change dispatch routine to be called following a change of state This must have the prototype: void (*fcn)(const char *previousState,const char *currentState,void *reference). If a NULL is passed for this parameter then any callback routine will be de-registered.
eqm	the local equipment module name of the desired central server (e.g. "BPMEQM")
stateKey	is an optional specification of the desired state keyword from the GLOBALS server. If a NULL is passed, then the default of /<context>/GLOBALS/DeclaredState will be used.
reference	is a caller supplied void pointer which will be returned to the called in the dispatch routine. A NULL can be passed if no reference is required.

Returns

0 if successful, otherwise a TINE completion code

Example:

#define EQMTAG "SINEQM"
void tstinit(void);
void tstbkg(void);
 
enum operationModes
{
  mode_not_running,
  mode_electrons,
  mode_positrons
}; 
 
void myStaChg(const char *prv,const char *nxt,void *ref)
{
  printf("changed from %s to %s\n",prv,nxt);
  if (!strncmp(nxt,"running_e-"))
  {
    opMode = mode_electrons;
  }
  else if (!strncmp(nxt,"running_e+"))
  {
    opMode = mode_positrons;
  }
  else
  {
    opMode = mode_not_running;
  }
}
 
void PostSystemInit(void)
{
  // register equipment module(s) ...
  RegisterEquipmentModule("WinSineServer","SINEQM",NUM_DEVICES,sineqm,sininit,sinbkg,100,NULL);
  // other code omitted ...
 
}
 
void sininit(void)
{
  int cc = 0;
  // call restration routines ...
  registerSineProperties();
  registerSineDevices();
 
  // add a state change callback to the equipment module
  // use the default State Variable ...
 
  if ((cc=RegisterStateChangeCallback(myStaChg,"SINEQM",NULL,NULL)) != 0)
  {
    printf("could not register state change callback : error %d\n",cc);
  }
 
}

ResolveSystemAlias()

TINE_EXPORT char* ResolveSystemAlias

(

char *

alias

)

Gets the registered property or registered device name for the given alias.

A client can make use of an alias in place of either a registered device name or a registered property name in any call. The alias name will be replaced by its target within the contract tables. Property aliases are also returned in queries to obtain the registered property list.

Parameters

alias

is the alias target for which the real registered name is desired (either a registered device or a registered property).

Returns

the registered name for the given input or NULL if the input is not a registered alias.

SetAllowBackgroundTaskReentrancy()

TINE_EXPORT void SetAllowBackgroundTaskReentrancy

(

int

value

)

Determines whether equipment module background tasks may be re-entered (boolean).

If set to TRUE, the server's background task will allow re-entrancy which might occur if the task rate instructs the background task to be called even though the previous call has not yet returned. In such cases the programmer must deal with whatever reentrancy issues there might be. The default is value is FALSE. (not reentrant).

Parameters

value

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

See also

GetAllowBackgroundTaskReentrancy().

SetBackgroundThreadPriority()

TINE_EXPORT 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().

SetClientThreadPriority()

TINE_EXPORT 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().

SetDefaultTransportMode()

TINE_EXPORT void SetDefaultTransportMode

(

int

value

)

Sets the default TINE transport mode used in client-side links.

Parameters

value

is the desired default transport mode. This can be either 'TCP' or 'UDP' (the default). Indeed, if value does not equal 'TCP' then the default transport mode will be taken as UDP.

See also

GetDefaultTransportMode()

SetKernelPriority()

TINE_EXPORT 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()

References not_accepted.

SetNumberDataOutputBuffers()

TINE_EXPORT int SetNumberDataOutputBuffers

(

int

value

)

sets the number of allocated buffers to use in contract access of a a registered property.

Parameters

value

is the number of buffers to use. This may only be set to 1 or 2. '1' is the default for single-threaded builds. For multi-threaded builds this value is fixed to 2.

Returns

the number of allocated buffers used.

SetPostSystemInitFunction()

TINE_EXPORT 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()

SetPreSystemInitFunction()

TINE_EXPORT 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()

SetPropertySubscriptionRenewalLength()

TINE_EXPORT int SetPropertySubscriptionRenewalLength	(	char *	eqm,
		char *	prpName,
		int	value
	)

Sets the current subscription renewal length for the property specified.

Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant.

Parameters

eqm	(input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prpName	is the registered property for the buffer is to be assigned.
value	is the desired setting

Returns

0 upon success of a TINE error code

See also

SetSystemSubscriptionRenewalLength()

References argument_list_error, feclog(), GetPropertyListStruct(), invalid_property, and out_of_range.

SetRespondToServiceRequests()

TINE_EXPORT void SetRespondToServiceRequests

(

int

value

)

Establishes whether a server can respond to multicast queries for its address.

Normally a client acquires the address of a targeted server via consulting the ENS (or its local address cache). In some cases it may not be possible to guarantee the availability of a running ENS. If a server declares itself ready and capable of responding to a 'where-are-you' multicast from a client application, it should call this API routine and pass the value of 'TRUE'. In this fashion it is possible to have a client-server pair communicate with each other in an 'ENS-less' scenario (provided the client and server exist on a network which can forward the multicast probes issued by the client (the multicast group 238.1.1.2).

Parameters

value

is the desired setting (default = FALSE)

See also

GetRespondToServiceRequests()

SetRunServerCycleInSeparateThread()

TINE_EXPORT void SetRunServerCycleInSeparateThread

(

int

value

)

Determines whether the server cycle is run in its own thread (boolean).

If set to TRUE (default for multi-threaded builds), the server cycle will run in its own thread, separate from the client cycle. If set to FALSE, both cycles will run in a round-robin fashion, where all socket descriptor sets are 'select()ed' on to assure a prompt response. This is usually fine. However under extreme scenarios where performance is of primary concern, then leaving this setting in its default TRUE state is the best policy. This of course only applies to multi-threaded builds of the TINE library.

Parameters

value

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

See also

GetRunServerCycleInSeparateThread().

SetRunTransportInSeparateThread()

TINE_EXPORT void SetRunTransportInSeparateThread

(

int

value

)

Determines whether the (tcp) transport is run in its own thread (boolean).

If set to TRUE (default for most multi-threaded builds), connected sockets will each have their own thread where prompt data transport is assured. If set to FALSE, all transport delivery will follow the server contract access. This (setting to FALSE) is generally an okay solution and is not very resource intensive. Setting this to TRUE will cause multiple buffering of data payloads for each connected peer, which could cause memory problems on some OSes such as VxWorks or other systems whether there is more concern about memory than speed. The default setting is TRUE for windows, unix, and macos builds, and FALSE for VxWorks.

Parameters

value

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

See also

GetRunServerCycleInSeparateThread().

SetServerThreadPriority()

TINE_EXPORT 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().

SetServerTransportCeiling()

TINE_EXPORT void SetServerTransportCeiling

(

int

value

)

Sets the server-side transport ceiling (in bytes) which gives the maximum transport size for supported by calls to a multi-threaded server.

Server-side equipment function calls are double buffered, one buffer being a dynamic allocation of the caller's requested data size to be used in data comparisons, the other buffer being in the case of multi-threaded servers, another dynamic allocation of the data size to be used in dispatch calls. In order to allow transfer of 'large' data sets, this size size needs to be adjusted accordingly. If not set, the setting given by the server work area size will be used.

Note

This setting essentially establishes a limit on the allowed output data size of client requests to multi-threaded servers, and prevents errant client calls from monopolizing server memory.

Stock properties will continue to make use of the server work area size as the allowed data size.

Parameters

value

is the size in bytes to be used as the transport ceiling for any property supported by the server. (default: the same value as the server work area size, i.e. 64 KBytes on most operating systems).

See also

GetServerTransportCeiling(), SetWorkAreaSize()

References MaxSystemTransportSize.

SetStreamTransportRetryLimit()

TINE_EXPORT 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().

SetSubscriptionRenewalThreshold()

TINE_EXPORT int SetSubscriptionRenewalThreshold	(	int	linkId,
		int	thresholdInPercent
	)

Gets the current client-side subscription threshold for the link in question.

Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The client side link can establish a higher renewal threshold value by making use of this call.

Parameters

linkId	is the link id for the link in question (returned from the original call to AttachLink().
thresholdInPercent	is the desired threshold given as a percent of the total number of subscription transfers. This should be positive integer. Accepted values range between 10 and 90 (percent).

Returns

0 upon success of a TINE error code

See also

GetSubscriptionRenewalThreshold()

SetSystemAlias()

TINE_EXPORT int SetSystemAlias	(	char *	alias,
		char *	name
	)

Sets an alias for either a registered property or registered device.

A client can make use of an alias in place of either a registered device name or a registered property name in any call. The alias name will be replaced by its target within the contract tables. Property aliases are also returned in queries to obtain the registered property list.

Parameters

alias	is the desired alias for the designated property or device
name	is the name of the alias target (either a registered device or a registered property).

Returns

0 upon success or a TINE error code.

SetSystemAttribute()

TINE_EXPORT int SetSystemAttribute	(	char *	attribute,
		void *	value,
		int	format
	)

Note

by definition the Attribute setting function takes a signed integer

References invalid_name, and invalid_parameter.

SetSystemCleanupFunction()

TINE_EXPORT 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)).

SetSystemStampDelay()

TINE_EXPORT void SetSystemStampDelay

(

int

cycleDelay

)

Establishes the system cycle delay.

If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the application of the cycle tag needs to be delayed by some value, then this routine may be used to establish such a cycle delay value (in milliseconds).

Parameters

cycleDelay

is the desired cycle delay (milliseconds), which will must elapse before the incoming cycle number from the registered CYCLER is to be applied to all readback data. (default = 0).

See also

GetSystemStampDelay

SetSystemStampOffset()

TINE_EXPORT void SetSystemStampOffset

(

int

cycleOffset

)

Establishes a system cycle offset.

If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the cycle tag needs to be offset by some value, then this routine may be used to establish such an offset.

Parameters

cycleOffset

is the desired cycle offset (counts) to be applied to the incoming cycle number from the registered CYCLER. (Default = 0).

See also

GetSystemStampOffset

SetSystemSubscriptionRenewalLength()

TINE_EXPORT void SetSystemSubscriptionRenewalLength

(

int

value

)

Sets the contract subscription renewal length.

Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The default value for subscription renewals can be adjusted with this call.

Parameters

value

is the desired contract renewal length. (mininum = default = 60; maximum = 32767)

See also

GetSystemSubscriptionRenewalLength()

SetUseCycleTrigger()

TINE_EXPORT void SetUseCycleTrigger

(

int

value

)

Establishes whether a server listens for a CycleNumber trigger from a CYCLER.

If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If for some reason this is not desired, this behavior can be determined via this call.

Parameters

value

(boolean) determines whether the server will listen for CycleNumber multicasts from a CYCLER (default: TRUE).

See also

GetUseCycleTrigger

SetUseMultiThreadedBackgroundTasks()

TINE_EXPORT 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().

SetUseMultiThreadedEquipmentFunctions()

TINE_EXPORT 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().

SetUseMultiThreadedStockFunctions()

TINE_EXPORT 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().

UnlockEquipmentModules()

TINE_EXPORT 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().

UnregisterCycleTriggerFunction()

TINE_EXPORT int UnregisterCycleTriggerFunction	(	CYCBFCNP	fcn,
		void *	reference
	)

Unregisters a previously registered cycle trigger callback dispatch function.

If a cycle trigger event dispatch routine is no longer required, it can be unregistered using this routine.

Parameters

fcn	is a reference to the previously registered cycle trigger dispatch routine which is to be removed.
reference	is a caller supplied void pointer which will be returned to the called in the dispatch routine.

Returns

0 if successful, otherwise a TINE completion code

See also

RegisterCycleTriggerFunction

Variable Documentation

dcsEvnSck

SOCKET dcsEvnSck

UDP doocs event listening Socket

glbClnSck

SOCKET glbClnSck

UDP Global listening Socket

gRequireAcknowledgments

TINE_EXPORT int gRequireAcknowledgments

Determines whether acknowledgements are expected following data changes where contracts use CM_DATACHANGE mode.

Under CM_TIMER link conditions the server is not directly interested as to whether the client received its data packet or not, since the client is expecting data to arrive at the polling interval and will complain if it is missing. However,when a client establishes a data link and requests CM_DATACHANGE mode, data are are only returned to the client when they have changed, or when the link heartbeat (1 minute) has expired. A server will under these conditions require an acknowledgement from the client if data do in fact change. A missing acknowledgement will cause the server to re-issue the data transfer. This default behavior will of course increase the network traffic when data are frequently changing. Under some circumstance it is undesireable to require acknowledgments and this feature can be turned off by setting this value to FALSE.

Note

Macro definition RequireAcknowledgments to provide compatibility with pre - refactoring usage

Default: TRUE

Referenced by GetSystemRequireAcknowledgments(), and SetSystemRequireAcknowledgments().

mcastClnSck

SOCKET mcastClnSck

UDP MCast/BCast Consumer Socket

netSrvSck

SOCKET netSrvSck

UDP MCast Net Services Socket

udpClnSck

SOCKET udpClnSck

UDP Consumer Socket

udpSrvSck

SOCKET udpSrvSck

UDP Producer Socket

udpSyncSck

SOCKET udpSyncSck

UDP trivial link Socket