TINE System API routines: More...
Functions | |
| int | _SystemCycle (int chkcmd) |
| Required call for the TINE engine to function property. More... | |
| void | _SystemDelay (int msec) |
| Blocks any activity inside a TINE task or equipment modules for the specified amount of time. More... | |
| int | _SystemFireEvent (char *eqm, char *prp) |
| Schedules an event for the given property for immediate delivery to all attached clients. More... | |
| int | _SystemInit (int chkcmd) |
| Required call for the TINE server engine to function property. More... | |
| int | _SystemReset (int level) |
| Flushes all entry tables and returns all counters and semaphores to their initial state. More... | |
| int | _SystemScheduleProperty (char *eqm, char *prp) |
| Schedules the given property for immediate delivery to all attached clients. More... | |
| int | _SystemSchedulePropertyEx (char *eqm, char *prp, int scope) |
| Schedules the given property for immediate delivery to all attached clients according scope specified. More... | |
| void | _SystemStop (int exitOnFree) |
| Free all system resources and optionally exit. More... | |
| int | clslog (char *context, char *tag, char *logger, int priority, int status, char *text,...) |
| Sends a logging entry to the central logging server. More... | |
| int | datacmp (BYTE *d1, BYTE *d2, int siz, int fmt, double t) |
| int | feclog (char *text,...) |
| Puts entries into a server's FEC log file. More... | |
| int | feclogEx (int logLevel, char *text,...) |
| Puts entries into a server's FEC log file and in error.log file if certain conditions match. More... | |
| int | GetBackgroundThreadPriority (void) |
| Returns the priority of the registered background threads. More... | |
| int | GetBurstLimit (void) |
| Gets the burst limit in number of packets which are allowed to be sent consecutively. More... | |
| int | GetCatchConsoleBreak (void) |
| Returns the current setting for this feature. More... | |
| int | GetClientThreadPriority (void) |
| Returns the priority of the client cycle thread as well as other associated client-side threads. More... | |
| int | GetContractAccessRate (int id) |
| Returns the access rate (interval) associated with the given contract. More... | |
| int | GetContractId (const char *eqm) |
| Returns the last contract identifier for the equipment module specified. More... | |
| int | GetCycleDelay (void) |
| Gets the delay time in milliseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit(). More... | |
| int | GetCycleMicroDelay (void) |
| Gets the delay time in microseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit(). More... | |
| double | GetDataTimeStamp (void) |
| Returns the last established data timestamp. More... | |
| struct timeval * | GetDataTimeStampAsTimeval (void) |
| Returns the last established data timestamp as a pointer to a struct timeval. More... | |
| double | GetDataTimeStampOffset (void) |
| Returns a the current data timestamp offset as assigned by the TINE global time service. More... | |
| char * | GetDataTimeString (double ts, int useLongStringFormat) |
| Returns the TINE data timestamp as a human-readable string. More... | |
| char * | GetDataTimeStringEx (double ts, int useLongStringFormat, char *tsstr) |
| Returns the TINE data timestamp as a human-readable string. More... | |
| int | GetDieOnAddressInUse (void) |
| Returns the current setting for this feature. More... | |
| int | GetDieOnFecIsAlias (void) |
| Returns the current setting for this feature. More... | |
| int | GetDieOnSocketError (void) |
| Returns the current setting for this feature. More... | |
| char * | GetFecHome (void) |
| Gets the current setting for the fec home database repository. More... | |
| int | GetFeclogDepth (void) |
| Returns the maximum size of the server's log file in lines. More... | |
| char * | GetFecLogPath (void) |
| Gets the current setting for the fec log repository. More... | |
| int | GetFormatSizeInBytesFromDataType (DTYPE *d) |
| Gives the size of bytes according to the DTYPE fields. More... | |
| int | GetLastContractId (void) |
| Returns the last contract identifier. More... | |
| int | GetLastContractTableId (void) |
| Returns the last contract table identifier. More... | |
| int | GetPutCommandsInFeclog (void) |
| Returns the current setting for putCommandsInFeclog (which determines whether all in-coming WRITE access calls are automatically included in the server's log file) More... | |
| int | GetServerIdleState (char *eqm) |
| Gets the server's idle state. More... | |
| int | GetServerThreadPriority (void) |
| Returns the priority of the server cycle thread as well as other associated server-side threads. More... | |
| int | GetServerWaiting (void) |
| Gets the server's waiting state. More... | |
| int | GetStreamTransportRetryLimit (void) |
| Returns the stream transport retry limit. More... | |
| char * | GetSystemErrorString (short cc, char *errstr) |
| Gets the system error code in plain text. More... | |
| int | GetSystemLogging (void) |
| Returns the current system logging setting (TRUE or FALSE) More... | |
| int | GetSystemRequireAcknowledgments (void) |
| Gets the require acknowledgments flag to the value given. More... | |
| int | GetSystemSchedulePropertyLazy (void) |
| Gets the 'lazy' flag for scheduling properties. More... | |
| int | GetSystemUseDataProtection (void) |
| Gets the data protection flag to the value given. More... | |
| char * | GetSystemUserName (void) |
| Gets the current value for the application user. More... | |
| double | GetTimeStampFromString (char *timestr) |
| Returns a TINE timestamp converted from the string argument given. More... | |
| int | GetUseGlobalSynchronization (void) |
| Returns whether data timestamps are to be externally synchronized. More... | |
| int | GetUseMultiThreadedBackgroundTasks (void) |
| Returns whether equipment module background tasks are to run in separate threads (boolean). More... | |
| int | GetUseMultiThreadedEquipmentFunctions (void) |
| Returns whether an equipment module equipment function can run in a separate threads (boolean). More... | |
| int | GetUseMultiThreadedStockFunctions (void) |
| Returns whether stock propery calls can run in a separate threads (boolean). More... | |
| UINT32 | GetWorkAreaSize (void) |
| Gets the server-side work area size which is coupled to the maximum transport size for supported by a single-threaded server. More... | |
| int | IsServerRunning (void) |
| Returns TRUE (non zero) if the server kernel is fully initialized and ready. More... | |
| int | LockEquipmentModules (void) |
| Locks all equipment modules. More... | |
| double | MakeDataTimeStamp (void) |
| Returns a data timestamp according to the current system time. More... | |
| int | MakeSystemDataStamp (void) |
| Returns the current valid global system data stamp. More... | |
| int | microsleep (int usecs) |
| sleep for given number of micro-seconds More... | |
| double | PutDataTimeStamp (double toffset, time_t tsec, int tmsec) |
| Returns a data timestamp according to the input parameters given. More... | |
| double | PutDataTimeStampU (double toffset, time_t tsec, int tusec) |
| Returns a data timestamp according to the input parameters given. More... | |
| int | ResetMultiChannelProperty (char *eqm, char *prp) |
| sends (schedules) a 'reset_mca_property' signal to any listening client More... | |
| int | SetBackgroundThreadPriority (int priority) |
| Determines the priority of any registered background threads. More... | |
| int | SetBurstLimit (int npackets) |
| Sets the burst limit in number of packets which are allowed to be set consecutively. More... | |
| void | SetCatchConsoleBreak (int value) |
| Determines whether an application will catch an interrupt or break signal (such as control-C) and issue a graceful exit or not. More... | |
| int | SetClientThreadPriority (int priority) |
| Determines the priority of the client cycle thread as well as other associated client-side threads. More... | |
| int | SetCycleDelay (int msecs) |
| Sets the delay time in milliseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit(). More... | |
| int | SetCycleMicroDelay (int usecs) |
| Sets the delay time in microseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit(). More... | |
| void | SetDataTimeStamp (double ts) |
| Sets the intrinsic data timestamp to the value given. More... | |
| void | SetDieAnotherDay (int value) |
| Revokes an 'exit' due to a 'die on' condition. More... | |
| void | SetDieFunction (DIEFCNP fcn) |
| Sets a dispatch routine to call if and when the FEC process dies due to e.g. 'address in use'. More... | |
| void | SetDieOnAddressInUse (int value) |
| Determines whether a server will exit() if an 'address in use' message is delivered by the ENS upon registration. More... | |
| void | SetDieOnFecIsAlias (int value) |
| Determines whether a server will exit() if a 'FEC has an alias' message is delivered by the ENS upon registration. More... | |
| void | SetDieOnSocketError (int value) |
| Determines whether a server will exit() if there are continuous socket errors on important server sockets. More... | |
| int | SetFecHome (char *fecHomePath) |
| Sets the current fec home database repository. More... | |
| void | SetFeclogDepth (int value) |
| Determines the approximate size of the server's log file in lines. More... | |
| int | SetFecLogPath (char *path) |
| Sets the fec log repository. More... | |
| int | SetKernelPriority (int priority) |
| Determines the priority of TINE kernel threads. More... | |
| void | SetPostSystemInitFunction (SYSTSKP fcn) |
| Sets a user-specific initialization routine to be executed following server initialization. More... | |
| void | SetPreSystemInitFunction (SYSTSKP fcn) |
| Sets a user-specific initialization routine to be executed prior to server initialization. More... | |
| void | SetPutCommandsInFeclog (int value) |
| Determines whether all in-coming WRITE access calls are automatically included in the server's log file. More... | |
| void | SetServerIdleState (char *eqm, int value) |
| Sets the server's idle state to the value given. More... | |
| int | SetServerThreadPriority (int priority) |
| Determines the priority of the server cycle thread as well as other associated server-side threads. More... | |
| void | SetServerWaiting (int value) |
| Sets the server's waiting state to the value given. More... | |
| void | SetStreamTransportRetryLimit (int value) |
| Sets the stream transport retry limit. More... | |
| void | SetSystemCleanupFunction (SYSTSKP fcn) |
| Sets a user-specific cleanup routine to be executed as a final step during a normal cleanup phase (e.g. typing 'quit' or 'exit' at the command prompt. More... | |
| void | SetSystemDataStamp (int value) |
| Sets the global system data stamp with which to tag outbound data sets. More... | |
| void | SetSystemLogging (int value) |
| Sets system logging (output to fec.log) to TRUE or FALSE. More... | |
| void | SetSystemRequireAcknowledgments (int value) |
| Sets the require acknowledgments flag to the value given. More... | |
| void | SetSystemSchedulePropertyLazy (int value) |
| Sets the 'lazy' flag for scheduling properties. More... | |
| void | SetSystemUseDataProtection (int value) |
| Sets the data protection flag to the value given. More... | |
| int | SetSystemUserName (char *usr) |
| Sets the current value for the application user. More... | |
| void | SetUseGlobalSynchronization (int value) |
| Determines whether data timestamps are to be externally synchronized. More... | |
| void | SetUseMultiThreadedBackgroundTasks (int value) |
| Determines whether equipment module background tasks are to run in separate threads (boolean). More... | |
| void | SetUseMultiThreadedEquipmentFunctions (int value) |
| Determines whether an equipment module equipment function can run in a separate threads (boolean). More... | |
| void | SetUseMultiThreadedStockFunctions (int value) |
| Determines whether stock propery calls can run in a separate threads (boolean). More... | |
| UINT32 | SetWorkAreaSize (UINT32 size) |
| Sets the server-side work area size which is coupled to the maximum transport size for supported by a single-threaded server. More... | |
| int | srvlog (char *filename, char *tag, char *text,...) |
| Puts entries into a named log file. More... | |
| BYTE * | SystemVersion (void) |
| Returns the system version as a 4-byte array containg the major and minor version numbers as the first two bytes and the current revision in the next two bytes. More... | |
| int | UnlockEquipmentModules (void) |
| Unlocks all equipment modules. More... | |
Variables | |
| int | FeclogDepth = FECLOG_DEPTH |
| Determines the approximate size of the server's log file in lines. More... | |
| int | gErrorLogLevel = TINE_LOGLEVEL_WARN |
| Determines which messages are written to error.log file. More... | |
| int | gStartupDebug = 1 |
| Determines whether server initialization messages are displayed or not. More... | |
| int | nofeclog = FALSE |
| Determines whether a server is to keep a log file on the local disk. More... | |
| int | putCommandsInFeclog = INCLUDE_IN_LOGFILE |
| Determines whether all in-coming WRITE access calls are automatically included in the server's log file. More... | |
| int | useGlobalSynchronization = GLOBAL_SYNCHRONIZATION |
| Determines whether data timestamps are to be externally synchronized. More... | |
TINE System API routines:
The API routines offered here generally refer to the TINE engine and have relevance for both client-side and server-side programming. Some routines such as _SystemCycle() are required. Others such as _SystemInit() are required for server operation. Many routines are optional and offer ways of setting and getting system timestamps for instance or making entries into the server's log file.
| int _SystemCycle | ( | int | chkcmd | ) |
Required call for the TINE engine to function property.
Should be called within an infinite loop. Prior to the start of this loop, all other device server registration should occur.
Clients with asynchronous links must see to it that _SystemCycle() is called regularly (unless SystemDelay(-1) is used to block the main process).
| chkcmd | is used to signal the presence of a local command interpreter. Developers wishing to bypass the built-in command interpreter in favor of another should pass FALSE for this argument |
Alias: SystemCycle
Example:
| void _SystemDelay | ( | int | msec | ) |
Blocks any activity inside a TINE task or equipment modules for the specified amount of time.
The TINE engine will continue to run and process data which is not related to 1) the equipment module being blocked if _SystemDelay() is called inside an equipment module or 2) the background task if _SystemDelay() is called inside a backgroung task.
| msec | is the amount of time in milliseonds to suspend the calling routine. |
Alias: SystemDelay
Example
| int _SystemFireEvent | ( | char * | eqm, |
| char * | prp | ||
| ) |
Schedules an event for the given property for immediate delivery to all attached clients.
Clients can attach to a particular property and reqest event notification only by applying the CM_EVENT polling mode. When a server schedules the property by calling either this routine of _SystemScheduleProperty() then the property handler is called and the attached clients receive the property's data (if any) and an event notification. This call is fully equivalent to _SystemScheduleProperty().
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is (comma separated) list of properties which are to be scheduled. |
Alias: SystemFireEvent()
Example:
References _SystemSchedulePropertyEx().
| int _SystemInit | ( | int | chkcmd | ) |
Required call for the TINE server engine to function property.
Should be called prior to the start of the main TINE server engine. Any deviations from default system parameters should be made before any call to _SystemInit(). This might include server settings which fix the size of the local connection table entries, the maximum date transport size, etc. Note that _SystemInit() will begin be allocating space for its connection tables, so modifying these values away from their defaults will have no effect after _SystemInit() has been called. Also, if the FEC Name is given by calling RegisterFecInformation() or RegisterFecNameEx(), then this should also preceed a call to _SystemInit().
| chkcmd | is used only for UNIX servers and if TRUE will determine if the server is running in the foreground and if so, will check the stdin for console commands at the keyboard. |
Alias: SystemInit
Example:
| int _SystemReset | ( | int | level | ) |
Flushes all entry tables and returns all counters and semaphores to their initial state.
Useful under some circumstances, for instance following program suspension or interrupt due to CNTL-C, etc.
| level | is reserved for future use. |
Alias: SystemReset
Example:
| int _SystemScheduleProperty | ( | char * | eqm, |
| char * | prp | ||
| ) |
Schedules the given property for immediate delivery to all attached clients.
When clients are attached to a particular property, they have specified a polling rate, which defines the maximum latency for receiving updates at the client side. This is usually fine. However, if a server knows that important data have changed and which properties depend on these data, it can signal the scheduler to call the given properties immediately and send the data to all attached callers, regardless of their registered polling rates. In this way, a server can signal an event to its attached clients.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is (comma separated) list of properties which are to be scheduled. If the supplied property should only be scheduled if the associated contracts call the property with a specific device then the device can also be supplied in the property string as in "property<device>". Note: the device specification applies only to 'remote' contracts (not to local history or alarm system contracts). |
Alias: SystemScheduleProperty()
Example:
References _SystemSchedulePropertyEx().
| int _SystemSchedulePropertyEx | ( | char * | eqm, |
| char * | prp, | ||
| int | scope | ||
| ) |
Schedules the given property for immediate delivery to all attached clients according scope specified.
When clients are attached to a particular property, they have specified a polling rate, which defines the maximum latency for receiving updates at the client side. This is usually fine. However, if a server knows that important data have changed and which properties depend on these data, it can signal the scheduler to call the given properties immediately and send the data to all attached callers, regardless of their registered polling rates. In this way, a server can signal an event to its attached clients. In this extended call, the caller can specify the 'scope' of the call : CA_NETWORK (all listening clients), CA_HIST (the local history subsystem) or CA_ALARM (the local alarm server).
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is (comma separated) list of properties which are to be scheduled. If the supplied property should only be scheduled if the associated contracts call the property with a specific device then the device can also be supplied in the property string as in "property<device>". |
| scope | is any of CA_NETWORK, CA_HIST, or CA_ALARM ORed together. Note: a call to _SystemScheduleProperty() is equivalent to supplying all bits. |
Alias: SystemSchedulePropertyEx()
Example:
Referenced by _SystemFireEvent(), and _SystemScheduleProperty().
| void _SystemStop | ( | int | exitOnFree | ) |
Free all system resources and optionally exit.
Calling this routine will close down all client-side connections, call any registered equipment module exit routines, stop all registered background tasks, free up all system memory, close all system sockets and pipes, and call exit(0) if the 'exitOnFree' parameter is TRUE.
| exitOnFree | if TRUE will call exit(0) after freeing resources. Otherwise the process will remain active (for an additional startup sequence, for example). |
| int clslog | ( | char * | context, |
| char * | tag, | ||
| char * | logger, | ||
| int | priority, | ||
| int | status, | ||
| char * | text, | ||
| ... | |||
| ) |
Sends a logging entry to the central logging server.
An application (be it client or server) can send an entry to the central logger at any time. As this will require WRITE access, the entry will only be accepted if the caller has WRITE privileges.
| context | is the logging context. If NULL or empty, the currently defined TINE context will be used. Logging entries can be browsed or sorted according to context. |
| tag | is a brief logging tag. Logging entries can be browsed or sorted according to logging tag. |
| logger | is the user submitting the logging entry. This is typically the user name, but can be a fec name, or application name, for example. Logging entries can be browsed or sorted according the logger. |
| priority | is the logging entry priority. This should be one of CLOG_PRIORITY_NONE, CLOG_PRIORITY_USEFUL, CLOG_PRIORITY_IMPORTANT, or CLOG_PRIORITY_URGENT. |
| status | is the logging status. This should be one of CLOG_STATUS_NONE, CLOG_STATUS_INFO, CLOG_STATUS_WARN, or CLOG_STATUS_ERR. |
| text | is the logging entry. Variable argument ellipses (i.e. printf-style) is allowed. |
| int datacmp | ( | BYTE * | d1, |
| BYTE * | d2, | ||
| int | siz, | ||
| int | fmt, | ||
| double | t | ||
| ) |
\intern compares array d1[siz] against d2[siz] with given format and absolute tolerance
| int feclog | ( | char * | text, |
| ... | |||
| ) |
Puts entries into a server's FEC log file.
Servers by default maintain a log file (fec.log) which contains system information at startup and shutdown time, as well as WRITE access command calls, as well as other notifications.
The server can all place its own text in the server's log file by using this routine. All entries will be pre-pended with a time stamp and the FEC NAME of the server providing the log entry. A new-line character will be appended if the supplied string does not already end in a new line.
| text | is the text string (up to 200 characters) to be logged. |
References argument_list_error.
Referenced by SetAlarmCollapseWindow(), SetAllowNetworkAddressResolution(), SetClientListCapacity(), SetContractListCapacity(), SetFeclogDepth(), SetLinkWatchdogPollingInterval(), SetPacketMTU(), SetPropertySubscriptionRenewalLength(), and SetSystemCycleDeadband().
| int feclogEx | ( | int | loglevel, |
| char * | text, | ||
| ... | |||
| ) |
Puts entries into a server's FEC log file and in error.log file if certain conditions match.
Servers by default maintain a log file (fec.log) which contains system information at startup and shutdown time, as well as WRITE access command calls, as well as other notifications.
The server can all place its own text in the server's log file by using this routine. All entries will be pre-pended with a time stamp and the FEC NAME of the server providing the log entry. A new-line character will be appended if the supplied string does not already end in a new line. In this extended call an int constant parameter indicates if entry should also be logged to error.log This is done, if and only if loglevel parameter is greater than global gErrorLogLevel. Loglevel constants are defined in errors.h: TINE_LOGLEVEL_INFO ..._WARN ..._ERROR ..._FATAL (FATAL is largest value).
| text | is the text string (up to 200 characters) to be logged. |
| loglevel | indicates if text should be written to error.log file |
Referenced by SystemGetStartupCommand().
| int GetBackgroundThreadPriority | ( | void | ) |
Returns the priority of the registered background threads.
| int GetBurstLimit | ( | void | ) |
Gets the burst limit in number of packets which are allowed to be sent consecutively.
For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the cycle delay and determines how many UDP packets (datagrams) are allowed to be sent consecutively within the transport loop before a brake is applies (cycle delay). If all clients and servers are on the same speed ethernet, this value can be adjusted to a much larger value. However, a fast server sending to a slow client (a remote client via a DSL link for instance) might send more datagrams in a burst than can be received. The default value should compensate for this effect.
| int GetCatchConsoleBreak | ( | void | ) |
Returns the current setting for this feature.
If TRUE an application will catch an interrupt or break signal (such as control-C) and issue a graceful exit.
| int GetClientThreadPriority | ( | void | ) |
Returns the priority of the client cycle thread as well as other associated client-side threads.
| int GetContractAccessRate | ( | int | id | ) |
Returns the access rate (interval) associated with the given contract.
A server can retieve the access rate of the specified contract. If a negative number is passed, then the most recently invoked contract is assumed. This routine is most usefull however when used within a server's equipment module.
| id | is the contract table indentifier whose access rate is desired |
| int GetContractId | ( | const char * | eqm | ) |
Returns the last contract identifier for the equipment module specified.
A server can retieve the current contract identifier when the equipment module dispatch routine is being called. If this routine is called outside of the dispatch routine, the value returned will only represent the contract ID valid when the equipment module was last called.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| int GetCycleDelay | ( | void | ) |
Gets the delay time in milliseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().
For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the burst limit and determines how long to delay further datagram transmission when the burst limit has been reached. If all clients and servers are on the same speed ethernet, this value can be adjusted to 0. However, a fast server sending to a slow client (a remote client via a DSL link for instance) might send more datagrams in a burst than can be received. The default value should compensate for this effect.
| int GetCycleMicroDelay | ( | void | ) |
Gets the delay time in microseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().
For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the burst limit and determines how long to delay further datagram transmission when the burst limit has been reached. If all clients and servers are on the same speed ethernet, this value can left at its default value 0. However, when fine adjustments in flow control are necessary, a delay in the micro second region following each 'burst' of packets can be applied, where the delay in microseconds is given by this setting.
| double GetDataTimeStamp | ( | void | ) |
Returns the last established data timestamp.
A call to getDataTimeStamp() immediately following a call to ExecLink() or within a callback routine will yield the data timestamp of the call.
| struct timeval* GetDataTimeStampAsTimeval | ( | void | ) |
Returns the last established data timestamp as a pointer to a struct timeval.
A call to getDataTimeStampAsTimeval() immediately following a call to ExecLink() or within a callback routine will yield the data timestamp of the call.
| double GetDataTimeStampOffset | ( | void | ) |
Returns a the current data timestamp offset as assigned by the TINE global time service.
| char* GetDataTimeString | ( | double | ts, |
| int | useLongStringFormat | ||
| ) |
Returns the TINE data timestamp as a human-readable string.
A call to getDataTimeStamp() returns an 8-byte double containing the current TINE system timestamp. This will be the UTC timestamp appended with milliseconds after the decimal (if available). This timestamp can be converted to a human readable string with this call. The format will depend on the value of the second parameter. If useLongStringFormat is non-zero, the a date of the form:
"Mon Jan 10 12:08:43.355 CET 2005"
will be returned. If useLongStringFormat is zero, then the date string will be of the form (dd.mm.yy hh:mm:ss.msec TZ):
"10.01.05 12:08:43.355 CET"
| ts | is the TINE Data Timestamp for which the string conversion is to be applied. |
| useLongStringFormat | is a flag which if non-zero returns a longer representation of the timestamp. |
References GetDataTimeStringEx().
| char* GetDataTimeStringEx | ( | double | ts, |
| int | useLongStringFormat, | ||
| char * | tsstr | ||
| ) |
Returns the TINE data timestamp as a human-readable string.
A call to getDataTimeStamp() returns an 8-byte double containing the current TINE system timestamp. This will be the UTC timestamp appended with milliseconds after the decimal (if available). This timestamp can be converted to a human readable string with this call. The format will depend on the value of the second parameter. If useLongStringFormat is non-zero, the a date of the form:
"Mon Jan 10 12:08:43.355 CET 2005"
will be returned. If useLongStringFormat is zero, then the date string will be of the form (dd.mm.yy hh:mm:ss.msec TZ):
"10.01.05 12:08:43.355 CET"
| ts | is the TINE Data Timestamp for which the string conversion is to be applied. |
| useLongStringFormat | is a flag which if non-zero returns a longer representation of the timestamp. |
| tsstr | is a buffer to contain the time string (should be at least 64 characters). this same buffer will be returned by the call as a matter of convenience. |
Referenced by GetDataTimeString().
| int GetDieOnAddressInUse | ( | void | ) |
Returns the current setting for this feature.
If TRUE a server will exit() if an 'address in use' message is delivered by the ENS upon registration.
| int GetDieOnFecIsAlias | ( | void | ) |
Returns the current setting for this feature.
If TRUE a server will exit() if a 'FEC has an alias' message is delivered by the ENS upon registration.
| int GetDieOnSocketError | ( | void | ) |
Returns the current setting for this feature.
If TRUE a server will exit() if there are continuous socket errors on important server sockets.
| char* GetFecHome | ( | void | ) |
Gets the current setting for the fec home database repository.
| int GetFeclogDepth | ( | void | ) |
Returns the maximum size of the server's log file in lines.
The server's log file, if located on the local disk, is a file called 'fec.log'. When it's length surpasses the FecLogDepth, this file is rotated to 'fec.bak' and a new 'fec.log' file is started. A call for the server's log file will always be able to scan both the 'fec.bak' file and 'fec.log', and will thus always be able to scan at least FeclogDepth entries.
The value of the log depth also determines the depth of any named log file (see srvlog()).
References FeclogDepth.
| char* GetFecLogPath | ( | void | ) |
Gets the current setting for the fec log repository.
| int GetFormatSizeInBytesFromDataType | ( | DTYPE * | d | ) |
Gives the size of bytes according to the DTYPE fields.
| d | is a pointer to the DTYPE object whose size in bytes is desired |
References DTYPE::dArrayLength, DTYPE::dFormat, and DTYPE::dTag.
| int GetLastContractId | ( | void | ) |
Returns the last contract identifier.
A server can retieve the last contract identifier at any time.
| int GetLastContractTableId | ( | void | ) |
Returns the last contract table identifier.
A server can retieve the last contract table identifier at any time. This routine is most usefull however when used within a server's equipment module.
| int GetPutCommandsInFeclog | ( | void | ) |
Returns the current setting for putCommandsInFeclog (which determines whether all in-coming WRITE access calls are automatically included in the server's log file)
References putCommandsInFeclog.
| int GetServerIdleState | ( | char * | eqm | ) |
Gets the server's idle state.
A Server can be set in an idle state where no background activity occurs and the server's equipment function is temporarily disabled. This call returns the current idle state of the equipment module specified.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| int GetServerThreadPriority | ( | void | ) |
Returns the priority of the server cycle thread as well as other associated server-side threads.
| int GetServerWaiting | ( | void | ) |
Gets the server's waiting state.
A Server can be set in a wait state prior to initialization by passing a non-zero value as argument. In this state, the server will respond to all contract requests with the status code 'not_initialized'. This is useful, if the server needs to undergo a long initialization precedure before allowing clients access. The call retrieves the current wait state (0 = not waiting, non-zero = waiting). The server's wait state is, of course, FALSE (not waiting) by default.
| 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.
| char* GetSystemErrorString | ( | short | cc, |
| char * | errstr | ||
| ) |
Gets the system error code in plain text.
This routine only returns the corresponding string for TINE system error codes. User defined error codes should use the routine GetLastLinkError().
| cc | is the completion code or status code for which the internal system error string is desired. |
| errstr | is a string buffer capable of handling up to 32 characters. |
| int GetSystemLogging | ( | void | ) |
Returns the current system logging setting (TRUE or FALSE)
References nofeclog.
| int GetSystemRequireAcknowledgments | ( | void | ) |
Gets the require acknowledgments flag to the value given.
A server normally requires an acknowledgment from clients being sent changed data if the client link is a data-change style monitor. Under some circumstances this extra acknowledgment network traffic might be unnecessary or undesireable. The current setting can be acquired with this function call.
References gRequireAcknowledgments.
| int GetSystemSchedulePropertyLazy | ( | void | ) |
Gets the 'lazy' flag for scheduling properties.
When a property is scheduled, the delivery can either occur immedidately (default) and thereby invoke the TINE scheduler within the call to SystemScheduleProperty() or occur within the next normal delivery cycle (lazy), which could add a latency of up to a clock tick to the delivery. This call reads the 'lazy flag'.
| int GetSystemUseDataProtection | ( | void | ) |
Gets the data protection flag to the value given.
Multi-threaded servers using background tasks can ensure the thread safety of any data sets used in both an equipment module's background thread and dispatch function handler by explicit coding. As an alternative, calling this routine at initialization time with a non-zero value will automatically generate a data protection mutex which will prevent concurrent exectution of a module's background task and dispatch handler.
| char* GetSystemUserName | ( | void | ) |
Gets the current value for the application user.
| double GetTimeStampFromString | ( | char * | ts | ) |
Returns a TINE timestamp converted from the string argument given.
A call to getDataTimeStampAsTimeval() immediately following a call to ExecLink() or within a callback routine will yield the data timestamp of the call.
| ts | is the string representation of a timestamp. 'NOW' returns the current system clock as a TINE timestamp. A UTC value passed as a string (with or without milliseconds) is converted to a double value and returned. Otherwise a string of the form 'mm.dd.yy hh:mm:ss.msec' is assumed. |
| int GetUseGlobalSynchronization | ( | void | ) |
Returns whether data timestamps are to be externally synchronized.
References useGlobalSynchronization.
| int GetUseMultiThreadedBackgroundTasks | ( | void | ) |
Returns whether equipment module background tasks are to run in separate threads (boolean).
If set to TRUE, the server's background task will run in its own thread, where a multi-threaded build of the library is in use. Note that this could result in data concurrency issues if the background task is acquiring data which is to be used by an equipment module's equipment function.
| 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).
| 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.
| UINT32 GetWorkAreaSize | ( | void | ) |
Gets the server-side work area size which is coupled to the maximum transport size for supported by a single-threaded server.
Server-side equipment function calls are double buffered, one buffer being a dynamic allocation of the caller's requested data size, the other buffer being in the case of single threaded servers, a temporary use of the server's work area. In order to allow transfer of 'large' data sets, this size needs to be adjusted accordingly prior to server initialization. Note that multi-threaded servers will dynamically allocate both buffers on a call by call basis.
References MaxSystemTransportSize.
| int IsServerRunning | ( | void | ) |
Returns TRUE (non zero) if the server kernel is fully initialized and ready.
References SystemRunning.
| int LockEquipmentModules | ( | void | ) |
Locks all equipment modules.
Applying this call seizes a system mutex which will not allow the scheduler to cycle thru the equipment module dispatch routines. Consider setting the IDLE state of the module in lieu of locking and unlocking.
| double MakeDataTimeStamp | ( | void | ) |
Returns a data timestamp according to the current system time.
Referenced by sendNetGlobal().
| int MakeSystemDataStamp | ( | void | ) |
Returns the current valid global system data stamp.
A server can set a global data stamp value (e.g. cycle id or run number, etc.) which will accompany all data transactions.
| value | is the integer value to use as the system data stamp. |
| 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 |
| double PutDataTimeStamp | ( | double | toffset, |
| time_t | tsec, | ||
| int | tmsec | ||
| ) |
Returns a data timestamp according to the input parameters given.
This call is has the same purpose as makeDataTimeStamp(), but can assign a TINE data timestamp according to the input seconds, milliseconds and system time offset. This call is used only under special circumstances.
| toffset | is the systematic time offset to be applied. |
| tsec | is the data timestamp in seconds |
| tmsec | is the millisecond part of the data timestamp |
| double PutDataTimeStampU | ( | double | toffset, |
| time_t | tsec, | ||
| int | tusec | ||
| ) |
Returns a data timestamp according to the input parameters given.
This call is has the same purpose as makeDataTimeStamp(), but can assign a TINE data timestamp according to the input seconds, microseconds and system time offset. This call is used only under special circumstances.
| toffset | is the systematic time offset to be applied. |
| tsec | is the data timestamp in seconds |
| tusec | is the microsecond part of the data timestamp |
| int ResetMultiChannelProperty | ( | char * | eqm, |
| char * | prp | ||
| ) |
sends (schedules) a 'reset_mca_property' signal to any listening client
A server with registered multi-channel array properties can inform any attached clients that the mutli-channel array configuration has changed (e.g. array elements have been added, removed, or otherwise edited) by using this call. Any listening clients with multi-channel array links will then return to the original client startup conditions and 're-learn' the new array indexing now in place.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is (comma separated) list of properties which are to be reset at the client side. |
References argument_list_error.
| 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). |
| int SetBurstLimit | ( | int | npackets | ) |
Sets the burst limit in number of packets which are allowed to be set consecutively.
For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the cycle delay and determines how many UDP packets (datagrams) are allowed to be sent consecutively within the transport loop before a brake is applies (cycle delay). If all clients and servers are on the same speed ethernet, this value can be adjusted to a much larger value. However, a fast server sending to a slow client (a remote client via a DSL link for instance) might send more datagrams in a burst than can be received. The default value should compensate for this effect.
| npackets | is the number of packet allowed to be set consecutively for a given call (default: 1000). |
| void SetCatchConsoleBreak | ( | int | value | ) |
Determines whether an application will catch an interrupt or break signal (such as control-C) and issue a graceful exit or not.
| value | is the desired setting (default = TRUE) |
| 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). |
| int SetCycleDelay | ( | int | msecs | ) |
Sets the delay time in milliseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().
For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the burst limit and determines how long to delay further datagram transmission when the burst limit has been reached. If all clients and servers are on the same speed ethernet, this value can be adjusted to 0. However, a fast server sending to a slow client (a remote client via a DSL link for instance) might send more datagrams in a burst than can be received. The default value should compensate for this effect.
| msec | is the time in milliseconds to delay before sending further ethernet packets. (default: 20 msec). |
| int SetCycleMicroDelay | ( | int | usecs | ) |
Sets the delay time in microseconds following a 'burst' of ethernet packets (as defined by SetBurstLimit().
For UDP transport (the default) TINE does not make use of flow control in any systematic way, other than adjusting this parameter setting at the server side. This parameter works together with the burst limit and determines how long to delay further datagram transmission when the burst limit has been reached. If all clients and servers are on the same speed ethernet, this value can be left at its default value 0. However, when fine adjustments in flow control are necessary, a delay in the micro second region following each 'burst' of packets can be applied, where the delay in microseconds is given by this setting.
| usec | is the time in microseconds to delay before sending further ethernet packets. (default: 0 usec => use cycle delay in milliseconds). |
| void SetDataTimeStamp | ( | double | ts | ) |
Sets the intrinsic data timestamp to the value given.
This call is typically used inside an equipment function to set the data timestamp associated with the request being made. For instance, when the data are taken from the hardware IO loop, a call to makeDataTimeStamp() is made to get the current system timestamp. Then when a request for data is made the caller can know the precise time of data acquisition. If this routine is not called, then the current system time will be used to stamp the data.
| ts | is the timestamp to be associated with the next data set. |
| void SetDieAnotherDay | ( | int | value | ) |
Revokes an 'exit' due to a 'die on' condition.
| value | is the desired setting. |
| void SetDieFunction | ( | DIEFCNP | fcn | ) |
Sets a dispatch routine to call if and when the FEC process dies due to e.g. 'address in use'.
| void SetDieOnAddressInUse | ( | int | value | ) |
Determines whether a server will exit() if an 'address in use' message is delivered by the ENS upon registration.
| value | is the desired setting (default = TRUE) |
| void SetDieOnFecIsAlias | ( | int | value | ) |
Determines whether a server will exit() if a 'FEC has an alias' message is delivered by the ENS upon registration.
| value | is the desired setting (default = FALSE) |
| void SetDieOnSocketError | ( | int | value | ) |
Determines whether a server will exit() if there are continuous socket errors on important server sockets.
| value | is the desired setting (default = TRUE) |
| int SetFecHome | ( | char * | fecHomePath | ) |
Sets the current fec home database repository.
| void SetFeclogDepth | ( | int | value | ) |
Determines the approximate size of the server's log file in lines.
The server's log file, if located on the local disk, is a file called 'fec.log'. When it's length surpasses the FecLogDepth, this file is rotated to 'fec.bak' and a new 'fec.log' file is started. A call for the server's log file will always be able to scan both the 'fec.bak' file and 'fec.log', and will thus always be able to scan at least FeclogDepth entries. The log file depth is controlled via this API call.
| value | is the desired log depth in lines of fec.log. Default: 100. Minimum: 100. |
References feclog(), and FeclogDepth.
| int SetFecLogPath | ( | char * | path | ) |
Sets the fec log repository.
| path | is the desired path for the fec.log file |
| 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). |
References not_accepted.
| 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. |
| 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. |
| void SetPutCommandsInFeclog | ( | int | value | ) |
Determines whether all in-coming WRITE access calls are automatically included in the server's log file.
| value | is the desired setting (default = TRUE). |
References putCommandsInFeclog.
| void SetServerIdleState | ( | char * | eqm, |
| int | value | ||
| ) |
Sets the server's idle state to the value given.
A Server can be set in an idle state where no background activity occurs and the server's equipment function is temporarily disabled. Calls to the equipment function will receive the status code 'server_idle' if this is the case.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| value | is the value of the idle state. Any non-zero sets the idle state to TRUE. A zero value sets the idle state to FALSE. |
| 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). |
| void SetServerWaiting | ( | int | value | ) |
Sets the server's waiting state to the value given.
A Server can be set in a wait state prior to initialization by passing a non-zero value as argument. In this state, the server will respond to all contract requests with the status code 'not_initialized'. This is useful, if the server needs to undergo a long initialization precedure before allowing clients access. Setting the wait state to TRUE before stating the server's cycle() and then later to FALSE when all properties and equipment modules are ready is a safe way to prevent premature access. The server's wait state is, of course, FALSE (not waiting) by default.
| value | is the value of the wait state. |
| 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.
| 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)). |
| void SetSystemDataStamp | ( | int | value | ) |
Sets the global system data stamp with which to tag outbound data sets.
A server can set a global data stamp value (e.g. cycle id or run number, etc.) which will accompany all data transactions.
| value | is the integer value to use as the system data stamp. |
| void SetSystemLogging | ( | int | value | ) |
Sets system logging (output to fec.log) to TRUE or FALSE.
| value | should be TRUE (non zero) if logging is desired (DEFAULT) or FALSE if not. |
References nofeclog.
| void SetSystemRequireAcknowledgments | ( | int | value | ) |
Sets the require acknowledgments flag to the value given.
A server normally requires an acknowledgment from clients being sent changed data if the client link is a data-change style monitor. Under some circumstances this extra acknowledgment network traffic might be unnecessary or undesireable and can be disabled with the function call.
| value | is the desired setting (default = TRUE). |
References gRequireAcknowledgments.
| void SetSystemSchedulePropertyLazy | ( | int | value | ) |
Sets the 'lazy' flag for scheduling properties.
When a property is scheduled, the delivery can either occur immedidately (default) and thereby invoke the TINE scheduler within the call to SystemScheduleProperty() or occur within the next normal delivery cycle (lazy), which could add a latency of up to a clock tick to the delivery. This call sets the 'lazy' flag deteriming this behavior.
| value | will be interpreted in a boolean manner. If TRUE (non-zero) then calls to SystemScheduleProperty() will mark the associated properties for scheduling, which will duly occur during the next call to the scheduler (usually within a clock tick) by the TINE kernel. If FALSE (default) then scheduled properties will immediately invoke the TINE scheduler. |
| void SetSystemUseDataProtection | ( | int | value | ) |
Sets the data protection flag to the value given.
Multi-threaded servers using background tasks can ensure the thread safety of any data sets used in both an equipment module's background thread and dispatch function handler by explicit coding. As an alternative, calling this routine at initialization time with a non-zero value will automatically generate a data protection mutex which will prevent concurrent exectution of a module's background task and dispatch handler.
| value | is the desired setting (default = FALSE). |
| int SetSystemUserName | ( | char * | usr | ) |
Sets the current value for the application user.
| usr | The desired appliation's user name. |
References argument_list_error.
| void SetUseGlobalSynchronization | ( | int | value | ) |
Determines whether data timestamps are to be externally synchronized.
| value | If set to TRUE, data timestamps will be synchronized to an externally supplied timestamp. This requires a TINE Time Server to be in operation and sending timestamps at regular intervals either as multicast or as broadcast (default TRUE); |
| 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. |
| 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. |
| 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. |
| UINT32 SetWorkAreaSize | ( | UINT32 | size | ) |
Sets the server-side work area size which is coupled to the maximum transport size for supported by a single-threaded server.
Server-side equipment function calls are double buffered, one buffer being a dynamic allocation of the caller's requested data size, the other buffer being in the case of single threaded servers, a temporary use of the server's work area. In order to allow transfer of 'large' data sets, this size needs to be adjusted accordingly prior to server initialization. Note that multi-threaded servers will dynamically allocate both buffers on a call by call basis.
| size | is the size in bytes to be reserved for the server's work area and hence the maximum allowed transport size for any property supported by the server. (default: 64 KBytes on most operating systems). |
| int srvlog | ( | char * | filename, |
| char * | tag, | ||
| char * | text, | ||
| ... | |||
| ) |
Puts entries into a named log file.
Servers can write log entries to any log file of their choosing by making use of this call. All entries will be pre-pended with a time stamp and the given tag and appended with a new-line character.
| filename | is the desired file name. If this name does not specify a full path then the FEC_HOME location determines the location of the log file. Likewise, if the filename does not specify an extension, the extension ".log" will be automatically appended. |
| tag | is an optional tag to be applied to each log entry, following the timestamp. This can be used to specify the routine or process supplying the log information, for example. If not specified, the tag "Logger" will be used. |
| text | is the text string (up to 200 characters) to be logged. |
| BYTE* SystemVersion | ( | void | ) |
Returns the system version as a 4-byte array containg the major and minor version numbers as the first two bytes and the current revision in the next two bytes.
Example:
Referenced by GetSystemVersionString().
| 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.
| int FeclogDepth = FECLOG_DEPTH |
Determines the approximate size of the server's log file in lines.
The server's log file, if located on the local disk, is a file called 'fec.log'. When it's length surpasses the FecLogDepth, this file is moved to 'fec.bak' and a new 'fec.log' file is started. A call for the server's log file will always be able to scan both the 'fec.bak' file and 'fec.log', and will thus always be able to scan at least FeclogDepth entries.
Default: 100
Referenced by GetFeclogDepth(), and SetFeclogDepth().
| int gErrorLogLevel = TINE_LOGLEVEL_WARN |
Determines which messages are written to error.log file.
by default it is set to TINE_LOGLEVEL_WARN, so WARN, ERROR and FATAL are written to error.log
| int gStartupDebug = 1 |
Determines whether server initialization messages are displayed or not.
A running server is quiet regarding information displayed on the standard output. An initializing server is however by default not quiet, and will echo various steps of the initialization process on the screen, including whether of not optional configuration files are found or not, etc. This information can be surpressed by setting gStartupDebug to FALSE prior to calling SystemInit().
Default: TRUE
| int nofeclog = FALSE |
Determines whether a server is to keep a log file on the local disk.
The location of the log file is determined by the FECDB environment variable or, if not set, the current working directory is used. If set to TRUE, then no log file will be maintained on the local disk. A log file will nonetheless be maintained in a local ring-buffer, with the caveat that all entries will disappear upon server restart. To eliminate the log file entirely, 'nofeclog' should be set to TRUE and 'FeclogDepth' should be set to 0.
Default: FALSE for most operating systems. Exceptions: VxWorks, NIOS.
Referenced by GetSystemLogging(), and SetSystemLogging().
| int putCommandsInFeclog = INCLUDE_IN_LOGFILE |
Determines whether all in-coming WRITE access calls are automatically included in the server's log file.
Default: TRUE
Referenced by GetPutCommandsInFeclog(), and SetPutCommandsInFeclog().
| int useGlobalSynchronization = GLOBAL_SYNCHRONIZATION |
Determines whether data timestamps are to be externally synchronized.
If set to TRUE, data timestamps will be synchronized to an externally supplied timestamp. This requires a TINE Time Server to be in operation and sending timestamps at regular intervals either as multicast or as broadcast.
Default: TRUE
Referenced by GetUseGlobalSynchronization().
1.5.8