#include "project.def"#include "prolog.h"#include "tinetype.h"#include "errors.h"#include "almlib.h"#include "threader.h"Data Structures | |
| struct | ClnInfoStruct |
| Client Information Structure used in GetCallerInformation. More... | |
Typedefs | |
| typedef struct ClnInfoStruct | ClnInfo |
| Client Information Structure used in GetCallerInformation. | |
Functions | |
| TINE_EXPORT int | FindServerOnNetwork (char *context, char *eqmName, char *exportName, FecDataStruct *fec, ExpDataStruct *srv) |
| Issues a multicast (or broadcast) to which configured TINE central servers respond. | |
| TINE_EXPORT int | GetAllowBackgroundTaskReentrancy (void) |
| Returns whether equipment module background tasks may be re-entered (boolean). | |
| TINE_EXPORT int | GetBackgroundThreadPriority (void) |
| Returns the priority of the registered background threads. | |
| TINE_EXPORT GrpTblEntry * | GetCallbackGroup (size_t id) |
| Returns a reference to the callback Group Table Entry associated with the identifier supplied. | |
| TINE_EXPORT int | GetCallerInformation (char *eqm, ClnInfo *clnInfoList, int *num) |
| Returns the user name, network address and other information of all callers interested in the current contract. | |
| TINE_EXPORT int | GetClientThreadPriority (void) |
| Returns the priority of the client cycle thread as well as other associated client-side threads. | |
| TINE_EXPORT int | GetConnectionTable (ConTblInfo *tbl, int *tblSize) |
| Gets the current connection table. | |
| TINE_EXPORT int | GetDefaultTransportMode (void) |
| Gets the default TINE transport mode used in client-side links. | |
| TINE_EXPORT GrpMember * | GetGroupMemberList (GrpTblEntry *grp) |
| Returns a linked list of the group members for the callback group supplied. | |
| TINE_EXPORT int | GetRespondToServiceRequests (void) |
| Returns whether a server can respond to multicast queries for its address. | |
| TINE_EXPORT int | GetRunServerCycleInSeparateThread (void) |
| Returns whether the server cycle is run in its own thread (boolean). | |
| TINE_EXPORT int | GetRunTransportInSeparateThread (void) |
| Returns whether the (tcp) transport is run in its own thread (boolean). | |
| TINE_EXPORT int | GetServerThreadPriority (void) |
| Returns the priority of the server cycle thread as well as other associated server-side threads. | |
| TINE_EXPORT int | GetServerTransportCeiling (void) |
| Gets the server-side transport ceiling (in bytes) which gives the maximum transport size for supported by calls to a multi-threaded server. | |
| TINE_EXPORT int | GetStreamTransportRetryLimit (void) |
| Returns the stream transport retry limit. | |
| TINE_EXPORT int | GetSystemStampDelay (void) |
| Returns the registered system cycle delay. | |
| TINE_EXPORT int | GetSystemStampOffset (void) |
| Returns the registered system cycle offset. | |
| TINE_EXPORT int | GetSystemSubscriptionRenewalLength (void) |
| Gets the current contract subscription renewal length. | |
| TINE_EXPORT int | GetUseMultiThreadedBackgroundTasks (void) |
| Returns whether equipment module background tasks are to run in separate threads (boolean). | |
| TINE_EXPORT int | GetUseMultiThreadedEquipmentFunctions (void) |
| Returns whether an equipment module equipment function can run in a separate threads (boolean). | |
| TINE_EXPORT int | GetUseMultiThreadedStockFunctions (void) |
| Returns whether stock propery calls can run in a separate threads (boolean). | |
| TINE_EXPORT int | LockEquipmentModules (void) |
| Locks all equipment modules. | |
| TINE_EXPORT int | microsleep (int usecs) |
| sleep for given number of micro-seconds | |
| TINE_EXPORT int | RegisterCycleTriggerFunction (CYCBFCNP fcn, char *eqm, char *prpLst, void *reference) |
| Registers a cycle trigger callback dispatch function. | |
| TINE_EXPORT int | RegisterStateChangeCallback (SCCBFCNP fcn, const char *eqm, const char *stateKey, void *reference) |
| Registers a state change callback dispatch function. | |
| TINE_EXPORT void | SetAllowBackgroundTaskReentrancy (int value) |
| Determines whether equipment module background tasks may be re-entered (boolean). | |
| TINE_EXPORT int | SetBackgroundThreadPriority (int priority) |
| Determines the priority of any registered background threads. | |
| TINE_EXPORT int | SetClientThreadPriority (int priority) |
| Determines the priority of the client cycle thread as well as other associated client-side threads. | |
| TINE_EXPORT void | SetDefaultTransportMode (int value) |
| Sets the default TINE transport mode used in client-side links. | |
| TINE_EXPORT int | SetKernelPriority (int priority) |
| Determines the priority of TINE kernel threads. | |
| TINE_EXPORT void | SetPostSystemInitFunction (SYSTSKP fcn) |
| Sets a user-specific initialization routine to be executed following server initialization. | |
| TINE_EXPORT void | SetPreSystemInitFunction (SYSTSKP fcn) |
| Sets a user-specific initialization routine to be executed prior to server initialization. | |
| TINE_EXPORT void | SetRespondToServiceRequests (int value) |
| Establishes whether a server can respond to multicast queries for its address. | |
| TINE_EXPORT void | SetRunServerCycleInSeparateThread (int value) |
| Determines whether the server cycle is run in its own thread (boolean). | |
| TINE_EXPORT void | SetRunTransportInSeparateThread (int value) |
| Determines whether the (tcp) transport is run in its own thread (boolean). | |
| TINE_EXPORT int | SetServerThreadPriority (int priority) |
| Determines the priority of the server cycle thread as well as other associated server-side threads. | |
| TINE_EXPORT void | SetServerTransportCeiling (int value) |
| Sets the server-side transport ceiling (in bytes) which gives the maximum transport size for supported by calls to a multi-threaded server. | |
| TINE_EXPORT void | SetStreamTransportRetryLimit (int value) |
| Sets the stream transport retry limit. | |
| TINE_EXPORT int | SetSystemAlias (char *alias, char *name) |
| Sets an alias for either a registered property or registered device. | |
| TINE_EXPORT void | SetSystemCleanupFunction (SYSTSKP fcn) |
| Sets a user-specific cleanup routine to be executed as a final step during a normal cleanup phase (e.g. typing 'quit' or 'exit' at the command prompt. | |
| TINE_EXPORT void | SetSystemStampDelay (int cycleDelay) |
| Establishes the system cycle delay. | |
| TINE_EXPORT void | SetSystemStampOffset (int cycleOffset) |
| Establishes a system cycle offset. | |
| TINE_EXPORT void | SetSystemSubscriptionRenewalLength (int value) |
| Sets the contract subscription renewal length. | |
| TINE_EXPORT void | SetUseMultiThreadedBackgroundTasks (int value) |
| Determines whether equipment module background tasks are to run in separate threads (boolean). | |
| TINE_EXPORT void | SetUseMultiThreadedEquipmentFunctions (int value) |
| Determines whether an equipment module equipment function can run in a separate threads (boolean). | |
| TINE_EXPORT void | SetUseMultiThreadedStockFunctions (int value) |
| Determines whether stock propery calls can run in a separate threads (boolean). | |
| TINE_EXPORT int | UnlockEquipmentModules (void) |
| Unlocks all equipment modules. | |
| TINE_EXPORT int | UnregisterCycleTriggerFunction (CYCBFCNP fcn, void *reference) |
| Unregisters a previously registered cycle trigger callback dispatch function. | |
Variables | |
| SOCKET | glbClnSck |
| SOCKET | mcastClnSck |
| SOCKET | netSrvSck |
| int | RequireAcknowledgments |
| Determines whether acknowledgements are expected following data changes where contracts use CM_DATACHANGE mode. | |
| SOCKET | udpClnSck |
| SOCKET | udpSrvSck |
| SOCKET | udpSyncSck |
server-side (and client-side) transport definitions and prototypes.
| TINE_EXPORT 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.
| 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. |
References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), NAME16::name, NAME32::name, and DUNION::vptr.
Referenced by FindNameServerOnNetwork().
| TINE_EXPORT int GetAllowBackgroundTaskReentrancy | ( | void | ) |
Returns whether equipment module background tasks may be re-entered (boolean).
If set to TRUE, the server's background task will allow re-entrancy which might occur if the task rate instructs the background task to be called even though the previous call has not yet returned. In such cases the programmer must deal with whatever reentrancy issues there might be. This routine returns the current setting.
| TINE_EXPORT int GetBackgroundThreadPriority | ( | void | ) |
Returns the priority of the registered background threads.
| TINE_EXPORT GrpTblEntry* GetCallbackGroup | ( | size_t | id | ) |
Returns a reference to the callback Group Table Entry associated with the identifier supplied.
| id | is the group callback id (effectively the reference pointer to the callback function associated with the group. |
| TINE_EXPORT int GetCallerInformation | ( | char * | eqm, |
| ClnInfo * | clnInfoList, | ||
| int * | num | ||
| ) |
Returns the user name, network address and other information of all callers interested in the current contract.
| 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. |
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.
| TINE_EXPORT int GetClientThreadPriority | ( | void | ) |
Returns the priority of the client cycle thread as well as other associated client-side threads.
| TINE_EXPORT int GetConnectionTable | ( | ConTblInfo * | tbl, |
| int * | tblSize | ||
| ) |
Gets the current connection table.
A client's connections are managed and maintained in a connection table. You can retrieve the current connection table by using this call
| tbl | is a reference to block of memory which will hold the ConTblInfo array giving the current client connection table. |
| tblSize | (input) is a pointer to an integer value containing the maximum size (number of entries) the the tbl reference can hold. (output) will contain the size of the current connection table. |
| TINE_EXPORT int GetDefaultTransportMode | ( | void | ) |
Gets the default TINE transport mode used in client-side links.
| TINE_EXPORT GrpMember* GetGroupMemberList | ( | GrpTblEntry * | grp | ) |
Returns a linked list of the group members for the callback group supplied.
| grp | is a reference to the group table entry (GrpTblEntry *) whose member list is desired. |
References feclog(), and PutDataTimeStamp().
| TINE_EXPORT int GetRespondToServiceRequests | ( | void | ) |
Returns whether a server can respond to multicast queries for its address.
Normally a client acquires the address of a targeted server via consulting the ENS (or its local address cache). In some cases it may not be possible to guarantee the availability of a running ENS. A server capable of responding to a 'where-are-you' multicast from a client application will have enabled this feature.
| TINE_EXPORT int GetRunServerCycleInSeparateThread | ( | void | ) |
Returns whether the server cycle is run in its own thread (boolean).
If set to TRUE (default for multi-threaded builds), the server cycle will run in its own thread, separate from the client cycle. If set to FALSE, both cycles will run in a round-robin fashion, where all socket descriptor sets are 'select()ed' on to assure a prompt response. This is usually fine. However under extreme scenarios where performance is of primary concern, then leaving this setting in its default TRUE state is the best policy. This of course only applies to multi-threaded builds of the TINE library.
| TINE_EXPORT int GetRunTransportInSeparateThread | ( | void | ) |
Returns whether the (tcp) transport is run in its own thread (boolean).
If set to TRUE (default for most multi-threaded builds), connected sockets will each have their own thread where prompt data transport is assured. If set to FALSE, all transport delivery will follow the server contract access. This (setting to FALSE) is generally an okay solution and is not very resource intensive. Setting this to TRUE will cause multiple buffering of data payloads for each connected peer, which could cause memory problems on some OSes such as VxWorks or other systems whether there is more concern about memory than speed. The default setting is TRUE for windows, unix, and macos builds, and FALSE for VxWorks.
| TINE_EXPORT int GetServerThreadPriority | ( | void | ) |
Returns the priority of the server cycle thread as well as other associated server-side threads.
| TINE_EXPORT int GetServerTransportCeiling | ( | void | ) |
Gets the server-side transport ceiling (in bytes) which gives the maximum transport size for supported by calls to a multi-threaded server.
Server-side equipment function calls are double buffered, one buffer being a dynamic allocation of the caller's requested data size to be used in data comparisons, the other buffer being in the case of multi-threaded servers, another dynamic allocation of the data size to be used in dispatch calls. In order to allow transfer of 'large' data sets, this size size needs to be adjusted accordingly. If not set, the setting given by the server work area size will be used. This call returns the current setting of this value. If the call returns '-1' this indicates that there is no setting and in such cases the server work area size is used as the allowed output data size in bytes.
| TINE_EXPORT int GetStreamTransportRetryLimit | ( | void | ) |
Returns the stream transport retry limit.
When a server attempts to deliver data via a stream (TCP) connection to a client it attempts to find available TCP send buffers to deliver the data. This generally is successful upon the initial attempt but can fail due to network or buffering congestion. In such cases a delay of a clock tick and a retry will then succeed. The number of times these retries are allowed to happen are influenced by this parameter setting. The default value of '2' is generally correct, but under some conditions (one sluggish client) can impede transfer to other clients and in such cases it might be advisible to set this value to a lower value or even to '0' so as not to make all attached clients suffer.
| TINE_EXPORT int GetSystemStampDelay | ( | void | ) |
Returns the registered system cycle delay.
If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the application of the cycle tag needs to be delayed by some value, then this routine may be used to obtain the currently registered cycle delay value (in milliseconds).
| TINE_EXPORT int GetSystemStampOffset | ( | void | ) |
Returns the registered system cycle offset.
If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the cycle tag needs to be offset by some value, then this routine may be used to obtain the currently registered cycle offset.
| TINE_EXPORT int GetSystemSubscriptionRenewalLength | ( | void | ) |
Gets the current contract subscription renewal length.
Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The default value for subscription renewals can be retrieved with this call.
| TINE_EXPORT int GetUseMultiThreadedBackgroundTasks | ( | void | ) |
Returns whether equipment module background tasks are to run in separate threads (boolean).
If set to TRUE, the server's background task will run in its own thread, where a multi-threaded build of the library is in use. Note that this could result in data concurrency issues if the background task is acquiring data which is to be used by an equipment module's equipment function.
| TINE_EXPORT int GetUseMultiThreadedEquipmentFunctions | ( | void | ) |
Returns whether an equipment module equipment function can run in a separate threads (boolean).
If set to TRUE, the an equipment function will handle designated properties in a separate thread, where a multi-threaded build of the library is in use. Ordinarily an equipment function should be regarded as an interrupt service routine which should return 'promptly' after being called. All properties will be directed to the equipment function using the same thread as the server cycle, unless otherwise specified. On the other hand if a property is specifically registered to run the equipment module in a separate thread (because the action is known to require significant time to complete) then it will run in its own thread if this setting has been enabled. This will result in other calls to the equipment function receiving an 'operation busy' completion while the equipment function is handling the time-consuming call. Otherwise, concurrent calls will simply time out at the client side. To configure a property to be called in a separate thread one can either call SetCallPropertyInSeparateThread() following the property registration of supply an "MT" switch in the properties 'access' string which registering via file (either exports.csv or fec.xml).
| TINE_EXPORT int GetUseMultiThreadedStockFunctions | ( | void | ) |
Returns whether stock propery calls can run in a separate threads (boolean).
If set to TRUE, certain stock property calls will be handled in a separate thread, where a multi-threaded build of the library is in use. Ordinarily stock property calls return 'promptly' after being called, and make use of the same thread as the server cycle, unless otherwise specified. On the other hand certain stock properties which make heavy use of the local disk might require considerable time to complete, noteably calls to the local history subsystem or file retrieval calls. A calls to such property will run in its own thread if this setting has been enabled. This will result in other calls to the same stock property receiving an 'operation busy' completion while the system is handling the time-consuming call. Otherwise, concurrent calls will simply time out at the client side.
| TINE_EXPORT int LockEquipmentModules | ( | void | ) |
Locks all equipment modules.
Applying this call seizes a system mutex which will not allow the scheduler to cycle thru the equipment module dispatch routines. Consider setting the IDLE state of the module in lieu of locking and unlocking.
| TINE_EXPORT int microsleep | ( | int | usecs | ) |
sleep for given number of micro-seconds
If the input is less than 4 micro-seconds the delay is a 'hard-spin' where the OS system clock is examined in a loop without yielding the time slice. If the input is greater than 4 but less than 50 micro-seconds the delay is a 'soft-spin' where the OS system clock is examined in a loop but yielding the thread's time slice at each pass through the loop. If the input is greater than 50 micro-seconds the delay invokes a nanosleep or equivalent which yields the thread until the delay time expires. Unless a real-time clock is used (e.g. VxWorks) the granularity of this latter technique is never better than 50 micro-seconds (often more like a clock tick).
| usecs | the desired number of micro-seconds to sleep |
| TINE_EXPORT int RegisterCycleTriggerFunction | ( | CYCBFCNP | fcn, |
| char * | eqm, | ||
| char * | prpLst, | ||
| void * | reference | ||
| ) |
Registers a cycle trigger callback dispatch function.
If a CYCLER is running in a server's context, then the server will receive 'Cycle Number' events scheduled by the designated CYCLER server. The cycle number will make use of the 'System Data Stamp' to tag all data sets obtained from the server. A server can also register a trigger function dispatch routine (or routines) to be called when a 'Cycle Number' event occurs. The dispatch routines will be called prior to setting the 'System Stamp' to the new Cycle Number, which will be set following the execution of all dispatch routines. Optionally, the server can provide a property (or list of properties) to be scheduled following the dispatch execution. This will ensure that such properties will be called immediately following dispatch execution AND contain the most recent Cycle Number as the 'System Data Stamp'.
| fcn | is a reference to the cycle trigger dispatch routine to be called following the reception of a new Cycle Number. This must have the prototype: void (*fcn)(int cycleNumber,int cycleStatus,void *reference). Thus, the dispatch routine will be called with the current cycle number, the cycle status (possibly 'link_timeout' if no cycle is received within the assigned globals heartbeat (see SetGlobalsHeartbeat)), and an optional 'reference', which is a void pointer of the caller's choosing (and will be returned to the caller in the dispatch routine). |
| eqm | the local equipment module name of the desired central server (e.g. "BPMEQM") |
| prpLst | is the property or properties which are to be 'scheduled' following the execution of the dispatch routine. If more than a single property is to be scheduled, this should be a string containing a comma separated list. |
| reference | is a caller supplied void pointer which will be returned to the called in the dispatch routine. |
Example:
#define EQMTAG "TSTEQM" #define PRP_CYCLE 1 int cycleNumber = 0; int tsteqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access); void tstinit(void); void tstbkg(void); typedef void (*HDWIOFCNP)(int); void hdwIoCycle(int cycle) { /* read relevant hardware (here we just print something out) */ printf("read hardware for cycle %d\n",cycle); } void onCycleTrigger1(int cycle,int cc,void *ref) { printf("received cycle %d <%d>\n",cycle,cc); cycleNumber = cycle; } void onCycleTrigger2(int cycle,int cc,void *ref) { /* call the referenced function */ if (cc == 0) ((HDWIOFCNP)ref)(cycle); } void PreSystemInit(void) { SetSystemUseDataProtection(TRUE); SetPacketMTU(64000); RegisterFecInformation("CYCCATCH.8","TST","TEST","Cycle catcher tester","My Office","none","me",8); } void PostSystemInit(void) { /* register the equipment module: */ RegisterEquipmentModule("CycleCatcher",EQMTAG,1,tsteqm,tstinit,tstbkg,100,NULL); /* register a cycle trigger function with no scheduling and no reference */ RegisterCycleTriggerFunction(onCycleTrigger1,EQMTAG,NULL,NULL); /* register another cycle trigger function with a scheduled property and a reference to another function */ RegisterCycleTriggerFunction(onCycleTrigger2,EQMTAG,"CycleNumber",(void *)hdwIoCycle); } void tstbkg(void) { } void tstinit(void) { int cc = 0; DTYPE dout; memset(&dout,0,sizeof(DTYPE)); dout.dFormat = CF_INT32; dout.dArrayLength = 1; RegisterPropertyInformation(EQMTAG,"CycleNumber",&dout,NULL,CA_READ,AT_SCALAR,0,"current system cycle number",PRP_CYCLE,NULL); RegisterDeviceName(EQMTAG,"keyword",0); } int tsteqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access) { int devnr,prpid,cc; devnr = GetDeviceNumber(EQMTAG,devName); prpid = GetPropertyId(EQMTAG,devProperty); switch (prpid) { case PRP_CYCLE: if (access&CA_WRITE) return illegal_read_write; if ((cc=putValuesFromLong(dout,&cycleNumber,1)) != 0) return cc; return 0; default: break; } return illegal_property; }
References feclog().
| TINE_EXPORT int RegisterStateChangeCallback | ( | SCCBFCNP | fcn, |
| const char * | eqm, | ||
| const char * | stateKey, | ||
| void * | reference | ||
| ) |
Registers a state change callback dispatch function.
If STATE and GLOBALS servers are running, a server can receive state change notifications and react accordingly by calling this routine and passing a callback dispatch routine. The callback routine will be called only upon change of state. In the event of any i/o errors which prevent the server from receiving the state information, the state will be changed automatically to 'unavailable' following 5 consecutive readback errors.
| 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. |
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); } }
| TINE_EXPORT void SetAllowBackgroundTaskReentrancy | ( | int | value | ) |
Determines whether equipment module background tasks may be re-entered (boolean).
If set to TRUE, the server's background task will allow re-entrancy which might occur if the task rate instructs the background task to be called even though the previous call has not yet returned. In such cases the programmer must deal with whatever reentrancy issues there might be. The default is value is FALSE. (not reentrant).
| value | should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. FALSE is the default. |
| TINE_EXPORT int SetBackgroundThreadPriority | ( | int | priority | ) |
Determines the priority of any registered background threads.
The priority passed should be regarded as an offset to the 'normal' thread priorty for the operating system in use. That is, the TINE definition STD_THREAD_PRIORITY will be 'correct' for the target operating system (where a multi-threaded build of the library is in use). It is up to the developer to take the appropriate steps to ensure that this call in fact works as planned. For instance, using real-time priorities on Windows will require a call to the Windows function SetPriorityClass() using REALTIME_PRIORITY_CLASS prior to server initialization (otherwise the resulting thread priorities will not be as desired). Using any non-standard priorities on Unix will likely require running the application as root! VxWorks will take the initial task priority as a reference for the 'standard thread priority'.
| priority | is the desired thread priority (default STD_THREAD_PRIORITY). |
| TINE_EXPORT int SetClientThreadPriority | ( | int | priority | ) |
Determines the priority of the client cycle thread as well as other associated client-side threads.
The priority passed should be regarded as an offset to the 'normal' thread priorty for the operating system in use. That is, the TINE definition STD_THREAD_PRIORITY will be 'correct' for the target operating system (where a multi-threaded build of the library is in use). It is up to the developer to take the appropriate steps to ensure that this call in fact works as planned. For instance, using real-time priorities on Windows will require a call to the Windows function SetPriorityClass() using REALTIME_PRIORITY_CLASS prior to server initialization (otherwise the resulting thread priorities will not be as desired). Using any non-standard priorities on Unix will likely require running the application as root! VxWorks will take the initial task priority as a reference for the 'standard thread priority'.
| priority | is the desired thread priority (default STD_THREAD_PRIORITY). |
| TINE_EXPORT void SetDefaultTransportMode | ( | int | value | ) |
Sets the default TINE transport mode used in client-side links.
| value | is the desired default transport mode. This can be either 'TCP' or 'UDP' (the default). Indeed, if value does not equal 'TCP' then the default transport mode will be taken as UDP. |
| TINE_EXPORT int SetKernelPriority | ( | int | priority | ) |
Determines the priority of TINE kernel threads.
Use this routine to set the priority of all TINE kernel threads (server-side, client-side, background tasks) to the desired value. This is primarily a convenience routine and is equivalent to calling SetServerThreadPriority(), SetClientThreadPriority() and SetBackgroundThreadPriority() individually.
| priority | is the desired thread priority (default STD_THREAD_PRIORITY). |
| TINE_EXPORT void SetPostSystemInitFunction | ( | SYSTSKP | fcn | ) |
Sets a user-specific initialization routine to be executed following server initialization.
| fcn | is the function to be called following system initialization. (prototype void fcn(void)). Typically one places registration calls such as RegisterEquipmentModule(), etc. in such a routine. |
| TINE_EXPORT void SetPreSystemInitFunction | ( | SYSTSKP | fcn | ) |
Sets a user-specific initialization routine to be executed prior to server initialization.
| fcn | is the function to be called prior to system initialization. (prototype void fcn(void)). Typically one places parameter settings which differ from the default values in such a routine, so that they have an effect on the server initialization. Likewise, calls such as RegisterFecInformation() should be made in such a routine. |
| TINE_EXPORT void SetRespondToServiceRequests | ( | int | value | ) |
Establishes whether a server can respond to multicast queries for its address.
Normally a client acquires the address of a targeted server via consulting the ENS (or its local address cache). In some cases it may not be possible to guarantee the availability of a running ENS. If a server declares itself ready and capable of responding to a 'where-are-you' multicast from a client application, it should call this API routine and pass the value of 'TRUE'. In this fashion it is possible to have a client-server pair communicate with each other in an 'ENS-less' scenario (provided the client and server exist on a network which can forward the multicast probes issued by the client (the multicast group 238.1.1.2).
| value | is the desired setting (default = FALSE) |
| TINE_EXPORT void SetRunServerCycleInSeparateThread | ( | int | value | ) |
Determines whether the server cycle is run in its own thread (boolean).
If set to TRUE (default for multi-threaded builds), the server cycle will run in its own thread, separate from the client cycle. If set to FALSE, both cycles will run in a round-robin fashion, where all socket descriptor sets are 'select()ed' on to assure a prompt response. This is usually fine. However under extreme scenarios where performance is of primary concern, then leaving this setting in its default TRUE state is the best policy. This of course only applies to multi-threaded builds of the TINE library.
| value | should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. TRUE is the default. |
| TINE_EXPORT void SetRunTransportInSeparateThread | ( | int | value | ) |
Determines whether the (tcp) transport is run in its own thread (boolean).
If set to TRUE (default for most multi-threaded builds), connected sockets will each have their own thread where prompt data transport is assured. If set to FALSE, all transport delivery will follow the server contract access. This (setting to FALSE) is generally an okay solution and is not very resource intensive. Setting this to TRUE will cause multiple buffering of data payloads for each connected peer, which could cause memory problems on some OSes such as VxWorks or other systems whether there is more concern about memory than speed. The default setting is TRUE for windows, unix, and macos builds, and FALSE for VxWorks.
| value | should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. FALSE is the default. |
| TINE_EXPORT int SetServerThreadPriority | ( | int | priority | ) |
Determines the priority of the server cycle thread as well as other associated server-side threads.
The priority passed should be regarded as an offset to the 'normal' thread priorty for the operating system in use. That is, the TINE definition STD_THREAD_PRIORITY will be 'correct' for the target operating system (where a multi-threaded build of the library is in use). It is up to the developer to take the appropriate steps to ensure that this call in fact works as planned. For instance, using real-time priorities on Windows will require a call to the Windows function SetPriorityClass() using REALTIME_PRIORITY_CLASS prior to server initialization (otherwise the resulting thread priorities will not be as desired). Using any non-standard priorities on Unix will likely require running the application as root! VxWorks will take the initial task priority as a reference for the 'standard thread priority'.
| priority | is the desired thread priority (default STD_THREAD_PRIORITY). |
| TINE_EXPORT void SetServerTransportCeiling | ( | int | value | ) |
Sets the server-side transport ceiling (in bytes) which gives the maximum transport size for supported by calls to a multi-threaded server.
Server-side equipment function calls are double buffered, one buffer being a dynamic allocation of the caller's requested data size to be used in data comparisons, the other buffer being in the case of multi-threaded servers, another dynamic allocation of the data size to be used in dispatch calls. In order to allow transfer of 'large' data sets, this size size needs to be adjusted accordingly. If not set, the setting given by the server work area size will be used.
| value | is the size in bytes to be used as the transport ceiling for any property supported by the server. (default: the same value as the server work area size, i.e. 64 KBytes on most operating systems). |
References feclog(), and MaxSystemTransportSize.
| TINE_EXPORT void SetStreamTransportRetryLimit | ( | int | value | ) |
Sets the stream transport retry limit.
When a server attempts to deliver data via a stream (TCP) connection to a client it attempts to find available TCP send buffers to deliver the data. This generally is successful upon the initial attempt but can fail due to network or buffering congestion. In such cases a delay of a clock tick and a retry will then succeed. The number of times these retries are allowed to happen are influenced by this parameter setting. The default value of '2' is generally correct, but under some conditions (one sluggish client) can impede transfer to other clients and in such cases it might be advisible to set this value to a lower value or even to '0' so as not to make all attached clients suffer. This value setting can be established by making use of this call.
| TINE_EXPORT int SetSystemAlias | ( | char * | alias, |
| char * | name | ||
| ) |
Sets an alias for either a registered property or registered device.
A client can make use of an alias in place of either a registered device name or a registered property name in any call. The alias name will be replaced by its target within the contract tables. Property aliases are also returned in queries to obtain the registered property list.
| 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). |
| TINE_EXPORT void SetSystemCleanupFunction | ( | SYSTSKP | fcn | ) |
Sets a user-specific cleanup routine to be executed as a final step during a normal cleanup phase (e.g. typing 'quit' or 'exit' at the command prompt.
| fcn | is the cleanup function to be called (prototype void fcn(void)). |
| TINE_EXPORT void SetSystemStampDelay | ( | int | cycleDelay | ) |
Establishes the system cycle delay.
If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the application of the cycle tag needs to be delayed by some value, then this routine may be used to establish such a cycle delay value (in milliseconds).
| cycleDelay | is the desired cycle delay (milliseconds), which will must elapse before the incoming cycle number from the registered CYCLER is to be applied to all readback data. (default = 0). |
| TINE_EXPORT void SetSystemStampOffset | ( | int | cycleOffset | ) |
Establishes a system cycle offset.
If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the cycle tag needs to be offset by some value, then this routine may be used to establish such an offset.
| cycleOffset | is the desired cycle offset (counts) to be applied to the incoming cycle number from the registered CYCLER. (Default = 0). |
| TINE_EXPORT void SetSystemSubscriptionRenewalLength | ( | int | value | ) |
Sets the contract subscription renewal length.
Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The default value for subscription renewals can be adjusted with this call.
| value | is the desired contract renewal length. (mininum = default = 60; maximum = 32767) |
References feclog().
| TINE_EXPORT void SetUseMultiThreadedBackgroundTasks | ( | int | value | ) |
Determines whether equipment module background tasks are to run in separate threads (boolean).
If set to TRUE, the server's background task will run in its own thread, where a multi-threaded build of the library is in use. Note that this could result in data concurrency issues if the background task is acquiring data which is to be used by an equipment module's equipment function.
| value | should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. TRUE is the default. |
| TINE_EXPORT void SetUseMultiThreadedEquipmentFunctions | ( | int | value | ) |
Determines whether an equipment module equipment function can run in a separate threads (boolean).
If set to TRUE, the an equipment function will handle designated properties in a separate thread, where a multi-threaded build of the library is in use. Ordinarily an equipment function should be regarded as an interrupt service routine which should return 'promptly' after being called. All properties will be directed to the equipment function using the same thread as the server cycle, unless otherwise specified. On the other hand if a property is specifically registered to run the equipment module in a separate thread (because the action is known to require significant time to complete) then it will run in its own thread if this setting has been enabled. This will result in other calls to the equipment function receiving an 'operation busy' completion while the equipment function is handling the time-consuming call. Otherwise, concurrent calls will simply time out at the client side. To configure a property to be called in a separate thread one can either call SetCallPropertyInSeparateThread() following the property registration of supply an "MT" switch in the properties 'access' string which registering via file (either exports.csv or fec.xml).
| value | should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. FALSE is the default. |
| TINE_EXPORT void SetUseMultiThreadedStockFunctions | ( | int | value | ) |
Determines whether stock propery calls can run in a separate threads (boolean).
If set to TRUE, certain stock property calls will be handled in a separate thread, where a multi-threaded build of the library is in use. Ordinarily stock property calls return 'promptly' after being called, and make use of the same thread as the server cycle, unless otherwise specified. On the other hand certain stock properties which make heavy use of the local disk might require considerable time to complete, noteably calls to the local history subsystem or file retrieval calls. A calls to such property will run in its own thread if this setting has been enabled. This will result in other calls to the same stock property receiving an 'operation busy' completion while the system is handling the time-consuming call. Otherwise, concurrent calls will simply time out at the client side.
| value | should be non-zero (TRUE) to turn this feature on or FALSE to turn it off. TRUE is the default. |
| TINE_EXPORT int UnlockEquipmentModules | ( | void | ) |
Unlocks all equipment modules.
If the equipment modules were locked by applying a call to LockEquipmentModules() then this call frees the lock state, allowing equipment module dispatch routines and background tasks to continue. Consider setting the IDLE state of the module in lieu of locking and unlocking.
| TINE_EXPORT int UnregisterCycleTriggerFunction | ( | CYCBFCNP | fcn, |
| void * | reference | ||
| ) |
Unregisters a previously registered cycle trigger callback dispatch function.
If a cycle trigger event dispatch routine is no longer required, it can be unregistered using this routine.
| fcn | is a reference to the previously registered cycle trigger dispatch routine which is to be removed. |
| reference | is a caller supplied void pointer which will be returned to the called in the dispatch routine. |
References feclog().
| SOCKET glbClnSck |
UDP Global listening Socket
Referenced by CloseGlobalLink().
| SOCKET mcastClnSck |
UDP MCast/BCast Consumer Socket
| SOCKET netSrvSck |
UDP MCast Net Services Socket
Determines whether acknowledgements are expected following data changes where contracts use CM_DATACHANGE mode.
Under CM_TIMER link conditions the server is not directly interested as to whether the client received its data packet or not, since the client is expecting data to arrive at the polling interval and will complain if it is missing. However,when a client establishes a data link and requests CM_DATACHANGE mode, data are are only returned to the client when they have changed, or when the link heartbeat (1 minute) has expired. A server will under these conditions require an acknowledgement from the client if data do in fact change. A missing acknowledgement will cause the server to re-issue the data transfer. This default behavior will of course increase the network traffic when data are frequently changing. Under some circumstance it is undesireable to require acknowledgments and this feature can be turned off by setting this value to FALSE.
Default: TRUE
Referenced by GetSystemRequireAcknowledgments(), and SetSystemRequireAcknowledgments().
| SOCKET udpClnSck |
UDP Consumer Socket
| SOCKET udpSrvSck |
UDP Producer Socket
| SOCKET udpSyncSck |
UDP trivial link Socket
1.5.8