server.c File Reference

TINE server engine plus API routines. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <math.h>
#include "prolog.h"
#include "srvcore.h"
#include "threader.h"
#include "globals.h"
#include "errors.h"
#include "dbtools.h"
#include "almlib.h"
#include "hstlib.h"
#include "srvip.h"
#include "toolkit.h"
#include "ttycmd.h"

Functions
int	datacmp (BYTE *d1, BYTE *d2, int siz, int fmt, double t)
TINE_EXPORT int	FecIsInitialized (void)
	Determines whether the FEC process has initialized services and all known equipment modules. More...
TINE_EXPORT int	GetNumberDataOutputBuffers (void)
	gets the number of allocated buffers to use in contract access of a a registered property. More...
TINE_EXPORT int	GetServerCycleState (char *cycleStateString)
	Returns the current server cycle state. 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	GetUseCycleTrigger (void)
	Returns whether a server listens for a CycleNumber trigger from a CYCLER. More...
TINE_EXPORT int	ServerIsInitialized (const char *eqm)
	Determines whether the server has initialized;. 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	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	SetUseCycleTrigger (int value)
	Establishes whether a server listens for a CycleNumber trigger from a CYCLER. More...

Variables
int	gRequireAcknowledgments = 1
	Determines whether acknowledgements are expected following data changes where contracts use CM_DATACHANGE mode. More...
TINE_EXPORT UINT32	MaxSystemTransportSize = MAX_TRANSPORTSIZE
	Determines the maximum size in bytes of any call supported by the server. More...
TINE_EXPORT int	SystemPresetMemory = TRUE
	Determines whether data requests preset the calling buffer to zero before issuing the call. More...
int	SystemRunning = FALSE
	Determines whether a server has been successfully initialized or not. More...

Detailed Description

TINE server engine plus API routines.

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

FecIsInitialized()

TINE_EXPORT int FecIsInitialized

(

void

)

Determines whether the FEC process has initialized services and all known equipment modules.

In addition to equipment modules being initialized, any save/restore values must be restored before this routine returns TRUE;

Returns

TRUE if all equipment modules have run through their initialization routines AND all save/restore values have been restored.

See also

_SystemInit(), ServerIsInitialized(),

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.

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

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

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

ServerIsInitialized()

TINE_EXPORT int ServerIsInitialized

(

const char *

eqm

)

Determines whether the server has initialized;.

Parameters

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

Returns

TRUE if the given equipment modules has run through its initialization routine.

See also

_SystemInit(), FecIsInitialized(),

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.

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.

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

Variable Documentation

gRequireAcknowledgments

int gRequireAcknowledgments = 1

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

MaxSystemTransportSize

TINE_EXPORT UINT32 MaxSystemTransportSize = MAX_TRANSPORTSIZE

Determines the maximum size in bytes of any call supported by the server.

Any call which attempts to access more than the MaxSystemTransportSize will fail with 'invalid transport size'. If it is known before hand that the server should support calls for very large amounts of data, and there is available main memory on the server, this value should be set accordingly prior to the call to SystemInit().

Default: 64 Kb for most operating systems. Exceptions: DOS (16 Kbyte), Win16 (32 Kbyte).

Referenced by GetWorkAreaSize(), and SetServerTransportCeiling().

SystemPresetMemory

TINE_EXPORT int SystemPresetMemory = TRUE

Determines whether data requests preset the calling buffer to zero before issuing the call.

If a server always returns the amount of data requested, then presetting the calling buffer contents can be entirely superfluous, and in the case of large data call, can result in a non-negligible increase in the server CPU load. On the other hand, if a server returns less than the amount of data asked for, or the caller asks for an array of fixed string length data, there could be unforseen side-effects if the calling buffer has not been zeroed out.

Default: TRUE

SystemRunning

int SystemRunning = FALSE

Determines whether a server has been successfully initialized or not.

A server can query this flag at any stage to determine if all initialization step have been successfully completed or not. You should never set this flag yourself.

Default: FALSE

Referenced by IsServerRunning().