TINE server engine and registration API routines. More...

Functions
int	AddFieldToBitField (char srv, char tag, UINT32 mask, char *field)
	Adds a field definition to a registered bitfield.
int	AddFieldToStruct (char tag, int addr, int size, int fmt, char field)
	Adds a field description to a tagged structure.
int	AppendRegisteredBCastNetsList (NAME32 *ipaddr, int addsiz)
	appends the current network broadcast list with the name list given
int	AppendRegisteredNetsList (const char eqm, NAME32 ipaddr, int addsiz)
	appends the current network access list with the name list given
int	AppendRegisteredUsers (const char eqm, NAME16 userlist, int listsize)
	appends the current users access list with the name list given
int	AssignDataStampsToGlobal (char *keyword, int dataStamp, int sysStamp)
	Assigns additional data stamps to the registered global keyword.
int	AssignDeviceAccessList (const char eqm, const char dev, NAME16 *users, int nusers)
	Assigns an access list for the device given.
int	AssignDeviceListToProperty (char eqm, char prp, NAME64 *devlst, int lstlen)
	Assigns the given device list to the given registered property.
int	AssignDeviceNetsList (const char eqm, const char dev, NAME16 *ipnets, int nipnets)
	Assigns an ip nets access list for the device given.
int	AssignNumDevices (char *eqm, int num)
	Fixes the number of modules (devices) attached to the specified equipment module.
int	AssignPropertyAccessList (const char eqm, const char prp, NAME16 *users, int nusers)
	Assigns an access list for the property given.
int	AssignPropertyList (char eqm, char devname, char listname, int listsize, NAME64 list)
	Assigns the given property list to the given device to be used in device-oriented queries.
int	AssignPropertyNetsList (const char eqm, const char prp, NAME16 *ipnets, int nipnets)
	Assigns an ip nets access list for the property given.
int	ExecLocalLink (const char devName, const char devProperty, DTYPE dout, DTYPE din, short access)
	Executes a synchronous link within the local process.
int	FindNameServerOnNetwork ()
	Issues a multicast (or broadcast) to which the TINE equipment name server repsonds.
int	FindServerOnNetwork (char context, char eqmName, char exportName, FecDataStruct fec, ExpDataStruct *srv)
	Issues a multicast (or broadcast) to which configured TINE central servers respond.
void	FlushContractTable (void)
	Flushes the current contract and client entry tables.
int	GetAllowBackgroundTaskReentrancy (void)
	Returns whether equipment module background tasks may be re-entered (boolean).
int	GetAllowedRemoteManagement (void)
	Returns whether remote management via stock properties is possible.
int	GetAllowNetworkAddressResolution (void)
	returns whether NETWORK address resolution is allowed
int	GetBitfieldAsString (char srv, char tag, UINT32 value, char *strbuf, int buflen)
	Retrieves the requested field value from a bit field as a string value.
char *	GetCaller (char *eqm)
	Gives the user name of the current caller.
int	GetCallerInfo (char eqm, NAME16 un, BYTE ipx, UINT32 ip, short prot, int num)
	Returns the user name(s) and network address(es) of all callers interested in the current contract.
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.
int	GetClientListCapacity (void)
	Gets the maximum number of clients a server will service.
int	GetConfigurationCoded (void)
	Returns whether TINE configuration files will be scanned.
int	GetContractListCapacity (void)
	Gets the maximum number of contracts a server will service.
char *	GetDeviceDescription (char *eqm, int devnr)
	Gives the registered device description (if known) for the device number.
char *	GetDeviceName (char *eqm, int devnr)
	Gives the registered device name for the specified equipment module and device number.
int	GetDeviceNumber (char eqm, char devname)
	Gives the registered device number for the specified device name.
int	GetDeviceNumberEx (char eqm, char devname, char *prpname)
	Gives the registered device number for the specified device name and property name.
int	GetEnforceMcaAcquisition (void)
	returns the setting for multi-channel array handshaking enforcement.
char *	GetExportedContext (char *eqmName)
	Returns the exported context associated with the equipment function name given.
NAME64 *	GetExportedDeviceList (char *eqm)
	Returns the list of exported device names explicitly associated with the equipment module passed as the input parameter.
char *	GetExportedFecName (void)
	Returns the FEC name exported at the time of server initialization.
char *	GetExportedName (char *eqm)
	Returns the exported name associated with the equipment function name given.
char *	GetExportedSubSystem (char *eqmName)
	Returns the exported subsystem associated with the equipment function name given.
int	GetFieldFromBitfield (char srv, char tag, char *field, UINT32 value)
	Retrieves the requested field value from a bit field.
int	GetGCastTableCapacity (void)
	gets the globals multicast table capacity (server-side)
int	GetIgnoreCommonFiles (void)
	returns the current setting (default = FALSE)
char *	GetLocalName (char *exportName)
	Returns the local equipment module name associated with the export name given.
int	GetMinimumAllowedPollingInterval (void)
	returns the minimum polling rate in milliseconds a server will allow.
int	GetNumberRegisteredDevices (char *eqm)
	Gives the number of registered devices explicitly associated with the equiment module name given.
int	GetNumCallers (char *eqm)
	Returns the current number of callers associated with the equipment module given.
int	GetNumConsumers (char *eqm)
	Returns the current number of consumers associated with the equipment module given.
int	GetNumContracts (char *eqm)
	Returns the current number of contracts associated with the equipment module given.
BYTE *	GetPropertyBuffer (char eqmName, char prpName)
	Returns the address of the buffer previously assigned to the property given.
int	GetPropertyId (char eqm, char prpName)
	Gives the associated property identifier for the given property name.
int	GetRegisteredPropertyList (char eqm, NAME64 prpNames, int *nprps)
	Returns the list of registered properties explicitly associated with the equipment module passed as the first argument input parameter.
int	GetRegisteredPropertyListStruct (char eqm, char prpName, ExportPropertyListStruct *prpLstStruct)
	Returns the ExportPropertyListStruct structure for the registered property specified by the first two arguments.
int	GetRejectOverloadedMetaProperties (void)
	returns the current setting
int	GetRetardSingleContractRemoval (void)
	returns the current setting of this feature.
int	GetSchedulerInterval (void)
	Gets the system scheduler interval.
int	GetSizeDeviceCapacity (char *eqm)
	Gives the maximum size of the device table associated with the equiment module name given.
int	GetSystemCycleDeadband (void)
	Gets the system cycle deadband.
int	GetSystemSubscriptionRenewalLength (void)
	Gets the current contract subscription renewal length.
int	GetSystemSynchronizeContracts (void)
	Returns the setting for general contract synchronization at the server.
int	IsStandAlone (void)
	Determines whether a client or server process is running in stand-alone mode.
int	JoinEquipmentGroup (char eqmName, char groupname, int groupindex)
	Instructs the equipment module to join the specified equipment group.
int	JoinEquipmentGroupEx (char eqmName, char groupname, int groupindex, char devPrefix, char devPostfix)
	Instructs the equipment module to join the specified equipment group.
int	OpenBitField (char srv, char tag, int fmt)
	Declares a bit field type and registers with the bitfield registry.
int	RedirectDeviceName (char eqm, char devname, char *rdr)
	Applies the redirection string to the given device for all properties.
int	RedirectProperty (char eqm, char property, char *rdr)
	Applies the redirection string to the given property.
int	RegisterDeviceDescription (char eqm, char devname, char *description)
	Assigns a device description to the specified device.
int	RegisterDeviceName (char eqm, char devname, int devnr)
	Assigns a device name to the specified device number.
int	RegisterEquipmentModule (char expName, char eqmName, int numdevices, int(fcn)(char , char , DTYPE , DTYPE , short), void(ini)(void), void(tsk)(void), int rate, void(exi)(void))
	Registers an equipment module with the TINE server engine.
int	RegisterEquipmentModuleEx (char expName, char eqmName, int numdevices, int(fcn)(char , char , DTYPE , DTYPE , short, void ), void(ini)(void ), void(tsk)(void ), int rate, void(exi)(void ), void *reference)
	Registers an equipment module with the TINE server engine (extended call)
int	RegisterFecInformation (char name, char sub, char cntxt, char dsc, char loc, char hdw, char *resp, UINT16 poff)
	Assigns a FEC Name and descriptive information to the server process.
int	RegisterFecName (char name, char desc, char os, char loc, char hdw, char resp, UINT16 poff)
	Assigns a FEC Name to the server process.
int	RegisterFecNameEx (char name, char desc, char os, char loc, char hdw, char resp, UINT16 poff, char *context)
	Assigns a FEC Name to the server process. Extended call.
int	RegisterMultiChannelGroupDevice (char eqm, char grpname, char *devname, int grpindex, int grpsize)
	Assigns a device name to the specified multi-channel group device.
int	RegisterProperty (char eqm, char property, int siz, short fmt, short acc, char *dsc)
	Assigns pertinent information for the specified property.
int	RegisterPropertyAlias (char eqm, char property, char *alias)
	Assigns an alias to the specified property.
int	RegisterPropertyEx (char eqm, char property, int siz, short fmt, short acc, char *dsc, int propId)
	Assigns pertinent information for the specified property.
int	RegisterPropertyInformation (char eqm, char property, DTYPE dout, DTYPE din, short acc, short atype, UINT16 rowlength, char dsc, int propId, char rdr)
	Assigns pertinent information for the specified property.
short	RegisterPropertyQueryFunction (char eqm, int(fcn)(char devName, PrpQueryStruct *prpqs), int numprops)
	Registers an extended property query function.
int	RegisterPropertySignalFunction (const char eqm, const char prp, PRPSIG fcn, int mask, void *ref)
	Registers a property signal function.
int	RegisterStateChangeCallback (SCCBFCNP fcn, const char eqm, const char stateKey, void *reference)
	Registers a state change callback dispatch function.
short	RegisterXPropertyQueryFunction (char eqm, int(fcn)(char devName, XPropertyQueryStruct *xpqs), int numprops)
	Registers an extended property query function.
int	RemoveEquipmentModule (const char *eqm)
	Unregisters an equipment module with the TINE server engine and frees all associated memory.
int	RemoveRegisteredBCastNetsList (NAME32 *ipaddr, int rmvsiz)
	removes those networks in the name list given from the current broadcast list.
int	RemoveRegisteredNetsList (const char eqm, NAME32 ipaddr, int rmvsiz)
	removes those networks in the name list given from the current network address access list.
int	RemoveRegisteredUser (char eqm, NAME16 userlist, int listsize)
	removes those users in the name list given from the current users access list.
int	SealTaggedStruct (char *tag, int size, int number)
	Seals a tagged structure (registration finished!).
int	sendNetGlobal (char keyword, DTYPE din, void(*callback)(int, int), int minPeriod, int maxPeriod, double tolerance)
	registers and sends the accompanying keyword and data as a network global.
void	SetAllowBackgroundTaskReentrancy (int value)
	Determines whether equipment module background tasks may be re-entered (boolean).
void	SetAllowNetworkAddressResolution (int value)
	Determines whether NETWORK address resolution is allowed.
void	SetAllowRemoteManagement (int value)
	Determines whether remote management via stock properties is possible.
void	SetAppDate (time_t appdate)
	Sets the compilation date of the current running server process.
void	SetAppVersion (int major, int minor, int revision)
	Sets the application version of the current running server process.
int	SetCallPropertyInSeparateThread (char eqm, char property, int value)
	Determines whether the specified property is called in a separate handler thread or not.
void	SetClientListCapacity (int value)
	Sets the maximum number of clients a server will service.
void	SetConfigurationCoded (int value)
	Determines whether TINE configuration files will be scanned or not.
void	SetContractListCapacity (int value)
	Sets the maximum number of contracts a server will service.
void	SetContractSignalFunction (CONSIG fcn, int mask, void *ref)
	Registers a contract signal function.
void	SetEnforceMcaAcquisition (int value)
	Forces multi-channel array handshaking if set to TRUE.
void	SetEqmCompletion (char eqm, char errstr)
	Sets the error string to accompany the current server call.
void	SetExportedContext (char eqmName, char context)
	Assigns the exported context associated with the equipment function name given.
void	SetExportedSubSystem (char eqmName, char subsystem)
	Assigns the exported subsystem associated with the equipment function name given.
int	SetFailoverMaster (char eqm, char masterName)
	Sets the designated server as a failover master.
void	SetFailoverPollingInterval (int pollingInterval)
	Sets the server failover interval to the value given.
int	SetFailoverSlave (char eqm, char masterName, char *slaveMaster)
	Delcares the server a failover slave and targets the designated server.
void	SetFailoverThreshold (int errorCounts)
	Sets the server failover threshold to the value given.
void	SetGCastTableCapacity (int value)
	sets the globals multicast table capacity
void	SetIgnoreCommonFiles (int value)
	turns searching for common database files in the FEC_HOME directory on or off
void	SetInitializeIdle (int value)
	When set to TRUE, all equipment modules are initialized in an 'idle' state.
void	SetlookupRedirectionNameStub (int(fcn)(char eqm, char prpName, char devName))
	Sets a stub to an existing lookupRedirectionNameStub function for cases where a Property Query Function is in force and the server needs to redirect calls.
void	SetMinimumAllowedPollingInterval (int value)
	Sets the minimum polling interval in milliseconds a server will allow.
int	SetNameServerAddress (char *ens)
	Sets the address of the Equipment Name Server via API call.
int	SetPropertyBuffer (char eqmName, char prpName, BYTE *buffer)
	Assigns a fixed buffer to handle output data for the given property.
void	SetRedirectionParameters (char eqm, char rdrCnt, char rdrSrv, char rdrDev, char *rdrPrp)
	Sets the redirection string to accompany the current server call.
void	SetRejectOverloadedMetaProperties (int value)
	Enables/Disables overloaded meta properties.
void	SetRetardSingleContractRemoval (int value)
	sets the retard contract removal state
int	SetScanForNetsFiles (const char *eqm)
	Instructs the initialization process to look for device and property specific 'ipnets' files.
int	SetScanForUsersFiles (const char *eqm)
	Instructs the initialization process to look for device and property specific 'users' files.
void	SetSchedulerInterval (int value)
	Sets the system scheduler interval.
int	SetSizeDeviceCapacity (char *eqm, int size)
	Sets (increases) the maximum size of the device table and associated tables.
int	SetSystemAlias (char alias, char name)
	Sets an alias for either a registered property or registered device.
void	SetSystemCycleDeadband (int value)
	Sets the system cycle deadband.
void	SetSystemSubscriptionRenewalLength (int value)
	Sets the contract subscription renewal length.
void	SetSystemSynchronizeContracts (int value)
	Establishes the setting for general contract synchronization at the server.
UINT32	SystemGetProcessId (void)
	Returns the process id of the running application if available.
char *	SystemGetStartupCommand (void)
	Returns the command line used to start this process.
char *	SystemGetStartupDirectory (void)
	Returns the working directory in use when this process started.
Variables
int	MaxNumClients = CLIENTLIST_CAPACITY
	Determines the maximum number of clients a server will service.
int	MaxNumContracts = CONTRACTLIST_CAPACITY
	Determines the maximum number of contracts a server will service.

Detailed Description

TINE server engine and registration API routines.

The API routines presented here deal almost exclusively with server-side registration calls. All TINE servers must export their behavior in the form of properties, devices, server names, etc. The routines offered here provide ways to do this. In most cases there are also alternatives based on startup configuration files such as fecid.csv, exports.csv, etc. On front-end systems where a local disk is available, this is the suggested registration method, since it avoids the hard coding of 'names' inside of the server programs themselves.

Function Documentation

int AddFieldToBitField	(	char *	srv,
		char *	tag,
		UINT32	mask,
		char *	field
	)

Adds a field definition to a registered bitfield.

Parameters:

srv	is the orginating server declaring the bitfield. A server declaring a bit field should pass a NULL or otherwise a simple tag such as "this".
tag	is the bitfield tag
mask	is the mask to be applied to the bitfield value to obtain the field element
field	is the field name assigned to the masked value.

Returns:: a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: OpenBitField(), GetBitfieldAsString(), GetFieldFromBitfield()

Example:

/* a registration call on the server : */
void registerBitFields(void)
{
# define SRVTAG "this" /* a local bit field */

  /* register a bitfield called "StsBits" with the local registry */
  OpenBitField(SRVTAG,"StsBits",CF_BITFIELD16);
  /* add the named fields to the bit field */
  AddFieldToBitField(SRVTAG,"StsBits",0x01,"field1");
  AddFieldToBitField(SRVTAG,"StsBits",0x02,"field2");
  AddFieldToBitField(SRVTAG,"StsBits",0x04,"field3");
  AddFieldToBitField(SRVTAG,"StsBits",0x08,"field4");
  AddFieldToBitField(SRVTAG,"StsBits",0xf0,"field5");
  AddFieldToBitField(SRVTAG,"StsBits",0xf00,"field6");
  AddFieldToBitField(SRVTAG,"StsBits",0xf000,"field7");

  /* etc. */

}

/* a bit-field access by a client */
int getBitFieldData(void)
{
  DTYPE dout;
  int cc;
  UINT16 v;
  char strbuf[1024];

  /* get the entire bit field */
  dout.dFormat = CF_BITFIELD16;
  dout.dArrayLength = 1;
  dout.data.sptr = &v;
  strncpy(dout.dTag,"StsBits",8);

  cc = ExecLinkEx("/TEST/SomeServer/device1","Status",&dout,NULL,CA_READ,200);
  if (cc == 0)
  {
    GetBitfieldAsString(NULL,"StsBits",v,strbuf,1024);
    printf("Status returned %d (%x)\n\n%s",v,v,strbuf);
  }

  /* get any named field also works ... */
  dout.dFormat = CF_BITFIELD16;
  dout.dArrayLength = 1;
  dout.data.sptr = &v;
  strncpy(dout.dTag,"StsBits",8);

  cc = ExecLinkEx("/TEST/SomeServer/device1","Status.field1",&dout,NULL,CA_READ,200);
  if (cc == 0)
  {
    printf("field1 returned %d\n",v);
  }

  /* etc. */

  return cc;
}

References feclog().

int AddFieldToStruct	(	char *	tag,
		int	addr,
		int	size,
		int	fmt,
		char *	field
	)

Adds a field description to a tagged structure.

Use this routine to register the fields of your structure within the structure registry. The fields can be any TINE format type or another tagger structure (in which case fmt = CF_STRUCT, and field = <parent tag>="">fieldname).

Parameters:

tag	structure tag name
addr	is the address offset of this field inside the structure.
size	is the array length if the described field. (not the size in bytes)
fmt	format of the new struct element
field	field name

Returns:: 0 or out_of_local_memory if no struct could be found/allocated for tag.

See also:: SealTaggedStruct

Example:

/*
   The code section below illustrates how one registers a structure
   to be exported.  
*/
typedef struct
{
  int   a;
  float b;
  char  t[16];
} StHdr;

typedef struct
{
  int c;
  float d;
  FLTINT e;
} StBod;

typedef struct
{
  StHdr hdr;
  StBod body[4];
} StCmp;

typedef struct
{
  float amplitude;
  float frequency;
  float noise;
  float phase;
  int   numberCalls;
  char  description[64];
} SineInfo;

#define quit(i) { printf("Register struct: out of memory\n"); exit(i); }
void registerStructs(void)
{
  static int done = 0;
  if (done) return;
  done = TRUE;
  /* this must follow the order of the structure explicitly! */
  if (AddFieldToStruct("SineInfo",OFFSETIN(SineInfo,amplitude),1,CF_FLOAT,"amplitude")) quit(1);
  if (AddFieldToStruct("SineInfo",OFFSETIN(SineInfo,frequency),1,CF_FLOAT,"frequency")) quit(1);
  if (AddFieldToStruct("SineInfo",OFFSETIN(SineInfo,noise),1,CF_FLOAT,"noise")) quit(1);
  if (AddFieldToStruct("SineInfo",OFFSETIN(SineInfo,phase),1,CF_FLOAT,"phase")) quit(1);
  if (AddFieldToStruct("SineInfo",OFFSETIN(SineInfo,numberCalls),1,CF_LONG,"numberCalls")) quit(1);
  if (AddFieldToStruct("SineInfo",OFFSETIN(SineInfo,description),64,CF_TEXT,"description")) quit(1);
  /* terminate the structure definition like this! */
  if (SealTaggedStruct("SineInfo",sizeof(SineInfo),NUM_DEVICES)) quit(1);

  /* below a status header struct */
  if (AddFieldToStruct("StHdr",OFFSETIN(StHdr,a),1,CF_INT32,"a")) quit(1);
  if (AddFieldToStruct("StHdr",OFFSETIN(StHdr,b),1,CF_FLOAT,"b")) quit(1);
  if (AddFieldToStruct("StHdr",OFFSETIN(StHdr,t),16,CF_TEXT,"t")) quit(1);
  if (SealTaggedStruct("StHdr",sizeof(StHdr),NUM_DEVICES)) quit(1);

  /* below a status body struct */
  if (AddFieldToStruct("StBod",OFFSETIN(StBod,c),1,CF_INT32,"c")) quit(1);
  if (AddFieldToStruct("StBod",OFFSETIN(StBod,d),1,CF_FLOAT,"d")) quit(1);
  if (AddFieldToStruct("StBod",OFFSETIN(StBod,e),1,CF_FLTINT,"e")) quit(1);
  if (SealTaggedStruct("StBod",sizeof(StBod),NUM_DEVICES)) quit(1);

  /* below a struct composed of the above header a 4 X the above body : */
  if (AddFieldToStruct("StCmp",OFFSETIN(StCmp,hdr),1,CF_STRUCT,"<StHdr>hdr")) quit(1);
  if (AddFieldToStruct("StCmp",OFFSETIN(StCmp,body),4,CF_STRUCT,"<StBod>body")) quit(1);
  if (SealTaggedStruct("StCmp",sizeof(StCmp),NUM_DEVICES)) quit(1);
}

SineInfo sineInfoTable[NUM_DEVICES];

void init(void)
{
  DTYPE dout;
  int i;

  /* register the structure ... */
  registerStructs();

  /* register the properties which use the structures ...*/
  dout.dFormat = CF_STRUCT;
  dout.dArrayLength = NUM_DEVICES;
  strcpy(dout.dTag,"SineInfo");
  RegisterPropertyInformation(SINEQM_TAG,"SineInfo",&dout,NULL,CA_READ,AT_SCALAR,0,"Sine Curve Information",PRP_SINEINFO,NULL);

  dout.dFormat = CF_STRUCT;
  dout.dArrayLength = NUM_DEVICES;
  strcpy(dout.dTag,"StCmp");
  RegisterPropertyInformation(SINEQM_TAG,"Status",&dout,NULL,CA_READ,AT_SCALAR,0,"Status Information",PRP_STATUSINFO,NULL);

  // etc. ...
}

int AppendRegisteredBCastNetsList	(	NAME32 *	iplist,
		int	listsize
	)

appends the current network broadcast list with the name list given

The network broadcast list assigned to FEC is often read in via configuration file (see ipbcast.csv or fec.xml). However networks can also be assigned via this API call. The list given will be appended to any existing list of allowed network addresses. Generally use of this API call or configuration files is unncessary, as most modern operating systems will be able to receive TINE multicasts. Some legacy systems will not be able to do this however. In such cases, applying a broadcast list will re-send all multicasted transmission as UDP broadcasts to those networks specified in the list.

Parameters:

iplist	is a list of network addresses to be appended to the current broadcast list. If a network address in the input is already in the current access list, nothing happens.
listsize	is the size of the input list.

Returns:: 0 or a TINE error code.

See also:: RemoveRegisteredBCastNetsList()

int AppendRegisteredNetsList	(	const char *	eqm,
		NAME32 *	iplist,
		int	listsize
	)

appends the current network access list with the name list given

The network access list assigned to FEC is often read in via configuration file (see ipnets.csv or fec.xml). However networks can also be assigned via this API call. The list given will be appended to any existing list of allowed network addresses.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
iplist	is a list of network addresses to be appended to the current network access list. If a network address in the input is already in the current access list, nothing happens.
listsize	is the size of the input list.

Returns:: 0 or a TINE error code.

See also:: RemoveRegisteredNetsList()

int AppendRegisteredUsers	(	const char *	eqm,
		NAME16 *	userlist,
		int	listsize
	)

appends the current users access list with the name list given

The users access list assigned to an equipment module is often read in via configuration file (see users.csv or fec.xml). However users can also be assigned via this API call. The list given will be appended to any existing list of allowed users.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
userlist	is a list of users to be appended to the current users access list. If a user in the input is already in the current access list, nothing happens.
listsize	is the size of the input list.

Returns:: 0 or a TINE error code.

See also:: RemoveRegisteredUser()

References NAME16::name.

int AssignDataStampsToGlobal	(	char *	keyword,
		int	dataStamp,
		int	sysStamp
	)

Assigns additional data stamps to the registered global keyword.

The keyword supplied must already exist in the globals table, else an error occurs.

Returns 0 upon successful globals transmission, otherwise a TINE error code.

Parameters:

keyword	is the globals KEYWORD which identifies the data set being sent.
dataStamp	is a user-defined integer value to accompany the globals multicast.
sysStamp	is a system-defined integer value to accompany the globals multicast.

int AssignDeviceAccessList	(	const char *	eqm,
		const char *	dev,
		NAME16 *	users,
		int	nusers
	)

Assigns an access list for the device given.

In addtion to the overall access lists for the server process, devices can be individually assigned a user access list.

Note:: As the general access lists constitute the first barrier which must be overcome, any user name assigned to a property's access list but not assigned to the server (if the server has an access list) will not be granted WRITE access.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
dev	is the registered device for the access list is to be applied.
users	is a list of user names for whom WRITE access is to be granted.
nusers	is the size of the users list supplied.

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

See also:: RegisterPropertyInformation(), AssignDeviceNetsList()

References GetDeviceNumber().

int AssignDeviceListToProperty	(	char *	eqm,
		char *	prp,
		NAME64 *	devlst,
		int	lstlen
	)

Assigns the given device list to the given registered property.

Properties (e.g. multi-channel array properties) which wish to present a property-specific device list can assign the list to the property in this way.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prp	is property name for which the device list is to be assigned.
devlst	is the device list which is to be associated with the given property
lstlen	is the length of the device list.

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

See also:: RegisterProperty(), RegisterPropertyEx(), RegisterPropertyInformation()

References NAME64::name.

int AssignDeviceNetsList	(	const char *	eqm,
		const char *	dev,
		NAME16 *	ipnets,
		int	nipnets
	)

Assigns an ip nets access list for the device given.

In addtion to the overall access lists for the server process, devices can be individually assigned a network access list.

Note:: As the general access lists constitute the first barrier which must be overcome, any user name assigned to a property's access list but not assigned to the server (if the server has an access list) will not be granted WRITE access.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
dev	is the registered device for the access list is to be applied.
ipnets	is a list of network names for which WRITE access is to be granted. For example a list entry "192.168.100.18" would grant the host at "192.168.100.18" WRITE access. The list entry "192.168.100.255" would grant all hosts on the .100 subnet write access, and so on.
nipnets	is the size of the ipnets list supplied.

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

See also:: RegisterPropertyInformation(), AssignDeviceAccessList()

References GetDeviceNumber().

int AssignNumDevices	(	char *	eqm,
		int	num
	)

Fixes the number of modules (devices) attached to the specified equipment module.

Servers generally do not need to make this call, as the number of modules or devices is either specified in the local database file 'exports.csv', or has been passed as an argument in a call to RegisterEquipmentModule(). However, in cases where the number so assigns represents an upper limit, and the actual number of modules is only known after the server is running, then a call to AssignNumDevices() can be made to reduce the querieable number of modules to this number.

Note:: An upper limit of the number of devices (capacity) must have already been specified either through the exports.csv file or through a call to RegisterEquipmentModule(). The number specied in a call to AssignNumDevices() must be smaller than this number. The capacity can however be increased (if memory is available) via a call to SetSizeDeviceCapacity().

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
num	is the number of modules (devices) to be associated with the equipment module

Returns:: 0 is successful or a TINE completion code

See also:: SetSizeDeviceCapacity()

int AssignPropertyAccessList	(	const char *	eqm,
		const char *	prp,
		NAME16 *	users,
		int	nusers
	)

Assigns an access list for the property given.

In addtion to the overall access lists for the server process, properties can be individually assigned a user access list.

Note:: As the general access lists constitute the first barrier which must be overcome, any user name assigned to a property's access list but not assigned to the server (if the server has an access list) will not be granted WRITE access.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prp	is the registered property for the access list is to be applied.
users	is a list of user names for whom WRITE access is to be granted.
nusers	is the size of the users list supplied.

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

See also:: RegisterPropertyInformation(), AssignPropertyNetsList()

int AssignPropertyList	(	char *	eqm,
		char *	devname,
		char *	listname,
		int	listsize,
		NAME64 *	prplist
	)

Assigns the given property list to the given device to be used in device-oriented queries.

Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. Most device servers provide a list of all instances, a device list, and a list of all properties, where every instance (device) supports all exported properties. Under some circumstances, it is desireable to support only a (device-specific) subset of properties per device. This can be achieved by supplying a property query function, or by configuration file, or by using this call to assign a property list to the specified device. The latter is the preferred method, as then all registered properties are contained within the TINE property registry, which will contain sometimes crucial additional information about the registered property.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
devname	is device name in question (up to 32 characters, preferably 16 or less).
listname	is a 'tag' name to be assigned to the list. Where many devices share the same property list, this tag is used to avoid unnecessarily allocating new memory for the same list.
listsize	is the length of the property list.
list	is the property list as an array of NAME64 entities. If the list provided is not at least as long as indicated by parameter listsize, the server's behavior is undefined.

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

See also:: RegisterPropertyQueryFunction(), RegisterXPropertyQueryFunction().

References GetDeviceNumberEx().

int AssignPropertyNetsList	(	const char *	eqm,
		const char *	prp,
		NAME16 *	ipnets,
		int	nipnets
	)

Assigns an ip nets access list for the property given.

In addtion to the overall access lists for the server process, properties can be individually assigned a network access list.

Note:: As the general access lists constitute the first barrier which must be overcome, any user name assigned to a property's access list but not assigned to the server (if the server has an access list) will not be granted WRITE access.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prp	is the registered property for the access list is to be applied.
ipnets	is a list of network names for which WRITE access is to be granted. For example a list entry "192.168.100.18" would grant the host at "192.168.100.18" WRITE access. The list entry "192.168.100.255" would grant all hosts on the .100 subnet write access, and so on.
nipnets	is the size of the ipnets list supplied.

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

See also:: RegisterPropertyInformation(), AssignPropertyAccessList()

int ExecLocalLink	(	const char *	devName,
		const char *	devProperty,
		DTYPE *	dout,
		DTYPE *	din,
		short	access
	)

Executes a synchronous link within the local process.

Synchronous data exchange within a process. ExecLocalLink() does not complete until the data transfer has completed or a timeout has ensued. ExecLocalLink() has marginal applicability other than processing and returning the result of a call within a server, which could be of use if multiple equipment functions are bound together or a server's background task needs to know the outcome of a call into the server, etc.

Parameters:

devName	is the local device name (/LOCAL/<Local Equipment Name>/<Device>) of the device to contact. For example: "/LOCAL/BPMEQM/WL167".
devProperty	is the device property requested, for example "ORBIT.X"
dout	is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned.
din	is a pointer to the input data set, that is, the data set to be sent to the server from the client. If din is a NULL pointer, it is assumed that no data are to be sent to the server
access	is the data access mode. This can be any combination of TINE access code ORed together (e.g. CA_READ\|CA_WRITE).

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

See also:: ExecLink(), ExecLinkEx(), DTYPE

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, and DTYPE::dFormat.

Referenced by ExecLink().

int FindNameServerOnNetwork ( void )

Issues a multicast (or broadcast) to which the TINE equipment name server repsonds.

In lieu of accessing the file 'cshosts.csv' (whose location is determined by the environment variable TINE_HOME) a server can make this call to ascertain the address(es) of the Equipment Name Server (ENS). This is convenient for platforms which do not have a hard disk and do not know a-priori the address of the equipment name server.

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

See also:: SetNameServerAddress()

References feclog(), and FindServerOnNetwork().

int FindServerOnNetwork	(	char *	context,
		char *	eqmName,
		char *	exportName,
		FecDataStruct *	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

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

Referenced by FindNameServerOnNetwork().

void FlushContractTable ( void )

Flushes the current contract and client entry tables.

Calling this routine will effectively disconnect all attached clients and remove all persistent contracts. This will appear to any connected client to be a server 'time-out' and attached clients will attempt to re-establish any lost connections. Any link callbacks a client might have will receive 'link_timeout' status messages during the reconnection interval. Thus this routine can effectively be used to signal a 'server restart' during server runtime.

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

int GetAllowedRemoteManagement ( void )

Returns whether remote management via stock properties is possible.

The stock properties "SRVEXIT", "SRVINIT", "SRVRESET" will return 'not_allowed' unless remote managment is turned on (default OFF)

Returns:: the desired setting

See also:: SetAllowRemoteManagement()

int GetAllowNetworkAddressResolution ( void )

returns whether NETWORK address resolution is allowed

In an ENS-less (minimal) infrastructure, an initializing client can attempt to find server addresses by sending a NETWORK (multicast) probe to ascertain a server's address. In lieu of an ENS configuration, this requires a running server (configured to respond to NETWORK requests). Otherwise the servers address cannot be resolved.

Note:: this value can also be determined by environment TINE_NETWORKADDRESS_RESOLUTION = TRUE

Returns:: the current setting (default = FALSE)

See also:: SetAllowNetworkAddressResolution()

int GetBitfieldAsString	(	char *	srv,
		char *	tag,
		UINT32	value,
		char *	strbuf,
		int	buflen
	)

Retrieves the requested field value from a bit field as a string value.

Parameters:

srv	(input) is the orginating server declaring the bitfield. A server declaring a bit field should pass a NULL or otherwise a simple tag such as "this".
tag	(input) is the bitfield tag
field	(input) is the field for which the values is desired
value	(input) is the full value of the bitfield (cast as a 32 bit integer)
strbuf	(output) is the string buffer which should contain the converted string value
buflen	(input) is the length of the supplied string buffer

Returns:: a tine return code.

See also:: OpenBitField(), AddFieldToBitField(), GetFieldFromBitfield()

char* GetCaller ( char * eqmName )

Gives the user name of the current caller.

If a call to an equipment module is made on behalf of more than one user, then GetCaller() only refers to the first in the list. Typically, GetCaller() is used to see who is making a WRITE access call, which is usually synchronous and has only one user attached. When more information is required or the contract is liable to be monitored by many clients, then GetCallerInfo() should be used instead.

Parameters:

eqmName (in) is the equipment function name (local name) for which the exported name is desired.

Returns:: The user name of the current caller

See also:: GetCallerInformation()

Example:

if (!strcmp("SMITH",GetCaller("MYEQM")) return access_denied; // don’t let SMITH issue this command

References GetCallerInfo(), and NAME16::name.

int GetCallerInfo	(	char *	eqmName,
		NAME16 *	un,
		BYTE *	ipx,
		UINT32 *	ip,
		short *	prot,
		int *	num
	)

Returns the user name(s) and network address(es) of all callers interested in the current contract.

Parameters:

eqmName	(in) is the equipment function name (local name) for which the exported name is desired.
un	(out) if non-NULL is a reference to an array of NAME16 objects to be filled with the caller list
ipx	(out) if non-NULL is a reference to a byte array to be filled with the IPX addresses of the caller(s).
ip	(out) if non-NULL is a reference to an unsigned long array to be filled with the IP addresses of the caller(s).
prot	(out) if non-NULL is a reference to a short array to be filled with the requested protocol level of the caller(s).
num	(in/out) is a reference to an int value which initially contains the buffer size of the array references used in the parameter list. Upon return of the call, it contains the actual number of callers.

Note:: The non-NULL arguments supplied must point to buffer with enough room to hold at least the input 'num' entries, otherwise a system crash is likely.; This call has been deprecated in favor of GetCallerInformation

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

See also:: GetCallerInformation()

Example:

NAME16 userlist[10];
UINT32 ipaddrlist[10];
char ip[17];
int n = 10;
 
GetCallerInfo(userlist,NULL,ipaddrlist,NULL,&n);

printf(“there are %d callers\n”,n);

if (n > 10) n = 10;

for (i=0; i<n; i++) 
{  
    inet_ntoa_b(*(struct in_addr *)&ipaddrlist[i],ip);
    printf(“%s : %s\n”,userlist[i].name,ip);
}

References NAME16::name.

Referenced by GetCaller().

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++)
  {
    inet_ntoa_b(clninf[i].addr.sin_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);
  }

References ClnInfoStruct::accessMode, ClnInfoStruct::addr, ClnInfoStruct::counter, ClnInfoStruct::inetProtocol, ClnInfoStruct::ncontracts, ClnInfoStruct::pollingRate, ClnInfoStruct::starttime, ClnInfoStruct::tineProtocol, and ClnInfoStruct::userName.

int GetClientListCapacity ( void )

Gets the maximum number of clients a server will service.

A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number clients, then this value should be set accordingly at initialization time. The current setting can be obtained with this call

Returns:: the current client table size

See also:: SetClientListCapacity()

int GetConfigurationCoded ( void )

Returns whether TINE configuration files will be scanned.

Returns:: the current setting

See also:: SetConfigurationCoded()

int GetContractListCapacity ( void )

Gets the maximum number of contracts a server will service.

A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number contracts, then this value should be set accordingly at initialization time. The current setting can be obtained with this call

Returns:: the current contract table size

See also:: SetContractListCapacity()

char* GetDeviceDescription	(	char *	eqm,
		int	devnr
	)

Gives the registered device description (if known) for the device number.

A server can determine the device description which has been associated with a device number by making this call.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
devnr	is the device number to be looked up.

Returns:: The device description corresponding to the input device number if successful, otherwise a error string indicating the problem.

See also:: RegisterDeviceName(), GetDeviceNumber()

char* GetDeviceName	(	char *	eqm,
		int	devnr
	)

Gives the registered device name for the specified equipment module and device number.

A server can determine the name which has been associated with a device number by making this call.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
devnr	is the device number to be looked up.

Returns:: The device name corresponding to the input device number if successful, otherwise a string reiterating the input device number.

See also:: RegisterDeviceName(), GetDeviceNumber()

Alias: GetModuleName

Example:

   printf("device %d is registered as %s\n",i,GetDeviceName("EQP1",i));

int GetDeviceNumber	(	char *	eqm,
		char *	devname
	)

Gives the registered device number for the specified device name.

Callers frequently address specific devices by their human-readable names rather than a device number (which might be an entry point into an array, for example). If the caller registers device names via calls to RegisterDeviceName() then the cross reference exists in the form of a hash table. A server's equipment module can thus rapidly determine the corresponding device number from an input device name by calling GetDeviceNumber().

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
devname	is the device name to be looked up

Returns:: The device number corresponding to the input device name if successful, otherwise the negative of a TINE return code (indicating that the name input is not registered as a device on the server).

See also:: RegisterDeviceName(), GetDeviceNumberEx()

Alias: GetModuleNumber

Example:

#include "toolkit.h"
#include "bpmeqm.h"

...

/* BPM Equipment module handler */
int bpmeqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  int devnr,prpid,i,cc;
  short l_online;

  /* get the device number associated with the requested device name : */
  devnr = GetDeviceNumber(BPMEQM_TAG,devName);
  if (devnr < 0) return illegal_equipment_number;

  switch (GetPropertyId(BPMEQM_TAG,devProperty))
  {
    case PRP_ONLINE:
 ...

References GetDeviceNumberEx().

Referenced by AssignDeviceAccessList(), AssignDeviceNetsList(), and RegisterDeviceName().

int GetDeviceNumberEx	(	char *	eqm,
		char *	devname,
		char *	prpname
	)

Gives the registered device number for the specified device name and property name.

Callers frequently address specific devices by their human-readable names rather than a device number (which might be an entry point into an array, for example). If the caller registers device names via calls to RegisterDeviceName() or has registered a "<property>.NAM" meta property (corresponding to a property-specific set of device names for <property>), then the cross reference exists in the form of a hash table. A server's equipment module can thus rapidly determine the corresponding device number from an input device name by calling GetDeviceNumberEx().

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
devname	is the device name to be looked up
prpname	if non-NULL should be the targeted property name for which the device names apply

Returns:: The device number (i.e. multi-channel array index) corresponding to the input device name if successful, otherwise the negative of a TINE return code (indicating that the name input is not registered as a device on the server.)

See also:: RegisterDeviceName(), GetDeviceNumber()

Example:

  // find the device number/multi-channel array index for given device name and property
  idx = GetDeviceNumberEx(MSTEQM_TAG,devName,devProperty);
  if (idx < 0) return illegal_device;

Referenced by _SystemSchedulePropertyEx(), AssignPropertyList(), GetDeviceNumber(), GetLastStoredData(), RedirectDeviceName(), RegisterDeviceDescription(), RegisterMultiChannelGroupDevice(), and RestorePropertyValues().

int GetEnforceMcaAcquisition ( void )

returns the setting for multi-channel array handshaking enforcement.

A server can absolutely enforce multi-channel array handshaking independent of the release level of the client. This has relevance as to whether persistent single-element links are allowed or not. If allowed then a 'modern' client might be able to latch on to a pre-existing single-element link established by an older client.

Returns:: the current setting for this value

See also:: SetEnforceMcaAcquisition

char* GetExportedContext ( char * eqmName )

Returns the exported context associated with the equipment function name given.

A server as coded, frequently does not know the context under which it is registered, as this is information is often contained in a registration file such as 'fecid.csv' or 'exports.csv'. Nonetheless it might be desireable to know what name was actually exported, for use in say conditional trapping or logging. This call returns the name finally exported after the server has been initialized.

Parameters:

eqmName is the equipment function name (local name) for which the exported context is desired.

Returns:: If successful, the export context associated with the equipment function name supplied.

NAME64* GetExportedDeviceList ( char * eqm )

Returns the list of exported device names explicitly associated with the equipment module passed as the input parameter.

A server can retieve the list of explicitly exported device names by making this call.

Parameters:

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

Returns:: A array of NAME32 objects containing the exported device names or a NULL pointer if there is an error, such as the equipment module given is not registered or there are no exported device names associated with the equipment module.

See also:: RegisterDeviceName()

Referenced by GetDeviceNamesEx(), and GetSystemDevices().

char* GetExportedFecName ( void )

Returns the FEC name exported at the time of server initialization.

Returns:: If successful, the fec name registered at the equipment name server.

char* GetExportedName ( char * eqmName )

Returns the exported name associated with the equipment function name given.

A server as coded, frequently does not know its system wide identity (i.e. its 'export name'), as this is information is contained in a registration file such as 'exports.csv'. Nonetheless it might be desireable to know what name was actually exported, for use in say conditional trapping or logging. This call returns the name finally exported after the server has been initialized.

Parameters:

eqmName is the equipment function name (local name) for which the exported name is desired.

Returns:: If successful, the export name associated with the equipment function name supplied. Otherwise a NULL pointer is returned.

See also:: GetCompletionStatus()

Referenced by AppendHistoryInformationEx().

char* GetExportedSubSystem ( char * eqmName )

Returns the exported subsystem associated with the equipment function name given.

A server as coded, frequently does not know the subsystem under which it is registered, as this is information is often contained in a registration file such as 'fecid.csv' or 'exports.csv'. Nonetheless it might be desireable to know what name was actually exported, for use in say conditional trapping or logging. This call returns the name finally exported after the server has been initialized.

Parameters:

eqmName is the equipment function name (local name) for which the exported subsystem is desired.

Returns:: If successful, the export subsystem associated with the equipment function name supplied.

int GetFieldFromBitfield	(	char *	srv,
		char *	tag,
		char *	field,
		UINT32	value
	)

Retrieves the requested field value from a bit field.

Parameters:

srv	is the orginating server declaring the bitfield. A server declaring a bit field should pass a NULL or otherwise a simple tag such as "this".
tag	is the bitfield tag
field	is the field for which the values is desired
value	is the full value of the bitfield (cast as a 32 bit integer)

Returns:: the bitfield value from the supplied value or a negative tine return code.

See also:: OpenBitField(), AddFieldToBitField(), GetBitfieldAsString()

int GetGCastTableCapacity ( void )

gets the globals multicast table capacity (server-side)

See also:: SetGCastTableCapacity(), recvNetGlobal().

int GetIgnoreCommonFiles ( void )

returns the current setting (default = FALSE)

When set to TRUE, attempts to read an exports.csv or related equipment module files which directly reside in the FEC_HOME directory (or working directory, if not set) are blocked. Any related files within the equipment module 'local name' sub-directory will still be scanned and read.

Returns:: the current setting of this feature.

See also:: SetIgnoreCommonFiles()

char* GetLocalName ( char * exportName )

Returns the local equipment module name associated with the export name given.

Parameters:

exportName is the exported device server name for which the local equipment module name is desired.

Returns:: a string pointing to the local equipment module name.

int GetMinimumAllowedPollingInterval ( void )

returns the minimum polling rate in milliseconds a server will allow.

A server will not honor polling rates smaller than this value. An attempt to poll a property a 1 msec for instance will be serviced at the MinPollingRate instead. If it is known that the server should support very fast polling rates, then this value should be set accordingly at initialization time.

Returns:: the current setting for this value

See also:: SetMinimumAllowedPollingInterval

int GetNumberRegisteredDevices ( char * eqm )

Gives the number of registered devices explicitly associated with the equiment module name given.

Parameters:

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

Returns:: The number of registered devices if successful, or the negative of a TINE return code (indicating that the name input is not registered as a device on the server.)

See also:: RegisterDeviceName(), GetDeviceNumber()

int GetNumCallers ( char * eqm )

Returns the current number of callers associated with the equipment module given.

Parameters:

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

Returns:: The total number of callers (i.e. clients) associated with the given equipment module. If a NULL parameter is passed, the function returns the total number of consumers for all registered equipment modules. This call is synonymous with GetNumConsumers().

References GetNumConsumers().

int GetNumConsumers ( char * eqm )

Returns the current number of consumers associated with the equipment module given.

Parameters:

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

Returns:: The total number of consumers (i.e. clients) associated with the given equipment module. If a NULL parameter is passed, the function returns the total number of consumers for all registered equipment modules. This call is synonymous with GetNumCallers().

Example:

   printf("EQP1 has %d active clients\n",GetNumConsumers("EQP1");

Referenced by GetNumCallers().

int GetNumContracts ( char * eqm )

Returns the current number of contracts associated with the equipment module given.

Parameters:

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

Returns:: The total number of contracts associated with the given equipment module. If a NULL parameter is passed, the function returns the total number of contracts for all registered equipment modules.

Example:

   printf("EQP1 has %d active contracts\n",GetNumContracts("EQP1");

BYTE* GetPropertyBuffer	(	char *	eqmName,
		char *	prpName
	)

Returns the address of the buffer previously assigned to the property given.

Generally an equipment module's dispatch handler is called with a reference to an allocated buffer into which the property's output is written. In some circumstances (e.g. large video frames) it is prudent to instruct the dispatch handler to make use of a pre-assigned buffer area (which is likely already filled with data) and to forgo any double buffering and memory copying that might otherwise occur. If a buffer has been assigned, its address can be obtained with this call.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prpName	is the registered property for which the buffer space is desired.

Returns:: The address of the assigned buffer space (NULL if not assigned).

See also:: SetPropertyBuffer()

int GetPropertyId	(	char *	eqm,
		char *	prpName
	)

Gives the associated property identifier for the given property name.

Callers will alway address properties by their human-readable names. Equipment modules can either initiate a series of strcmp()s in order to determine which property is being called or make direct use of the associated property identifier in a case switch or address table. Note that properties registered with RegisterProperty() simply return an index in the server's ordered list. You can associate any indentifier you like by calling either RegisterPropertyEx() or RegisterPropertyInformation() to register the property. The cross reference from property name to property identifier exists in the form of a hash table. A server's equipment module can thus rapidly determine the corresponding identifier from an input property by calling GetPropertyId().

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prpName	is the property name to be looked up

Returns:: The property identifier corresponding to the input property name if successful, otherwise -1 (indicating that the name input is not registered as a property on the server).

See also:: RegisterProperty(), RegisterPropertyEx(), RegisterPropertyInformation()

Example:

#include "toolkit.h"
#include "bpmeqm.h"

...

int bpmeqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  int devnr,prpid,i,cc;
  short l_online;

  /* Get the device number associated with the requested device name : */
  devnr = GetDeviceNumber(BPMEQM_TAG,devName);
  if (devnr < 0) return illegal_equipment_number;

  /* Get the assigned Property Id : */
  prpid = GetPropertyId(BPMEQM_TAG,devProperty);

  /* case switch to the requested property : */
  switch (prpid)
  {
    case PRP_ONLINE:
        if (access&CA_WRITE) 
        {
  ...

int GetRegisteredPropertyList	(	char *	eqm,
		NAME64 *	prpNames,
		int *	nprps
	)

Returns the list of registered properties explicitly associated with the equipment module passed as the first argument input parameter.

A server can retieve the list of registered properties by making this call. This is sometimes useful when the property list is maintained in an 'exports.csv' file and the server application needs to retrieve this list.

Parameters:

eqm	(input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prpNames	(output) is the address location which is to hold the property list upon completion
nprps	(intput/output) is a pointer to an integer which as input specifies the size of the buffer pointed to by the second parameter. Upon return it contains the actual number of registered properties.

Returns:: '0' upon success, othereise a tine return code.

int GetRegisteredPropertyListStruct	(	char *	eqm,
		char *	prpName,
		ExportPropertyListStruct *	prpLstStruct
	)

Returns the ExportPropertyListStruct structure for the registered property specified by the first two arguments.

A server can retieve the ExportPropertyListStruct structure of the input registered property by making this. This will give the full information pertaining to the property given.

Parameters:

eqm	(input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prpName	(input) is the name of the property for which the ExportPropertyListStruct structure is desired.
prpLstStruct	(output) contains the output structure when the call completes.

Returns:: '0' upon success, othereise a tine return code.

See also:: GetRegisteredPropertyList()

Referenced by AssertRangeValid().

int GetRejectOverloadedMetaProperties ( void )

returns the current setting

Meta-properties such as .HIST or .NAM can be 'overloaded' by registering the appropriately named property. This will prevent the systematically available meta-property from being called. This is by default the case (if a property ABC.HIST is itself registered it will be called instead of the TINE local history). Explicitly calling SetRejectOverloadedMetaProperties(TRUE) will disable this feature.

Returns:: the current setting (default: FALSE -> overloaded meta properties are allowed and will not be rejected)

See also:: SetRejectOverloadedMetaProperties()

int GetRetardSingleContractRemoval ( void )

returns the current setting of this feature.

When all clients disappear from a contract the contract is then scheduled for removal at the server. This can either happen 'immediately' or be 'retarded' for a duration of 1 second. Typically a synchronous READ or WRITE command establishes a transient contract which if allowed to persist for this extra second can handle 'RETRY' requests by returning the results of the contract. However this strategy also occupies a slot in the servers contract table until the contract is officially removed, when can effectively lock up the contract table if a large number of synchronous requests are issued (clients will receive a 'resources_exhausted' return code in such cases. If a server can tolerate idempotent requests (the same request twice, so to speak) then it might be advisable to turn this feature off.

Returns:: the current setting of this feature.

See also:: SetRetardSingleContractRemoval()

int GetSchedulerInterval ( void )

Gets the system scheduler interval.

The TINE kernel will call the scheduler regularly in order to service the current contract list. Under some circumstances it may be wished to control this interval. For instance, if it is known a priori that a server will need to respond to heavy synchronous polling while at the same time maintaining a lengthy contract list, it is desireable to limit the number of passes through the scheduler per second (as this will traverse the contract list with each pass). Thus setting the scheduler interval to some reasonable number (e.g. 50 or 100 milliseconds) might significantly reduce the CPU load on the server. Note however, that this will impose a latency on all synchronous requests! If the value for the schedular interval is set to 0 (the default value) or less, then the scheduler will be called at often as necessary, usually at the system polling interval (as determined by the most eager contract) and/or following a client request.

Returns:: the current setting for this value.

See also:: SetSchedulerInterval()

int GetSizeDeviceCapacity ( char * eqm )

Gives the maximum size of the device table associated with the equiment module name given.

This given the originally registered amount of device space for this equipment module. Attempts to register devices with device numbers greater than this value will fail.

Parameters:

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

Returns:: The size of the device table associated with the given equipment module or negative of a TINE return code (indicating that the name input is not registered as a device on the server.)

See also:: RegisterDeviceName(), GetDeviceNumber()

int GetSystemCycleDeadband ( void )

Gets the system cycle deadband.

A TINE client or server requires a 'cycler' to run either on separate thread (see SystemStartCycleTimer() where available) or as part of a user defined engine (running SystemCycle() in an infinite loop). The cycler will block on incoming network traffic for a duration up to the given system cycle deadband (typically 10 msec). Either a network request wakes the cycler up or the deadband timeout expires. Following this other background activity will take place (such as processing contracts, checking local histories, and alarms, etc.). The system cycle deadband can be read with this API call.

Returns:: the current system cycle deadband (default: OS dependent, typically 10 msec)

See also:: SetSystemCycleDeadband()

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

int GetSystemSynchronizeContracts ( void )

Returns the setting for general contract synchronization at the server.

A server will try to schedule contracts at the regular intervals necessary to satisfy its clients' needs. If 'contract synchronization' is in effect, the server will attempt to call the relevant equipment module dispatch routines in a tight loop in order to collect and disperse information in the smallest number of data transfers (contract packing). You can ascertain the current setting with this API call.

Returns:: the current setting for contract synchronization (default = TRUE);

See also:: SetSystemSynchronizeContracts()

int IsStandAlone ( void )

Determines whether a client or server process is running in stand-alone mode.

Stand-alone mode is only set by setting the environment variable TINE_STANDALONE to TRUE prior starting the client or server process. If TRUE, no attempt is made to contact the TINE equipment name server. Instead the local address CACHE is consulted. A server updates its own entry by supplying the registered port offset and the loopback address.

Default: FALSE.

int JoinEquipmentGroup	(	char *	eqm,
		char *	groupname,
		int	groupindex
	)

Instructs the equipment module to join the specified equipment group.

It is sometimes desireable to access a collection of like devices via a device group, rather than a device server. This is of course true when the devices in the group span more than one physical device server. You can use this API call to instruct the equipment module to join the specified group. You should use this call prior to calling SystemCycle().

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
groupname	is the name of the group the equipment module is to join.
groupindex	is an ordered index, which can specify which location within the group this equipment module's devices are to have. If '0' is passed, the group server will assign an order.

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

Example:

  // designate equipment module "SINEQM" to be a member of device group "SineGroup" 
  // and assign it the metric '0' (associated devices at the 'beginning' of the 
  // group's device list :

  JoinEquipmentGroup("SINEQM","SineGroup",0);

  // designate equipment module "COSEQM" to be a member of device group "CoSineGroup" 
  // and assign it the metric '0' (associated devices at the 'beginning' of the 
  // group's device list and instruct the group server to assign the prefix 
  // "Marthas." and the postfix ".Bldg12" to each device.

  JoinEquipmentGroupEx("COSEQM","CoSineGroup",0,"Marthas.",".Bldg12");

See also:: JoinEquipmentGroupEx()

int JoinEquipmentGroupEx	(	char *	eqmName,
		char *	groupname,
		int	groupindex,
		char *	devPrefix,
		char *	devPostfix
	)

Instructs the equipment module to join the specified equipment group.

It is sometimes desireable to access a collection of like devices via a device group, rather than a device server. This is of course true when the devices in the group span more than one physical device server. You can use this API call to instruct the equipment module to join the specified group. You should use this call prior to calling SystemCycle(). With the extended call you can also pass an optional prefix or postfix to be appended to the device names used at the group server. This can be a very useful option where multiple instances of a device server each supply a device list of identical names (e.g. where the device names do not correspond to specific locations, etc.).

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
groupname	is the name of the group the equipment module is to join.
groupindex	is an ordered index, which can specify which location within the group this equipment module's devices are to have. If '0' is passed, the group server will assign an order.
devPrefix	is a (up to 8-character) prefix to be added to all device names acquired from the physical server.
devPostfix	is a (up to 8-character) prostfix to be appended to all device names acquired from the physical server.

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

Example:

  // designate equipment module "SINEQM" to be a member of device group "SineGroup" 
  // and assign it the metric '0' (associated devices at the 'beginning' of the 
  // group's device list :

  JoinEquipmentGroup("SINEQM","SineGroup",0);

  // designate equipment module "COSEQM" to be a member of device group "CoSineGroup" 
  // and assign it the metric '0' (associated devices at the 'beginning' of the 
  // group's device list and instruct the group server to assign the prefix 
  // "Marthas." and the postfix ".Bldg12" to each device.

  JoinEquipmentGroupEx("COSEQM","CoSineGroup",0,"Marthas.",".Bldg12");

int OpenBitField	(	char *	srv,
		char *	tag,
		int	fmt
	)

Declares a bit field type and registers with the bitfield registry.

Parameters:

srv	is the orginating server declaring the bitfield. A server declaring a bit field should pass a NULL or otherwise a simple tag such as "this".
tag	is the bitfield tag
fmt	is the bit field format (one of CF_BITFIELD8, CF_BITFIELD16, or CF_BITFIELD32).

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

See also:: AddFieldToBitField(), GetBitfieldAsString(), GetFieldFromBitfield()

References feclog().

int RedirectDeviceName	(	char *	eqm,
		char *	devname,
		char *	rdr
	)

Applies the redirection string to the given device for all properties.

Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. A server can export devices which live on other servers. To do so a redirection string needs to be applied to the device in question.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
devname	is device name in question.
rdr	is the redirection string whose general form is "/<context>/<server>/<device>/[property]". The only relevant tag in the redirection string is the <server> tag as a call to RedirectDeviceName will apply to all properties for the specified device. The <context> tag is as yet always assumed to be the same context as the redirecting server. Thus the redirection string can be specified as simply "<server>"

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

See also:: RedirectProperty(), RegisterProperty(), RegisterPropertyEx(), RegisterPropertyInformation()

References GetDeviceNumberEx().

int RedirectProperty	(	char *	eqm,
		char *	prop,
		char *	rdr
	)

Applies the redirection string to the given property.

Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. A server can export properties or devices which live on other servers. To do so a redirection string needs to be applied to the property in question. As different registered devices can also be redirected to different servers. This routine can be called several times for the same property, once for each remote device.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prop	is property name in question (up to 64 characters).
rdr	is the redirection string of the form "/<context>/<server>/<device>/[property]" where <server> is the only non-optional entry in the redirection string. If <device> is omitted, all calls for the given property will be redirected to the given <server>. If device is included, only those calls to the specified device and property will be redirected. If <property> is specified then the given property name will be redirected to the remote <server> and the remote <property>.

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

See also:: RegisterProperty(), RegisterPropertyEx(), RegisterPropertyInformation(), RedirectDeviceName()

Example:

// don't handle the registered property "Sine" in this server!
// redirect the call to the target server given
RedirectProperty("MYEQM","Sine","/TEST/SineServer");

int RegisterDeviceDescription	(	char *	eqm,
		char *	devname,
		char *	description
	)

Assigns a device description to the specified device.

Many servers handle instances of a given device type, such as a set of vacuum pumps, beam position monitors, magnet power supply controllers, etc. It is occasionally useful to assign individual description texts pro device (e.g. a hardware address) An alternative is to provide a startup database file 'devices.csv' containing device descriptions.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
devname	is device name to be assigned
description	is the device description to be associated with the device specified.

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

See also:: GetDeviceName(), GetDeviceNumber()

References GetDeviceNumberEx().

int RegisterDeviceName	(	char *	eqm,
		char *	devname,
		int	devnr
	)

Assigns a device name to the specified device number.

Many servers handle instances of a given device type, such as a set of vacuum pumps, beam position monitors, magnet power supply controllers, etc. It is frequently very efficient to code in terms of device numbers which might be an index into an array, but to specify modules in calls by their human-readable names. For such purposes a device name can be assigned to a number at initialization via a call to RegisterDeviceName() (alias: RegisterModuleName()). An alternative is to provide a startup database file 'devices.csv' containing a cross-reference for numbers and names. Internally, a hash table is maintained for fast lookups inside equipment module routines.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
devname	is device name to be assigned
devnr	is the device number associated with the device name specified.

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

See also:: GetDeviceName(), GetDeviceNumber()

Example:

  char s[1024];

  // assign meaningful device names to the 10 sine generator instances ...
  for (n=0; n<10; n++) 
  {
    sprintf(s,"SineGen%d",n);
    RegisterDeviceName("SINEQM",s,n);
  }

References feclog(), and GetDeviceNumber().

int RegisterEquipmentModule	(	char *	expName,
		char *	eqm,
		int	ndevices,
		int()(char , char , DTYPE , DTYPE *, short)	fcn,
		void(*)(void)	ini,
		void(*)(void)	tsk,
		int	rate,
		void(*)(void)	exi
	)

Registers an equipment module with the TINE server engine.

The point of contract between the TINE server engine and server-specific code is the equpment module, which can be regarded as an interupt service routine.

Parameters:

expName	is the exported device server name to be associated with this equipment module. If this is NULL, then it is assumed that an 'exports.csv' local database file exists, which contains the export name. Otherwise it will contain a system-wide unique name (e.g. "HERA-P-BPM")
eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
ndevices	is this number of devices managed via this equipment module. If this is 0, then it is assumed that an 'exports.csv' local database file exists, which contains the number of devices.
fcn	is a reference to the equipment module, which must have the prototype shown. Namely, it is an interrupt service routine which will receive the device name, device property, the output data set, the input data set, and the data access flags as parameters.
ini	is a reference to an initialization routine which should be called prior to enabling the equipment module. It does not take arguments.
tsk	is a reference to a background task which will be called at regular intervals, and is frequently used for hardware IO, etc. Where multi-threaded servers are specified, or VxWorks tasks are available these tasks exists as separate threads, or tasks. In other cases, they are managed by the TINE server engine scheduler.
rate	is the rate in milliseconds used to schedule the background task supplied by the 'tsk' parameter.
exi	is a reference to an exit routine which should be called prior to shutting down the equipment module. It does not take arguments, and applies of course to graceful exits of the server.

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

Example:

#define NUM_MOTORS 100

// register an equipment module "MSTEQM" on this FEC which will export itself with the server name "MotorSteering"
RegisterEquipmentModule("MotorSteering","MSTEQM",NUM_MOTORS,msteqm,msteqm_ini,msteqm_bkg,MSTEQM_RATE,msteqm_exi);

// register the context for equipment module "MSTEQM" as "BEAMLINE1"
SetExportedContext("MSTEQM","BEAMLINE1");

// so the equipment module on this FEC will be seen as server "MotorSteering" in context "BEAMLINE1"

// register an equipment module "IOEQM" on this FEC which will consult the local configuration files (exports.csv or fec.xml)
// to find the designated exported server name (and the number of device instances)
RegisterEquipmentModule(NULL,"IOEQM",0,msteqm,msteqm_ini,msteqm_bkg,MSTEQM_RATE,msteqm_exi);

// register the context for equipment module "IOEQM" as "HARDWARE"
SetExportedContext("IOEQM","HARDWARE");

// etc.

int RegisterEquipmentModuleEx	(	char *	expName,
		char *	eqmName,
		int	numdevices,
		int()(char , char , DTYPE , DTYPE , short, void )	fcn,
		void()(void )	ini,
		void()(void )	tsk,
		int	rate,
		void()(void )	exi,
		void *	reference
	)

Registers an equipment module with the TINE server engine (extended call)

The point of contract between the TINE server engine and server-specific code is the equpment module, which can be regarded as an interupt service routine. This extended call allows a reference to be passed, which in turn will be used in all associated dispatch routines.

Parameters:

expName	is the exported device server name to be associated with this equipment module. If this is NULL, then it is assumed that an 'exports.csv' local database file exists, which contains the export name. Otherwise it will contain a system-wide unique name (e.g. "HERA-P-BPM")
eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
ndevices	is this number of devices managed via this equipment module. If this is 0, then it is assumed that an 'exports.csv' local database file exists, which contains the number of devices.
fcn	is a reference to the equipment module, which must have the prototype shown. Namely, it is an interrupt service routine which will receive the device name, device property, the output data set, the input data set, and the data access flags as parameters, as well as the original reference pointer.
ini	is a reference to an initialization routine which should be called prior to enabling the equipment module. When it is called, it passes the original reference pointer.
tsk	is a reference to a background task which will be called at regular intervals, and is frequently used for hardware IO, etc. When it is called, it passes the original reference pointer. Where multi-threaded servers are specified, or VxWorks tasks are available these tasks exists as separate threads, or tasks. In other cases, they are managed by the TINE server engine scheduler.
rate	is the rate in milliseconds used to schedule the background task supplied by the 'tsk' parameter.
exi	is a reference to an exit routine which should be called prior to shutting down the equipment module. When it is called, it passes the original reference pointer, and applies of course to graceful exits of the server.
reference	is a reference pointer which will be returned in all dispatch routines, and thus can be used as a means for de-referencing the equipment module container.

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

Example:

#define NUM_MOTORS 100


int eqm_dispatch(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access,void *ref)
{
  MyDevSrv *instance = (MyDevSrv *)ref;
  if (instance == NULL) return code_failure;
  // call the appopriate instance method
  return instance->eqm(devName,devProperty,dout,din,access);
}


// assume that 'this' refers to an instance of the device server module contruct MyDevSrv:
// the dispatch routine eqm_dispatch must have the prototype shown above
// pass NULL for the module's init and exit routines and let the contructor/destructor of MyDevSrv handle this 
// register an equipment module "MSTEQM" on this FEC which will export itself with the server name "MotorSteering"
RegisterEquipmentModuleEx("MotorSteering","MSTEQM",NUM_MOTORS,eqm_dispatch,NULL,msteqm_bkg,MSTEQM_RATE,NULL,(void *)this);

// etc.

int RegisterFecInformation	(	char *	name,
		char *	sub,
		char *	cntxt,
		char *	dsc,
		char *	loc,
		char *	hdw,
		char *	resp,
		UINT16	poff
	)

Assigns a FEC Name and descriptive information to the server process.

Servers must be assigned to a Front End Computer (FEC), which for many operating systems corresponds to a process running on the computer rather than the computer itself (meaning there can in some cases be more than one servers with different 'FEC' names running on the same computer. There can be several device servers attached to the same FEC (i.e. sharing the same address space), so the FEC name is a distinct quantity from the device server name (see RegisterExport()), and this name must also be system-wide unique. The call RegisterFecInformation() supercedes RegisterFecNameEx() and RegisterFecName() and differs from them in that it accepts 'Context' and 'SubSystem' as parameters, both of which will be applied to all device servers attaching to the same FEC name.

The FEC name can also be (and frequently is) registered via the presence of an 'fecid.csv' startup database file.

Parameters:

name	is the FEC name indentifying the Front End Computer and to which all registered equipment modules are bound.
sub	is the subsystem to which attached device servers belong. Note that the subsystem (unlike context) is itself not part of the name space, although the name space can be queried for device servers belonging to a subsystem. System. This information is now deduced automatically from the library build.
cntxt	is a 32-character string giving the context of all registered equipment modules. (earlier versions of TINE truncated at 16 characters).
dsc	is a 64-character desciption of the FECs server duties. A 'subsystem' can be associated with ALL equipment modules found on the FEC by prefixing the description with a subsystem tag of the form "[<tag>]". This information will be parsed by the Equipment name server and used for sub-system specific queries. For example, the associate the FEC "HEPHF" with the subsystem "RF", the description field might be "[RF]Hera Proton HF Control".
loc	is a 32-character string giving the phyical location of the FEC.
hwd	is a 32-character brief description of the IO hardware found on the FEC.
resp	is a 32-character string listing the developer(s) responsible for the FEC. Note: The Equipment Name Server will allow the removal of FECs and associated equipment modules to the user(s) specified here.
poff	is the 'Port Offset' to be applied to the FEC. This parameter plays an important role where more that one FEC is to run on a machine running an operating system using virtual memory. In such cases 'Front End Computer' is a misnomer, since "FEC" really refers to a process running on the computer to which one or more equipment modules are bound. For operating systems where all processes run in the same address space (such as VxWorks, MS-DOS, Win16, NIOS) there is in fact only one such processes managing all requistered equipment modules. For systems using virtual memory (such as Linux, Solaris, HP-UX, Win32, etc.), you can have many such processes running independently of one another. Since each such process must listen on a unique set of server ports, you must see to it that all such FEC processes are registered with a unique 'Port Offset'.

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

Note:: FEC Names can also be registered by including the startup file 'fecid.csv'. In the file, most of the input parameters appear as (optional) column entries. It is frequently preferable to work with startup configuation files, since it is frequently desireable to avoid hard-coding names and description parameters.

See also:: RegisterFecName(), RegisterFecNameEx().

Example:

char thisFec[FEC_NAME_SIZE+4], thisContext[CONTEXT_NAME_SIZE+4], thisServer[EXPORT_NAME_SIZE+4];
char thisDescription[FEC_DESC_SIZE], thisHost[32], thisUser[32];

void makeFecName(char *myContext,char *myServer)
{
  char *c, ctx[16],srv[16];
  int i;
  ctx[0] = toupper(myContext[0]); // 'P'
  ctx[1] = tolower(myContext[1]); // 'e'
  c = myServer;
  memset(srv,0,16);
  srv[0] = toupper(*c++);
  for (i=1; i<16 && *c != 0; i++)
  {
    srv[i] = tolower(*c++);
    if (srv[i] == '_') srv[i] = toupper(*c++);
  }
  sprintf(thisFec, "Rpt%.2s%.7s.%d",ctx,srv,rpPortOffset);
}

int startup(void)
{
  char myContext[CONTEXT_NAME_SIZE+4],myServer[EXPORT_NAME_SIZE+4];
  makeFecName(myContext,myServer);

  if ((ptr=getenv("HOSTNAME")) == NULL && (ptr=getenv("COMPUTERNAME")) == NULL) ptr = "local.host";
  strncpy(thisHost,ptr,32);
  sprintf(thisDescription,"/%s/%s repeater",tgtContext,tgtServer);
  if ((ptr=getenv("USER")) == NULL && (ptr=getenv("USERNAME")) == NULL) ptr = "admin";
  strncpy(thisUser,ptr,16); 
  thisUser[16] = 0;

  if ((cc=RegisterFecInformation(thisFec,"RPT",thisContext,thisDescription,thisHost,"none",thisUser,(UINT16)rpPortOffset)) != 0)
  {
    feclog("could not register repeater FEC name : %s",cc2str(cc));
  }
  // etc., etc.
  // ....
}

References feclog().

Referenced by RegisterFecNameEx().

int RegisterFecName	(	char *	name,
		char *	desc,
		char *	os,
		char *	loc,
		char *	hdw,
		char *	resp,
		UINT16	poff
	)

Assigns a FEC Name to the server process.

Servers must be assigned to a Front End Computer (FEC), which for many operating systems corresponds to a process running on the computer rather than the computer itself (meaning there can in some cases be more than one servers with different 'FEC' names running on the same computer. There can be several device servers attached to the same FEC (i.e. sharing the same address space), so the FEC name is a distinct quantity from the device server name (see RegisterExport()), and this name must also be system-wide unique.

The FEC name can also be (and frequently is) registered via the presence of an 'fecid.csv' startup database file.

Parameters:

name	is the FEC name indentifying the Front End Computer and to which all registered equipment modules are bound.
dsc	is a 64-character desciption of the FECs server duties. A 'subsystem' can be associated with ALL equipment modules found on the FEC by prefixing the description with a subsystem tag of the form "[<tag>]". This information will be parsed by the Equipment name server and used for sub-system specific queries. For example, the associate the FEC "HEPHF" with the subsystem "RF", the description field might be "[RF]Hera Proton HF Control".
os	is included for backward compatibility. Historicall it defined the FEC's Operating System. This information is now deduced automatically from the library build.
loc	is a 32-character string giving the phyical location of the FEC.
hwd	is a 32-character brief description of the IO hardware found on the FEC.
resp	is a 32-character string listing the developer(s) responsible for the FEC. Note: The Equipment Name Server will allow the removal of FECs and associated equipment modules to the user(s) specified here.
poff	is the 'Port Offset' to be applied to the FEC. This parameter plays an important role where more that one FEC is to run on a machine running an operating system using virtual memory. In such cases 'Front End Computer' is a misnomer, since "FEC" really refers to a process running on the computer to which one or more equipment modules are bound. For operating systems where all processes run in the same address space (such as VxWorks, MS-DOS, Win16, NIOS) there is in fact only one such processes managing all requistered equipment modules. For systems using virtual memory (such as Linux, Solaris, HP-UX, Win32, etc.), you can have many such processes running independently of one another. Since each such process must listen on a unique set of server ports, you must see to it that all such FEC processes are registered with a unique 'Port Offset'.

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

Note:: FEC Names can also be registered by including the startup file 'fecid.csv'. In the file, most of the input parameters appear as (optional) column entries. It is frequently preferable to work with startup configuation files, since it is frequently desireable to avoid hard-coding names and description parameters.

See also:: RegisterFecNameEx(), RegisterFecInformation().

References RegisterFecNameEx().

int RegisterFecNameEx	(	char *	name,
		char *	dsc,
		char *	os,
		char *	loc,
		char *	hdw,
		char *	resp,
		UINT16	poff,
		char *	context
	)

Assigns a FEC Name to the server process. Extended call.

Servers must be assigned to a Front End Computer (FEC), which for many operating systems corresponds to a process running on the computer rather than the computer itself (meaning there can in some cases be more than one servers with different 'FEC' names running on the same computer. There can be several device servers attached to the same FEC (i.e. sharing the same address space), so the FEC name is a distinct quantity from the device server name (see RegisterExport()), and this name must also be system-wide unique. The extended call RegisterFecNameEx() differs from RegisterFecName() in that it accepts the server 'Context' as an additional parameter. The context will be applied to all device servers attaching to the same FEC name.

The FEC name can also be (and frequently is) registered via the presence of an 'fecid.csv' startup database file.

Parameters:

name	is the FEC name indentifying the Front End Computer and to which all registered equipment modules are bound.
dsc	is a 64-character desciption of the FECs server duties. A 'subsystem' can be associated with ALL equipment modules found on the FEC by prefixing the description with a subsystem tag of the form "[<tag>]". This information will be parsed by the Equipment name server and used for sub-system specific queries. For example, the associate the FEC "HEPHF" with the subsystem "RF", the description field might be "[RF]Hera Proton HF Control".
os	is included for backward compatibility. Historicall it defined the FEC's Operating System. This information is now deduced automatically from the library build.
loc	is a 32-character string giving the phyical location of the FEC.
hwd	is a 32-character brief description of the IO hardware found on the FEC.
resp	is a 32-character string listing the developer(s) responsible for the FEC. Note: The Equipment Name Server will allow the removal of FECs and associated equipment modules to the user(s) specified here.
poff	is the 'Port Offset' to be applied to the FEC. This parameter plays an important role where more that one FEC is to run on a machine running an operating system using virtual memory. In such cases 'Front End Computer' is a misnomer, since "FEC" really refers to a process running on the computer to which one or more equipment modules are bound. For operating systems where all processes run in the same address space (such as VxWorks, MS-DOS, Win16, NIOS) there is in fact only one such processes managing all requistered equipment modules. For systems using virtual memory (such as Linux, Solaris, HP-UX, Win32, etc.), you can have many such processes running independently of one another. Since each such process must listen on a unique set of server ports, you must see to it that all such FEC processes are registered with a unique 'Port Offset'.
context	is a 32-character string giving the context of all registered equipment modules. (earlier versions of TINE truncated at 16 characters).

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

Note:: FEC Names can also be registered by including the startup file 'fecid.csv'. In the file, most of the input parameters appear as (optional) column entries. It is frequently preferable to work with startup configuation files, since it is frequently desireable to avoid hard-coding names and description parameters.

See also:: RegisterFecName(), RegisterFecInformation().

References RegisterFecInformation().

Referenced by RegisterFecName().

int RegisterMultiChannelGroupDevice	(	char *	eqm,
		char *	grpname,
		char *	devname,
		int	grpindex,
		int	grpsize
	)

Assigns a device name to the specified multi-channel group device.

In a device-oriented model, one can still make use of multi-channel array efficiency by registering a 'group' device which knows its device members and group size. Individual devices can then be designated as multi-channel array 'participants' such that any persistent client-side links to group members results in a delivery of the entire group to the client and an associated 'collapse' in the number of associated single-element contracts to a 'group' contract.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
grpname	is device group name
devname	is device name to be assigned to a group
grpindex	is the array index of the device member within the group
grpsize	is the array length of the group

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

Example:

  // assign SineGen5 -> 9 to device group "SineGroup"
  RegisterMultiChannelGroupDevice("SINEQM","SineGroup","SineGen5",0,5);
  RegisterMultiChannelGroupDevice("SINEQM","SineGroup","SineGen6",1,5);
  RegisterMultiChannelGroupDevice("SINEQM","SineGroup","SineGen7",2,5);
  RegisterMultiChannelGroupDevice("SINEQM","SineGroup","SineGen8",3,5);
  RegisterMultiChannelGroupDevice("SINEQM","SineGroup","SineGen9",4,5);

References GetDeviceNumberEx().

int RegisterProperty	(	char *	eqm,
		char *	prop,
		int	siz,
		short	fmt,
		short	acc,
		char *	dsc
	)

Assigns pertinent information for the specified property.

Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. The general behavior of the property (including descriptions) can be specified with this call. Properties can also be (and frequently are) registered via the presence of an 'exports.csv' startup database file.

Note:: Properties which are overloaded can and should be registered more than once with the appropriate characteristics supplied in the registration call. However, if input data sets require different data set specifications than the output data sets then the call to RegisterPropertyInformation() should be used. If the property identifier is important, then either RegisterPropertyInformation() or RegisterPropertyEx should be used, otherwise, the associated property identifier will be supplied by the server engine and be given via the return code.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prop	is property name in question (up to 64 characters).
siz	is expected data size (i.e. maximum allowed data size) for this property
fmt	is exected data format for this property
acc	is the data 'access' (CA_READ or CA_WRITE) accepted by the server. Note: Applying the CA_NETWORK flag to the access will enforce asynchronous NETWORK (i.g. multicast acquisition) by the client.
dsc	is the 64-character description of what the property reads or writes. returned in calls to GetPropertyId().

Returns:: The (positive) associated property identifier if successful, otherwise the negative of a TINE return code.

See also:: RegisterPropertyEx(), RegisterPropertyInformation(), GetPropertyId()

References RegisterPropertyEx().

int RegisterPropertyAlias	(	char *	eqm,
		char *	property,
		char *	alias
	)

Assigns an alias to the specified property.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
property	is property name in question (up to 64 characters).
alias	is an alias which maps to the property in question (up to 64 characters).

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

See also:: RegisterProperty(), RegisterPropertyInformation(), GetPropertyId()

int RegisterPropertyEx	(	char *	eqm,
		char *	prop,
		int	siz,
		short	fmt,
		short	acc,
		char *	dsc,
		int	prpId
	)

Assigns pertinent information for the specified property.

Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. The general behavior of the property (including descriptions) can be specified with this call. Properties can also be (and frequently are) registered via the presence of an 'exports.csv' startup database file.

Note:: Properties which are overloaded can and should be registered more than once with the appropriate characteristics supplied in the registration call. However, if input data sets require different data set specifications than the output data sets then the call to RegisterPropertyInformation() should be used.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prop	is property name in question (up to 64 characters).
siz	is expected data size (i.e. maximum allowed data size) for this property
fmt	is exected data format for this property
acc	is the data 'access' (CA_READ or CA_WRITE) accepted by the server. Note: Applying the CA_NETWORK flag to the access will enforce asynchronous NETWORK (i.g. multicast acquisition) by the client.
dsc	is the 64-character description of what the property reads or writes.
propId	is the property identifier to be associated with the property name returned in calls to GetPropertyId().

Returns:: The (positive) associated property identifier if successful, otherwise the negative of a TINE return code.

See also:: RegisterProperty(), RegisterPropertyInformation(), GetPropertyId()

Example:

References DTYPE::dArrayLength, DTYPE::dFormat, DTYPE::dTag, and RegisterPropertyInformation().

Referenced by RegisterProperty().

int RegisterPropertyInformation	(	char *	eqm,
		char *	prop,
		DTYPE *	dout,
		DTYPE *	din,
		short	acc,
		short	atype,
		UINT16	rowlength,
		char *	dsc,
		int	propId,
		char *	rdr
	)

Assigns pertinent information for the specified property.

Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. The general behavior of the property (including descriptions) can be specified with this call. Properties can also be (and frequently are) registered via the presence of an 'exports.csv' startup database file.

Note:: Properties which are overloaded can and should be registered more than once with the appropriate characteristics supplied in the registration call.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prop	is property name in question (up to 64 characters).
dout	is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the output data set to be returned by the server to the caller.
din	is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the input data set to be supplied by the caller.
acc	is the data 'access' (e.g. CA_READ or CA_WRITE) accepted by the server. This parameter can be used to coerce client-side links into using preferred link attributes. For example, by applying the CA_NETWORK flag (CA_READ\|CA_NETWORK) to the access, asynchronous NETWORK (i.g. multicast acquisition) will be enforced at the client side. Applying the CA_XREAD access flag will likewise allow exclusive READ access regarding the registered property (i.e. the same security rules applied to CA_WRITE will be in force for READ acquisitions, either permanently - no CA_READ flag, or temporarily in case of an applied access lock - if both CA_READ and CA_XREAD are applied). Applying the CA_SAVERESTORE flag will apply the internal save-and-restore logic to the registered property (restoring the last property settings upon server startup, and saving any changed property settings).
atype	is the data 'array type' (AT_SCALAR, AT_SINGLE, etc.) associated with the returned data.
rowlength	if > 0 gives the row length of the returned array data. This is most relevant for double arrays, where the number of rows is then given by the output data size divided by the row length.
dsc	is the 64-character description of what the property reads or writes.
propId	is the property identifier to be associated with the property name returned in calls to GetPropertyId().
rdr	is a redirection string, if the property is to be redirected to another server. Most properties are not redirected, and this parameter is usually NULL. If used, if will be parsed according to /<device context>/<device server>/<device name>[device property], where the 'device name' and 'device property' are optional. If 'device context' is not present, the same context will be assumed as the currently registered context. If 'device name' is not present, all devices will be redirected to the specified device server. If 'device property' is not present then the identical property name as registered will be redirected to the device server specified. If on the other hand, the device property is present in the string to be parsed, then the property registered will be redirected to the device server specified as well as to the device property specified.

Returns:: The (positive) associated property identifier if successful, otherwise the negative of a TINE return code.

See also:: RegisterProperty(), RegisterPropertyEx(), GetPropertyId()

Example:

  int i;
  float fv[NUM_DEVICES];
  DTYPE dout, din;

  // zero the contents of dout and din:
  memset(&dout,0,sizeof(DTYPE)); memset(&din,0,sizeof(DTYPE));
  // specify the default output object information: property "Sine" is a spectrum type array (i.e. a waveform)
  dout.dFormat = CF_FLOAT;
  dout.dArrayLength = 8192;
  // no input -> fix the input format at CF_NULL
  din.dFormat = CF_NULL;
  // register property "Sine":
  RegisterPropertyInformation(SINEQM_TAG,"Sine",&dout,&din,CA_READ,AT_SPECTRUM,8192,"[-1000:1000 V][0:1000 ms]Sine Curve",PRP_SINE,NULL);

  // property "Amplitude" will be a multi-channel array (length 10) and support save-and-restore
  dout.dArrayLength = 10;
  // property "Amplitude" is also an 'attribute' -> allow setting the amplitude of a single instance
  din.dFormat = CF_FLOAT;
  din.dArrayLength = 1;
  RegisterPropertyInformation(SINEQM_TAG,"Amplitude",&dout,&din,CA_READ|CA_WRITE|CA_SAVERESTORE,AT_CHANNEL,10,"[1:1000 V]Sine Curve Amplitude",PRP_AMPLITUDE,NULL);

  // property "SineInfo" is a user defined atomic structure:
  dout.dFormat = CF_STRUCT;
  strncpy(dout.dTag,"SineInfo",TAG_NAME_SIZE);
  // also allow setting various attributes atomically via this structure:
  din.dFormat = CF_STRUCT;
  strncpy(din.dTag,"SineInfo",TAG_NAME_SIZE);
  RegisterPropertyInformation(SINEQM_TAG,"SineInfo",&dout,&din,CA_READ|CA_WRITE,AT_UNKNOWN,10,"Sine Generator Information",PRP_INFO,NULL);

  // etc. ...

References DTYPE::dArrayLength, DTYPE::dFormat, DTYPE::dTag, feclog(), MaxSystemTransportSize, and RestorePropertyValues().

Referenced by RegisterPropertyEx().

short RegisterPropertyQueryFunction	(	char *	eqm,
		int()(char devName, PrpQueryStruct **prpqs)	fcn,
		int	numprops
	)

Registers an extended property query function.

If a server's properties are all registered via a call to RegisterPropertyInformation(), RegisterPropertyEx(), or RegisterProperty(), then there is no need to deal with property query functions. Some servers may wish to have a different property list for any given device, in which case a one-time query of the list of properties will not apply in general. This is infrequently the case, but when it arises, a server will need to field all property queries explicitly by registering its own property query structure. The query function must have the propotype shown in the parameter 'fcn'. That is, it should be a routine which accepts a device name as a parameter, and returns via a second paramter a reference to a list of extended property query structures (PropertyQueryStruct).

Note:: This is a legacy call and deals with lists of 'simple' property query structures as opposed to extended property query structures.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
fcn	is the extended property query function which will handle property information queries
numprops	is the number of properties which are registered.

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

See also:: RegisterXPropertyQueryFunction()

Example:

int myPropertyQueryFunction(char *devName, PrpQueryStruct **pqs)
{
  int i, n, nr;
  PrpQueryStruct *p = PrpQueryStruct *)tmpWorkArea;

  n  = GetNumberOfProperties(devName);
  nr = GetDeviceNumber("DCSEQM",devName);

  for (i=0; i<n; i++)
  {
    strncpy(p[i].Redirection,myPropertyRedirectionStrings[nr][i].in,PROPERTY_REDIR_SIZE);
    strncpy(p[i].prpName,myPropertyNames[nr][i],PROPERTY_NAME_SIZE);
    strncpy(p[i].prpDescription,myPropertyDescriptions[nr][i],PROPERTY_DESC_SIZE);
    strncpy(p[i].prpTag,myPropertyFormatTags[nr][i].out,TAG_NAME_SIZE);
    strncpy(p[i].prpTagIn,myPropertyFormatTags[nr][i].in,TAG_NAME_SIZE);
    p[i].prpFormat = myPropertyFormats[nr][i];
    p[i].prpSize = myPropertySizes[nr][i];
    p[i].prpFormatIn = myPropertyInputFormats[nr][i];
    p[i].prpSizeIn = myPropertyInputSizes[nr][i];
    strncpy(p[i].prpUnits,myPropertyUnits[nr][i],UNITS_SIZE);
    strncpy(p[i].rngUnits,myPropertyRangeUnits[nr][i],UNITS_SIZE);
    p[i].prpMinValue = myPropertyLimits[nr][i].min;
    p[i].prpMaxValue = myPropertyLimits[nr][i].max;
    p[i].rngMinValue = myPropertyRanges[nr][i].min;
    p[i].rngMaxValue = myPropertyRanges[nr][i].max;
    p[i].prpAccess = myPropertyAccess[nr][i];
    p[i].prpArrayType = myPropertyArrayType[nr][i];;
    p[i].prpHistoryDepthLong = myPropertyHistoryDepth[nr][i].longDepth;
    p[i].prpHistoryDepthShort = myPropertyHistoryDepth[nr][i].shortDepth;
  }
  *pqs = p;
  return n;
}

int MyInit(void)
{
  int cc;
  ...

  if ((cc=RegisterPropertyQueryFunction("DCSEQM",myPropertyQueryFunction,512)) != 0)
  {
    sprintf(s,"RegisterPropertyQueryFunction : %s",erlst[cc]);
    feclog(s);
  }
  
  ...

  return cc;
}

int RegisterPropertySignalFunction	(	const char *	eqm,
		const char *	prp,
		PRPSIG	fcn,
		int	mask,
		void *	ref
	)

Registers a property signal function.

If a property is accessed by remote callers, it will be represented within a server's contract list. The appropriate equipment module will be called, which is the extent of the transaction in most cases. The server can also optionally receive signals during the course of the transaction by attaching a signal function to the property in question. Signals will include

PS_ACCESS (is being accessed by a new caller),
PS_RETRY (is being retried),
PS_LATE (is being returned late),
PS_PENDING (is being called while last transmission still pending),
PS_CALLED (has returned from call to the equipment module dispatch routine),
PS_PROCESSED (has returned from dispatch call and has finished processing all returned information),
PS_SENT (has been sent to caller),

Note:: the access bits CA_FIRST and CA_LAST can be used with the equipment module to check the scope of the caller's transaction.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
prp	is the registered property for the signal function is to be applied.
fcn	is the property signal function of prototype: void sigfcn(int signal,int contractId,int propertyId,int currentStatus,void *reference);
mask	is a signal mask indicating which signals are of interest (use PS_ALL to receive all signals).
ref	is a caller supplied reference which will be returned when the signal function. As this is a void pointer, it can refer to any structure or function the caller wants to have returned when the signal function is called.

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

example:

// a simple struct to keep some interesting variables (used as a 'reference')
typedef struct
{
  int contractId;
  int propertyId;
} CalledProperty;
CalledProperty sineCalledProperty;


// a property signal function which doesn't do much except print any signal for the given
// contract id ...
void sinesig(int signal,int contractId,int propertyId,int currentStatus,void *reference)
{
  CalledProperty *cp = (CalledProperty *)reference;
  if (contractId == cp->contractId)
  { // can distinguish among contracts by noting which contract id called what ...
    printf("received signal %d; contract id %d, property id %d, current status %d, reference %x\n",
      signal,contractId,propertyId,currentStatus,reference);
  }
}

void PostSystemInit(void)
{
  // ...

  // register a property signal function for receiving a signal when the caller's data have been sent ...
  RegisterPropertySignalFunction("SINEQM","Sine",sinesig,PS_SENT,&sineCalledProperty);

  // ...
}


// the equipment module (we have a property signal handler fixed to property "Sine" ...
int sineqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access,void *ref)
{
  int devnr,prpid,cc;
  // ...

  devnr = GetDeviceNumber("SINEQM",devName);
  prpid = GetPropertyId("SINEQM",devProperty);

  switch (prpid)
  {
    case PRP_SINE:
        if (access&CA_WRITE) return illegal_read_write;
        if ((cc=putValuesFromFloat(dout,sinbuf[devnr],NUM_VALUES)) != 0) return cc;
        sineInfoTable[devnr].numberCalls++;
        sineCalledProperty.contractId = GetContractId("SINEQM");
        sineCalledProperty.propertyId = prpid;
        return 0;
  // ...

}

See also:: RegisterPropertyInformation(), SetContractSignalFunction()

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);
  }

}

short RegisterXPropertyQueryFunction	(	char *	eqm,
		int()(char devName, XPropertyQueryStruct **xpqs)	fcn,
		int	numprops
	)

Registers an extended property query function.

deprecated Please use RegisterPropertyQueryFunction() instead

If a server's properties are all registered via a call to RegisterPropertyInformation(), RegisterPropertyEx(), or RegisterProperty(), then there is no need to deal with property query functions. Some servers may wish to have a different property list for any given device, in which case a one-time query of the list of properties will not apply in general. This is infrequently the case, but when it arises, a server will need to field all property queries explicitly by registering its own property query structure. The query function must have the propotype shown in the parameter 'fcn'. That is, it should be a routine which accepts a device name as a parameter, and returns via a second paramter a reference to a list of extended property query structures (PropertyQueryStructEx).

Note:: This extended call deals with lists of the more modern extended property query structure as opposed to the legacy 'simple' property query structure.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
fcn	is the extended property query function which will handle property information queries
numprops	is the number of properties which are registered.

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

See also:: RegisterPropertyQueryFunction()

Example:

int myXPropertyQueryFunction(char *devName, XPropertyQueryStruct **xpqs)
{
  int i, n, nr;
  XPropertyQueryStruct *p = (XPropertyQueryStruct *)tmpWorkArea;

  n  = GetNumberOfProperties(devName);
  nr = GetDeviceNumber("DCSEQM",devName);

  for (i=0; i<n; i++)
  {
    strncpy(p[i].prpName,myPropertyNames[nr][i],32);
    strncpy(p[i].prpDescription,myPropertyDescriptions[nr][i],32);
    p[i].prpFormat = myPropertyFormats[nr][i];
    p[i].prpSize = myPropertySizes[nr][i];
    p[i].prpAccess = CA_READ;
    p[i].prpRedirection[0] = 0; // nothing is redirected
    p[i].prpTag[0] = 0;  // no property uses tagged structures
    p[i].prpTagIn[0] = 0; // no property uses tagged structures
    strncpy(p[i].prpUnits,myPropertyUnits[nr][i],16);
    p[i].prpMinValue = myPropertyMin[nr][i];
    p[i].prpMaxValue = myPropertyMax[nr][i];
    p[i].prpSizeIn = myPropertyInputSizes[nr][i];
    p[i].prpNumOverloads = 0; // properties aren't overloaded
    p[i].prpHistoryDepthShort = myPropertyShortHistory[nr][i];
    p[i].prpHistoryDepthLong = myPropertyLongHistory[nr][i];
    p[i].prpFormatIn = myPropertyInputFormats[nr][i];
    p[i].prpGraphType = GT_LIN;  // only linear plottable properties
    strncpy(p[i].prpUnits,myPropertyXUnits[nr][i],16);
    p[i].rngMinValue = myPropertyXMin[nr][i];
    p[i].rngMaxValue = myPropertyXMax[nr][i];
    p[i].numRows = 1;
    p[i].rowSize = myPropertySizes[nr][i];
    p[i].prpArrayType = myPropertyArrayTypes[nr][i]; // e.g. AT_SINGLE|AT_SPECTRUM
  }
  *xpqs = p;
  return n;
}

int MyInit(void)
{
  int cc;
  ...

  if ((cc=RegisterXPropertyQueryFunction("DCSEQM",myXPropertyQueryFunction,512)) != 0)
  {
    sprintf(s,"RegisterPropertyQueryFunction : %s",erlst[cc]);
    feclog(s);
  }
  
  ...

  return cc;
}

int RemoveEquipmentModule ( const char * eqm )

Unregisters an equipment module with the TINE server engine and frees all associated memory.

The point of contract between the TINE server engine and server-specific code is the equpment module, which can be regarded as an interupt service routine. This extended call allows a reference to be passed, which in turn will be used in all associated dispatch routines. Under (rare) circumstances it may be desired to unregister an equipment module. This routine can be used to accomplish that task.

Parameters:

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

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

See also:: RegisterEquipmentModule(), RegisterEquipmentModuleEx()

Example:

// remove the equiment module registered with the local name "CYCEQM":
RemoveEquipmentModule("CYCEQM");

int RemoveRegisteredBCastNetsList	(	NAME32 *	iplist,
		int	listsize
	)

removes those networks in the name list given from the current broadcast list.

The network broadcast list assigned to FEC is often read in via configuration file (see ipbcast.csv or fec.xml). However networks can also be removed via this API call. Items in the list given will be removed from the existing list of broadcasted network addresses.

Parameters:

iplist	is a list of network addresses to be removed from the current broadcast list. If a network address in the input is not in the current access list, nothing happens.
listsize	is the size of the input list.

Returns:: 0 or a TINE error code.

See also:: AppendRegisteredBCastNetsList()

int RemoveRegisteredNetsList	(	const char *	eqm,
		NAME32 *	iplist,
		int	listsize
	)

removes those networks in the name list given from the current network address access list.

The network access list assigned to FEC is often read in via configuration file (see ipnets.csv or fec.xml). However networks can also be removed via this API call. Items in the list given will be removed from the existing list of allowed network addresses.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
iplist	is a list of network addresses to be removed from the current network access list. If a network address in the input is not in the current access list, nothing happens.
listsize	is the size of the input list.

Returns:: 0 or a TINE error code.

See also:: AppendRegisteredNetsList()

int RemoveRegisteredUser	(	char *	eqm,
		NAME16 *	userlist,
		int	listsize
	)

removes those users in the name list given from the current users access list.

The users access list assigned to an equipment module is often read in via configuration file (see users.csv or fec.xml). However users can also be removed via this API call.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
userlist	is a list of users to be removed from the current users access list. If a user in the input is not in the current access list, nothing happens.
listsize	is the size of the input list.

Returns:: 0 or a TINE error code.

See also:: AppendRegisteredUsers()

int SealTaggedStruct	(	char *	tag,
		int	size,
		int	number
	)

Seals a tagged structure (registration finished!).

Call this routine to signal the structure registry that there are no more fields to be added to the tagged structure.

Parameters:

tag	structure tag name
size	total size of the structure in bytes
number	number of elements of this structure to allocate

Returns:: 0, un_allocated, out_of_local_memory

typedef struct
{
  float a[3];
  long  b[2];
  short c[1];
  short reserved;
  char  d[32];
} Test1Struct;

#define Test1StructSize ((sizeof(float)*3) +\
                         (sizeof(long)*2)  +\
                         (sizeof(short)*1) +\
                         (sizeof(short)*1) +\
                         32)

/* maximum structure array length you're willing to manage: */
#define MAX_TEST1 10
#define quit(i) { printf("Register struct: out of memory\n"); exit(i); }
void registerStructs(void)
{
  /* this must follow the order of the structure explicitly! */
  if (AddFieldToStruct("TEST1",OFFSETIN(Test1Struct,a),3,CF_FLOAT,"a")) quit(1);
  if (AddFieldToStruct("TEST1",OFFSETIN(Test1Struct,b),2,CF_LONG,"b")) quit(1);
  if (AddFieldToStruct("TEST1",OFFSETIN(Test1Struct,c),1,CF_SHORT,"c")) quit(1);
  if (AddFieldToStruct("TEST1",OFFSETIN(Test1Struct,reserved),1,CF_SHORT,"reserved")) quit(1);
  if (AddFieldToStruct("TEST1",OFFSETIN(Test1Struct,d),32,CF_TEXT,"d")) quit(1);
  /* terminate the structure definition like this! */
  if (SealTaggedStruct("TEST1",sizeof(Test1Struct),MAX_TEST1)) quit(1);
}

See also:: AddFieldToStruct

References feclog().

int sendNetGlobal	(	char *	keyword,
		DTYPE *	din,
		void(*)(int, int)	callback,
		int	minPeriod,
		int	maxPeriod,
		double	tolerance
	)

registers and sends the accompanying keyword and data as a network global.

The keyword supplied is appended to the globals table if not already registered and sent immediately as a netork global per multicast if multicasting is enabled and/or per broadcast if a broadcast nets table has been registered (via the inclusion of a ipbcast.csv or ipxbcast.csv file in the startup database set). Multicasts/Broadcasts will then be scheduled according the the minPeriod, maxPeriod, and tolerance specified, in which case the din data object should contain a reference to a data object which will be regularly updated by the server code. Alternatively, the call can specify '-1' as minPeriod and maxPeriod, in which case the network global will only be sent upon a call to sendNetGlobal(). If a callback function is supplied, is it called following the successful transmission of the network global.

Returns 0 upon successful globals transmission, otherwise a TINE error code.

Parameters:

keyword	is the globals KEYWORD which identifies the data set being sent.
din	is a pointer to the input data set, that is, the data set to be sent from the server If din is a NULL pointer or contains a NULL data set, sendNetGlobal() returns an error.
callback	is the address of the user-supplied callback routine to be called when data are sent from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError().
minPeriod	is the minimum period in milliseconds between scheduled multi/broadcasts
maxPeriod	is the maximum period in milliseconds between scheduled multi/broadcasts. If the data are still within tolerance at the end of this period, the data set will nonetheless be sent as a network global.
tolerance	is the allowed range between the current and previous data sets. If exceeded, the current data set is then sent as a network global.

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, feclog(), MakeDataTimeStamp(), and DUNION::vptr.

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

void SetAllowNetworkAddressResolution ( int value )

Determines whether NETWORK address resolution is allowed.

In an ENS-less (minimal) infrastructure, an initializing client can attempt to find server addresses by sending a NETWORK (multicast) probe to ascertain a server's address. In lieu of an ENS configuration, this requires a running server (configured to respond to NETWORK requests). Otherwise the servers address cannot be resolved.

Parameters:

value is the desired setting (default = FALSE)

Note:: this value can also be determined by environment TINE_NETWORKADDRESS_RESOLUTION = TRUE

See also:: GetAllowNetworkAddressResolution()

References feclog().

void SetAllowRemoteManagement ( int value )

Determines whether remote management via stock properties is possible.

The stock properties "SRVEXIT", "SRVINIT", "SRVRESET" will return 'not_allowed' unless remote managment is turned on (default OFF)

Parameters:

value is the desired setting

See also:: GetAllowedRemoteManagement()

void SetAppDate ( time_t appdate )

Sets the compilation date of the current running server process.

The server's application creation date is queriable from a TINE server. However this information needs to be passed to the server engine at initialization time via this call.

Parameters:

appdate is the creation time as a UNIX time variable.

See also:: SetAppVersion()

void SetAppVersion	(	int	major,
		int	minor,
		int	revision
	)

Sets the application version of the current running server process.

The server's application version number is queriable from a TINE server. However this information needs to be passed to the server engine at initialization time via this call.

Parameters:

major	is the major version number of the application
minor	is the minor version number of the application
revision	is the revision version number of the application

See also:: SetAppVersion()

int SetCallPropertyInSeparateThread	(	char *	eqm,
		char *	property,
		int	value
	)

Determines whether the specified property is called in a separate handler thread or not.

Some equipment module properties might take a non-negligible time to complete. In general the equipment module should try to minimize the time spent in the dispatch handler (i.e. simply copying results into the request buffer), but this is often not possible if long calculations need to be performed or hardware access is required, etc. If it is known before hand that this is the case it is advisable to specify that the property in question is called on a special dispatch handler thread (avialable only in the multi-threaded library build). Other properties to the equipment modules will not be called while such a call is underway, as it can not be known before hand if the equiment module is thread safe. However the caller will receive an 'operation busy' notification rather than a 'time out' if the callers timeout limit was exceeded.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
property	is the property which is to be called on a separate dispatch handler thread.
value	determines whether the property is called in a separate thread (TRUE) or not (FALSE).

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

See also:: RegisterPropertyInformation()

void SetClientListCapacity ( int value )

Sets the maximum number of clients a server will service.

A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number clients, then this value should be set accordingly at initialization time.

Parameters:

value is the requested client table size

Default: 100 (Or #define CLIENTLIST_CAPACITY in project.def)

See also:: GetClientListCapacity()

void SetConfigurationCoded ( int value )

Determines whether TINE configuration files will be scanned or not.

By default the TINE kernel will look for configuration files covering all ranges of server initialization as well as client initialization (such as the cshost.csv file giving a list of configured Equipment Name Servers). Some server builds might make use entirely and intentionally of API calls to establish all free configuration parameters. And in such cases it is possibly not desireable to even scan for the existence of such files (e.g. VxWorks CPUs which want to avoid querying the host parent's file system). By passing a value of TRUE this default scanning will be turned off.

Parameters:

value is the desired setting (default: FALSE);

Note:: : If set to TRUE then at least one ENS address should be set via a call to SetNameServerAddress() or FindNameServerOnNetwork().; : The default value can also be changed by building the TINE library with -DTINE_CONFIGURATION_CODED=TRUE or by editing project.def to include the line #define TINE_CONFIGURATION_CODED TRUE

See also:: GetConfigurationCoded()

void SetContractListCapacity ( int value )

Sets the maximum number of contracts a server will service.

A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number contracts, then this value should be set accordingly at initialization time.

Parameters:

value is the requested contract table size

Default: 1000 (Or #define CONTRACTLIST_CAPACITY in project.def)

See also:: GetContractListCapacity()

void SetContractSignalFunction	(	CONSIG	fcn,
		int	mask,
		void *	ref
	)

Registers a contract signal function.

If a property is accessed by remote callers, it will be represented within a server's contract list. The appropriate equipment module will be called, which is the extent of the transaction in most cases. The server can also optionally receive signals during the course of the transaction by attaching a signal function to the property in question (see RegisterPropertySignalFunction()), or by setting up a general contract signal function. A contract signal function will be called on behalf of any registered property from any registered equipment module. Signals will include

PS_ACCESS (is being accessed by a new caller),
PS_RETRY (is being retried),
PS_LATE (is being returned late),
PS_PENDING (is being called while last transmission still pending),
PS_CALLED (has returned from call to the equipment module dispatch routine),
PS_PROCESSED (has returned from dispatch call and has finished processing all returned information),
PS_SENT (has been sent to caller),

Note:: the access bits CA_FIRST and CA_LAST can be used with the equipment module to check the scope of the caller's transaction.

Parameters:

fcn	is the contract signal function of prototype: void sigfcn(const char eqm,const char dev,const char prp,int currentStatus,int signal,void reference);
mask	is a signal mask indicating which signals are of interest (use PS_ALL to receive all signals).
ref	is a caller supplied reference which will be returned when the signal function. As this is a void pointer, it can refer to any structure or function the caller wants to have returned when the signal function is called.

See also:: RegisterPropertySignalFunction()

void SetEnforceMcaAcquisition ( int value )

Forces multi-channel array handshaking if set to TRUE.

A server can absolutely enforce multi-channel array handshaking independent of the release level of the client. This has relevance as to whether persistent single-element links are allowed or not. If allowed then a 'modern' client might be able to latch on to a pre-existing single-element link established by an older client.

Parameters:

value TRUE or FALSE

Note:: An 'old' client will receive the error code 'propety_is_mca' which it will not be able to interpret in any meaningful way.

void SetEqmCompletion	(	char *	eqmName,
		char *	errStr
	)

Sets the error string to accompany the current server call.

For user-defined errors codes (equal to or above 512) the accompanying error string should be defined by calling this routine prior to returning from the equipment module call. When system error codes such as 'illegal_format' are used, a call to SetEqmCompletion() is not necessary.

Parameters:

eqmName	the local equipment module name whose completion code is to be set
errStr	is the 96-character string which is to accompany the outgoing error code.

Example:

#define my_hardware_broken 512

…

SetEqmCompletion(“My hardware is broken”);
return my_hardware_broken;

void SetExportedContext	(	char *	eqmName,
		char *	context
	)

Assigns the exported context associated with the equipment function name given.

Calling this function after the equipment module is registered will have no effect. Any argument list error will be logged but otherwise will have no effect.

Parameters:

eqmName is the equipment function name (local name) for which the exported context should be set. is the desired context

Example:

#define NUM_MOTORS 100

// register an equipment module "MSTEQM" on this FEC which will export itself with the server name "MotorSteering"
RegisterEquipmentModule("MotorSteering","MSTEQM",NUM_MOTORS,msteqm,msteqm_ini,msteqm_bkg,MSTEQM_RATE,msteqm_exi);

// register the context for equipment module "MSTEQM" as "BEAMLINE1"
SetExportedContext("MSTEQM","BEAMLINE1");

// so the equipment module on this FEC will be seen as server "MotorSteering" in context "BEAMLINE1"

// register an equipment module "IOEQM" on this FEC which will consult the local configuration files (exports.csv or fec.xml)
// to find the designated exported server name (and the number of device instances)
RegisterEquipmentModule(NULL,"IOEQM",0,msteqm,msteqm_ini,msteqm_bkg,MSTEQM_RATE,msteqm_exi);

// register the context for equipment module "IOEQM" as "HARDWARE"
SetExportedContext("IOEQM","HARDWARE");

// etc.

References feclog().

void SetExportedSubSystem	(	char *	eqmName,
		char *	subsystem
	)

Assigns the exported subsystem associated with the equipment function name given.

Calling this function after the equipment module is registered will have no effect. Any argument list error will be logged but otherwise will have no effect.

Parameters:

eqmName is the equipment function name (local name) for which the exported subsystem should be set. is the desired sub system

References feclog().

int SetFailoverMaster	(	char *	eqm,
		char *	masterName
	)

Sets the designated server as a failover master.

A server can declared itself as a failover master, which will register a 'master' server name as an additional alias for the equipment module specified. A server master will always overwrite any prior entries for the master name withing the ENS database.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
masterName	is the desired name of the server master. Ideally this is a distinct name different from the offically registered export name. A failover slave will use this same master name.

Returns:: a tine return code.

Note:: It is frequently better to make use of the "MASTER" column within the fecid.csv or the "MASTER" tag within the fec.xml database files to establish a failover master. Most often the identical server binary is simply run on different hardware, which means that hardcoding an API call such as this will require examining either the command line or local environment in order to deterimine whether the booting server is to be a master or slave.

See also:: SetFailoverSlave()

void SetFailoverPollingInterval ( int pollingInterval )

Sets the server failover interval to the value given.

If a server has declared itself as a failover slave then it monitors a designated master at the failover polling interval. The value of the polling interval can be set via this routine.

Parameters:

pollingInterval is the interval in milliseconds to check for connectivity with the targeted master (default: 1000 msec).

Returns:: a tine return code.

Note:: The 'polling' is an asynchronous link to the stock property "SRVSTARTTIME".

See also:: SetFailoverThreshold()

References feclog().

int SetFailoverSlave	(	char *	eqm,
		char *	masterName,
		char *	slaveMaster
	)

Delcares the server a failover slave and targets the designated server.

A server can declared itself as a failover slave, which will monitor the designated 'master' and only assume the role master if the monitored server no longer responds.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
masterName	is the desired name of the server master.
slaveMaster	is the targeted name of the slave monitor. This will be the officially registered name of the server designated as the master (hopefully distinct from the 'master' name).

Returns:: a tine return code.

Note:: It is frequently better to make use of the "MASTER" and "SLAVE_MASTER" columns within the fecid.csv or the "MASTER" and "SLAVE_MASTER" tags within the fec.xml database files to establish a failover master. Most often the identical server binary is simply run on different hardware, which means that hardcoding an API call such as this will require examining either the command line or local environment in order to deterimine whether the booting server is to be a master or slave. For instance, the master server exports itself officially as "BPM1" and declares a master name of "BPM". The slave server exports itself as "BPM2" and declares a master name of "BPM" and a slave master of "BPM1".

See also:: SetFailoverMaster()

void SetFailoverThreshold ( int timeoutCounts )

Sets the server failover threshold to the value given.

If a server has declared itself as a failover slave then it monitors a designated master at the failover polling interval. If consecutive errors acrue such that the failover threshold is exceeded, then a failover slave will assume the roll of master.

Parameters:

errorCounts is the number of consecutive errors which triggers a role reversal of slave to master (default: 5).

Returns:: a tine return code.

See also:: SetFailoverPollingInterval()

References feclog().

void SetGCastTableCapacity ( int value )

sets the globals multicast table capacity

This establishes the maximum size of the (server-side) globals table which is to send network globals via multicast. (Default : 50).

Parameters:

value is the desired table size.

Note:: this call must be made prior to the server-side registration for any network global in order to have any effect.

See also:: GetGCastTableCapacity(), sendNetGlobal().

void SetIgnoreCommonFiles ( int value )

turns searching for common database files in the FEC_HOME directory on or off

When set to TRUE, attempts to read an exports.csv or related equipment module files which directly reside in the FEC_HOME directory (or working directory, if not set) are blocked. Any related files within the equipment module 'local name' sub-directory will still be scanned and read.

Parameters:

value is the desired setting. (default = FALSE).

See also:: GetIgnoreCommonFiles()

void SetInitializeIdle ( int value )

When set to TRUE, all equipment modules are initialized in an 'idle' state.

If a Server is in an idle state 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. This is sometime useful during initialization, so that no activity (from for example the local history subsystem) can occur. If this flag is set to TRUE, then all equipment modules must be activated following the initialization procedure by calling SetServerIdleState(FALSE);

Parameters:

value is the value of the default idle state. Any non-zero sets the default idle state to TRUE. A zero value sets the default idle state to FALSE.

See also:: SetServerIdleState()

void SetlookupRedirectionNameStub ( int(*)(char *eqm, char *prpName, char *devName) fcn )

Sets a stub to an existing lookupRedirectionNameStub function for cases where a Property Query Function is in force and the server needs to redirect calls.

A lookupRedirectionNameStub function should return server_redirection if the property and device combination is to be redirected. It should also call the SetRPCRedirection() routine to establish the redirection string.

Parameters:

fcn	is the address of the lookupRedirectionNameStub function.

void SetMinimumAllowedPollingInterval ( int value )

Sets the minimum polling interval in milliseconds a server will allow.

A server will not honor polling rates smaller than this value. An attempt to poll a property a 1 msec for instance will be serviced at the MinPollingRate instead. If it is known that the server should support very fast polling rates, then this value should be set accordingly at initialization time.

Parameters:

value is the desired minimum polling interval (Default: 20 )

See also:: GetMinimumAllowedPollingInterval()

References feclog().

int SetNameServerAddress ( char * ens )

Sets the address of the Equipment Name Server via API call.

In lieu of accessing the file 'cshosts.csv' (whose location is determined by the environment variable TINE_HOME) a server can make this call to establish the address(es) of the Equipment Name Server (ENS). This is convenient for platforms which do not have a hard disk.

Parameters:

ens	a string containing a list of the IP addresses of the ENSes to be used, separated by commas (','), and optionally providing a port offset (separated by a colon ':').

Example (sets two ENS addresses, the second with port offset = 2):

SetNameServerAddress("131.169.120.141,131.169.120.146:2");

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

int SetPropertyBuffer	(	char *	eqmName,
		char *	prpName,
		BYTE *	buffer
	)

Assigns a fixed buffer to handle output data for the given property.

Generally an equipment module's dispatch handler is called with a reference to an allocated buffer into which the property's output is written. In some circumstances (e.g. large video frames) it is prudent to instruct the dispatch handler to make use of a pre-assigned buffer area (which is likely already filled with data) and to forgo any double buffering and memory copying that might otherwise occur. This is accomplished with this call.

Parameters:

eqm	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.
buffer	is the address of the buffer to assign to the property.

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

See also:: GetPropertyBuffer()

void SetRedirectionParameters	(	char *	eqmName,
		char *	rdrCnt,
		char *	rdrSrv,
		char *	rdrDev,
		char *	rdrPrp
	)

Sets the redirection string to accompany the current server call.

This routine can be used when Property Query Functions are in play. In such cases the equipment module is responsible for deciding if a call should be redirected to another server or not. If so, the server can call this routine to set the redirection information.

Parameters:

eqmName	the local equipment module name whose redirection parameters should be set
rdrCon	is the device context to which the call should be redirected
rdrSrv	is the device server to which the call should be redirected
rdrPrp	is the device property to which the call should be redirected. (Note that property length is restricted to 32 characters for redirected calls).
rdrDev	is the device name to which the call should be redirected (Note that device length is restricted to 32 characters for redirected calls).

void SetRejectOverloadedMetaProperties ( int value )

Enables/Disables overloaded meta properties.

Meta-properties such as .HIST or .NAM can be 'overloaded' by registering the appropriately named property. This will prevent the systematically available meta-property from being called. This is by default the case (if a property ABC.HIST is itself registered it will be called instead of the TINE local history). Explicitly calling SetRejectOverloadedMetaProperties(TRUE) will disable this feature.

Parameters:

value if non-zero will reject any meta-property overloads. (default: FALSE)

See also:: GetRejectOverloadedMetaProperties()

void SetRetardSingleContractRemoval ( int value )

sets the retard contract removal state

When all clients disappear from a contract the contract is then scheduled for removal at the server. This can either happen 'immediately' or be 'retarded' for a duration of 1 second. Typically a synchronous READ or WRITE command establishes a transient contract which if allowed to persist for this extra second can handle 'RETRY' requests by returning the results of the contract. However this strategy also occupies a slot in the servers contract table until the contract is officially removed, when can effectively lock up the contract table if a large number of synchronous requests are issued (clients will receive a 'resources_exhausted' return code in such cases. If a server can tolerate idempotent requests (the same request twice, so to speak) then it might be advisable to turn this feature off.

Parameters:

value is the desired setting. (default = TRUE).

See also:: GetRetardSingleContractRemoval()

int SetScanForNetsFiles ( const char * eqm )

Instructs the initialization process to look for device and property specific 'ipnets' files.

Normally this routine is not necessary. However for some systems such as VxWorks, where directory scanning only works in conjunction with NFS mounts it is then useful to explicitly intruct the initialization process to look for device and property specific ACL files (such as 'device1-ipnets.csv', etc.).

Returns:: 0 upon success

See also:: SetScanForNetsFiles()

int SetScanForUsersFiles ( const char * eqm )

Instructs the initialization process to look for device and property specific 'users' files.

Normally this routine is not necessary. However for some systems such as VxWorks, where directory scanning only works in conjunction with NFS mounts it is then useful to explicitly intruct the initialization process to look for device and property specific ACL files (such as 'device1-users.csv', etc.).

Returns:: 0 upon success

See also:: SetScanForNetsFiles()

void SetSchedulerInterval ( int value )

Sets the system scheduler interval.

The TINE kernel will call the scheduler regularly in order to service the current contract list. Under some circumstances it may be wished to control this interval. For instance, if it is known a priori that a server will need to respond to heavy synchronous polling while at the same time maintaining a lengthy contract list, it is desireable to limit the number of passes through the scheduler per second (as this will traverse the contract list with each pass). Thus setting the scheduler interval to some reasonable number (e.g. 50 or 100 milliseconds) might significantly reduce the CPU load on the server. Note however, that this will impose a latency on all synchronous requests! If the value for the schedular interval is set to 0 (the default value) or less, then the scheduler will be called at often as necessary, usually at the system polling interval (as determined by the most eager contract) and/or following a client request.

Parameters:

value is the desired scheduler interval in milliseconds. (default = 0).

See also:: GetSchedulerInterval()

int SetSizeDeviceCapacity	(	char *	eqm,
		int	size
	)

Sets (increases) the maximum size of the device table and associated tables.

Servers spcecify the maximum device capacity with the equipment module registration, either through exports.csv, fec.xml or a call to RegisterEquipmentModule(). In some dynamic situations, a server might note the available capacity is too small and can augment it via this API call.

Parameters:

eqm	is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM".
size	is the maximum number (capacity) of allowed devices. If the 'size' passed is smaller than the current device list capacity, nothing happens, and the call returns 'already_assigned'. If the call is made before the initial capacity has been determined (through equipment module registration), the call returnes 'not_initialized'.

Returns:: 0 is successful or a TINE completion code

See also:: AssignNumDevices()

References feclog().

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.

void SetSystemCycleDeadband ( int value )

Sets the system cycle deadband.

A TINE client or server requires a 'cycler' to run either on separate thread (see SystemStartCycleTimer() where available) or as part of a user defined engine (running SystemCycle() in an infinite loop). The cycler will block on incoming network traffic for a duration up to the given system cycle deadband (typically 10 msec). Either a network request wakes the cycler up or the deadband timeout expires. Following this other background activity will take place (such as processing contracts, checking local histories, and alarms, etc.). The system cycle deadband can be 'pinned' with this API call.

Parameters:

value is the desired system cycle deadband (default: OS dependent, typically 10 msec)

See also:: GetSystemCycleDeadband()

References feclog().

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

References feclog().

void SetSystemSynchronizeContracts ( int value )

Establishes the setting for general contract synchronization at the server.

A server will try to schedule contracts at the regular intervals necessary to satisfy its clients' needs. If 'contract synchronization' is in effect, the server will attempt to call the relevant equipment module dispatch routines in a tight loop in order to collect and disperse information in the smallest number of data transfers (contract packing). You can control this behavior with this API call.

Parameters:

value is the desired setting for contract synchronization (default = TRUE);

See also:: GetSystemSynchronizeContracts()

UINT32 SystemGetProcessId ( void )

Returns the process id of the running application if available.

Returns:: the process id of the running application

char* SystemGetStartupCommand ( void )

Returns the command line used to start this process.

If available the command line used to start the process is returned including all command line argurments.

Returns:: the command line used to start this process

References feclog().

char* SystemGetStartupDirectory ( void )

Returns the working directory in use when this process started.

Returns:: the working directory in use when this process started

Variable Documentation

int MaxNumClients = CLIENTLIST_CAPACITY

Determines the maximum number of clients a server will service.

A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number clients, then this value should be set accordingly at initialization time.

Default: 50 (Or #define CLIENTLIST_CAPACITY in project.def)

See also:: SetClientListCapacity(), GetClientListCapacity()

int MaxNumContracts = CONTRACTLIST_CAPACITY

Determines the maximum number of contracts a server will service.

A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number contracts, then this value should be set accordingly at initialization time.

Default: 1000 (Or #define CONTRACTLIST_CAPACITY in project.def)

See also:: SetContractListCapacity(), GetContractListCapacity()

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation